# MVP v3.0 详细设计方案（基于 v2.5） ## 0. 结论摘要（v3.0 要交付什么） v3.0 = v2.5 + **WebUI** + **用户数据上传/下载（SFTPGo）**，形成第一个可对外发布的版本： - 用户可以通过 **SFTP** 上传数据/模型/代码（至少数据），落到 GPFS（容器内 `/private`）并对 Ray worker 可见。 - 用户可以通过 API/WebUI 提交训练任务，任务读取自己上传的数据。 - 用户可以下载训练产物（checkpoints/logs 等），最小闭环跑通。 ## 1. 范围与原则 ### 1.1 继承 v2.5 的前提（不回退） - **Stateless Ray Node Pool**：head 写 `head.json`，worker watchdog 自动 join/自愈。 - **User Management**：token 鉴权、任务可见性隔离（跨用户 404 不泄漏）。 - **作业产物隔离**：Ray job 目录落到 `/private/users//jobs//...`。 - **API server 短期运行方式**：代码在宿主机，挂载到 head 容器，在 head 容器内启动（保持现状）。 ### 1.2 v3.0 新增目标 1) **Data Management（SFTPGo）** - 提供用户上传/下载入口（SFTP 为主）。 - 数据落到 GPFS（dev 环境 NFS/GPFS，生产环境 GPFS），训练 job 在 worker 容器内可直接读取。 2) **WebUI** - 用户可视化创建任务、查看队列/状态/日志、查看“数据路径约定”和自己的 SFTP 信息。 - 目标是 “可用而非豪华”，支持核心工作流。 3) **权限闭环** - 用户只能使用自己目录下的数据（`/private/users//...`）或公共目录（`/private/common/...`）。 - 防止用户提交任务读取其他用户的文件路径。 ### 1.3 v3.0 明确不做（留给 v3.5） - 不做 “自定义 reward function / 自定义 verl 代码 / 多版本 verl 共存”（路线图 v3.5）。 - 不做复杂 Serving/训推一体（路线图 v3.5）。 - 不做 IB 网络/拓扑优化（路线图 v3.5）。 - 不做系统级可观测性平台（路线图 v4.0）。 ## 2. 架构概览 参考 `roadmap_v3.0.png`，v3.0 的控制面与数据面： ### 2.1 控制面（Control Plane） - **API Server（FastAPI）** - v2.5 的任务队列/调度/重试 + 用户管理能力继续复用 - 新增：数据管理能力（与 SFTPGo 对接） + WebUI - **WebUI** - 通过 API 使用 token 登录 - 提供任务/日志/数据入口（不直接运行训练） - **Ray Head（状态节点）** - 仍在 head 容器内（或单独节点） - job server/dashbaord 提供 job submit/status/logs 能力 ### 2.2 数据面（Data Plane） - **GPFS（容器内挂载 `/private`）** - 存放 common 与 users 两大根目录 - **Ray Worker Node（无状态）** - 自动连接 head，执行训练 - 读取 `/private/users//...` 的数据 ### 2.3 新增组件：SFTPGo（Data Management） - 作为独立服务运行（容器化优先），后端存储使用 **filesystem**（GPFS 挂载路径）。 - 用户的 home directory 指向 `/private/users/`（或其子目录）。 ## 3. 存储与目录规范（v3.0 统一约定） ### 3.1 目录层级 统一以容器内 `/private` 作为根路径（dev/prod 对齐）： - `/private/common/`：公共资源 - `hf/`：HF cache - `datasets/`：公共数据集（可选） - `code/`：公共代码（例如公共 verl repo snapshot） - `db/`：SQLite（队列、用户、token） - `logs/`：API/supervisor/watchdog 日志 - `/private/users//`：用户空间（v3.0 重点） - `datasets/`：用户上传的数据集（推荐） - `models/`：用户保存/上传的本地模型（允许；也用于“把 job 产物移动到长期保存目录”） - `code/`：用户上传的代码（v3.0 **不支持执行**；仅存放/下载） - `jobs/`：训练任务产物（已在 v2.5 落地） - `tmp/`：临时文件（可选） ### 3.2 Jobs Retention（两段式：3 天移入回收站，7 天后永久删除） v3.0 引入 **jobs 目录两段式保留策略**： - 第 1 阶段（soft-delete）：job 结束后 **3 天**，将该 job 目录从 `jobs/` **移动到用户回收目录**； - 第 2 阶段（hard-delete）：进入回收目录后再过 **7 天**，从回收目录 **永久删除**。 目录约定（建议）： - jobs 根目录：`/private/users//jobs//...` - 回收目录：`/private/users//trash/jobs//...` 计时规则： - 以 job 进入 terminal 状态（SUCCEEDED/FAILED/CANCELED）的结束时间为起点； - “3 天”用于从 `jobs/` 移入 `trash/jobs/`； - “7 天”用于从 `trash/jobs/` 永久删除（即总共最多 10 天窗口）。 用户保留关键产物的方式（无需 keep 标记）： - 在 “3 天窗口”内把需要长期保存的文件从 `jobs//...` **移动/复制**到 `models/`（例如权重）或 `datasets/`（例如评估输出数据）； - 即便已被移动到回收目录，用户仍可在 “7 天窗口”内从 `trash/jobs//...` 把需要的文件移到 `models/` / `datasets/`； - janitor 只管理 `jobs/` 与 `trash/jobs/`，不会触碰 `models/` 与 `datasets/`。 这里的“清理程序”我们称为 **janitor**： - 定义：一个后台清理执行器，按固定周期扫描“已结束且已过期”的 job 目录并删除 - v3.0 目标：实现“3 天移入回收站 + 7 天后删除”这一条产品规则（不提供 keep/延长保留标记） 实现建议（按你的偏好）： - **janitor 作为 API server 内置后台线程**运行： - 优点：天然可访问 SQLite（任务状态、结束时间、user_id、ray_submission_id），并能把清理结果写回 events 表用于审计 - 部署更简单：不额外引入 cronjob/独立服务 - 删除/移动动作建议 **直接在 GPFS/NFS 文件系统上操作**（API server 运行在 head 容器，已挂载 `/private`）： - 第 1 阶段：`os.rename`（同文件系统原子移动）把 `jobs/` 移到 `trash/jobs/`； - 若跨文件系统（理论上不应发生），则降级为 copy+delete； - 移动前做严格路径前缀校验（必须在 `.../users//jobs/` 下）。 - 第 2 阶段：对 `trash/jobs/` 执行递归删除（例如 `shutil.rmtree`），同样做路径前缀校验（必须在 `.../users//trash/jobs/` 下）。 - 为什么不依赖 SFTPGo API：SFTPGo 只是用户访问协议层（SFTP/Web），目录物理就在同一份文件系统；文件系统直连更简单、也不依赖 SFTPGo 在线。 - 如果你强烈希望“通过 SFTPGo API 删除”： - 可以作为可选实现/补充（例如用于统一审计或未来接入配额/策略），但不建议作为唯一手段（SFTPGo 停机不应阻塞清理）。 ### 3.3 用户在 SFTPGo 内移动/整理文件（确认点） 支持用户在 SFTPGo 中进行“移动/重命名/整理”（例如把权重从 `jobs/` 移动到 `models/`）： - 前提：SFTPGo 用户权限允许对其 home 目录进行 `rename/mkdir/remove` 等操作（v3.0 默认可写）。 - 行为：用户可以把 `jobs/` 下某些文件移动到 `models/` 或 `datasets/`，用于长期保存权重/评估产物等。 - 与 retention 的关系：只要文件被移动出 `jobs/`，就不会被 jobs 清理逻辑删除。 ### 3.4 路径权限规则（API 侧校验） v2.5 约束是 “只允许 `/private/common/...`”。 v3.0 需要升级为： - 允许： - `/private/common/...` - `/private/users//...` - 禁止： - 任何其他绝对路径（例如 `/private/users/other/...`、`/etc/...`） 并把该规则应用到 TaskSpec 的相关字段（至少）： - `train_file` / `val_file` - `code_path`：仍仅允许 `/private/common/...`（v3.0 不支持执行用户 code） - 本地模型路径字段：允许 `/private/users//models/...`（确认：v3.0 允许） ## 4. SFTPGo 方案设计（Data Management） ### 4.1 运行形态 推荐用容器运行 SFTPGo（与 Ray/API 解耦），挂载同一份 `/private`： - `sftpgo` 容器挂载 `../../shared:/private` - 对外暴露： - SFTP 端口（建议 2022） - WebAdmin/API 端口（建议 8081，仅内网或管理员访问） #### 4.1.1 镜像来源（现成 Docker 镜像） SFTPGo 有现成可用的 Docker 镜像（无需自建）： - v3.0 推荐优先使用官方/上游发布的 `sftpgo` 镜像作为运行基座 - 我们在 v3.0 里不需要定制 SFTPGo 代码，只需要： - 正确挂载 GPFS/NFS（容器内 `/private`） - 配置管理员账号（用于 API server 联动创建/禁用用户、重置密码） - 配置每用户 home/chroot > 注意：具体镜像名/tag 在不同环境可能有差异（官方/镜像仓库策略会变动）。落地时建议在 `argus@h1` 上 `docker search sftpgo` 或由你们内部镜像仓库提供固定版本；v3.0 设计只要求“使用现成镜像”，不强依赖某个 tag。 #### 4.1.2 docker-compose 服务草案（示意） 下面给出一个**示意**（最终以实际镜像名/tag 与你们端口规划为准）： ```yaml services: sftpgo: image: sftpgo/sftpgo:latest # 示例：使用现成镜像 container_name: argus-sftpgo ports: - "2022:2022" # SFTP - "8081:8080" # WebAdmin/API（建议仅内网/管理员） volumes: - ../../shared:/private - ../../shared/common/sftpgo:/var/lib/sftpgo # 持久化 SFTPGo 元数据（可选/建议） environment: # 管理员账号/密码（示意，具体变量名以镜像文档为准） SFTPGO_ADMIN_USERNAME: "admin" SFTPGO_ADMIN_PASSWORD: "${SFTPGO_ADMIN_PASSWORD}" ``` 与 v3.0 的配合点： - API server 使用 `data.sftpgo.admin_api_base` + admin 凭据联动创建用户 - 用户 home/chroot 统一指向 `/private/users/` ### 4.2 用户隔离 每个用户在 SFTPGo 中的 home dir 绑定到： - `/private/users/`（chroot），用户只能读写自己的目录。 ### 4.3 用户创建与凭据管理（两种实现，建议先做 A） **方案 A（v3.0 推荐）：API Server 负责“联动创建 SFTPGo 用户”** - 在 v2.5 的 `POST /api/v2/users` 成功后： - API server 调用 SFTPGo 管理 API 创建同名用户 - 设置 home dir = `/private/users/` - 设置权限（默认可写；是否只读可配置） - 认证方式： - v3.0 最小可用：用户名+密码（确认：v3.0 先 password；API 生成一次性密码，用户首次登录后要求改密） - 或：SSH public key（WebUI 允许上传 public key，API 写入 SFTPGo） **方案 B（更强但复杂）：SFTPGo 外部认证** - SFTPGo 把认证委托给 API server（token/SSO），SFTP 也走内部 token。 - 复杂度高，建议 v3.0 不做，放到 v3.5 或更后。 ### 4.4 用户上传/下载体验 用户通过 SFTP 上传： - `datasets/...`（训练数据） - `models/...`（本地模型，可选） 下载： - `jobs//...`（checkpoints/logs） WebUI/文档提供 “路径如何写进 TaskSpec” 的指引。 ## 5. WebUI 方案设计（最小可用） ### 5.1 目标页面 v3.0 WebUI 采用“**多子页面 + 侧边导航栏**”而不是把所有功能挤到单页： - 原因：信息密度更可控，后续可扩展（v3.5+）且不会把一个页面做成“巨型表单/巨型列表”。 - 实现仍保持轻量：服务端渲染（或静态 HTML + 少量 JS），不引入复杂前端工程。 信息架构（IA）建议如下： 1) **登录页**（`/ui/login`） - 用户粘贴 token（管理员发放），浏览器保存（localStorage/sessionStorage） - 提供“退出登录/清空 token” 2) **任务列表页**（`/ui/tasks`） - 默认列表：最近 N 条任务（按 created_at 倒序） - 支持过滤：workload、state（QUEUED/RUNNING/SUCCEEDED/FAILED/CANCELED）、时间范围 - 支持快捷操作：进入详情、取消任务 3) **新建任务页**（`/ui/tasks/new`） - 两种模式（二选一，均可实现）： - **YAML 直接提交**：上传/粘贴 TaskSpec YAML（最省开发） - **表单生成 YAML**：选择 workload，填写核心字段（train/val/model/nnodes/gpus），生成 YAML 预览后提交 - 提交后跳转到任务详情页 4) **任务详情页**（`/ui/tasks/{task_id}`） - 顶部：task_id、workload、state、created_at、updated_at、error_summary - Attempt 卡片：latest attempt_no、ray_submission_id、ray_status、start/end - 操作区：取消任务（若非 terminal）、刷新状态、复制路径/ID - 链接到日志页与产物提示（SFTP 路径） 5) **任务日志页**（`/ui/tasks/{task_id}/logs`） - 默认 tail=2000，可选 200/1000/5000 - 提供“自动刷新（每 3~5 秒）”开关（简单轮询即可） 6) **数据页**（`/ui/data`） - 显示 SFTP 连接信息（host/port/username） - 显示用户目录约定： - home：`/private/users/` - datasets：`/private/users//datasets` - models：`/private/users//models` - jobs：`/private/users//jobs` - trash/jobs：`/private/users//trash/jobs` - 明确 retention：jobs 结束后 3 天移入回收站，回收站 7 天后删除；重要文件请移到 `models/` 或 `datasets/` 7) **（仅管理员可见）用户管理页**（`/ui/admin/users`，可选但很有价值） - 创建用户、禁用用户、签发 token、重置 SFTP 密码（方案 A） ### 5.2 页面组织与导航（建议） 侧边栏导航（普通用户）： - Tasks（列表） - New Task（新建） - Data（SFTP/目录说明） 管理员侧边栏额外增加： - Admin / Users ### 5.3 大致示意图（wireframe） 下面是一个粗略示意（非最终 UI，仅表达信息结构与布局）： ``` ┌──────────────────────────────────────────────────────────────────────┐ │ Argus MVP v3.0 [user: alice] │ ├───────────────┬──────────────────────────────────────────────────────┤ │ Side Nav │ /ui/tasks │ │ │ │ │ • Tasks │ [Filter] workload=all state=all [Search task_id] │ │ • New Task │ │ │ • Data │ Task List │ │ • Admin(*) │ ┌────────────────────────────────────────────────┐ │ │ │ │ task_id workload state ... │ │ │ │ │ mvp2-alice-ppo-... ppo RUNNING ... │ │ │ │ │ mvp2-alice-sft-... sft SUCCEEDED... │ │ │ │ └────────────────────────────────────────────────┘ │ │ │ [View] [Cancel] │ └───────────────┴──────────────────────────────────────────────────────┘ ``` 任务详情页（示意）： ``` ┌──────────────────────────────────────────────────────────────────────┐ │ /ui/tasks/{task_id} │ ├──────────────────────────────────────────────────────────────────────┤ │ task_id: mvp2-alice-ppo-... state: RUNNING workload: ppo │ │ created_at: ... updated_at: ... │ │ error_summary: (empty) │ │ │ │ latest_attempt: a01 ray_submission_id: ...--a01 ray_status: RUNNING │ │ [Open Logs] [Cancel Task] [Refresh] │ │ │ │ Artifacts (SFTP paths): │ │ jobs/: /private/users/alice/jobs// │ │ trash/: /private/users/alice/trash/jobs// │ │ tip: move important files to /private/users/alice/models/ │ └──────────────────────────────────────────────────────────────────────┘ ``` ### 5.2 技术取舍（建议：不引入 Node 构建） 为了降低部署复杂度，建议 v3.0 WebUI 以 “服务端渲染 + 少量 JS/HTMX” 或 “纯静态 HTML+fetch” 实现： - 由 API server 提供静态资源（FastAPI StaticFiles） - 页面调用同源 API，避免跨域与复杂前端构建链 ## 6. API 扩展设计（概览） v3.0 可以保持 `/api/v2/...` 不变，增量加： - SFTPGo 集成管理端点（管理员）： - 创建/禁用用户时联动 SFTPGo - 重置 SFTP 密码 / 更新 SSH key - 用户数据端点（可选，最小化）： - `/api/v2/me`：返回 user_id、SFTP 信息（host/port/home） - `/api/v2/files`：仅用于浏览/下载（上传仍走 SFTP） 详细见 `specs/mvp/v3.0/v3.0_api.md`。 ## 7. 配置与部署（v3.0 新增项） 在 `configs/dev.yaml` 基础上扩展一组 `data` 配置（示意）： ```yaml data: shared_root: "/private" # 通常与 ray.shared_root 一致 user_root: "/private/users" # 用户空间根目录 allow_common_prefix: "/private/common/" allow_user_prefix_template: "/private/users/{user_id}/" sftpgo: enabled: true host: "127.0.0.1" sftp_port: 2022 admin_api_base: "http://127.0.0.1:8081/api/v2" admin_user: "admin" admin_password_env: "SFTPGO_ADMIN_PASSWORD" # 仅 head 容器内可读 retention: jobs_trash_after_days: 3 jobs_purge_after_days: 7 trash_root_template: "/private/users/{user_id}/trash/jobs" janitor_interval_s: 3600 # 每小时扫一次（可配置） ``` ## 8. 风险点与对策 1) **路径逃逸/越权读取** - 必须在 API 提交任务时校验路径前缀 - SFTPGo 必须 chroot 到用户 home 2) **大文件上传稳定性** - 优先用 SFTP（断点续传/可靠性更好） 3) **用户 token 与 SFTP 凭据的生命周期** - token 走 v2.5 SQLite - SFTP 凭据建议独立（密码/SSH key），并提供 reset 流程 4) **GPFS/NFS 权限** - 确保 `/private/users/` 目录权限可被 SFTPGo 写入且 worker 可读 ## 9. 已确认结论（来自你的反馈） 1) 允许用户上传并在训练时使用自定义数据集：允许（`/private/users//datasets/...`）。 2) 允许用户上传并在训练时使用本地模型路径：允许（`/private/users//models/...`）。 3) v3.0 不允许执行用户自定义代码（不注入 `PYTHONPATH` 作为可执行 code path）。 4) SFTPGo 认证方式：v3.0 先 password。 5) WebUI：按“简单最小必要功能”做（token 粘贴登录优先）。 ## 10. 待确认问题（需要你给结论） （已确认）jobs 清理执行主体：v3.0 采用 **API server 内置 janitor 后台线程**。