wordcloud/DOCKER.md

WordCloud — Docker Compose 部署指南

本项目提供完整的 Docker Compose 配置，可在任意 Ubuntu / Linux 服务器上一键启动前后端服务。

---

1. 推荐：Release 包一键部署（Ubuntu）

1.1 上传并解压

# 把 release.tar.gz 传到服务器后：
tar -xzf release.tar.gz
cd wordcloud

1.2 一键安装 Docker 并启动

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. 手动命令

# 构建
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	上传字体

查看卷：

docker volume ls | grep wordcloud
docker volume inspect wordcloud_workspace

---

7. 端口修改

编辑 docker-compose.yml 的 ports，例如前端改为 8080:80：

ports:
  - "8080:80"

然后：

make up

---

8. 常见问题

8.1 构建 C++ 扩展失败

确保构建时能访问 Debian/Ubuntu 软件源以安装 build-essential、g++。国内服务器可配置 Docker 镜像加速。

8.2 前端能开但接口 502

make logs-backend
curl -f http://127.0.0.1:8000/api/health

确认 backend 健康检查通过后再访问前端。

8.3 权限问题

sudo usermod -aG docker $USER
# 重新登录后再执行 ./install-ubuntu.sh

8.4 清理后重装

make clean
./install-ubuntu.sh

注意：make clean 会删除命名卷，用户数据会丢失。

---

9. 本地重新打包 Release

在开发机项目根目录：

make release
# 或
./scripts/pack-release.sh

会覆盖：

• release/
• release.tar.gz