2c1e08a271
- 将 Dockerfile 和 docker-compose.yml 迁移至 docker/ 目录下统一管理 - 新增 compute 计算模块（API 入口、依赖配置） - 新增 docker/app 和 docker/compute 部署配置 - 新增 demo-development-plan.md 演示开发计划文档 - 更新后端 API 设计、部署计划、架构需求等文档 - 更新 postgres 数据库 schema Co-Authored-By: Claude <noreply@anthropic.com>
220 lines
7.4 KiB
Markdown
220 lines
7.4 KiB
Markdown
# Docker 部署说明
|
||
|
||
本文档对应 `docs/deployment-plan.md`，按应用服务器和算力服务器拆分 Dockerfile 与 Docker Compose 文件。所有业务代码均通过 volume 外挂到容器内，镜像只包含运行时环境和第三方依赖。
|
||
|
||
## 目录
|
||
|
||
```text
|
||
docker/
|
||
app/
|
||
Dockerfile.backend
|
||
Dockerfile.frontend
|
||
docker-compose.yml
|
||
.env.example
|
||
compute/
|
||
Dockerfile.compute
|
||
docker-compose.yml
|
||
.env.example
|
||
```
|
||
|
||
项目根目录不再保留 `Dockerfile` 和 `docker-compose.yml`，避免与应用服务器、算力服务器拆分部署入口混淆。
|
||
|
||
## 应用服务器部署
|
||
|
||
应用服务器包含前端 Nginx、Backend API、PostgreSQL、Redis。
|
||
|
||
开发阶段默认由项目自带 PostgreSQL/Redis：
|
||
|
||
```env
|
||
USE_BUILTIN_POSTGRES=true
|
||
USE_BUILTIN_REDIS=true
|
||
DATABASE_URL=postgresql+asyncpg://yg_ft:change_me@postgres:5432/yg_ft
|
||
REDIS_URL=redis://redis:6379/0
|
||
```
|
||
|
||
后续切换企业统一基础设施时，保留应用配置方式，只需要：
|
||
|
||
- 修改 `DATABASE_URL` 指向企业 PostgreSQL。
|
||
- 修改 `REDIS_URL` 指向企业 Redis。
|
||
- 从 Compose 中移除或禁用 `postgres`、`redis` 服务。
|
||
- 保留 `docs/postgres-schema.sql` 作为数据库初始化或迁移参考。
|
||
|
||
首次部署前先构建前端产物：
|
||
|
||
```bash
|
||
cd docker/app
|
||
cp .env.example .env
|
||
docker compose --profile build run --rm frontend-builder
|
||
docker compose up -d --build
|
||
```
|
||
|
||
默认访问地址：
|
||
|
||
```text
|
||
http://<app-server-ip>:6801
|
||
```
|
||
|
||
应用侧代码外挂：
|
||
|
||
```text
|
||
../../backend -> /app
|
||
../../frontend/dist -> /usr/share/nginx/html
|
||
../../runtime/app/logs/backend -> /opt/yg-ft/logs/backend
|
||
../../runtime/app/data -> /data/yg-ft
|
||
```
|
||
|
||
如果算力服务独立部署，需要在 `docker/app/.env` 中修改：
|
||
|
||
```env
|
||
COMPUTE_API_BASE_URL=http://<compute-server-ip>:9100
|
||
FILE_GATEWAY_BASE_URL=http://<compute-server-ip>:9101
|
||
COMPUTE_SERVICE_TOKEN=change_me
|
||
COMPUTE_STATUS_SYNC_MODE=polling
|
||
COMPUTE_POLL_INTERVAL_SECONDS=10
|
||
COMPUTE_POLL_BATCH_SIZE=100
|
||
```
|
||
|
||
状态同步采用应用侧定时轮询 Compute API 为主，避免算力服务器需要访问应用服务器，从而减少双向网络策略开通。
|
||
|
||
## 应用服务与算力服务交互
|
||
|
||
应用服务与算力服务之间只要求应用服务器主动访问算力服务器：
|
||
|
||
```text
|
||
Frontend
|
||
-> Backend API
|
||
-> Compute API
|
||
-> Compute Agent / LLaMA-Factory
|
||
-> 本地数据盘 / 模型目录 / 训练产物
|
||
<- Backend Worker 定时轮询 Compute API
|
||
```
|
||
|
||
默认交互流程：
|
||
|
||
- `Backend API` 读取 `COMPUTE_API_BASE_URL`，向 `Compute API` 提交训练、评测、合并、导出等任务。
|
||
- `Compute API` 在算力服务器上调度 `Compute Agent`。
|
||
- `Compute Agent` 通过宿主机挂载目录调用 LLaMA-Factory，并读写 `/data/yg-ft` 下的数据集、模型和训练产物。
|
||
- `Backend Worker` 按 `COMPUTE_POLL_INTERVAL_SECONDS` 定时轮询 Compute API，同步任务状态、训练指标、日志摘要和产物索引。
|
||
- 前端只访问应用服务；文件下载和产物访问由应用服务完成权限校验后，再通过 `FILE_GATEWAY_BASE_URL` 获取受控资源。
|
||
|
||
当前支持通过环境变量动态配置算力服务地址：
|
||
|
||
```env
|
||
COMPUTE_API_BASE_URL=http://<compute-server-ip>:9100
|
||
FILE_GATEWAY_BASE_URL=http://<compute-server-ip>:9101
|
||
COMPUTE_SERVICE_TOKEN=change_me
|
||
COMPUTE_STATUS_SYNC_MODE=polling
|
||
COMPUTE_POLL_INTERVAL_SECONDS=10
|
||
COMPUTE_POLL_BATCH_SIZE=100
|
||
```
|
||
|
||
后续多算力节点阶段建议升级为数据库配置：在 `compute_nodes` 表中维护节点地址、服务 token、启用状态、权重、标签和健康状态，并通过“算力节点管理”页面动态启停节点，避免每次调整地址都重启应用服务。
|
||
|
||
## 算力服务器部署
|
||
|
||
算力服务器包含 Compute API、后续 Compute Agent、后续 File Gateway、GPU runtime、本地训练数据目录和宿主机挂载的 LLaMA-Factory。
|
||
|
||
部署前需要安装：
|
||
|
||
- NVIDIA Driver。
|
||
- NVIDIA Container Toolkit。
|
||
- Docker Engine 和 Docker Compose Plugin。
|
||
- LLaMA-Factory 宿主机目录，默认 `/opt/LLaMA-Factory`。
|
||
- 本地训练数据盘，默认 `/data/yg-ft`。
|
||
|
||
算力服务器上的 LLaMA-Factory 使用宿主机挂载方式，不在当前 Compose 中重新构建 LLaMA-Factory 镜像：
|
||
|
||
```env
|
||
LLAMA_FACTORY_HOME=/opt/LLaMA-Factory
|
||
LLAMA_FACTORY_HOST_PATH=/opt/LLaMA-Factory
|
||
```
|
||
|
||
启动：
|
||
|
||
```bash
|
||
cd docker/compute
|
||
cp .env.example .env
|
||
docker compose up -d --build
|
||
```
|
||
|
||
健康检查：
|
||
|
||
```text
|
||
GET http://<compute-server-ip>:9100/health
|
||
GET http://<compute-server-ip>:9100/api/v1/compute/health
|
||
```
|
||
|
||
算力侧代码和数据外挂：
|
||
|
||
```text
|
||
../../compute -> /app/compute
|
||
${LLAMA_FACTORY_HOST_PATH} -> /opt/LLaMA-Factory
|
||
${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
|
||
```
|
||
|
||
算力侧只需要允许应用服务器访问 Compute API/File Gateway，不要求访问应用服务器：
|
||
|
||
```env
|
||
ENABLE_APP_CALLBACK=false
|
||
COMPUTE_SERVICE_TOKEN=change_me
|
||
```
|
||
|
||
## 多算力节点部署
|
||
|
||
多算力节点仍按“单机多 GPU 节点”部署。每台 GPU 服务器都需要独立部署一套算力服务和宿主机挂载的 LLaMA-Factory：
|
||
|
||
```text
|
||
gpu-node-01: docker/compute + /opt/LLaMA-Factory + /data/yg-ft
|
||
gpu-node-02: docker/compute + /opt/LLaMA-Factory + /data/yg-ft
|
||
gpu-node-03: docker/compute + /opt/LLaMA-Factory + /data/yg-ft
|
||
```
|
||
|
||
节点之间默认不互相访问。应用服务器主动访问每个节点的 Compute API/File Gateway，并通过 `compute_nodes` 表或算力节点管理页面维护：
|
||
|
||
- `api_base_url`
|
||
- `file_gateway_url`
|
||
- `enabled`
|
||
- `scheduler_status`
|
||
- `scheduler_weight`
|
||
- `tags`
|
||
- `data_root`
|
||
- `model_root`
|
||
- `log_root`
|
||
|
||
长期使用每台算力服务器本地磁盘时，需要由应用平台维护资源副本关系。调度前先检查目标节点是否已有数据集和模型副本；如果没有，应用平台通过目标节点 File Gateway 创建资源同步任务，同步完成后再提交训练任务。
|
||
|
||
## 单机所有服务部署在算力服务器
|
||
|
||
在同一台 GPU 服务器上分别启动两套 Compose：
|
||
|
||
```bash
|
||
cd docker/app
|
||
docker compose --profile build run --rm frontend-builder
|
||
docker compose up -d --build
|
||
|
||
cd ../compute
|
||
docker compose up -d --build
|
||
```
|
||
|
||
应用侧 `.env` 中可使用：
|
||
|
||
```env
|
||
COMPUTE_API_BASE_URL=http://host.docker.internal:9100
|
||
FILE_GATEWAY_BASE_URL=http://host.docker.internal:9101
|
||
COMPUTE_STATUS_SYNC_MODE=polling
|
||
```
|
||
|
||
Linux 环境如需容器访问宿主机地址，可在应用侧 Compose 中按需增加 `extra_hosts: ["host.docker.internal:host-gateway"]`，或直接配置算力服务器内网 IP。
|
||
|
||
## 生产注意事项
|
||
|
||
- 当前 Compose 是工程部署骨架，后续 Backend Worker、Compute Agent、File Gateway 有可运行入口后，再拆分为独立服务。
|
||
- PostgreSQL 和 Redis 开发阶段采用项目自带部署，生产阶段保留切换企业统一基础设施的配置入口。
|
||
- 生产环境请把 `change_me` 替换为强密码或密钥管理系统注入。
|
||
- 当前镜像默认优先保证宿主机外挂日志和数据目录可写；生产环境如需非 root 运行，需要统一宿主机目录 UID/GID 后在 Compose 中增加 `user` 配置。
|
||
- Compute API 不应暴露公网，建议通过防火墙限制只允许应用服务器访问。
|
||
- GPU 容器需要 NVIDIA Container Toolkit，否则 `gpus: all` 无法生效。
|
||
- 前端 Nginx 默认挂载 `frontend/dist`，发布前需要先运行 `frontend-builder` 或由 CI 构建产物。
|