From 5b00ebabad05508eeccfe6685875c4ceead4ac24 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sisyphus=20=F0=9F=8F=94=EF=B8=8F?= Date: Fri, 22 May 2026 02:23:02 +0800 Subject: [PATCH] docs(patrol): update admin API, feishu interaction, and security model docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - admin-api.md: fix cron paths /api/cron/ → /admin/cron/, add restart endpoint, add API Key User Management section (5 endpoints) - feishu-integration.md: update Q&A interaction to describe CardKit v2 copy_text buttons instead of text-only response - security-model.md: add APIKeyResolver enterprise multi-user session isolation to Layer 2 description Co-Authored-By: Claude Opus 4.7 --- docs/explanation/security-model.md | 4 +- docs/reference/admin-api.md | 56 +++++++++++++++++++++------- docs/tutorials/feishu-integration.md | 4 +- 3 files changed, 47 insertions(+), 17 deletions(-) diff --git a/docs/explanation/security-model.md b/docs/explanation/security-model.md index f89b2411..d1e28aff 100644 --- a/docs/explanation/security-model.md +++ b/docs/explanation/security-model.md @@ -42,7 +42,9 @@ HotPlex Gateway 的安全模型遵循两条核心原则： ### Layer 2：Authentication（认证） -- **API Key**：Gateway 级别的访问控制 +- **API Key**：Gateway 级别的访问控制。支持两种解析模式： + - **默认模式**：所有有效 Key 映射到 `api_user`（单用户场景） + - **企业模式**（APIKeyResolver）：通过数据库映射将 Key 关联到具体用户身份，实现多用户 Session 隔离。支持 `MapResolver`（配置文件）和 `DBResolver`（SQLite）两种实现 - **JWT**：Session 级别的身份验证，携带 `user_id`、`bot_id`、`scopes` ### Layer 3：Input Validation（输入验证） diff --git a/docs/reference/admin-api.md b/docs/reference/admin-api.md index 4d98f3e1..1cc64a9c 100644 --- a/docs/reference/admin-api.md +++ b/docs/reference/admin-api.md @@ -49,8 +49,8 @@ admin: | `stats:read` | - | - | 🟢 Read | - | - | - | `GET /admin/stats`
`GET /admin/metrics` | | `config:read` | - | - | - | 🟢 Read | - | - | `POST /admin/config/validate` | | `config:write` | - | - | - | 🟠 Write | - | - | `POST /admin/config/rollback` | -| `admin:read` | - | - | - | - | 🟢 Read | 🟢 Read | `GET /admin/logs`
`GET /admin/debug/...`
`GET /admin/bots`
`GET /api/cron/jobs` | -| `admin:write` | - | - | - | - | - | 🟠 Write | `POST/PATCH/DELETE /api/cron/jobs`
`POST /api/cron/jobs/{id}/run` | +| `admin:read` | - | - | - | - | 🟢 Read | 🟢 Read | `GET /admin/logs`
`GET /admin/debug/...`
`GET /admin/bots`
`GET /admin/cron/jobs`
`GET /admin/api-keys` | +| `admin:write` | - | - | - | - | - | 🟠 Write | `POST/PATCH/DELETE /admin/cron/jobs`
`POST /admin/cron/jobs/{id}/run`
`POST/PATCH/DELETE /admin/api-keys`
`POST /admin/restart` | > 💡 **图例**：🟢 **Read** (只读查询) | 🟠 **Write** (状态变更/操作) | 🔴 **Delete** (物理删除) @@ -152,13 +152,13 @@ curl -X POST -H "Authorization: Bearer $TOKEN" \ | 方法 | 路径 | Scope | 说明 | |------|------|-------|------| -| GET | `/api/cron/jobs` | `admin:read` | 列出所有任务 | -| GET | `/api/cron/jobs/{id}` | `admin:read` | 获取单个任务 | -| POST | `/api/cron/jobs` | `admin:write` | 创建任务 | -| PATCH | `/api/cron/jobs/{id}` | `admin:write` | 更新任务 | -| DELETE | `/api/cron/jobs/{id}` | `admin:write` | 删除任务 | -| POST | `/api/cron/jobs/{id}/run` | `admin:write` | 手动触发执行 | -| GET | `/api/cron/jobs/{id}/runs` | `admin:read` | 执行历史 | +| GET | `/admin/cron/jobs` | `admin:read` | 列出所有任务 | +| GET | `/admin/cron/jobs/{id}` | `admin:read` | 获取单个任务 | +| POST | `/admin/cron/jobs` | `admin:write` | 创建任务 | +| PATCH | `/admin/cron/jobs/{id}` | `admin:write` | 更新任务 | +| DELETE | `/admin/cron/jobs/{id}` | `admin:write` | 删除任务 | +| POST | `/admin/cron/jobs/{id}/run` | `admin:write` | 手动触发执行 | +| GET | `/admin/cron/jobs/{id}/runs` | `admin:read` | 执行历史 | Cron 未启用时返回 `503 Service Unavailable`。 @@ -189,6 +189,34 @@ Bot 状态查询、配置管理和 Agent 配置文件操作端点。 **PUT /admin/bots/{name}/config/{file}`** — 写入指定 Agent 配置文件（如 `SOUL.md`、`AGENTS.md`、`USER.md`）。请求体为文件内容，Content-Type 为 `text/plain`。 +### 网关重启 + +| 方法 | 路径 | Scope | 说明 | +|------|------|-------|------| +| POST | `/admin/restart` | `admin:write` | 触发网关重启 | + +**POST /admin/restart** — 异步触发网关重启。Gateway 在 500ms 延迟后执行重启，立即返回 `{ "status": "restarting" }`。使用 `restart helper`（独立 PGID）确保安全隔离。未配置 restart handler 时返回 `503`。 + +### API Key 用户管理 + +管理 API Key 到用户身份的映射，用于企业级多用户 Session 隔离。需要数据库支持（SQLite），未配置 DB resolver 时返回 `501 Not Implemented`。 + +| 方法 | 路径 | Scope | 说明 | +|------|------|-------|------| +| GET | `/admin/api-keys` | `admin:read` | 列出所有 API Key 映射 | +| POST | `/admin/api-keys` | `admin:write` | 创建 API Key 映射 | +| GET | `/admin/api-keys/{id}` | `admin:read` | 获取单个映射详情 | +| PATCH | `/admin/api-keys/{id}` | `admin:write` | 更新映射 | +| DELETE | `/admin/api-keys/{id}` | `admin:write` | 删除映射 | + +**POST /admin/api-keys** — 创建 API Key → UserID 映射。JSON body 含 `user_id`（必填，最长 128 字符）和 `description`（可选，最长 512 字符）。API Key 由系统自动生成（32 字节随机 hex）。返回 `201 Created`。 + +**GET /admin/api-keys** — 返回所有映射列表，`api_key` 字段自动脱敏（仅显示前 8 + 后 4 位）。 + +**PATCH /admin/api-keys/{id}`** — 更新指定映射的 `user_id` 和 `description`。 + +**DELETE /admin/api-keys/{id}`** — 物理删除映射，同时清除缓存的 resolver 条目。 + ## Gateway API 端点 Gateway API（`/api/sessions`）监听在网关主端口（`8888`），面向客户端 SDK 和 WebSocket 连接，使用 API Key 或 JWT 认证（非 Bearer Token）。 @@ -205,13 +233,13 @@ Gateway API（`/api/sessions`）监听在网关主端口（`8888`），面向客 所有 Gateway API 端点启用 CORS（`Access-Control-Allow-Origin: *`），支持 `GET`、`POST`、`DELETE`、`OPTIONS` 方法。 -**POST /api/cron/jobs** — JSON body 含 `name`、`schedule`（cron:/every:/at: 前缀）、`message`、`bot_id`、`owner_id`、`enabled`。返回 `201 Created`。 +**POST /admin/cron/jobs** — JSON body 含 `name`、`schedule`（cron:/every:/at: 前缀）、`message`、`bot_id`、`owner_id`、`enabled`。返回 `201 Created`。 -**PATCH /api/cron/jobs/{id}** — 部分更新，JSON body。返回 `204 No Content`。 +**PATCH /admin/cron/jobs/{id}** — 部分更新，JSON body。返回 `204 No Content`。 -**POST /api/cron/jobs/{id}/run** — 手动触发（异步），返回 `202 Accepted`。 +**POST /admin/cron/jobs/{id}/run** — 手动触发（异步），返回 `202 Accepted`。 -**GET /api/cron/jobs/{id}/runs** — 查询执行历史。 +**GET /admin/cron/jobs/{id}/runs** — 查询执行历史。 ## 错误响应格式 @@ -255,5 +283,5 @@ curl -H "Authorization: Bearer $TOKEN" \ # 触发 Cron 任务 curl -X POST -H "Authorization: Bearer $TOKEN" \ - http://localhost:9999/api/cron/jobs/daily-health/run + http://localhost:9999/admin/cron/jobs/daily-health/run ``` diff --git a/docs/tutorials/feishu-integration.md b/docs/tutorials/feishu-integration.md index 06579357..e1ca4229 100644 --- a/docs/tutorials/feishu-integration.md +++ b/docs/tutorials/feishu-integration.md @@ -243,9 +243,9 @@ HOTPLEX_MESSAGING_TTS_MAX_CHARS=150
交互与指示器 -**权限交互**：Bot 发送确认卡片时，用户直接回复文本「允许」或「拒绝」即可，无需点击按钮。 +**权限交互**：Bot 发送确认卡片时，用户直接回复文本「允许」或「拒绝」即可。 -**Typing 指示器**：Bot 收到消息后自动添加 👀 emoji reaction，回复完成后自动移除。 +**选项交互**：当 Bot 发送多选项问题（如 AskUserQuestion）时，卡片包含可点击的复制按钮。点击按钮自动复制选项文本到剪贴板，粘贴发送即可响应。也可直接手动输入选项文本或自定义答案。 这些行为为内置默认，无需额外配置。