200 lines
3.9 KiB
Markdown
200 lines
3.9 KiB
Markdown
# WordCloud — Docker Compose 部署指南
|
||
|
||
本项目提供完整的 Docker Compose 配置，可在任意 Ubuntu / Linux 服务器上一键启动前后端服务。
|
||
|
||
---
|
||
|
||
## 1. 推荐：Release 包一键部署（Ubuntu）
|
||
|
||
### 1.1 上传并解压
|
||
|
||
```bash
|
||
# 把 release.tar.gz 传到服务器后：
|
||
tar -xzf release.tar.gz
|
||
cd wordcloud
|
||
```
|
||
|
||
### 1.2 一键安装 Docker 并启动
|
||
|
||
```bash
|
||
chmod +x install-ubuntu.sh
|
||
./install-ubuntu.sh
|
||
```
|
||
|
||
脚本会：
|
||
|
||
1. 检测 Docker；若缺失则在 Ubuntu 上自动安装 Docker Engine + Compose 插件
|
||
2. 执行 `docker compose up -d --build`
|
||
3. 构建后端（含 C++ 扩展）与前端静态资源
|
||
|
||
### 1.3 访问
|
||
|
||
- 前端：`http://<服务器IP>:3000`
|
||
- 后端 API 文档：`http://<服务器IP>:8000/docs`
|
||
- 健康检查：`http://<服务器IP>:8000/api/health`
|
||
|
||
> 前端 Nginx 已将 `/api/*` 反向代理到后端，浏览器通常只需访问 3000 端口。
|
||
|
||
---
|
||
|
||
## 2. 目录结构
|
||
|
||
```
|
||
wordcloud/
|
||
├── docker-compose.yml
|
||
├── Makefile
|
||
├── install-ubuntu.sh # Ubuntu 一键安装/启动
|
||
├── DOCKER.md
|
||
├── frontend/
|
||
│ ├── Dockerfile
|
||
│ ├── nginx.conf
|
||
│ └── ...
|
||
└── backend/
|
||
├── Dockerfile
|
||
├── requirements.txt
|
||
└── ...
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 环境要求
|
||
|
||
- Ubuntu 20.04+（推荐）或其他 Linux
|
||
- Docker Engine >= 20.10
|
||
- Docker Compose V2 插件（`docker compose`）或 `docker-compose` >= 1.29
|
||
- 开放端口：`3000`（前端）；`8000`（后端，可选）
|
||
|
||
若使用 `install-ubuntu.sh`，Docker 可自动安装。
|
||
|
||
---
|
||
|
||
## 4. 手动命令
|
||
|
||
```bash
|
||
# 构建
|
||
make build
|
||
# 或
|
||
docker compose build --no-cache
|
||
|
||
# 启动
|
||
make up
|
||
# 或
|
||
docker compose up -d
|
||
|
||
# 一键构建并启动
|
||
docker compose up -d --build
|
||
```
|
||
|
||
首次构建会：
|
||
|
||
1. 后端安装 Python 依赖并编译 `EfficientWordCloud` C++ 扩展
|
||
2. 前端执行 `npm ci` 与 `npm run build`
|
||
|
||
视机器性能，首次约 3–10 分钟。
|
||
|
||
---
|
||
|
||
## 5. 常用命令
|
||
|
||
| 命令 | 说明 |
|
||
|------|------|
|
||
| `./install-ubuntu.sh` | Ubuntu 一键安装 Docker 并启动 |
|
||
| `make build` | 重新构建镜像 |
|
||
| `make up` | 后台启动 |
|
||
| `make down` | 停止并移除容器 |
|
||
| `make restart` | 重启 |
|
||
| `make logs` | 实时日志 |
|
||
| `make logs-backend` | 后端日志 |
|
||
| `make logs-frontend` | 前端日志 |
|
||
| `make status` | 查看容器状态 |
|
||
| `make clean` | 停止并删除容器 + 镜像 + 卷（慎用） |
|
||
| `make shell-backend` | 进入后端容器 |
|
||
|
||
---
|
||
|
||
## 6. 数据持久化
|
||
|
||
Compose 使用命名卷，容器重建不丢数据：
|
||
|
||
| 卷名 | 容器内路径 | 用途 |
|
||
|------|------------|------|
|
||
| `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 ls | grep wordcloud
|
||
docker volume inspect wordcloud_workspace
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 端口修改
|
||
|
||
编辑 `docker-compose.yml` 的 `ports`，例如前端改为 `8080:80`：
|
||
|
||
```yaml
|
||
ports:
|
||
- "8080:80"
|
||
```
|
||
|
||
然后：
|
||
|
||
```bash
|
||
make up
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 常见问题
|
||
|
||
### 8.1 构建 C++ 扩展失败
|
||
|
||
确保构建时能访问 Debian/Ubuntu 软件源以安装 `build-essential`、`g++`。国内服务器可配置 Docker 镜像加速。
|
||
|
||
### 8.2 前端能开但接口 502
|
||
|
||
```bash
|
||
make logs-backend
|
||
curl -f http://127.0.0.1:8000/api/health
|
||
```
|
||
|
||
确认 backend 健康检查通过后再访问前端。
|
||
|
||
### 8.3 权限问题
|
||
|
||
```bash
|
||
sudo usermod -aG docker $USER
|
||
# 重新登录后再执行 ./install-ubuntu.sh
|
||
```
|
||
|
||
### 8.4 清理后重装
|
||
|
||
```bash
|
||
make clean
|
||
./install-ubuntu.sh
|
||
```
|
||
|
||
注意：`make clean` 会删除命名卷，用户数据会丢失。
|
||
|
||
---
|
||
|
||
## 9. 本地重新打包 Release
|
||
|
||
在开发机项目根目录：
|
||
|
||
```bash
|
||
make release
|
||
# 或
|
||
./scripts/pack-release.sh
|
||
```
|
||
|
||
会覆盖：
|
||
|
||
- `release/`
|
||
- `release.tar.gz`
|