feat: 添加平台管理、计算模块适配器及前端页面更新

- 新增 platform API 端点和存储
- 新增 llama_factory 适配器
- 新增前端 compute、guide、system 等视图页面
- 新增 echarts 插件和 mock 数据
- 更新 Docker 配置、后端配置及文档
- 更新前端路由、API、侧边栏等组件

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
wuyongtao
2026-07-21 09:23:43 +08:00
parent 2c1e08a271
commit a67ca2c19c
43 changed files with 3632 additions and 814 deletions

View File

@@ -1,60 +1,106 @@
# Docker 部署说明
文档对应 `docs/deployment-plan.md`按应用服务器和算力服务器拆分 Dockerfile 与 Docker Compose 文件。所有业务代码均通过 volume 外挂到容器内,镜像只包含运行时环境和第三方依赖
目录按应用服务器和算力服务器拆分 Dockerfile 与 Docker Compose 文件。Compose 文件不包含 `build:`,不会在 `docker compose up` 时自动构建业务镜像。所有业务镜像需要先通过手动 `docker build` 构建,再由 Compose 启动
## 目录
## 基础镜像
```text
docker/
app/
Dockerfile.backend
Dockerfile.frontend
docker-compose.yml
.env.example
compute/
Dockerfile.compute
docker-compose.yml
.env.example
| 镜像 | 用途 |
| --- | --- |
| `python:3.12-slim` | 应用后端基础镜像,后端运行环境要求 Python 3.12 及以上 |
| `nginx:1.27-alpine` | 前端静态资源与 `/api` 反向代理运行镜像 |
| `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
```
项目根目录不再保留 `Dockerfile``docker-compose.yml`,避免与应用服务器、算力服务器拆分部署入口混淆。
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` | 后续服务端口 | 当前预留,后续拆出文件网关服务时使用 |
对应配置文件:
- `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`
## 应用服务器部署
应用服务器包含前端 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 <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 --profile build run --rm frontend-builder
docker compose up -d --build
docker compose up -d
```
默认访问地址:
```text
http://<app-server-ip>:6801
http://<app-server-ip>:16801
```
应用侧代码外挂:
应用侧代码和数据外挂:
```text
../../backend -> /app
@@ -63,157 +109,128 @@ http://<app-server-ip>:6801
../../runtime/app/data -> /data/yg-ft
```
如果算力服务独立部署,需要在 `docker/app/.env` 中修改
如果使用企业统一 PostgreSQL/Redis修改 `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
DATABASE_URL=postgresql+asyncpg://<user>:<password>@<postgres-host>:15432/<db>
REDIS_URL=redis://<redis-host>:16379/0
USE_BUILTIN_POSTGRES=false
USE_BUILTIN_REDIS=false
```
状态同步采用应用侧定时轮询 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、启用状态、权重、标签和健康状态并通过“算力节点管理”页面动态启停节点避免每次调整地址都重启应用服务。
生产环境如完全使用外部基础设施,可以删除或注释 Compose 中的 `postgres``redis` 服务及 `backend-api.depends_on` 中对应依赖
## 算力服务器部署
算力服务器包含 Compute API、后续 Compute Agent、后续 File Gateway、GPU runtime、本地训练数据目录和宿主机挂载的 LLaMA-Factory。
算力服务器包含 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
- LLaMA-Factory 宿主机目录,默认 `/opt/LLaMA-Factory`
- 本地训练数据盘,默认 `/data/yg-ft`
- NVIDIA Driver
- NVIDIA Container Toolkit
- Docker Engine 和 Docker Compose Plugin
- 本地训练数据目录,默认 `/data/yg-ft`
算力服务器上的 LLaMA-Factory 使用宿主机挂载方式,不在当前 Compose 中重新构建 LLaMA-Factory 镜像
```env
LLAMA_FACTORY_HOME=/opt/LLaMA-Factory
LLAMA_FACTORY_HOST_PATH=/opt/LLaMA-Factory
```
启动:
首次部署
```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 --build
docker compose up -d
```
健康检查:
```text
GET http://<compute-server-ip>:9100/health
GET http://<compute-server-ip>:9100/api/v1/compute/health
GET http://<compute-server-ip>:19100/health
GET http://<compute-server-ip>:19100/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不要求访问应用服务器
## 应用与算力分离部署
应用服务器只需要主动访问算力服务器,不要求算力服务器回调应用服务器。
`docker/app/.env` 中配置:
```env
ENABLE_APP_CALLBACK=false
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 服务器都需要独立部署一套算力服务和宿主机挂载的 LLaMA-Factory
多算力节点仍按“单机多 GPU 节点”部署。每台 GPU 服务器都独立部署一套 `docker/compute`
```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
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` 表或算力节点管理页面维护:
节点之间默认不互访。应用平台主动访问每个节点的 Compute API/File Gateway并通过 `compute_nodes``resource_replicas``resource_sync_jobs` 统一调度和同步。
- `api_base_url`
- `file_gateway_url`
- `enabled`
- `scheduler_status`
- `scheduler_weight`
- `tags`
- `data_root`
- `model_root`
- `log_root`
## 常用命令
长期使用每台算力服务器本地磁盘时,需要由应用平台维护资源副本关系。调度前先检查目标节点是否已有数据集和模型副本;如果没有,应用平台通过目标节点 File Gateway 创建资源同步任务,同步完成后再提交训练任务。
重新构建应用镜像:
## 单机所有服务部署在算力服务器
```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 .
```
在同一台 GPU 服务器上分别启动两套 Compose
重新构建算力镜像
```bash
docker build -f docker/compute/Dockerfile.compute -t yg-ft-compute-api:latest .
```
启动服务:
```bash
cd docker/app
docker compose --profile build run --rm frontend-builder
docker compose up -d --build
docker compose up -d
cd ../compute
docker compose up -d --build
docker compose up -d
```
应用侧 `.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
```bash
docker compose ps
docker compose logs -f
```
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 构建产物。

View File

@@ -2,6 +2,15 @@ APP_ENV=prod
APP_NAME=YG Fine-Tune Platform API
API_PREFIX=/api
FRONTEND_IMAGE=yg-ft-frontend-runtime:latest
BACKEND_API_IMAGE=yg-ft-backend-api:latest
# Five-digit host ports exposed outside the application server.
FRONTEND_PORT=16801
BACKEND_API_PORT=17861
POSTGRES_PORT=15432
REDIS_PORT=16379
POSTGRES_DB=yg_ft
POSTGRES_USER=yg_ft
POSTGRES_PASSWORD=change_me
@@ -23,7 +32,7 @@ LOG_RETENTION_DAYS=10
API_PROXY_PASS=http://backend-api:8000
# Split deployment: set these to the compute server address, for example http://10.10.20.31:9100.
# Split deployment: set these to the compute server address, for example http://10.10.20.31:19100.
COMPUTE_API_BASE_URL=http://compute-api:9100
COMPUTE_SERVICE_TOKEN=change_me
FILE_GATEWAY_BASE_URL=http://compute-api:9101

View File

@@ -1,6 +1,4 @@
# syntax=docker/dockerfile:1
FROM python:3.11-slim
FROM python:3.12-slim
ENV PYTHONDONTWRITEBYTECODE=1 \
PYTHONUNBUFFERED=1 \

View File

@@ -1,4 +1,3 @@
# syntax=docker/dockerfile:1
FROM nginx:1.27-alpine

View File

@@ -1,25 +1,12 @@
services:
frontend-builder:
image: node:20-alpine
profiles:
- build
working_dir: /workspace
volumes:
- ../../frontend:/workspace
- frontend_node_modules:/workspace/node_modules
command: sh -c "npm ci && npm run build"
frontend:
build:
context: ../..
dockerfile: docker/app/Dockerfile.frontend
image: yg-ft-frontend-runtime:latest
image: ${FRONTEND_IMAGE:-yg-ft-frontend-runtime:latest}
container_name: yg-ft-frontend
depends_on:
backend-api:
condition: service_started
ports:
- "6801:80"
- "${FRONTEND_PORT:-16801}:80"
environment:
API_PROXY_PASS: ${API_PROXY_PASS:-http://backend-api:8000}
volumes:
@@ -30,10 +17,7 @@ services:
restart: unless-stopped
backend-api:
build:
context: ../..
dockerfile: docker/app/Dockerfile.backend
image: yg-ft-backend-api:latest
image: ${BACKEND_API_IMAGE:-yg-ft-backend-api:latest}
container_name: yg-ft-backend-api
depends_on:
postgres:
@@ -42,6 +26,8 @@ services:
condition: service_healthy
expose:
- "8000"
ports:
- "${BACKEND_API_PORT:-17861}:8000"
environment:
APP_ENV: ${APP_ENV:-prod}
APP_NAME: ${APP_NAME:-YG Fine-Tune Platform API}
@@ -88,6 +74,8 @@ services:
volumes:
- postgres_data:/var/lib/postgresql/data
- ../../docs/postgres-schema.sql:/docker-entrypoint-initdb.d/001-schema.sql:ro
ports:
- "${POSTGRES_PORT:-15432}:5432"
networks:
- yg-ft-app
healthcheck:
@@ -103,6 +91,8 @@ services:
command: ["redis-server", "--appendonly", "yes"]
volumes:
- redis_data:/data
ports:
- "${REDIS_PORT:-16379}:6379"
networks:
- yg-ft-app
healthcheck:
@@ -117,6 +107,5 @@ networks:
name: yg-ft-app
volumes:
frontend_node_modules:
postgres_data:
redis_data:

View File

@@ -1,14 +1,16 @@
COMPUTE_ENV=prod
COMPUTE_HOST_ID=gpu-node-01
COMPUTE_API_PORT=9100
FILE_GATEWAY_PORT=9101
# Five-digit host ports exposed outside the compute server.
COMPUTE_API_PORT=19100
FILE_GATEWAY_PORT=19101
COMPUTE_API_IMAGE=yg-ft-compute-api:latest
# The application server actively polls Compute API; compute server does not need reverse access.
COMPUTE_SERVICE_TOKEN=change_me
ENABLE_APP_CALLBACK=false
LLAMA_FACTORY_HOME=/opt/LLaMA-Factory
LLAMA_FACTORY_HOST_PATH=/opt/LLaMA-Factory
# LLaMA-Factory is provided by the official hiyouga/llamafactory base image.
LLAMA_FACTORY_HOME=/app/LLaMA-Factory
YG_FT_DATA_ROOT=/data/yg-ft
YG_FT_DATA_ROOT_HOST=/data/yg-ft

View File

@@ -1,6 +1,5 @@
# syntax=docker/dockerfile:1
FROM nvidia/cuda:12.4.1-cudnn-runtime-ubuntu22.04
FROM hiyouga/llamafactory:latest
ENV DEBIAN_FRONTEND=noninteractive \
PYTHONDONTWRITEBYTECODE=1 \
@@ -10,25 +9,16 @@ ENV DEBIAN_FRONTEND=noninteractive \
WORKDIR /app
RUN apt-get update \
&& apt-get install -y --no-install-recommends \
python3 \
python3-pip \
python3-venv \
git \
curl \
ca-certificates \
tini \
&& ln -sf /usr/bin/python3 /usr/local/bin/python \
&& ln -sf /usr/bin/pip3 /usr/local/bin/pip \
&& apt-get install -y --no-install-recommends tini \
&& rm -rf /var/lib/apt/lists/*
COPY compute/requirements.txt /tmp/requirements.txt
RUN pip install --upgrade pip \
&& pip install -r /tmp/requirements.txt \
RUN pip install --upgrade pip -i https://pypi.tuna.tsinghua.edu.cn/simple \
&& pip install -r /tmp/requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple \
&& rm -f /tmp/requirements.txt
RUN mkdir -p /opt/yg-ft/logs/compute /opt/yg-ft/logs/training /data/yg-ft /opt/LLaMA-Factory \
&& chmod -R 0775 /opt/yg-ft /data/yg-ft /opt/LLaMA-Factory
RUN mkdir -p /opt/yg-ft/logs/compute /opt/yg-ft/logs/training /data/yg-ft /app/LLaMA-Factory \
&& chmod -R 0775 /opt/yg-ft /data/yg-ft /app/LLaMA-Factory
ENTRYPOINT ["/usr/bin/tini", "--"]

View File

@@ -1,19 +1,16 @@
services:
compute-api:
build:
context: ../..
dockerfile: docker/compute/Dockerfile.compute
image: yg-ft-compute-api:latest
image: ${COMPUTE_API_IMAGE:-yg-ft-compute-api:latest}
container_name: yg-ft-compute-api
gpus: all
ports:
- "${COMPUTE_API_PORT:-9100}:9100"
- "${COMPUTE_API_PORT:-19100}:9100"
environment:
COMPUTE_ENV: ${COMPUTE_ENV:-prod}
COMPUTE_HOST_ID: ${COMPUTE_HOST_ID:-gpu-node-01}
COMPUTE_SERVICE_TOKEN: ${COMPUTE_SERVICE_TOKEN:-change_me}
ENABLE_APP_CALLBACK: ${ENABLE_APP_CALLBACK:-false}
LLAMA_FACTORY_HOME: ${LLAMA_FACTORY_HOME:-/opt/LLaMA-Factory}
LLAMA_FACTORY_HOME: ${LLAMA_FACTORY_HOME:-/app/LLaMA-Factory}
YG_FT_DATA_ROOT: ${YG_FT_DATA_ROOT:-/data/yg-ft}
LOG_DIR: ${LOG_DIR:-/opt/yg-ft/logs/compute}
CUDA_VISIBLE_DEVICES: ${CUDA_VISIBLE_DEVICES:-all}
@@ -22,7 +19,6 @@ services:
PYTHONPATH: /app
volumes:
- ../../compute:/app/compute:ro
- ${LLAMA_FACTORY_HOST_PATH:-/opt/LLaMA-Factory}:${LLAMA_FACTORY_HOME:-/opt/LLaMA-Factory}
- ${YG_FT_DATA_ROOT_HOST:-/data/yg-ft}:${YG_FT_DATA_ROOT:-/data/yg-ft}
- ../../runtime/compute/logs:/opt/yg-ft/logs/compute
- ../../runtime/compute/training-logs:/opt/yg-ft/logs/training