# 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`。