v2.0 补充单元测试，行覆盖90以上

specs/mvp/mvp_roadmap_v2.md

@@ -1,96 +1,49 @@
-渐进的 AI Infrastructure 演进路线图。从最初的单机脚本执行，到最终的智能化运维平台
-
-对应架构演进图，设计**基于 Native Ray Cluster 与 Verl 框架的 AI Infra Roadmap 设计文档**。
+这一版的设计采用了 **Overlay 架构 + GPFS 核心存储 + 无状态（Stateless）节点池** 的模式，逻辑非常自洽且具备极高的云原生弹性。
 
 ---
 
-### **项目代号：AI Infra Roadmap (Native Ray + Verl)**
+### **项目代号：AI Infra Overlay Platform (Stateless Ray + GPFS)**
 
-#### **阶段一：核心内核构建 (Foundation & Core Execution)**
+#### **阶段一：内核构建与验证 (Kernel & Verification)**
 
-这一阶段主要解决“能不能跑”的问题，聚焦于核心计算引擎的对接和基础任务调度。
+*目标：验证核心计算逻辑，跑通“提交-执行”的最小闭环。*
 
 * **v1.1: 原型验证 (Verl Task Spec & Ray Job)**
-    * **核心功能**：实现了最基础的任务提交链路。
-    * **组件**：
-        * **Ray Job Tool (Ray Client)**：作为客户端工具。
-        * **VerlTaskSpec YAML**：定义任务的标准配置文件。
-        * **Multi-Verl Code Path**：支持多代码路径。
+* **核心功能**：实现基础的任务定义与提交。
+* **组件**：
+* `Ray Job Tool (Ray Client)`：客户端工具。
+* `VerlTaskSpec YAML`：定义多代码路径 (Multi-Verl Code Path) 和任务参数。
 
-    * **基础设施**：Handmade Ray Cluster（手工搭建的 Ray 集群）。
-    * **目标**：验证 Verl 框架与 Ray 的基本交互。
+
+* **基础设施**：Handmade Ray Cluster（手工搭建的集群），用于验证核心代码。
 
 
 * **v2.0: 任务管理层 (Task Management)**
-    * **核心功能**：引入了服务化管理，不再单纯依赖命令行工具。
-    * **新增组件**：
-        * **API Server**：提供统一的接口层。
-        * **Task Management**：实现了任务队列 (Queue)、映射 (Map) 和重试/重新提交 (Resubmit) 机制。
+* **核心功能**：引入服务端，管理任务生命周期。
+* **新增组件**：
+* `API Server`：统一接口层。
+* `Task Management`：实现任务的队列 (Queue)、映射 (Map) 和重试 (Resubmit) 机制。
 
 
-    * **基础设施**：仍运行在 Handmade Ray Cluster 上。
-
-
-* **v2.5: 资源与用户管理 (User & Node Management)**
-    * **核心功能**：从“手工集群”迈向“自动化集群”，并增加了多租户基础。
-    * **新增组件**：
-        * **User Management**：用户权限与身份管理。
-        * **Node Management**：核心升级点。支持通过 SSH 管理节点池，实现 Auto-managed Ray Cluster（自动管理的 Ray 集群），不再手动维护。
-
-
-    * **演进**：基础设施层由 Handmade 变为 SSH Node (Auto Managed)。
+* **基础设施**：仍运行在手工集群上，但控制面开始服务化。
 
 
 
 ---
 
-### **阶段二：产品化与服务化 (Productization & Serving)**
+### **阶段二：架构质变 - 无状态节点池 (The Stateless Shift)**
 
-这一阶段主要解决“好不好用”的问题，发布了第一个正式版本，并扩展了业务场景。
+*目标：通过 GPFS 实现控制反转 (IoC)，彻底解耦平台层与计算节点层。这是本架构最关键的转折点。*
 
-* **v3.0: 正式发布版 (Frontend & Data Management)**     * **里程碑**：**1st Version to Release!!** (首个对外发布版本)
-    * **核心功能**：完整的前后端分离，闭环了用户的数据流。
-    * **新增组件**：
-        * **WebUI**：提供可视化的用户界面。
-        * **Data Management (SFTPGo)**：集成了 SFTPGo，解决用户训练数据、代码的上传与下载问题。
-
-
-    * **价值**：用户可以通过 Web 界面完成从数据上传到任务提交的全流程。
-
-
-* **v3.5: 定制化与推理服务 (Customized Task & Serving)**
-    * **核心功能**：支持更复杂的训练需求和模型推理。
-    * **新增组件**：
-        * **Model Serving**：不仅能训练，还能部署模型服务。
-        * **Customized VerlTaskSpec YAML**：支持自定义参数 (Param)、奖励函数 (Reward)、Verl 代码等。
-
-
-    * **价值**：从单一的训练平台扩展为“训练+推理”的一体化平台，且支持算法工程师深度定制实验参数。
-
-
-
----
-
-### **阶段三：可观测性体系 (Observability)**
-
-这一阶段主要解决“看得清”的问题，确保系统的稳定性和模型训练的可追踪性。
-
-* **v4.0: 系统级可观测性 (System Observability)**
-    * **核心功能**：建立完整的基础设施监控。
-    * **新增组件**：
-        * **Prometheus**：指标采集。
-        * **Grafana**：监控大盘展示。
-        * **Alert**：告警系统。
-        * **ELK**：日志收集与分析 (Elasticsearch, Logstash, Kibana)。
-
-
-    * **基础设施升级**：在 SSH Node 上部署了 **Exporter**，用于采集节点层面的 metrics。
-
-
-* **v4.5: 实验级可观测性 (ML Observability)**
-    * **核心功能**：专注于模型训练过程的指标追踪。
-    * **新增组件**：
-        * **Weight & Bias (WanB)**：集成专业的 ML 实验追踪工具，用于记录 Loss、Accuracy 等训练指标。
+* **v2.5: 用户管理 & 无状态 Ray 节点池 (User Mgmt & Stateless Ray Node Pool)**     * **核心机制：基于 GPFS 的服务发现 (Service Discovery)**
+* **Ray Head (有状态)**：由 `Node Management` 启动（通常通过 SSH 或 K8s StatefulSet）。启动后，将自身的 IP 地址写入 GPFS 中的 `Head IP File`。
+* **Ray Worker (无状态)**：
+* **Stateless**：Worker 容器启动时不依赖平台指令。
+* **Auto Connect**：启动脚本读取 GPFS 中的 `Head IP File`，获得 Head 地址并自动加入集群。
+* **Watchdog**：Worker 内部运行看门狗进程，监控 Head IP 变化。如果 Head 变动，Worker 自动重启或重连，实现自愈。
+* **新增组件**：
+* `User Management`：多用户隔离。
+* `GPFS`：取代了之前的 JuiceFS，作为唯一的共享存储和元数据交换媒介。
 
 
 
@@ -98,33 +51,83 @@
 
 ---
 
-### **阶段四：智能化运维 (Operability & Intelligence)**
+### **阶段三：产品化与高级能力 (Productization & Advanced Features)**
 
-这一阶段主要解决“自动化”的问题，引入 AI 来管理 AI 平台。
+*目标：发布首个正式版本，并支持大模型训练所需的复杂网络与推理能力。*
 
-* **v5.0: 智能运维闭环 (Statistics, SOP, Agent)**
-    * **核心功能**：通过数据统计和 Agent 实现平台的自动化治理。
-    * **新增组件**：
-        * **Statistics**：平台维度的统计分析（资源利用率、任务成功率等）。
-        * **SOP Tools**：标准作业程序工具化（自动化运维脚本）。
-        * **Agent**：智能体。可能用于自动故障诊断、资源自动调度优化或交互式助手。
+* **v3.0: 正式发布版 (Release v1.0)**     * **里程碑**：**1st Version to Release!!**
+* **核心功能**：闭环用户数据流。
+* **新增组件**：
+* `WebUI`：可视化操作界面。
+* `Data Management (SFTPGo)`：用户上传数据/代码 -> SFTPGo -> 写入 GPFS -> Ray Worker 可见。
+
+
+* **基础设施**：全量切换到 `Ray Worker Node` (Stateless) + `GPFS` 的架构。
+
+
+* **v3.5: 高级定制与训推一体 (Advanced Task & Serving)**     * **核心功能**：支持复杂的科研需求。
+* **新增组件**：
+* `Model Serving`：支持模型推理服务。
+* `Advanced VerlTaskSpec`：支持自定义 Reward Function、自定义代码、Checkpoint 断点续训 (Resubmit from last checkpoint)。
+
+
+* **网络增强**：
+* **IB Network Supporting**：支持 InfiniBand 网络，确保多机训练的高性能互联。
 
 
-    * **愿景**：打造一个具备自我管理、自我修复能力的 AI 基础设施平台。
 
 
 
 ---
 
-### **架构层级总结**
+### **阶段四：全链路可观测性 (Full-Stack Observability)**
+
+*目标：打开黑盒，监控基础设施与业务指标。*
+
+* **v4.0: 系统级可观测性 (System Observability)**     * **核心功能**：监控集群“活着”且“健康”。
+* **新增组件**：
+* `Prometheus` + `Grafana` + `ELK`：指标与日志平台。
+* `Exporter`：部署在 Ray Worker Node 中的监控探针（采集 GPU/CPU/GPFS IO 指标）。
+
+
+
+
+* **v4.5: 算法级可观测性 (ML Observability)**     * **核心功能**：监控模型“练得好不好”。
+* **新增组件**：
+* `Weights & Bias (WanB)`：集成实验追踪工具，记录 Loss 曲线和训练参数。
+
+
+
 
-| 层级 | 关键组件/技术 |
-| --- | --- |
-| **接入层 (Frontend/API)** | WebUI, API Server, User Management |
-| **调度与编排 (Orchestration)** | Task Management, Ray Job Tool (Client), Node Management |
-| **计算引擎 (Compute)** | Native Ray Cluster, Verl Framework (TaskSpec YAML) |
-| **数据与存储 (Data)** | SFTPGo (Data Management), Model Serving |
-| **可观测性 (Observability)** | Prometheus, Grafana, ELK, Weights & Bias |
-| **运维与智能 (Ops)** | Exporters, Statistics, SOP Tools, Agent |
 
 ---
+
+### **阶段五：智能化运维 (AIOps)**
+
+*目标：迈向自动化与自治。*
+
+* **v5.0: 智能运维闭环 (Operability)**     * **核心功能**：降低运维成本，提升稳定性。
+* **新增组件**：
+* `Statistics`：集群资源利用率统计报表。
+* `SOP Tools`：标准运维工具（如自动清理 GPFS 垃圾文件、僵尸节点检测）。
+* `Agent`：智能运维助手（基于 LLM 的日志分析与故障诊断）。
+
+
+
+
+
+---
+
+### **新架构核心亮点总结**
+
+1. **极简的节点管理**：
+* 利用 v2.5 的 **Head IP File + Watchdog** 机制，平台层不再需要维护复杂的 Worker IP 列表和 SSH 连接池。
+* **扩缩容极其简单**：只需在底层（K8s/Docker）增加 Worker 副本数，它们就会自动通过 GPFS 找到 Head 并加入战斗。
+
+
+2. **统一的数据平面 (GPFS)**：
+* 从 v2.5 开始，GPFS 承担了 **数据存储** (Code/Data)、**状态同步** (Head IP) 和 **检查点存储** (Checkpoints) 三大职责，架构非常收敛。
+
+
+3. **高弹性 (Resilience)**：
+* Worker 的 **Watchdog** 机制确保了当 Head 重启或网络抖动时，集群具备自我修复能力，无需人工干预。

specs/mvp/v2.5/README.md

@@ -0,0 +1,14 @@
+# MVP v2.5（Design）— User Management & Stateless Ray Node Pool
+
+本目录基于 `specs/mvp/mvp_roadmap_v2.md` 与 `specs/mvp/image/roadmap_v2.5.png` 的 v2.5 规划，
+给出一份**可落地、可验证、可迭代实现**的详细方案设计文档集合。
+
+v2.5 的核心变化：
+- 在 v2.0 的任务队列/调度/重试基础上，引入 **User Management**（多用户隔离、目录隔离、token）。
+- 引入 **Stateless Ray Node Pool**：worker 节点/容器不再需要平台显式下发 head 地址，通过共享存储（GPFS/NFS）完成服务发现与自愈连接（watchdog）。
+
+文档：
+- `specs/mvp/v2.5/v2.5_design.md`：总体架构、关键机制（head IP file / watchdog / 用户隔离 / 任务流）。
+- `specs/mvp/v2.5/v2.5_api.md`：API 设计（用户、任务、队列、日志）与鉴权约定。
+- `specs/mvp/v2.5/v2.5_acceptance.md`：开发/部署/验收流程与可验证标准。
+

specs/mvp/v2.5/v2.5_acceptance.md

@@ -0,0 +1,67 @@
+# MVP v2.5 开发/部署/验收标准
+
+本文件定义 v2.5 的“可验证闭环”，确保每个里程碑可验收。
+
+---
+
+## 1. 开发交付物（Deliverables）
+
+### 1.1 代码交付（建议）
+
+- API Server 增强：user management + task 关联 user_id + 鉴权隔离
+- SQLite schema 迁移：新增 users/tokens，tasks 增加 user_id
+- Ray Head service discovery：head.json 写入与心跳刷新
+- Worker bootstrap + watchdog：
+  - dev：以脚本方式提供（docker compose 场景）
+  - prod：以容器 command/entrypoint 方式可注入
+
+### 1.2 文档交付
+
+- 目录结构与 GPFS 路径约定
+- API 文档（含用户与多租户隔离）
+- 运维 SOP：head 重启、worker 自愈、如何排障 head.json
+
+---
+
+## 2. 部署流程（Dev 环境可验证）
+
+### 2.1 启动顺序（推荐）
+
+1) 启动 head（包含 API server + Ray head）
+2) head 写入 `/private/ray/discovery/<cluster_name>/head.json`
+3) 启动若干 worker（无须指定 head 地址）
+4) worker 自动读取 head.json 并加入集群
+5) 通过 API 创建用户并获取 token
+6) 使用 user token 提交 PPO/GRPO/SFT
+
+---
+
+## 3. 验收标准（Acceptance Criteria）
+
+### 3.1 Stateless Ray Node Pool
+
+- A1：在 worker 启动时不传 head 地址，worker 能在 `T<=60s` 内加入集群（ray status 可见）
+- A2：head 容器重启（IP 变化或 Ray 重启）后：
+  - head.json 更新
+  - worker watchdog 在 `T<=60s` 内自动重连
+- A3：head 设置 `--num-gpus=0 --num-cpus=0`，训练 driver 不会跑到 head（可通过 Ray dashboard/日志验证）
+
+### 3.2 User Management
+
+- U1：admin 可创建用户并签发 token（token 仅返回一次）
+- U2：用户 A 提交的 task，用户 B 无法查询/取消/获取日志（API 返回 404 或 403，按设计约定）
+- U3：仅隔离 jobs 输出：任务输出落在 `/private/users/<user_id>/jobs/<ray_submission_id>/...`，不同用户互不覆盖
+- U4：训练输入（verl 代码、HF cache、datasets）统一使用 `/private/common/...`（v2.5 不做输入隔离）
+
+### 3.3 Task Flow（继承 v2.0）
+
+- T1：PPO/GRPO/SFT 三种 workload 都能成功提交并跑通（dev 规模可用 epoch=1/steps=10）
+- T2：资源不足时任务不会“直接失败不可恢复”，而是进入 `PENDING_RESOURCES` 并按间隔重试（与 v2.0 同逻辑）
+
+---
+
+## 4. 回归用例（最小集合）
+
+1) 创建用户 alice/bob，分别提交 sft，验证隔离与输出目录
+2) 启动 head + 2 workers，提交 ppo/grpo，验证 driver 落 worker
+3) 重启 head（或修改 head.json 指向新 IP），验证 worker watchdog 自动重连

specs/mvp/v2.5/v2.5_api.md

@@ -0,0 +1,109 @@
+# MVP v2.5 API 设计（User + Task + Queue）
+
+v2.5 在 v2.0 API 基础上，新增 **User Management** 与多租户隔离。
+
+约束：
+- 仍使用内部 token（API key）；
+- 不引入外部 IAM；
+- TaskSpec 仍为 YAML（沿用现有结构化字段）。
+
+---
+
+## 1. Auth
+
+Header：
+- `Authorization: Bearer <api_token>`
+
+服务端行为：
+- 将 `api_token` 映射到 `user_id`
+- 之后的 task 操作默认仅作用于该 `user_id`
+
+Admin token（可选）：
+- 支持额外配置 `MVP_ADMIN_TOKEN`（或 user.role=admin）
+- admin 可跨用户查询/取消（用于运维）。
+
+---
+
+## 2. User Management
+
+### 2.1 创建用户（admin）
+
+`POST /api/v2/users`
+
+Request（JSON）：
+```json
+{"user_id":"alice","display_name":"Alice"}
+```
+
+Response：
+```json
+{"user_id":"alice","state":"ACTIVE"}
+```
+
+### 2.2 为用户签发 token（admin）
+
+`POST /api/v2/users/{user_id}/tokens`
+
+Response（只返回一次明文 token）：
+```json
+{"user_id":"alice","token":"mvp_u_..."}
+```
+
+### 2.3 禁用用户（admin）
+
+`POST /api/v2/users/{user_id}:disable`
+
+---
+
+## 3. Task Management（多租户）
+
+### 3.1 提交任务
+
+`POST /api/v2/tasks`
+
+Body：
+- `Content-Type: application/yaml`
+- raw TaskSpec YAML（训练语义字段；不含 user_id）
+
+Response：
+```json
+{"task_id":"mvp25-ppo-20251225-170001-2a3f","state":"QUEUED"}
+```
+
+服务端 side effects：
+- 记录 tasks.user_id（由 token 得到）
+- 计算输出目录：`/private/users/<uid>/jobs/<ray_submission_id>/...`
+
+### 3.2 查询任务（仅本人）
+
+`GET /api/v2/tasks/{task_id}`
+
+若 task 不属于当前 user：
+- 返回 `404`（避免泄露存在性）
+
+### 3.3 取消任务（仅本人）
+
+`POST /api/v2/tasks/{task_id}:cancel`
+
+---
+
+## 4. Queue/Debug
+
+### 4.1 查看队列（本人视角）
+
+`GET /api/v2/queue`
+
+返回该 user 的 pending/running 列表。
+
+### 4.2 管理员查看全局队列（admin）
+
+`GET /api/v2/admin/queue`
+
+---
+
+## 5. Logs
+
+`GET /api/v2/tasks/{task_id}/logs?attempt=latest&tail=2000`
+
+行为与 v2.0 一致：透传 Ray Job logs tail。
+

specs/mvp/v2.5/v2.5_design.md

@@ -0,0 +1,255 @@
+# MVP v2.5 详细设计方案（User Management + Stateless Ray Node Pool）
+
+本文目标：把 `mvp_roadmap_v2.md` 中 v2.5 的思路落到**可工程化实现**的设计层，包括：
+- API Server 内新增 user management；
+- Ray node pool 变为无状态（worker 自发现 head、自动加入、watchdog 自愈）；
+- 仍保持 v2.0 的“任务管理层”语义：Task/Attempt、队列、资源判断、Ray Job 提交与状态同步；
+- 所有共享数据/状态统一落在 GPFS（dev 环境可先用 NFS），容器内路径统一为 `/private/`。
+
+> 术语说明：文中“GPFS”代表生产共享存储；dev 环境可用 NFS，但容器内仍以 `/private/` 访问。
+
+---
+
+## 1. 目标与非目标
+
+### 1.1 v2.5 目标（Must）
+
+1) **User Management（最小多租户）**
+- 支持创建/禁用用户；
+- 为每个用户签发内部 token（API key），用于认证与隔离；
+- 用户隔离（v2.5 先做最小闭环，仅隔离 **jobs 输出** 与 API 可见性）：
+  - 用户只能看到/操作自己的 Task；
+  - 训练输出（job root、checkpoints、日志归档等）按 user 目录落盘；
+  - 训练输入（verl 代码、HF cache、datasets）统一使用 `common/`（v2.5 不支持用户自定义代码/模型/数据集隔离）。
+
+2) **Stateless Ray Worker Node Pool**
+- worker 容器启动时无需被平台告知 head 地址；
+- worker 通过 GPFS 读取 **Head IP File** 自动连接 Ray head；
+- worker 内部 watchdog 监控 head 地址变化，发生变化时自动 `ray stop` + `ray start` 重连；
+- worker 尽量不依赖本地持久化状态（宕机/替换后可无感重建）。
+
+3) **保持 v2.0 的 Task 管理行为**
+- Task/Attempt 模型不变（或向后兼容扩展）；
+- 对齐 verl 的 fail-fast 行为：资源不足时服务侧 pending + 重试；
+- Ray Job 提交仍通过 Ray Python SDK（JobSubmissionClient）。
+
+### 1.2 v2.5 非目标（Not Now）
+
+- 完整 WebUI（留到 v3.0）。
+- 公平调度/配额/优先级（留到 v3.x）。
+- 完整生产级 IAM（留到 v4+），v2.5 仅内部 token。
+- K8s 原生编排（本阶段不要求，但设计需能适配“算力平台拉起容器，只能 ssh 进去纳管”的模式）。
+
+---
+
+## 2. 总体架构（对应 roadmap v2.5）
+
+### 2.1 组件划分
+
+**控制面（Control Plane）**
+- **API Server**
+  - user management
+  - task management（队列/调度/重试/状态聚合）
+  - Ray Job Tool（Ray Client）
+  - VerlTaskSpec（TaskSpec YAML，沿用 v2.0/v2.1 格式）
+  - 与 Ray head 在同一台/同一容器是推荐形态（便于访问 dashboard / job server）
+- **Ray Head（有状态）**
+  - 启动后把 head 地址写入 GPFS 的 Head IP File，用于 worker 服务发现
+
+**数据面（Data Plane）**
+- **Ray Workers（无状态节点池）**
+  - stateless bootstrap：从 GPFS 读取 head 地址自动加入集群
+  - watchdog：持续 watch head 地址文件变化并自愈重连
+
+**共享存储（GPFS）**
+- 统一数据路径：数据、模型 cache、代码、任务输出、以及 head 服务发现文件。
+
+### 2.2 v2.5 的控制反转（IoC）
+
+与 v2.0/手工集群的关键差异：
+- v2.0：平台脚本/运维显式启动 worker 并指定 `--address=<head>`。
+- v2.5：worker 自己从 GPFS 读取 `head_ip_file`，无需平台维持 worker 列表与 SSH 连接池。
+
+---
+
+## 3. GPFS 目录结构（容器内 `/private`）
+
+建议在 v2.5 固化以下目录（与现有 v2.0 兼容扩展）：
+
+```
+/private/
+  ray/
+    discovery/
+      <cluster_name>/
+        head.json              # Head IP File（服务发现）
+        head.json.lock         # 可选：写入锁（v2.5 可先不实现）
+  users/
+    <user_id>/
+      jobs/                    # /private/users/<uid>/jobs/<ray_submission_id>/*
+      outputs/                 # 训练输出聚合（按需要）
+  common/
+    code/                      # 平台/公共代码快照（verl code snapshot 等）
+    datasets/                  # 公共数据集
+    hf/                        # 公共 HF cache（dev 复用）
+    db/                        # sqlite
+    logs/                      # API 日志、平台日志
+```
+
+说明：
+- `common/`：平台默认目录（v2.5 先默认所有用户可写；后续再加 ACL/只读）。
+- `users/<user_id>/...`：用户隔离主边界（最小多租户的关键）。
+
+---
+
+## 4. Head IP File（服务发现）设计
+
+### 4.1 文件路径
+
+- `head_ip_file = /private/ray/discovery/<cluster_name>/head.json`
+- `<cluster_name>`：由配置指定（例如 `argus-ray`），允许同一 GPFS 上存在多个环境/集群。
+
+### 4.2 文件内容（JSON）
+
+建议采用 JSON（易扩展）：
+
+```json
+{
+  "cluster_name": "argus-ray",
+  "head_ip": "10.0.0.12",
+  "gcs_port": 6379,
+  "dashboard_port": 8265,
+  "job_server_url": "http://10.0.0.12:8265",
+  "updated_at": "2025-12-25T17:00:00Z",
+  "expires_at": "2025-12-25T17:01:00Z"
+}
+```
+
+关键点：
+- `updated_at`：便于排障与可观测；
+- `expires_at`：避免 worker 读取到“陈旧 head 地址”后无限重连；
+- `job_server_url`：对外可直接用于 Ray Job Tool 配置（便于无脑接入）。
+
+### 4.3 写入策略（原子更新）
+
+Head 写入时必须保证 worker 读取不会读到半文件：
+- 写临时文件 `head.json.tmp`；
+- `fsync`（可选）；
+- `rename(head.json.tmp -> head.json)`（原子替换）。
+
+### 4.4 心跳与 TTL
+
+Head 进程需周期性刷新 `head.json`：
+- 建议 `ttl_s=60`，刷新周期 `refresh_s=10`；
+- 若 head 进程异常退出，worker 读取到过期文件可进入“等待模式”而非无限重连。
+
+---
+
+## 5. Stateless Worker Bootstrap + Watchdog
+
+### 5.1 启动序列（worker 容器内）
+
+1) 启动脚本读取 `head.json`：
+   - 若文件不存在：sleep + 重试（直到存在）
+   - 若存在但 `expires_at` 已过期：sleep + 重试（直到变为新鲜）
+2) 解析 `head_ip:gcs_port` 并执行：
+   - `ray stop --force || true`
+   - `ray start --address=<head_ip>:<gcs_port> --resources='{"worker_node": 100, ...}' ...`
+3) 启动 watchdog 进程（同容器）：
+   - 轮询/监听 `head.json` 的内容变化
+   - 一旦 `head_ip` 或 `gcs_port` 改变，触发 `ray stop` + `ray start` 重连
+
+### 5.2 Watchdog 策略（最小可用）
+
+v2.5 推荐“简单且稳”的实现：
+- polling 间隔 `watch_s=5`；
+- 对比 `head.json` 的 `updated_at` 或 hash；
+- 若发现变更：执行重连；
+- 若连续多次重连失败：指数退避（v2.5 可先固定退避，v2.6 再增强）。
+
+### 5.3 资源标签（driver 强制落 worker）
+
+继续沿用 v2.0 的思路：
+- worker 启动时 `--resources='{"worker_node": 100}'`
+- head 不包含 `worker_node` 资源
+- Ray job submit 时设置 entrypoint_resources：`{"worker_node": 1}`
+
+### 5.4 GPU/CPU 的“无状态”约束
+
+- worker 是否有 GPU 由底层算力平台决定（生产上平台会为容器挂载 GPU）；
+- worker 启动脚本不应硬编码 GPU 编号，只依赖 `NVIDIA_VISIBLE_DEVICES`/平台注入；
+- head 推荐 `--num-gpus=0 --num-cpus=0`，避免训练调度到 head。
+
+---
+
+## 6. User Management 设计（最小多租户）
+
+### 6.1 数据模型（SQLite）
+
+新增两张表（示意）：
+- `users`
+  - `user_id`（PK）
+  - `display_name`
+  - `state`（ACTIVE/DISABLED）
+  - `created_at`
+- `api_tokens`
+  - `token_hash`（PK）
+  - `user_id`（FK）
+  - `created_at`
+  - `last_used_at`
+
+并在 `tasks` 表增加：
+- `user_id`（FK）
+
+### 6.2 鉴权策略
+
+内部 token 模式：
+- `Authorization: Bearer <token>`
+- 服务端将 token 映射到 `user_id`
+- 后续所有 task 查询/取消/日志默认 scope 到该 `user_id`
+
+管理员能力（v2.5 最小实现）：
+- 额外配置一个 admin token（或把特定 user 标记为 admin）
+- admin 可 list all users/tasks（用于运维排障）。
+
+### 6.3 用户目录隔离（路径约束）
+
+核心原则（v2.5 版）：
+- **输出**：必须落在 `/private/users/<uid>/jobs/...`（服务端统一计算，不允许用户任意指定输出根）
+- **输入**：统一使用 `/private/common/...`（v2.5 不支持用户自定义 verl 代码、也不做 hf/datasets 的用户隔离）
+
+服务端处理策略（最小可用）：
+- 解析 TaskSpec 后，对输入路径字段做白名单前缀校验（必须是 `/private/common/...`；拒绝 `../` 与越界路径）；
+- 输出目录统一由服务端计算：`job_root = /private/users/<uid>/jobs/<ray_submission_id>/`。
+
+---
+
+## 7. TaskSpec（VerlTaskSpec YAML）在 v2.5 的扩展点
+
+v2.5 **不扩展 TaskSpec**：保持与 v2.0/v2.1 的 YAML 结构化字段与语义一致。
+
+v2.5 的“用户语义”仅体现在服务端的补齐/约束：
+- user_id 由 token 推导（用户不需要在 YAML 里写 user_id）；
+- 服务端派生 `ray_submission_id`（由 task_id/attempt 派生）；
+- 服务端统一计算输出目录 `job_root=/private/users/<uid>/jobs/<ray_submission_id>/...`；
+- v2.5 不支持用户自定义 verl 代码路径（因此 runtime_env 不需要注入用户 code 目录）。
+
+---
+
+## 8. 迁移与兼容性
+
+v2.5 设计需满足：
+- 现有 v2.0 的“手工启动 worker”仍可运行（作为 dev fallback）；
+- 在不改镜像的前提下，worker watchdog 可以以“容器启动命令/entrypoint”方式注入（dev 用 scripts；生产由算力平台指定 command）。
+
+---
+
+## 9. 风险与对策（v2.5）
+
+1) **GPFS 上 head.json 一致性/延迟**
+- 对策：原子 rename + TTL；watchdog polling。
+
+2) **Ray head 重启后 job server URL 变化**
+- 对策：head.json 内写入 `job_server_url`，Ray Job Tool 可读取该文件更新 address（v2.6 可做动态 reload）。
+
+3) **Worker 重连期间任务波动**
+- 对策：服务侧调度器对齐 verl 的资源 fail-fast；任务失败可归因并排队重试。