Add advanced canvas editing and Ubuntu deployment
This commit is contained in:
@@ -1,184 +1,199 @@
|
||||
# WordCloud — Docker Compose 部署指南
|
||||
|
||||
本项目提供完整的 Docker Compose 配置，可在任意 Ubuntu / Linux 服务器上通过 `docker-compose up` 一键启动前后端服务。
|
||||
本项目提供完整的 Docker Compose 配置，可在任意 Ubuntu / Linux 服务器上一键启动前后端服务。
|
||||
|
||||
---
|
||||
|
||||
## 1. 目录结构
|
||||
## 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 # 编排 frontend + backend
|
||||
├── Makefile # 常用命令封装
|
||||
├── docker-compose.yml
|
||||
├── Makefile
|
||||
├── install-ubuntu.sh # Ubuntu 一键安装/启动
|
||||
├── DOCKER.md
|
||||
├── frontend/
|
||||
│ ├── Dockerfile # Node 构建 + Nginx 服务
|
||||
│ ├── nginx.conf # 静态资源 + /api 反向代理
|
||||
│ └── .dockerignore
|
||||
│ ├── Dockerfile
|
||||
│ ├── nginx.conf
|
||||
│ └── ...
|
||||
└── backend/
|
||||
├── Dockerfile # Python + C++ 扩展构建
|
||||
├── Dockerfile
|
||||
├── requirements.txt
|
||||
└── .dockerignore
|
||||
└── ...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 环境要求
|
||||
## 3. 环境要求
|
||||
|
||||
- Ubuntu 20.04+（推荐）或其他 Linux
|
||||
- Docker Engine >= 20.10
|
||||
- Docker Compose >= 1.29（或 `docker compose` plugin）
|
||||
- 服务器开放端口：`3000`（前端）、`8000`（后端，可选暴露）
|
||||
- Docker Compose V2 插件（`docker compose`）或 `docker-compose` >= 1.29
|
||||
- 开放端口：`3000`（前端）；`8000`（后端，可选）
|
||||
|
||||
若使用 `install-ubuntu.sh`，Docker 可自动安装。
|
||||
|
||||
---
|
||||
|
||||
## 3. 快速开始
|
||||
|
||||
### 3.1 克隆/上传代码到 Ubuntu 服务器
|
||||
## 4. 手动命令
|
||||
|
||||
```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 build --no-cache
|
||||
|
||||
# 或者直接使用 docker-compose
|
||||
docker-compose up -d --build
|
||||
# 启动
|
||||
make up
|
||||
# 或
|
||||
docker compose up -d
|
||||
|
||||
# 一键构建并启动
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
首次构建会：
|
||||
1. 后端：安装 Python 依赖并编译 `EfficientWordCloud` C++ 扩展。
|
||||
2. 前端：执行 `npm ci` 与 `npm run build`，生成静态文件。
|
||||
|
||||
根据服务器性能，首次构建通常需要 3–10 分钟。
|
||||
1. 后端安装 Python 依赖并编译 `EfficientWordCloud` C++ 扩展
|
||||
2. 前端执行 `npm ci` 与 `npm run build`
|
||||
|
||||
### 3.3 访问服务
|
||||
|
||||
- 前端页面：http://`<服务器IP>`:3000
|
||||
- 后端 API 文档：http://`<服务器IP>`:8000/docs
|
||||
- 后端健康检查：http://`<服务器IP>`:8000/api/health
|
||||
|
||||
> 前端 Nginx 已将所有 `/api/*` 请求反向代理到后端容器，因此浏览器只需访问 3000 端口。
|
||||
视机器性能，首次约 3–10 分钟。
|
||||
|
||||
---
|
||||
|
||||
## 4. 常用命令
|
||||
## 5. 常用命令
|
||||
|
||||
| 命令 | 说明 |
|
||||
|------|------|
|
||||
| `./install-ubuntu.sh` | Ubuntu 一键安装 Docker 并启动 |
|
||||
| `make build` | 重新构建镜像 |
|
||||
| `make up` | 后台启动服务 |
|
||||
| `make up` | 后台启动 |
|
||||
| `make down` | 停止并移除容器 |
|
||||
| `make restart` | 重启服务 |
|
||||
| `make logs` | 查看实时日志 |
|
||||
| `make logs-backend` | 只看后端日志 |
|
||||
| `make logs-frontend` | 只看前端日志 |
|
||||
| `make clean` | 停止并删除容器 + 镜像 + 卷（谨慎） |
|
||||
| `make shell-backend` | 进入后端容器调试 |
|
||||
| `make restart` | 重启 |
|
||||
| `make logs` | 实时日志 |
|
||||
| `make logs-backend` | 后端日志 |
|
||||
| `make logs-frontend` | 前端日志 |
|
||||
| `make status` | 查看容器状态 |
|
||||
| `make clean` | 停止并删除容器 + 镜像 + 卷（慎用） |
|
||||
| `make shell-backend` | 进入后端容器 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 数据持久化
|
||||
## 6. 数据持久化
|
||||
|
||||
Docker Compose 已声明以下命名卷，数据会保存在 Docker 宿主机上，容器重建不会丢失：
|
||||
Compose 使用命名卷，容器重建不丢数据：
|
||||
|
||||
| 卷名 | 容器内路径 | 用途 |
|
||||
|------|-----------|------|
|
||||
| `wordcloud_workspace` | `/app/service_workspace` | 词云任务工作目录 |
|
||||
| `wordcloud_assets` | `/app/service_assets` | 贴纸资源文件 |
|
||||
| `wordcloud_projects` | `/app/service_projects` | 保存的项目 |
|
||||
|------|------------|------|
|
||||
| `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` | 上传的字体文件 |
|
||||
| `wordcloud_fonts` | `/app/service_fonts` | 上传字体 |
|
||||
|
||||
如需查看本地卷位置：
|
||||
查看卷：
|
||||
|
||||
```bash
|
||||
docker volume ls | grep wordcloud
|
||||
docker volume inspect wordcloud_workspace
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 端口与网络
|
||||
## 7. 端口修改
|
||||
|
||||
- `frontend` 容器监听 `3000:80`
|
||||
- `backend` 容器监听 `8000:8000`
|
||||
- 两个服务通过默认 Docker bridge 网络通信，`frontend` 的 Nginx 通过服务名 `backend:8000` 访问后端。
|
||||
编辑 `docker-compose.yml` 的 `ports`，例如前端改为 `8080:80`：
|
||||
|
||||
如需修改端口，编辑 `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
|
||||
make up
|
||||
```
|
||||
|
||||
本地开发时前端通过 Vite 代理 `/api` 到 `http://localhost:8000`。
|
||||
---
|
||||
|
||||
## 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`
|
||||
|
||||
Reference in New Issue
Block a user