Initial project baseline

DOCKER.md

@@ -0,0 +1,184 @@
+# 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`。