feat: 新增 MinIO 对象存储与算力节点缓存预下载

- 后端新增 storage 模块（minio_store），支持 MinIO 预签名 URL 上传与对象管理 - config 新增 MinIO 及存储等待相关配置项 - 算力节点新增 /compute/cache/prepare 缓存预下载接口（带校验和原子落盘） - 算力节点健康接口增加存储可用性探针 - SQL 迁移补充资源存储相关表结构 - Docker 新增 minio 服务与后端 minio 配置 - 补充 minio-compute-cache-plan 设计文档 Co-Authored-By: Claude <noreply@anthropic.com>
2026-08-11 16:25:18 +08:00
parent a12f80492d
commit b5d2cd7935
20 changed files with 830 additions and 11 deletions
--- a/docs/minio-compute-cache-plan.md
+++ b/docs/minio-compute-cache-plan.md
@@ -0,0 +1,287 @@
+# MinIO + Compute Agent 本地缓存方案与开发计划
+
+## 1. 方案结论
+
+本方案用 MinIO 作为模型、数据集、checkpoint、评测结果和训练产物的唯一正式存储，算力节点不挂载 NFS，也不要求安装 NFS 客户端。
+
+算力节点只保留任务运行所需的本地缓存：
+
+```text
+MinIO
+  -> Backend API 生成资源授权和版本信息
+  -> Compute Agent 按任务下载到本地缓存
+  -> LLaMA-Factory / 推理 / 合并任务使用本地路径
+  -> 任务产物上传回 MinIO
+  -> PostgreSQL 更新资源和任务状态
+```
+
+MinIO 是唯一正式数据源，本地缓存不是正式资源，节点失效或缓存被清理不会丢失模型和数据。
+
+## 2. 为什么适合当前项目
+
+当前项目的 Compute API 已经负责：
+
+- 训练、评测、推理和权重合并任务启动；
+- 本地文件网关；
+- GPU 和任务状态管理；
+- 训练日志和产物路径管理。
+
+因此不需要把 LLaMA-Factory 改成直接读取远程对象，只需要在 Compute Agent 启动任务前准备本地路径，继续把原来的 `model_name_or_path`、`dataset_dir`、`output_dir` 传给训练引擎。
+
+## 3. MinIO 部署
+
+MinIO 独立部署在 Linux 存储服务器或专用存储节点：
+
+```text
+9000  S3 API
+9001  MinIO Console（仅管理员网络开放）
+```
+
+建议创建 bucket：
+
+```text
+yg-ft-resources
+```
+
+对象前缀建议：
+
+```text
+models/{model_id}/versions/{version_id}/...
+datasets/{dataset_id}/versions/{version_id}/...
+outputs/{task_id}/...
+evaluations/{task_id}/...
+logs/{task_id}/...
+```
+
+MinIO 可以使用官方 Docker 镜像，不需要在 Linux 主机安装 MinIO 软件包。需要持久化挂载 MinIO 的数据目录。
+
+## 4. 是否需要额外安装包
+
+### MinIO 服务端
+
+不需要安装额外系统包，使用 Docker 镜像即可：
+
+```text
+minio/minio
+```
+
+### Backend API
+
+建议增加 Python SDK：
+
+```text
+minio>=7.2.0
+```
+
+Backend 用 SDK 生成预签名上传、下载 URL，并负责 bucket、对象元数据和权限控制。
+
+### Compute API / Compute Agent
+
+推荐第一版只使用现有 `httpx` 访问预签名 URL，不额外安装 MinIO SDK。流程是：
+
+```text
+Backend -> 返回预签名 URL
+Compute Agent -> httpx 下载/上传
+```
+
+这样算力节点不需要 MinIO 客户端、AWS CLI 或 NFS 客户端。
+
+如果后续需要 Agent 直接操作 bucket、列目录或分片上传，再增加：
+
+```text
+minio>=7.2.0
+```
+
+但不建议第一阶段让算力节点持有 MinIO 管理密钥。
+
+## 5. 权限模型
+
+继续沿用当前项目的：
+
+- `projects`；
+- `project_members`；
+- `acls`。
+
+MinIO 只负责对象访问凭证，Backend 负责业务授权：
+
+1. 用户请求模型或数据集；
+2. Backend 校验项目成员关系和资源 ACL；
+3. 校验通过后生成短时预签名 URL；
+4. Compute Agent 使用 URL 下载；
+5. URL 过期后自动失效。
+
+MinIO bucket 不直接向前端或普通算力节点开放长期 Access Key。
+
+## 6. 本地缓存目录
+
+Compute API 容器继续以 root 运行，本地缓存挂载到：
+
+```text
+/data/yg-ft/cache/models
+/data/yg-ft/cache/datasets
+/data/yg-ft/cache/adapters
+/data/yg-ft/cache/outputs
+```
+
+每个缓存资源必须包含：
+
+```text
+resource_id
+version_id
+sha256
+byte_size
+last_used_at
+status
+```
+
+缓存状态：
+
+- `missing`：本地不存在；
+- `downloading`：正在下载；
+- `ready`：校验成功；
+- `corrupted`：校验失败；
+- `evicting`：正在清理。
+
+任务只能使用 `ready` 状态的缓存。
+
+## 7. 任务流程
+
+### 7.1 训练
+
+```text
+校验项目/用户权限
+  -> 获取基座模型版本和数据集版本
+  -> 检查本地缓存
+  -> 缺失则下载并校验 SHA256
+  -> 启动 LLaMA-Factory
+  -> checkpoint 写入本地临时目录
+  -> 任务完成后上传 outputs 到 MinIO
+  -> MinIO 上传完成并校验后更新数据库
+```
+
+### 7.2 推理
+
+```text
+校验模型权限
+  -> 下载或复用本地模型缓存
+  -> 使用本地模型路径加载
+  -> 推理服务只绑定当前节点缓存
+```
+
+### 7.3 权重合并
+
+```text
+下载 base model 和 adapter/checkpoint
+  -> 在指定节点执行 CPU 合并
+  -> 上传 merged model 到 MinIO
+  -> 数据库记录新的模型版本
+```
+
+### 7.4 NFS 故障规则对应关系
+
+MinIO 不可达时，节点不再依赖本地残留文件直接启动新任务：
+
+- 已有完整缓存且资源版本仍有效：允许继续执行当前任务；
+- 新任务无法确认资源版本：等待 MinIO 恢复；
+- 等待超过配置窗口：任务失败；
+- 产物无法上传：任务不得标记为最终成功，进入 `storage_error`。
+
+如果严格执行“共享存储故障时节点不能正常工作”，则即使本地缓存完整，也应禁止启动新任务。建议当前项目采用这一严格规则。
+
+## 8. 数据库建议
+
+现有 `resource_replicas` 可扩展为缓存索引，建议增加：
+
+```text
+storage_backend       -- minio
+storage_bucket
+storage_object_key
+version_id
+cache_path
+cache_status
+last_used_at
+download_progress
+```
+
+`resource_sync_jobs` 可继续用于下载和上传任务，但建议增加方向字段：
+
+```text
+direction -- download / upload
+```
+
+模型、数据集、checkpoint 和评测结果均使用 `resource_id + version_id`，不再把节点本地路径作为唯一资源标识。
+
+## 9. 开发计划
+
+### 阶段一：MinIO 服务和配置
+
+- 增加 `docker/minio/docker-compose.yml`；
+- 配置 MinIO endpoint、bucket、Access Key 和 Secret Key；
+- 增加 Backend `minio` 依赖；
+- 增加 MinIO 健康检查；
+- 创建统一 bucket 和对象前缀规则。
+
+### 阶段二：Backend 资源服务
+
+- 实现对象上传、下载、删除和 HEAD 校验；
+- 生成短时预签名 URL；
+- 接入项目成员和 ACL 校验；
+- 建立资源版本、SHA256 和大小记录；
+- 上传成功后再更新数据库资源状态。
+
+### 阶段三：Compute Agent 缓存服务
+
+- 增加缓存目录管理器；
+- 实现预签名 URL 下载；
+- 支持临时文件下载和原子改名；
+- 实现 SHA256 校验、失败重试和断点续传；
+- 增加缓存状态查询和清理接口。
+
+### 阶段四：接入业务任务
+
+- 训练前准备基座模型和数据集；
+- 推理前准备模型和 adapter；
+- 权重合并前准备 base model 和 checkpoint；
+- 评测前准备模型和数据集；
+- 训练产物、合并模型和评测结果上传 MinIO；
+- MinIO 故障时统一等待并超时失败。
+
+### 阶段五：前端和管理员功能
+
+- 显示资源版本和对象存储状态；
+- 显示节点缓存状态；
+- 支持手动预热模型；
+- 支持缓存清理；
+- 显示下载、上传和校验失败原因。
+
+### 阶段六：测试和切换
+
+- 单节点下载和缓存复用测试；
+- 多节点同时下载同一模型测试；
+- MinIO 重启和网络中断测试；
+- SHA256 损坏文件测试；
+- 训练、推理、权重合并全流程测试；
+- 关闭旧的逐节点上传逻辑。
+
+## 10. 预计工作量
+
+```text
+MinIO 部署和配置             1～2 人日
+Backend 对象存储服务          4～7 人日
+Compute Agent 缓存            6～10 人日
+训练/推理/合并/评测接入        8～15 人日
+权限、数据库和前端             5～10 人日
+故障和回归测试                 5～8 人日
+总计                          29～52 人日
+```
+
+## 11. 推荐结论
+
+当前项目建议采用 MinIO + HTTP 预签名 URL + Compute Agent 本地缓存：
+
+- MinIO 服务端使用 Docker，不安装主机软件包；
+- Backend 增加 `minio` Python SDK；
+- Compute Agent 第一阶段继续使用现有 `httpx`，不增加 MinIO SDK；
+- 算力节点不安装 NFS 客户端；
+- Compute API 继续以 root 运行；
+- 训练、推理和权重合并继续使用本地路径，改造风险低于直接让训练框架读取对象存储。