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 必须注入 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. 从脱敏管理投影计算版本与校验和；Secret 值及其可验证摘要不进入管理状态。
3. 在同一 adminstate mutation 中提交配置修订、管理状态、审计和 Outbox。
4. 提交成功后由 config.Store 一次原子指针交换发布完整运行配置；提交失败时旧 配置保持不变。幂等重放仍执行发布，以修复进程本地状态。

主配置或 Secret 文件 I/O 故障归类为 503；语法、未知字段、引用和语义校验失败 归类为 422。请求取消和截止时间保持原始上下文错误，不误报为配置错误。

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

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