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