AI 网关管理员手册：渠道上线、重试与供应商健康

小白：先认清四个控制台入口

/console/channel 管渠道、模型、权重与测试；/console/channel-health 看成功率、错误与临时状态；/console/adapter-workbench 管供应商、账户、目录扫描与价格；/console/setting 管全局重试等设置。它们是受保护的管理面，不是给业务客户端调用的公开 AI API。

渠道管理组要求运营身份与“渠道”权限；批量图片存储开关还要求管理员。读取单个渠道密钥额外要求 Root、关键操作限流、禁缓存和安全验证。密钥不得放进工单、截图、浏览器地址、查询参数或普通日志。

上线前配置清单

新渠道先隔离，逐项确认：渠道类型与真实上游一致；base_url 只写可信 HTTPS 地址；密钥权限最小化；models 是上游真实可用集合；model_mapping 的入口名与上游名方向正确；分组、优先级和权重不会意外抢占生产流量；工具、流式、图片、音频和异步能力分别测试。

Copy{
  "name": "provider-canary",
  "type": "与实际适配器一致",
  "base_url": "https://trusted-upstream.example/v1",
  "models": "model-a,model-b",
  "model_mapping": {"public-model-a": "model-a"},
  "group": "canary",
  "priority": 0,
  "weight": 0
}

这是核对结构，不是可直接提交的完整请求。密钥不应出现在文档或自动化日志；实际保存使用控制台表单，并保持渠道未进入生产分组，直到验证完成。

单渠道测试、灰度与回滚

保存后用 POST /api/channel/test/{id}/run 做指定模型与协议测试；旧的 GET /api/channel/test/{id} 仍存在，但新测试入口能表达更完整的目标。测试只证明该样例在当时成功，不能替代真实端点、长上下文、流式、工具和媒体合约测试。

灰度时固定小流量或独立分组，记录变更人、时间、模型、价格和回滚条件。观察 /api/channel/success_rate、/api/channel/error_stats 与 24 小时调用量；达到错误率、p95 延迟、账单偏差或内容质量阈值就恢复原权重/状态。POST /api/channel/{id}/reset_temporary_state 只清理临时路由状态，不会修复凭据、余额或协议错误。

重试与幂等边界

普通转发的有效策略来自全局 RetryTimes、RetryTimeoutSeconds，模型元数据可用 max_retries 与 retry_timeout_seconds 覆盖；请求开始后策略会冻结。0 次表示不重试，时间预算 0 表示不额外限制累计重试时间，并不代表请求永不超时。

默认不会重试 400、408、504、524、已开始向客户端返回的响应、指定固定渠道、明确不可重试错误或客户端已取消的请求。可配置的状态码规则只是候选条件；媒体创建、工具副作用和任何上游可能已接受的操作仍需幂等判断。系统会限制 Retry-After 等待，且剩余客户端截止时间不足时不再发起新尝试。

冷却、自动禁用与人工处置

进程内渠道健康保护默认连续失败 3 次后冷却 30 秒，可用 CHANNEL_HEALTH_FAILURE_THRESHOLD 与 CHANNEL_HEALTH_COOLDOWN_SECONDS 调整；成功会清除连续失败状态。该状态保存在当前进程内，不应被当作跨节点、持久化熔断器。优先级和路由策略还可能改变实际恢复探测节奏。

自动禁用是独立规则，默认状态码范围包含 401。认证错误应先轮换或修复凭据，余额错误先核对供应商账户，参数错误先修模型映射；不要通过清状态或无限重试掩盖根因。恢复前先做一次窄测试，再逐步放量。

供应商、账户和目录健康

供应商目录回答“上游声称提供什么”，渠道测试回答“当前凭据和协议能否调用”，模型广场回答“本站实际开放什么”，三者不能互相替代。使用 /api/suppliers/catalog/supplier-health 看目录扫描健康，使用 /api/supplier_accounts/health/summary、余额最新值/趋势和账户事件判断凭据或资金问题。

目录扫描、价格同步和模型映射是管理变更：先预览差异，确认模型来源、快照、单位和币种，再应用到渠道。告警目标配置、密钥揭示、凭据写入和批量切流具有更高权限，必须记录操作者、审批与结果。

专家：观测、故障树与交接

每次尝试关联 Request-ID、请求模型、映射后模型、渠道 ID、供应商账户、尝试序号、状态码、错误类别、上游 Request-ID、用量、价格版本和最终结算。先按故障树分类：所有渠道失败看入口/模型/策略；单渠道失败看凭据/区域/协议；单账户失败看余额/封禁；单模型失败看映射/生命周期；仅流式或媒体失败看专用协议与结果存储。

交接文档至少包含渠道所有者、数据区域、配额、余额阈值、支持端点、允许模型、回滚动作和上游状态页。每次凭据、Base URL、映射、重试或权重变更后重跑合约测试；不要把原始密钥、提示词、Base64、签名 URL 或供应商私密成本写入普通观测标签。