94 lines
5.7 KiB
Markdown
94 lines
5.7 KiB
Markdown
# Admin API
|
||
|
||
Admin API 使用独立监听器与权限，契约位于 `api/openapi/admin.yaml`。公网部署
|
||
不得与 Distribution 复用认证 Token；推荐只绑定管理网段或回环地址。
|
||
|
||
## 端点
|
||
|
||
- `GET /api/v1/status`：返回配置/快照版本、Upstream 聚合计数和 Worker 状态。
|
||
- `GET /api/v1/audit`：按审计记录 ID 升序读取权威管理面的变更记录。
|
||
- `POST /api/v1/upstreams/{name}/enable`：启用 Upstream。
|
||
- `POST /api/v1/upstreams/{name}/disable`：停止新 Fetch/分配并自然 Drain。
|
||
- `POST /api/v1/routing/{name}/switch`：用 expectedCurrent 做 CAS 手工切换。
|
||
- `POST /api/v1/config/reload`：严格解析并原子发布新配置。
|
||
|
||
所有写操作写审计记录并返回最终 Request ID 与版本。Enable/Disable 对目标状态
|
||
幂等；Routing Switch 必须携带 `expectedCurrent`，避免并发操作跳过多个供应商。
|
||
|
||
## 授权
|
||
|
||
认证成功后的权限由 Listener `auth.permissions` 或 `auth.methods[].permissions` 提供。
|
||
`admin:read` 允许 Status 与审计查询；`admin:write` 允许 Upstream 启停、Routing
|
||
切换和配置重载。每个权限独立匹配，写权限不隐含读权限；未配置权限的旧凭据保持
|
||
全权限兼容。`mode: any` 使用实际命中凭据的方法级权限。权限不足返回 `403`，不会
|
||
调用 Service、写审计或触发配置发布。
|
||
|
||
配置重载校验失败返回 422，旧配置继续运行。Status 只返回低基数聚合信息，
|
||
不得返回 Proxy 地址、凭据、Client 标识或完整 Provider URL。
|
||
|
||
## 审计分页与数据范围
|
||
|
||
`GET /api/v1/audit` 使用 `afterId` 排他游标分页：响应只包含 `id` 大于
|
||
`afterId` 的记录，并按 `id` 升序排列；未传时 `afterId` 为 `0`。未传 `limit`
|
||
时服务端使用 `100`；
|
||
`limit` 必须为 `1..1000`，其中 `1000` 等于 `adminstate.MaxPageSize`。客户端应将
|
||
本页最后一条记录的 `id` 作为下一次请求的 `afterId`；空 `records` 表示当前游标后
|
||
没有记录。
|
||
|
||
该接口仅暴露管理面变更记录及操作者标识、可信来源 IP、操作类型、资源标识、变更
|
||
状态、控制面版本、原因和发生时间。它不返回 Proxy、任何 Upstream/Provider URL、
|
||
凭据或 Secret、Provider 响应载荷，也不读取或暴露 Redis 活动池及其提取状态。
|
||
|
||
## 运行时实现边界
|
||
|
||
`admin.Handler` 只依赖 `Service` 控制面接口，不直接操作数据库、路由游标或配置
|
||
文件。Service 必须保证 Status 来自同一修订快照，并将状态变更、审计和 Outbox
|
||
放在同一权威提交边界中。`MutationResult.version` 表示已提交的全局控制面修订，
|
||
不能混用配置格式版本或单 Worker Snapshot 版本。
|
||
|
||
严格 JSON、请求体上限、Request ID、JSON/Problem 响应由
|
||
`platform/httpapi` 公用实现提供。Admin Handler 必须注入 `IdentityResolver`，
|
||
标准装配使用 `httpsecurity.Protection`，并在路由匹配前完成保护。解析出的
|
||
Actor ID 与可信 SourceIP 会进入所有 mutation 命令，但认证材料不会进入审计。
|
||
网关使用的
|
||
`Proxy-Authorization`/407 语义不得复用到 Admin 的 `Authorization`/401 语义。
|
||
`controller/runtime` 将 Admin 与 Distribution 放在不同 `net.Listener`，任一
|
||
监听器异常会触发同组端点的有界优雅停机。
|
||
|
||
`admin.ApplicationService` 把 Handler DTO 映射到 `adminstate` 公用事务命令。
|
||
Status 以一个权威管理快照决定 Upstream 集合和 Enabled 状态，只从注入的运行态
|
||
读取器补充低基数计数、Worker 与已发布 Snapshot 版本。配置重载顺序固定为：
|
||
|
||
1. `FileConfigurationLoader` 通过 `config.LoadResolved` 严格解析、解析 Secret 引用
|
||
并完成全量校验。
|
||
2. 使用独立外部密钥对完整已解析配置计算 HMAC-SHA-256 指纹；PostgreSQL 只保存
|
||
不透明 HMAC，不保存密钥、配置正文或 Secret 明文，因此 URL、模板和 Secret
|
||
轮换都会产生新版本，也不能借数据库摘要离线猜测低熵 Secret。
|
||
3. 在同一 `adminstate` mutation 中提交配置修订、管理状态、审计和 Outbox。
|
||
4. 提交成功后由 `config.Store` 按 PostgreSQL revision 原子发布完整运行配置；
|
||
Store 只接受严格递增 revision，提交失败或迟到旧 revision 不覆盖当前配置。
|
||
幂等重放仅在本地 revision 落后时修复进程状态。
|
||
5. Provider Supervisor 在提交前构造预检所有启用 Upstream；发布后按新配置取消、
|
||
替换或新增 Runtime。enable 同样在管理状态 mutation 前预检目标 Runtime。
|
||
6. 其他 Controller 每秒比较本地指纹与 PostgreSQL 权威指纹；所有副本必须使用
|
||
相同 `PROXY_POOL_CONFIG_FINGERPRINT_KEY`。共享配置源已同步时严格重载、预检
|
||
并按 revision 发布，源尚未同步时停止旧 Provider Runtime，禁止旧 URL/Secret
|
||
在换主后继续调用。
|
||
|
||
disable 成功后会立即通知 Supervisor 取消目标 Runtime；每秒一次的权威状态对账
|
||
用于修复进程内通知丢失。已取得的分布式 Permit 仍按幂等、保守规则完成结算。
|
||
PostgreSQL 瞬时读取失败不会终止 Controller 或取消当前 Provider Runtime；
|
||
Supervisor 保留 last-known 状态并在下一周期重试。
|
||
|
||
主配置或 Secret 文件 I/O 故障归类为 503；语法、未知字段、引用和语义校验失败
|
||
归类为 422。请求取消和截止时间保持原始上下文错误，不误报为配置错误。
|
||
|
||
除契约中的 401/403/404/409/422 外，运行时还明确返回：
|
||
|
||
- `400`：Request ID 或 JSON 无效。
|
||
- `405`：方法不匹配，并返回 `Allow`。
|
||
- `413`：请求体超过管理入口上限。
|
||
- `415`：请求体不是 `application/json`。
|
||
- `500`：未分类内部错误，隐藏底层错误文本。
|
||
- `503`：权威控制面暂时不可用。
|