wordcloud/DOCKER.md

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 服务器

cd /opt
# 方式 A：git clone
git clone <你的仓库地址> wordcloud
cd wordcloud

# 方式 B：直接上传整个项目目录后进入
cd /path/to/wordcloud

3.2 构建并启动

# 使用 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	上传的字体文件

如需查看本地卷位置：

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. 更新部署

   git pull
   make build
   make restart
   

---

8. 常见问题

Q1: 前端页面空白或 502

检查后端是否健康：

make logs-backend

确认 /api/health 返回 {"status":"ok"}。

Q2: 构建 C++ 扩展失败

确保 base 镜像能联网安装 build-essential 与 g++。如在中国大陆服务器，可配置 Docker 镜像加速。

Q3: 贴纸/字体上传后丢失

检查卷是否正确挂载：

docker exec -it wordcloud-backend ls -la /app/service_assets

Q4: 端口被占用

修改 docker-compose.yml 中的端口映射，例如：

ports:
  - "8080:80"

---

9. 本地开发（非 Docker）

如需本地开发，可分别运行：

# 后端
cd backend
./start-dev.sh

# 前端
cd frontend
npm install
npm run dev

本地开发时前端通过 Vite 代理 /api 到 http://localhost:8000。