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

- 新增 platform API 端点和存储 - 新增 llama_factory 适配器 - 新增前端 compute、guide、system 等视图页面 - 新增 echarts 插件和 mock 数据 - 更新 Docker 配置、后端配置及文档 - 更新前端路由、API、侧边栏等组件 Co-Authored-By: Claude <noreply@anthropic.com>
2026-07-21 09:23:43 +08:00
parent 2c1e08a271
commit a67ca2c19c
43 changed files with 3632 additions and 814 deletions
--- a/docker/README.md
+++ b/docker/README.md
@@ -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 构建产物。