185 lines
4.6 KiB
Markdown
185 lines
4.6 KiB
Markdown
# WordCloud — Docker Compose 部署指南
|
||
|
||
本项目提供完整的 Docker Compose 配置，可在任意 Ubuntu / Linux 服务器上通过 `docker-compose up` 一键启动前后端服务。
|
||
|
||
---
|
||
|
||
## 1. 目录结构
|
||
|
||
```
|
||
wordcloud/
|
||
├── docker-compose.yml # 编排 frontend + backend
|
||
├── Makefile # 常用命令封装
|
||
├── frontend/
|
||
│ ├── Dockerfile # Node 构建 + Nginx 服务
|
||
│ ├── nginx.conf # 静态资源 + /api 反向代理
|
||
│ └── .dockerignore
|
||
└── backend/
|
||
├── Dockerfile # Python + C++ 扩展构建
|
||
├── requirements.txt
|
||
└── .dockerignore
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 环境要求
|
||
|
||
- Docker Engine >= 20.10
|
||
- Docker Compose >= 1.29（或 `docker compose` plugin）
|
||
- 服务器开放端口：`3000`（前端）、`8000`（后端，可选暴露）
|
||
|
||
---
|
||
|
||
## 3. 快速开始
|
||
|
||
### 3.1 克隆/上传代码到 Ubuntu 服务器
|
||
|
||
```bash
|
||
cd /opt
|
||
# 方式 A：git clone
|
||
git clone <你的仓库地址> wordcloud
|
||
cd wordcloud
|
||
|
||
# 方式 B：直接上传整个项目目录后进入
|
||
cd /path/to/wordcloud
|
||
```
|
||
|
||
### 3.2 构建并启动
|
||
|
||
```bash
|
||
# 使用 Makefile（推荐）
|
||
make build
|
||
make up
|
||
|
||
# 或者直接使用 docker-compose
|
||
docker-compose up -d --build
|
||
```
|
||
|
||
首次构建会：
|
||
1. 后端：安装 Python 依赖并编译 `EfficientWordCloud` C++ 扩展。
|
||
2. 前端：执行 `npm ci` 与 `npm run build`，生成静态文件。
|
||
|
||
根据服务器性能，首次构建通常需要 3–10 分钟。
|
||
|
||
### 3.3 访问服务
|
||
|
||
- 前端页面：http://`<服务器IP>`:3000
|
||
- 后端 API 文档：http://`<服务器IP>`:8000/docs
|
||
- 后端健康检查：http://`<服务器IP>`:8000/api/health
|
||
|
||
> 前端 Nginx 已将所有 `/api/*` 请求反向代理到后端容器，因此浏览器只需访问 3000 端口。
|
||
|
||
---
|
||
|
||
## 4. 常用命令
|
||
|
||
| 命令 | 说明 |
|
||
|------|------|
|
||
| `make build` | 重新构建镜像 |
|
||
| `make up` | 后台启动服务 |
|
||
| `make down` | 停止并移除容器 |
|
||
| `make restart` | 重启服务 |
|
||
| `make logs` | 查看实时日志 |
|
||
| `make logs-backend` | 只看后端日志 |
|
||
| `make logs-frontend` | 只看前端日志 |
|
||
| `make clean` | 停止并删除容器 + 镜像 + 卷（谨慎） |
|
||
| `make shell-backend` | 进入后端容器调试 |
|
||
|
||
---
|
||
|
||
## 5. 数据持久化
|
||
|
||
Docker Compose 已声明以下命名卷，数据会保存在 Docker 宿主机上，容器重建不会丢失：
|
||
|
||
| 卷名 | 容器内路径 | 用途 |
|
||
|------|-----------|------|
|
||
| `wordcloud_workspace` | `/app/service_workspace` | 词云任务工作目录 |
|
||
| `wordcloud_assets` | `/app/service_assets` | 贴纸资源文件 |
|
||
| `wordcloud_projects` | `/app/service_projects` | 保存的项目 |
|
||
| `wordcloud_design_templates` | `/app/service_design_templates` | 设计模板 |
|
||
| `wordcloud_fonts` | `/app/service_fonts` | 上传的字体文件 |
|
||
|
||
如需查看本地卷位置：
|
||
|
||
```bash
|
||
docker volume inspect wordcloud_workspace
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 端口与网络
|
||
|
||
- `frontend` 容器监听 `3000:80`
|
||
- `backend` 容器监听 `8000:8000`
|
||
- 两个服务通过默认 Docker bridge 网络通信，`frontend` 的 Nginx 通过服务名 `backend:8000` 访问后端。
|
||
|
||
如需修改端口，编辑 `docker-compose.yml` 中的 `ports` 映射即可，例如将前端改为 `8080:80`。
|
||
|
||
---
|
||
|
||
## 7. 生产环境建议
|
||
|
||
1. **使用反向代理（Nginx / Caddy / Traefik）**
|
||
- 将 `3000` 端口通过域名 + HTTPS 暴露。
|
||
- 关闭后端 `8000` 端口的外部访问，仅保留内部通信。
|
||
|
||
2. **设置环境变量**
|
||
- 后端 `UVICORN_WORKERS`：可通过环境变量增加工作进程数。
|
||
- 如需自定义后端日志级别，可挂载 `.env` 文件。
|
||
|
||
3. **备份数据卷**
|
||
- 定期备份 `wordcloud_assets`、`wordcloud_projects` 等卷，避免服务器故障丢失用户数据。
|
||
|
||
4. **更新部署**
|
||
```bash
|
||
git pull
|
||
make build
|
||
make restart
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 常见问题
|
||
|
||
### Q1: 前端页面空白或 502
|
||
检查后端是否健康：
|
||
```bash
|
||
make logs-backend
|
||
```
|
||
确认 `/api/health` 返回 `{"status":"ok"}`。
|
||
|
||
### Q2: 构建 C++ 扩展失败
|
||
确保 base 镜像能联网安装 `build-essential` 与 `g++`。如在中国大陆服务器，可配置 Docker 镜像加速。
|
||
|
||
### Q3: 贴纸/字体上传后丢失
|
||
检查卷是否正确挂载：
|
||
```bash
|
||
docker exec -it wordcloud-backend ls -la /app/service_assets
|
||
```
|
||
|
||
### Q4: 端口被占用
|
||
修改 `docker-compose.yml` 中的端口映射，例如：
|
||
```yaml
|
||
ports:
|
||
- "8080:80"
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 本地开发（非 Docker）
|
||
|
||
如需本地开发，可分别运行：
|
||
|
||
```bash
|
||
# 后端
|
||
cd backend
|
||
./start-dev.sh
|
||
|
||
# 前端
|
||
cd frontend
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
本地开发时前端通过 Vite 代理 `/api` 到 `http://localhost:8000`。
|