9798b34717
- 重新构建 frontend/dist（新版 hash 替换旧版） - 更新 docker 前端 Dockerfile 及 docker-compose 配置 - 新增 docs/team-development-plan.md 团队开发计划文档 - 更新 README、系统开发计划等文档 - 更新 LoginView 组件 Co-Authored-By: Claude <noreply@anthropic.com>
268 lines
8.7 KiB
Markdown
268 lines
8.7 KiB
Markdown
# Docker 部署说明
|
||
|
||
本目录按应用服务器和算力服务器拆分 Dockerfile 与 Docker Compose 文件。Compose 文件不包含 `build:`，不会在 `docker compose up` 时自动构建业务镜像。所有业务镜像需要先通过手动 `docker build` 构建，再由 Compose 启动。
|
||
|
||
## 基础镜像
|
||
|
||
| 镜像 | 用途 |
|
||
| --- | --- |
|
||
| `python:3.12-slim` | 应用后端基础镜像，后端运行环境要求 Python 3.12 及以上 |
|
||
| `nginx:1.27-alpine` | 前端静态资源与 `/modelTF` 反向代理运行镜像 |
|
||
| `hiyouga/llamafactory:latest` | 算力服务基础镜像，基于 LLaMA-Factory 官方镜像扩展 Compute API |
|
||
| `postgres:16-alpine` | 开发阶段内置 PostgreSQL |
|
||
| `redis:7-alpine` | 开发阶段内置 Redis |
|
||
|
||
一键拉取基础镜像：
|
||
|
||
```bash
|
||
docker pull python:3.12-slim && \
|
||
docker pull nginx:1.27-alpine && \
|
||
docker pull hiyouga/llamafactory:latest && \
|
||
docker pull postgres:16-alpine && \
|
||
docker pull redis:7-alpine
|
||
```
|
||
|
||
Windows PowerShell：
|
||
|
||
```powershell
|
||
$images = @(
|
||
"python:3.12-slim",
|
||
"nginx:1.27-alpine",
|
||
"hiyouga/llamafactory:latest",
|
||
"postgres:16-alpine",
|
||
"redis:7-alpine"
|
||
)
|
||
$images | ForEach-Object { docker pull $_ }
|
||
```
|
||
|
||
如果部署环境不能访问外网，需要提前在可联网环境执行上述拉取命令，再用 `docker save` / `docker load` 导出导入。
|
||
|
||
## 业务镜像
|
||
|
||
| 镜像 | Dockerfile | 构建命令 |
|
||
| --- | --- | --- |
|
||
| `yg-ft-backend-api:latest` | `docker/app/Dockerfile.backend` | `docker build -f docker/app/Dockerfile.backend -t yg-ft-backend-api:latest .` |
|
||
| `yg-ft-frontend-runtime:latest` | `docker/app/Dockerfile.frontend` | `docker build -f docker/app/Dockerfile.frontend -t yg-ft-frontend-runtime:latest .` |
|
||
| `yg-ft-compute-api:latest` | `docker/compute/Dockerfile.compute` | `docker build -f docker/compute/Dockerfile.compute -t yg-ft-compute-api:latest .` |
|
||
|
||
## 对外端口
|
||
|
||
所有宿主机对外端口统一使用 5 位端口。容器内部端口保持镜像默认端口，便于容器内服务和健康检查稳定。
|
||
|
||
| 服务 | 宿主机对外端口 | 容器内部端口 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| 前端 Nginx | `16801` | `80` | 前端页面入口 |
|
||
| 后端 API | `17861` | `8000` | FastAPI 服务 |
|
||
| PostgreSQL | `15432` | `5432` | 开发阶段内置数据库 |
|
||
| Redis | `16379` | `6379` | 开发阶段内置缓存 |
|
||
| Compute API | `19100` | `9100` | 算力服务器 API |
|
||
| File Gateway | `19101` | 后续服务端口 | 当前预留，后续拆出文件网关服务时使用 |
|
||
|
||
注意：`8000` 是后端容器内部端口，不作为宿主机对外访问端口。宿主机或浏览器应访问 `http://<app-server-ip>:17861/modelTF/health`；前端 Nginx 容器在 Docker 网络内部访问 `http://backend-api:8000/modelTF/...`。
|
||
|
||
对应配置文件：
|
||
|
||
- `docker/app/.env.example`
|
||
- `FRONTEND_PORT=16801`
|
||
- `BACKEND_API_PORT=17861`
|
||
- `POSTGRES_PORT=15432`
|
||
- `REDIS_PORT=16379`
|
||
- `docker/compute/.env.example`
|
||
- `COMPUTE_API_PORT=19100`
|
||
- `FILE_GATEWAY_PORT=19101`
|
||
|
||
## 运行模式
|
||
|
||
- 应用侧默认 `COMPUTE_MODE=real`，任务状态必须由真实算力同步逻辑更新。
|
||
- 算力侧默认 `COMPUTE_EXECUTION_MODE=real`，真实执行器未完成前不会伪造训练作业。
|
||
- 仅隔离联调时可显式设置 `COMPUTE_MODE=simulator` 或 `COMPUTE_EXECUTION_MODE=simulator`，该模式不得用于测试环境、生产环境或生产升级基线。
|
||
|
||
## 应用服务器部署
|
||
|
||
应用服务器包含前端 Nginx、Backend API、PostgreSQL、Redis。
|
||
|
||
当前 Compose 内置 PostgreSQL 使用 `backend/app/db/sql/001_platform_runtime.sql` 初始化运行库。`docs/postgres-schema.sql` 是完整目标架构设计，不应直接挂载为当前运行库初始化脚本，否则会与当前后端代码的运行表结构不兼容。
|
||
|
||
首次部署：
|
||
|
||
```bash
|
||
cd <repo-root>
|
||
|
||
# 1. 使用当前 Windows/宿主机 npm 构建前端静态产物
|
||
cd frontend
|
||
npm ci
|
||
npm run build
|
||
cd ..
|
||
|
||
# 2. 手动构建业务镜像
|
||
docker build -f docker/app/Dockerfile.backend -t yg-ft-backend-api:latest .
|
||
docker build -f docker/app/Dockerfile.frontend -t yg-ft-frontend-runtime:latest .
|
||
|
||
# 3. 启动应用服务
|
||
cd docker/app
|
||
cp .env.example .env
|
||
docker compose up -d
|
||
```
|
||
|
||
后端镜像构建过程中会执行依赖导入自检，确认 `fastapi`、`uvicorn`、`psycopg`、`sqlalchemy`、`redis` 等运行依赖已安装。构建后也可以手动检查：
|
||
|
||
```bash
|
||
docker run --rm yg-ft-backend-api:latest python -c "import psycopg; print(psycopg.__version__)"
|
||
```
|
||
|
||
默认访问地址：
|
||
|
||
```text
|
||
http://<app-server-ip>:16801
|
||
```
|
||
|
||
应用侧代码和数据外挂：
|
||
|
||
```text
|
||
../../backend -> /app
|
||
../../frontend/dist -> /usr/share/nginx/html
|
||
../../runtime/app/logs/backend -> /opt/yg-ft/logs/backend
|
||
../../runtime/app/data -> /data/yg-ft
|
||
```
|
||
|
||
前端容器启动前必须确保 `../../frontend/dist/index.html` 已存在。若前端 Nginx 日志出现 `directory index of "/usr/share/nginx/html/" is forbidden` 或 `rewrite or internal redirection cycle while internally redirecting to "/index.html"`，通常表示当前执行 `docker compose` 的项目目录下没有构建好的 `frontend/dist`，或挂载路径不是同一份代码目录。
|
||
|
||
```bash
|
||
# 在执行 docker compose 的同一份代码目录中检查
|
||
cd <repo-root>/frontend
|
||
npm run build
|
||
test -f dist/index.html && ls -lh dist/index.html
|
||
|
||
cd ../docker/app
|
||
docker compose up -d --force-recreate frontend
|
||
docker compose logs --tail=80 frontend
|
||
```
|
||
|
||
如果使用 Windows npm 构建、WSL 中运行 Docker Compose，需要确认 Windows 路径和 WSL 路径指向同一份仓库。例如在 `D:\...\YG_FT\frontend` 构建不会自动生成 `/mnt/d/wuyongtao/Code/YG_FT/frontend/dist` 下的产物，除非二者本就是同一个目录。
|
||
|
||
如果使用企业统一 PostgreSQL/Redis，修改 `docker/app/.env`：
|
||
|
||
```env
|
||
DATABASE_URL=postgresql+psycopg://<user>:<password>@<postgres-host>:15432/<db>
|
||
REDIS_URL=redis://<redis-host>:16379/0
|
||
USE_BUILTIN_POSTGRES=false
|
||
USE_BUILTIN_REDIS=false
|
||
```
|
||
|
||
生产环境如完全使用外部基础设施，可以删除或注释 Compose 中的 `postgres`、`redis` 服务及 `backend-api.depends_on` 中对应依赖。
|
||
|
||
## 算力服务器部署
|
||
|
||
算力服务器包含 Compute API、后续 Compute Agent、File Gateway、GPU runtime、本地训练数据目录和 LLaMA-Factory。`Dockerfile.compute` 基于 LLaMA-Factory 官方镜像：
|
||
|
||
```dockerfile
|
||
FROM hiyouga/llamafactory:latest
|
||
```
|
||
|
||
部署前需要安装：
|
||
|
||
- NVIDIA Driver
|
||
- NVIDIA Container Toolkit
|
||
- Docker Engine 和 Docker Compose Plugin
|
||
- 本地训练数据目录，默认 `/data/yg-ft`
|
||
|
||
首次部署：
|
||
|
||
```bash
|
||
cd <repo-root>
|
||
|
||
# 手动构建算力业务镜像
|
||
docker build -f docker/compute/Dockerfile.compute -t yg-ft-compute-api:latest .
|
||
|
||
# 启动算力服务
|
||
cd docker/compute
|
||
cp .env.example .env
|
||
docker compose up -d
|
||
```
|
||
|
||
健康检查：
|
||
|
||
```text
|
||
GET http://<compute-server-ip>:19100/modelTF/health
|
||
GET http://<compute-server-ip>:19100/modelTF/v1/compute/health
|
||
```
|
||
|
||
算力侧代码和数据外挂：
|
||
|
||
```text
|
||
../../compute -> /app/compute
|
||
${YG_FT_DATA_ROOT_HOST} -> /data/yg-ft
|
||
../../runtime/compute/logs -> /opt/yg-ft/logs/compute
|
||
../../runtime/compute/training-logs -> /opt/yg-ft/logs/training
|
||
```
|
||
|
||
## 应用与算力分离部署
|
||
|
||
应用服务器只需要主动访问算力服务器，不要求算力服务器回调应用服务器。
|
||
|
||
在 `docker/app/.env` 中配置：
|
||
|
||
```env
|
||
COMPUTE_API_BASE_URL=http://<compute-server-ip>:19100
|
||
FILE_GATEWAY_BASE_URL=http://<compute-server-ip>:19101
|
||
COMPUTE_SERVICE_TOKEN=change_me
|
||
COMPUTE_STATUS_SYNC_MODE=polling
|
||
COMPUTE_POLL_INTERVAL_SECONDS=10
|
||
COMPUTE_POLL_BATCH_SIZE=100
|
||
```
|
||
|
||
交互链路：
|
||
|
||
```text
|
||
Frontend
|
||
-> Backend API
|
||
-> Compute API
|
||
-> Compute Agent / LLaMA-Factory
|
||
-> 本地数据目录 / 模型目录 / 训练产物
|
||
<- Backend Worker 定时轮询 Compute API
|
||
```
|
||
|
||
## 多算力节点部署
|
||
|
||
多算力节点仍按“单机多 GPU 节点”部署。每台 GPU 服务器都独立部署一套 `docker/compute`：
|
||
|
||
```text
|
||
gpu-node-01: docker/compute + /data/yg-ft + 19100/19101
|
||
gpu-node-02: docker/compute + /data/yg-ft + 19100/19101
|
||
gpu-node-03: docker/compute + /data/yg-ft + 19100/19101
|
||
```
|
||
|
||
节点之间默认不互访。应用平台主动访问每个节点的 Compute API/File Gateway，并通过 `compute_nodes`、`resource_replicas`、`resource_sync_jobs` 统一调度和同步。
|
||
|
||
## 常用命令
|
||
|
||
重新构建应用镜像：
|
||
|
||
```bash
|
||
docker build -f docker/app/Dockerfile.backend -t yg-ft-backend-api:latest .
|
||
docker build -f docker/app/Dockerfile.frontend -t yg-ft-frontend-runtime:latest .
|
||
```
|
||
|
||
重新构建算力镜像：
|
||
|
||
```bash
|
||
docker build -f docker/compute/Dockerfile.compute -t yg-ft-compute-api:latest .
|
||
```
|
||
|
||
启动服务：
|
||
|
||
```bash
|
||
cd docker/app
|
||
docker compose up -d
|
||
|
||
cd ../compute
|
||
docker compose up -d
|
||
```
|
||
|
||
查看服务：
|
||
|
||
```bash
|
||
docker compose ps
|
||
docker compose logs -f
|
||
```
|