proxy-pool/docs/api/admin.md

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 必须注入 Authorizer，标准 装配使用 httpsecurity.Protection，并在路由匹配前完成保护。网关使用的 Proxy-Authorization/407 语义不得复用到 Admin 的 Authorization/401 语义。

除契约中的 401/403/404/409/422 外，运行时还明确返回：

• 400：Request ID 或 JSON 无效。
• 405：方法不匹配，并返回 Allow。
• 413：请求体超过管理入口上限。
• 415：请求体不是 application/json。
• 500：未分类内部错误，隐藏底层错误文本。
• 503：权威控制面暂时不可用。