ADR-005: hermesx-webui Admin Bootstrap 端点设计¶

决策信息¶

字段	值
编号	ADR-005
标题	POST /admin/v1/bootstrap — 首次部署超管引导端点
状态	Accepted
日期	2026-05-08
Owner	architect + backend-engineer
关联需求	docs/artifacts/2026-05-08-hermesx-webui/prd.md (US-Bootstrap)

背景与约束¶

PRD 决策 #3：首次部署时若无 admin key，展示 Bootstrap 引导页，通过 HERMES_ACP_TOKEN 完成首个 admin key 创建。
挑战会发现：ACP（Agent Communication Protocol）是编辑器集成协议包，不是 admin 引导 token 机制。
internal/acp/ 包实现了 editor ↔ agent 的 JSON-RPC 协议
HERMES_ACP_TOKEN 是静态 bearer，由 StaticTokenExtractor 在 auth chain 中处理，赋予 system:acp-admin identity
因此，Bootstrap 流程可以复用 HERMES_ACP_TOKEN 作为一次性授权凭证，但需要独立的 Bootstrap 端点
当前无 GET /admin/v1/tenants/{id}/api-keys 接口（已在 intake 识别为 backend gap）。

设计决策¶

Bootstrap 端点规格¶

GET /admin/v1/bootstrap/status¶

无需认证（公开端点）
响应：{"bootstrap_required": true} — 当 DB 中 admin role 的 API key 数量为 0 时返回 true
前端用途：页面加载时检查，决定展示"登录"还是"Bootstrap 引导"

POST /admin/v1/bootstrap¶

认证：Authorization: Bearer <HERMES_ACP_TOKEN>（静态 token，仅在初始化阶段已知）
请求体：{"name": "initial-admin-key", "expires_at": "2027-01-01T00:00:00Z"}
逻辑：
验证 ACP token（通过现有 StaticTokenExtractor chain）
原子检查：若 admin API key 数量 > 0，返回 403 Forbidden {"error": "bootstrap already completed"}
创建 API key，roles: ["admin"]，scopes: ["admin", "chat", "read"]
返回明文 key（唯一一次返回明文）：{"api_key": "hx-...", "key_id": "...", "name": "..."}
安全门：端点在 bootstrap_required=false 时返回 403，防止重复调用

GET /admin/v1/tenants/{id}/api-keys¶

新增接口，列出租户下所有 API keys（掩码展示）： - 认证：admin API key（RequireScope("admin")） - 响应：{"api_keys": [{"id": "...", "name": "...", "prefix": "hx-...", "roles": [...], "scopes": [...], "expires_at": "...", "revoked_at": null, "created_at": "..."}]} - 实现：查询 api_keys 表，按 tenant_id 过滤，不返回 key_hash

前端 Bootstrap 流程¶

GET /admin/v1/bootstrap/status
  → {bootstrap_required: true}  → BootstrapPage.vue
  → {bootstrap_required: false} → AdminLoginPage.vue

BootstrapPage.vue:
  1. 用户输入 HERMES_ACP_TOKEN（运维人员提供）
  2. 输入新 admin key 名称和过期时间
  3. POST /admin/v1/bootstrap → 显示一次性明文 key（复制后确认关闭）
  4. 跳转 AdminLoginPage，用新 key 登录

安全说明¶

HERMES_ACP_TOKEN 不存储在前端，仅用于一次性 POST 请求，不放 sessionStorage
Bootstrap 端点在正式运行后永久返回 403（因为 admin key 已存在）
明文 key 只在 POST /admin/v1/bootstrap 响应中出现一次，后端只存 SHA-256 hash

后续动作¶

动作	Owner	完成条件
实现 GET /admin/v1/bootstrap/status	backend-engineer	Phase 0
实现 POST /admin/v1/bootstrap	backend-engineer	Phase 0
实现 GET /admin/v1/tenants/{id}/api-keys	backend-engineer	Phase 0
前端 BootstrapPage.vue	frontend-engineer	Phase 1
前端 Bootstrap 状态检查集成到 AdminApp 启动	frontend-engineer	Phase 1