YG-Soft/YG_FT
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 精简 README 与 docker 部署说明，归档 20260812 文档快照

Browse Source 
- 重写根 README 为架构、端口、启动速览，替代原详细开发指南
- 重写 docker/README.md 聚焦跨服务器部署边界与数据安全
- 新增平台测试用例文档，归档 docs/20260812 快照副本

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
wuyongtao
2026-08-12 15:38:34 +08:00
parent 5ecca9f0bc
commit de9c8e4ffe
6 changed files with 388 additions and 548 deletions
Download Patch File Download Diff File Expand all files Collapse all files

59
docs/20260812/README.md Normal file
View File

@@ -0,0 +1,59 @@
# YG_FT 模型微调平台
YG_FT 是面向多用户、多租户和多算力节点的模型训练与推理平台，提供数据集、模型、训练、权重合并、推理、评测、算力节点、项目隔离、权限和审计能力。
## 架构
```text
浏览器 -> Frontend Nginx:16801 -> Backend API:17861
|-> PostgreSQL（元数据、权限、审计、任务状态）
|-> Redis（缓存及任务辅助状态）
|-> MinIO:19000（模型和数据唯一对象源）
|-> Compute API:19100
|-> Compute Agent/GPU/LLaMA-Factory
`-> File Gateway:19101
```
Backend、MinIO 和 Compute 节点可以部署在不同服务器，不依赖跨服务器 Docker 网络，通过 IP、DNS 或负载均衡地址通信。Compute 节点只保存按需准备的本地缓存，MinIO 是模型、数据集、权重、评测报告和训练产物的唯一数据源。
## 目录
| 目录 | 作用 |
| --- | --- |
| `frontend/` | Vue 3、TypeScript、Element Plus 控制台 |
| `backend/app/api/v1/` | 平台 REST API |
| `backend/app/core/` | 配置、认证、权限和日志 |
| `backend/app/db/` | PostgreSQL 访问和初始化 SQL |
| `backend/app/modules/` | 系统、资源、审批、数据处理和存储模块 |
| `backend/app/workers/` | 节点轮询、任务对账和资源同步 |
| `compute/` | Compute API、Agent、GPU 和训练引擎 |
| `docker/` | 应用、MinIO、算力服务部署文件 |
| `docs/` | 架构、权限、部署和测试文档 |
## 端口
| 服务 | 主机端口 | 容器端口 |
| --- | ---: | ---: |
| Frontend | 16801 | 80 |
| Backend API | 17861 | 8000 |
| Redis | 16379 | 6379 |
| MinIO API/Console | 19000/19001 | 9000/9001 |
| Compute API/File Gateway | 19100/19101 | 9100 |
## 启动
```bash
cd frontend && npm ci && npm run build && cd ..
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 .
docker build -f docker/compute/Dockerfile.compute -t yg-ft-compute-api:latest .
cd docker/minio && docker compose up -d
cd ../app && docker compose up -d
cd ../compute && docker compose up -d
```
## 权限与性能
系统使用角色权限、资源 ACL、用户/项目/租户归属联合校验；删除为软删除，关键操作写入审计。模型合并前准备 base model 和 adapter，结果归档 MinIO；推理前按选择节点准备缓存。远程 PostgreSQL 延迟会影响全量列表和看板，页面慢时应检查浏览器 Network、Nginx、Backend 日志、连接池和节点可达性。
详细部署见 `docker/README.md`，测试见 `测试用例.md`，本次快照见 `docs/20260812/`。

58
docs/20260812/docker-readme.md Normal file
View File

@@ -0,0 +1,58 @@
# Docker 部署说明
## 部署边界
生产规划分为应用服务器、存储服务器和算力服务器。应用服务器运行 Frontend Nginx、Backend API、Redis；存储服务器运行 MinIO；算力服务器运行 Compute API、Compute Agent、GPU 和训练引擎。三类服务器不共享 Docker 网络，通过可路由地址通信。
当前 WSL 联调地址为 `172.25.179.69`，拆分部署时必须替换为真实服务器地址。
## 配置
应用服务器 `docker/app/.env`：
```env
MINIO_ENABLED=true
MINIO_ENDPOINT=http://172.25.179.69:19000
COMPUTE_API_BASE_URL=http://172.25.179.69:19100
FILE_GATEWAY_BASE_URL=http://172.25.179.69:19101
COMPUTE_STATUS_SYNC_MODE=polling
COMPUTE_POLL_INTERVAL_SECONDS=3
```
MinIO 不需要额外安装 Python 包；Backend 的 MinIO 兼容访问依赖随 `backend/requirements.txt` 安装。生产环境应使用固定 DNS/IP、内网访问和防火墙白名单。
## 构建和启动
```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 .
docker build -f docker/compute/Dockerfile.compute -t yg-ft-compute-api:latest .
cd docker/minio && docker compose up -d
cd ../app && docker compose up -d
cd ../compute && docker compose up -d
```
验证命令：`docker compose ps`、`curl http://<app-server>:17861/modelTF/health`、`curl http://<compute-server>:19100/modelTF/health`、`curl http://<minio-server>:19000/minio/health/live`。
## 端口
| 服务 | 主机端口 | 容器端口 |
| --- | ---: | ---: |
| Frontend | 16801 | 80 |
| Backend API | 17861 | 8000 |
| Redis | 16379 | 6379 |
| MinIO API/Console | 19000/19001 | 9000/9001 |
| Compute API/File Gateway | 19100/19101 | 9100 |
## 数据和安全
算力主机应持久化 `/data/yg-ft/models`、`datasets`、`trained_models`、`outputs`、`cache` 以及训练日志目录。上述目录是 Compute Agent 的本地缓存和运行目录，权威对象必须归档 MinIO。
- Compute API 和 File Gateway 开启 token 认证。
- MinIO 不直接暴露公网，使用内网或安全组限制访问。
- 不在镜像和 Git 中提交数据库、Redis、MinIO 密码或服务 token。
- 当前 Compute API 默认 root 仅适用于开发阶段，生产环境需评估非 root 和 GPU/挂载目录权限改造。
## 拆分验证
从 Backend 容器验证 MinIO 和每个 Compute API 的 health；上传数据集、训练、权重合并、推理和节点断网重试均需完成一次联调。

99
docs/20260812/测试用例.md Normal file
View File

@@ -0,0 +1,99 @@
# YG_FT 平台测试用例
## 测试范围
覆盖部署、登录会话、权限、租户与项目隔离、算力节点、GPU 分配、数据集、MinIO、训练、权重合并、模型推理、模型评测、审计、日志、异常重试和性能。
测试地址：前端 `http://localhost:16801`，Backend `http://localhost:17861/modelTF`，Compute `http://localhost:19100/modelTF`，File Gateway `http://localhost:19101/modelTF`，MinIO `http://localhost:19000`。
## 前置条件
1. 前端已执行 `npm run build`。
2. Backend、Frontend、Redis、MinIO、Compute 容器均为 healthy。
3. PostgreSQL 表结构与 `backend/app/db/sql/000_full_init.sql` 一致。
4. 准备管理员、普通用户、不同项目和租户测试账号。
5. 准备 JSON、JSONL、空文件和非法格式数据集。
6. 准备 base model、adapter 和可推理模型。
## 用例
| 编号 | 场景 | 操作 | 预期 |
| --- | --- | --- | --- |
| DEP-001 | 容器启动 | 执行各 compose 的 `up -d` | 所有服务启动并 healthy |
| DEP-002 | Backend 健康 | 访问 `/health` | HTTP 200，依赖状态正常 |
| DEP-003 | Compute 健康 | 访问 Compute health | 返回节点服务正常 |
| DEP-004 | MinIO 健康 | 访问 `/minio/health/live` | 返回存活状态 |
| DEP-005 | 前端入口 | 打开 `:16801` | 无白屏、无外部 CDN 请求 |
| DEP-006 | 跨服务器 | 配置远程 MinIO/Compute 地址 | Backend 可访问远程服务 |
| AUTH-001 | 正常登录 | 输入正确账号密码 | 登录成功并保存 token |
| AUTH-002 | 错误密码 | 连续输入错误密码 | 返回 401，达到阈值后限流 |
| AUTH-003 | 过期会话 | 使用过期 token 请求接口 | 返回 401 并回登录页 |
| AUTH-004 | 退出登录 | 退出后再次请求业务接口 | token 失效 |
| AUTH-005 | 管理员 | 访问用户、节点、审计功能 | 可执行授权操作 |
| AUTH-006 | 普通用户 | 访问管理员功能 | 按钮隐藏，后端返回 403 |
| AUTH-007 | 项目隔离 | 用户 A 访问用户 B 项目 | 列表不显示，接口拒绝 |
| AUTH-008 | 租户隔离 | 租户 A 请求租户 B 数据 | 不返回跨租户数据 |
| AUTH-009 | ACL | 授予模型 read/execute | read 只能看，execute 才能运行 |
| AUTH-010 | 软删除 | 删除模型或数据集 | 列表隐藏，保留删除审计字段 |
| NODE-001 | 新增节点 | 填写 API、文件网关和标签 | 节点保存并显示 |
| NODE-002 | 节点测试 | 点击测试 | health/GPU 信息同步 |
| NODE-003 | 不可达节点 | 使用错误地址测试 | 快速失败并显示原因 |
| NODE-004 | 删除节点 | 点击删除 | 节点从可用列表消失 |
| NODE-005 | 多 GPU | 节点有多张卡 | 显示编号、显存和状态 |
| NODE-006 | 指定 GPU | 训练选择 GPU 0 | 只占用 GPU 0 |
| NODE-007 | GPU 冲突 | 两任务申请同卡 | 后者排队或拒绝，不抢占 |
| NODE-008 | 剩余 GPU | 节点有空闲卡 | 其他任务可继续选择该节点 |
| NODE-009 | 释放 GPU | 停止训练/卸载推理 | GPU 恢复可用 |
| DATA-001 | JSON 统计 | 上传 3 条 JSON 数据 | 列表和详情均为 3 条 |
| DATA-002 | JSONL 统计 | 上传 3 行 JSONL | 列表和详情均为 3 条 |
| DATA-003 | 非法文件 | 上传空或错误格式 | 返回明确错误 |
| DATA-004 | MinIO 归档 | 上传数据集 | 产生对象和 checksum |
| DATA-005 | 节点同步 | 选择算力节点上传 | 文件进入目标节点缓存 |
| DATA-006 | 同步断网 | 同步时阻断节点 | 进入重试或失败，不无限等待 |
| DATA-007 | 数据权限 | 用户查看数据集 | 只显示有权限的数据 |
| TRAIN-001 | 创建训练 | 选择项目、数据集、节点和 GPU | 任务关联完整 |
| TRAIN-002 | 启动训练 | 启动任务 | 进入 queued/running |
| TRAIN-003 | 日志轮询 | 打开训练日志 | 约 3 秒更新，不刷屏 |
| TRAIN-004 | 训练曲线 | 产生 loss/metric | 页面显示曲线 |
| TRAIN-005 | 停止训练 | 点击停止 | 进程停止且资源释放 |
| TRAIN-006 | 训练失败 | 模拟引擎失败 | 显示原因和日志 |
| MERGE-001 | 自动准备 | 执行权重合并 | 自动准备 base model/adapter |
| MERGE-002 | 节点一致 | 权重在训练节点 | 合并请求发往训练节点 |
| MERGE-003 | 合并归档 | 合并成功 | 结果上传 MinIO 并登记 |
| MERGE-004 | 合并权限 | 无 execute 用户操作 | 返回 403 |
| INF-001 | 列表加载 | 点击模型推理 | 列表快速显示，不长时间等待 |
| INF-002 | 指定节点 | 多节点时选择节点 B | 模型只在 B 加载 |
| INF-003 | 训练节点优先 | 未重新指定节点 | 优先使用训练节点 |
| INF-004 | 推理缓存 | 启动未缓存模型 | 从 MinIO 下载到目标节点 |
| INF-005 | 加载超时 | 模拟加载超过 15 分钟 | 失败并显示原因 |
| INF-006 | 对话推理 | 发送消息 | 返回推理结果 |
| INF-007 | 释放推理 | 点击释放 | 卸载模型并释放 GPU |
| INF-008 | 删除推理 | 删除任务记录 | 记录删除成功并释放资源 |
| EVAL-001 | 创建评测 | 选择模型、数据集、指标 | 任务创建成功 |
| EVAL-002 | 数据集权限 | 选择无权数据集 | 不出现在选择列表 |
| EVAL-003 | 指标保存 | 选择具体指标 | 结果不错误显示 custom |
| EVAL-004 | 评测报告 | 等待任务完成 | 返回非空报告和明细 |
| EVAL-005 | 页面轮询 | 打开评测页面 | 不刷屏，loading 可结束 |
| OPS-001 | 审计 | 登录、创建、删除、执行资源 | 记录 actor/action/resource/time |
| OPS-002 | 轮询日志 | 观察 Backend 日志 | 成功轮询不高频输出 INFO |
| OPS-003 | 错误日志 | 模拟依赖异常 | 保留 WARNING/ERROR 和 request_id |
| OPS-004 | 推理接口耗时 | 请求 `/model-compare` | 正常环境目标小于 1 秒 |
| OPS-005 | 看板耗时 | 请求 `/dashboard/stats` | 有短缓存且不无限等待 |
| OPS-006 | 并发访问 | 10 用户同时打开列表 | 无连接池耗尽和 5xx |
| OPS-007 | 数据库断开 | 临时阻断 PostgreSQL | 页面明确显示依赖异常 |
## 回归命令
```bash
cd frontend
npm run build
cd ..
python -m compileall backend/app compute
git diff --check
docker compose -f docker/app/docker-compose.yml ps
docker compose -f docker/compute/docker-compose.yml ps
curl http://localhost:17861/modelTF/health
curl http://localhost:19100/modelTF/health
```
失败用例必须附接口响应、容器日志、request_id 和复现步骤。