44 lines
2.3 KiB
Markdown
44 lines
2.3 KiB
Markdown
# Admin API
|
||
|
||
Admin API 使用独立监听器与权限，契约位于 `api/openapi/admin.yaml`。公网部署
|
||
不得与 Distribution 复用认证 Token；推荐只绑定管理网段或回环地址。
|
||
|
||
## 端点
|
||
|
||
- `GET /api/v1/status`：返回配置/快照版本、Upstream 聚合计数和 Worker 状态。
|
||
- `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`，避免并发操作跳过多个供应商。
|
||
|
||
配置重载校验失败返回 422，旧配置继续运行。Status 只返回低基数聚合信息，
|
||
不得返回 Proxy 地址、凭据、Client 标识或完整 Provider URL。
|
||
|
||
## 运行时实现边界
|
||
|
||
`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`，任一
|
||
监听器异常会触发同组端点的有界优雅停机。
|
||
|
||
除契约中的 401/403/404/409/422 外，运行时还明确返回：
|
||
|
||
- `400`：Request ID 或 JSON 无效。
|
||
- `405`：方法不匹配，并返回 `Allow`。
|
||
- `413`：请求体超过管理入口上限。
|
||
- `415`：请求体不是 `application/json`。
|
||
- `500`：未分类内部错误，隐藏底层错误文本。
|
||
- `503`：权威控制面暂时不可用。
|