110 lines
2.0 KiB
Markdown
110 lines
2.0 KiB
Markdown
# 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。
|
||
|