110 lines
3.8 KiB
Markdown
110 lines
3.8 KiB
Markdown
# MVP v3.0 — API 扩展设计（基于 v2.5）
|
||
|
||
v3.0 的原则是：**尽量复用 v2.5 API**，只增量增加 “数据闭环” 与 “WebUI 支持” 所需的最小接口。
|
||
|
||
## 1) 认证与权限
|
||
|
||
沿用 v2.5：
|
||
- Header：`Authorization: Bearer <token>`
|
||
- admin token：来自 `MVP_INTERNAL_TOKEN`
|
||
- 普通用户 token：由 admin 颁发并持久化在 SQLite
|
||
|
||
权限规则：
|
||
- 非 admin：只能访问自己的 task、自己的数据空间（`/private/users/<user_id>/...`）。
|
||
- 跨用户访问返回 404（不泄露存在性）。
|
||
|
||
## 2) 用户与 SFTPGo 联动（管理员接口）
|
||
|
||
### 2.1 创建用户（复用 v2.5）
|
||
`POST /api/v2/users`
|
||
- v3.0 行为：成功后，**可选**联动创建 SFTPGo 用户
|
||
- v3.0 默认启用联动：创建 SFTPGo 用户 + 生成一次性密码（password 认证）
|
||
- v3.0 仅保留该方案（方案 A）：不做外部认证/SSO 集成（留到更后续版本）
|
||
- `data.sftpgo.admin_api_base` 推荐形如：`http://argus-sftpgo:8080/api/v2`（包含 `/api/v2` 前缀）
|
||
|
||
### 2.2 下发 token（复用 v2.5）
|
||
`POST /api/v2/users/{user_id}/tokens`
|
||
|
||
### 2.3 禁用用户（复用 v2.5）
|
||
`POST /api/v2/users/{user_id}:disable`
|
||
- v3.0 行为：联动禁用 SFTPGo 用户（可选）
|
||
|
||
### 2.4 SFTP 凭据管理（新增，管理员或用户自助）
|
||
（具体由你确认 v3.0 需要“用户自助”还是“管理员操作”）
|
||
|
||
#### 重置 SFTP 密码（管理员）
|
||
`POST /api/v2/users/{user_id}/sftp:reset_password`
|
||
- 返回：一次性密码（只返回一次，服务端不保存明文）
|
||
> v3.0 先只做 password 方案；SSH public key 作为后续版本可选增强（不在 v3.0 范围）。
|
||
|
||
## 3) 用户自助信息（新增）
|
||
|
||
### 3.1 获取当前用户信息
|
||
`GET /api/v2/me`
|
||
- 返回示例：
|
||
```json
|
||
{
|
||
"user_id": "alice",
|
||
"is_admin": false,
|
||
"paths": {
|
||
"home": "/private/users/alice",
|
||
"datasets": "/private/users/alice/datasets",
|
||
"models": "/private/users/alice/models",
|
||
"code": "/private/users/alice/code",
|
||
"jobs": "/private/users/alice/jobs",
|
||
"trash_jobs": "/private/users/alice/trash/jobs"
|
||
},
|
||
"retention": {
|
||
"jobs_trash_after_days": 3,
|
||
"jobs_purge_after_days": 7
|
||
},
|
||
"sftp": {
|
||
"host": "h1.example.internal",
|
||
"port": 2022,
|
||
"username": "alice"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 3.2 Jobs Retention 提示（新增）
|
||
为了支撑 WebUI 展示与用户预期管理，可在 `/api/v2/me` 或单独接口返回：
|
||
- `jobs_trash_after_days`：默认 3
|
||
- `jobs_purge_after_days`：默认 7
|
||
- `jobs_root`：`/private/users/<me>/jobs`
|
||
- `trash_jobs_root`：`/private/users/<me>/trash/jobs`
|
||
- `recommendations`：提示用户把需要长期保存的产物移动到 `models/` 或 `datasets/`
|
||
|
||
## 4) 数据浏览/下载（可选，v3.0 最小化）
|
||
|
||
说明：上传/下载主通道仍是 SFTP。
|
||
WebUI 如果要提供“快速浏览/查看”，可实现只读接口（避免实现大文件上传/断点等复杂逻辑）。
|
||
|
||
### 4.1 列目录
|
||
`GET /api/v2/files?path=/private/users/alice`
|
||
- 权限：path 必须在 `/private/common/` 或 `/private/users/<me>/` 下
|
||
- 返回：文件列表（name/type/size/mtime）
|
||
|
||
### 4.2 下载文件（小文件为主）
|
||
`GET /api/v2/files:download?path=/private/users/alice/jobs/.../logs/...`
|
||
- 返回：流式下载
|
||
- 大文件仍建议走 SFTP
|
||
|
||
## 5) TaskSpec 路径校验升级（v3.0 关键）
|
||
|
||
v2.5：仅允许 `/private/common/...`
|
||
v3.0：允许 `/private/common/...` 与 `/private/users/<me>/...`
|
||
|
||
应用字段（至少）：
|
||
- `train_file` / `val_file`
|
||
- `code_path`：仍仅允许 `/private/common/...`（v3.0 不支持执行用户 code）
|
||
- 本地模型路径字段（如果引入）：允许 `/private/users/<me>/models/...`
|
||
|
||
## 6) WebUI 路由（新增）
|
||
|
||
由 API server 托管：
|
||
- `GET /ui`：主页面
|
||
- `GET /ui/login`：token 登录页
|
||
- 静态资源：`/ui/static/...`
|
||
|
||
WebUI 的所有操作均调用同源 API（不额外开 CORS）。
|