sub2api-cn-relay-manager/docs/PROVIDER_ONBOARDING_PLAYBOOK.md

Provider Onboarding Playbook

日期：2026-05-21

目的

这份文档面向两类场景：

1. 需要把一个新的 OpenAI-compatible 国产模型中转接入到 sub2api-cn-relay-manager
2. sub2api 宿主版本发生变化后，需要快速确认现有导入链路是否仍然兼容，并稳定完成重新导入与验收

它不是当前 gate 文档，也不替代真实宿主验收步骤文档。

分工如下：

• docs/SOURCE_OF_TRUTH.md
  • 回答“当前最新真相是什么”
• docs/PROVIDER_VALIDATION_MATRIX.md
  • 回答“哪些 provider 已有模板、哪些已有官方 key、哪些已经完成 live 验收”
• docs/REAL_HOST_ACCEPTANCE_RUNBOOK.md
  • 回答“标准真实宿主验收怎么跑”
• docs/REAL_HOST_ACCEPTANCE_LEARNINGS.md
  • 回答“之前踩过哪些坑”
• 本文
  • 回答“以后要新增 provider / 宿主升级后重跑时，最稳妥的工程步骤是什么”

适用边界

本文假设：

1. 目标上游是 OpenAI-compatible 接口
2. 目标宿主仍然是 sub2api
3. 控制面仍然遵守当前 PRD 首版范围：
   • 不修改宿主源码
   • 不写宿主数据库
   • 通过宿主管理 API 完成 group/channel/account/subscription 等资源编排

如果未来要接入“非 OpenAI-compatible”上游，这份文档只能复用框架，不能直接照抄字段约定。

先记住 8 条不变量

后续所有操作都围绕这 8 条不变量展开。只要其中一条被破坏，导入就容易出现“看起来像通了，实际上没通”的假阳性。

1. provider 的 account 视角模型暴露必须正确

   • credentials.model_mapping 必须真实落到宿主 account
   • GET /api/v1/admin/accounts/:id/models 必须返回目标 provider 模型，而不是 GPT 默认集

2. channel 的网关视角模型约束必须完整

   • model_mapping
   • model_pricing
   • restrict_models=true
   • billing_model_source=channel_mapped
   • 这四项缺一不可

3. access ready 不能只看 /v1/models

   • 当前代码已经把 ready gate 提升到 completion 层
   • 必须同时通过 /v1/models 和 /v1/chat/completions

4. subscription 和 self_service 的 probe key 语义不同

   • subscription 最终 probe key 是宿主 managed key
   • self_service 最终 probe key 是普通用户 gateway key

5. self_service 普通用户 key 的真实认证方式是 Authorization: Bearer

   • 不是 x-api-key

6. account test 不能默认回退到 gpt-5.4

   • 必须显式传 provider.SmokeTestModel
   • 否则会把非 GPT provider 错误判成 failed

7. remote/provider 验收要保留 upstream 直探证据

   • upstream /models
   • upstream /chat/completions
   • 21-summary.json

8. shared fresh-host 上 reconcile=drifted 不能直接覆盖 import/access 成功结论

   • 先看 05-import.json
   • 再看 07-access-status.json
   • 最后才解释 09-reconcile.json

一图理解完整链路

把一次稳定 onboarding 看成 5 个阶段：

1. 定义 provider
2. 落 pack
3. 导入宿主
4. 验证 access
5. 固化 artifact 与经验

只有这 5 个阶段都闭环，后续宿主升级或换 key 时才能快速复用。

阶段 1：定义 provider

1.1 先判断这个上游是否值得接

最先回答 5 个问题：

1. base_url 是否稳定，是否明确兼容 OpenAI-style /models 与 /chat/completions
2. 是否有至少一个可用于真实 completion 的 key
3. 上游返回的模型名是否稳定，是否可能带 vendor/model 前缀
4. 这个 provider 目标走 self_service、subscription，还是两者都要支持
5. 是否需要独立的 host 兼容性结论，而不是直接复用别的 provider 结论

如果连第 2 条都不满足，就不要把“导入失败”先归因为控制面。

1.2 provider 清单里必须关注的字段

至少明确这些信息：

1. provider_id
2. platform
3. default_model
4. smoke_test_model
5. channel_template.model_mapping
6. channel_template.model_pricing
7. account_template.credentials.model_mapping

经验规则：

• smoke_test_model 不要留空
• default_model 和 smoke_test_model 可以相同，但不要依赖宿主默认值
• 若 upstream 返回模型名带厂商前缀，要在验收脚本侧考虑归一化，而不是强行修改上游

1.3 什么时候要新增模型别名归一化

如果你看到的是这类模型名：

• deepseek-ai/DeepSeek-V4-Pro
• vendor-x/model-y

而 pack 里写的是：

• deepseek-v4-pro
• model-y

就不要把 upstream_models_has_expected_model=false 直接当失败。先补脚本归一化规则，再看真实 chat 是否通。

阶段 2：落 pack

2.1 最小改动原则

优先只改下面几类文件：

1. packs/openai-cn-pack/providers/<provider>.json
2. 必要时更新 checksums.txt
3. 若需要测试临时线路，优先复制出临时 pack，不要先污染正式 pack

不要为了一个新 provider 先改控制面逻辑。先让 pack 描述能力足够完整，再判断是否真的需要动 Go 代码。

2.2 pack 完成后的本地静态检查

至少确认：

1. pack 能被 loader 成功读取
2. provider schema 通过
3. checksum 对齐
4. smoke_test_model 非空

如果 pack 里已经缺字段，后面的导入问题会越来越难解释。

阶段 3：导入宿主

3.1 导入前先选 access mode

两条链路语义不同，不要混着看。

self_service：

1. 目标用户真实存在
2. 普通用户 key 可用
3. key 已绑定目标标准 group
4. 用户有可用余额

subscription：

1. 目标用户真实存在
2. 普通用户 key 可用
3. 目标 group 是 subscription 类型
4. 用户有 active subscription
5. key 已绑定该 subscription group

3.2 导入时最容易漏掉的三件事

1. account credentials.model_mapping

   • 漏掉就会回退 GPT 默认模型集

2. channel model_pricing

   • 只有 model_mapping 不够

3. account test 的 provider.SmokeTestModel

   • 不显式传递就可能被宿主默认拿 gpt-5.4 去测

3.3 既有 channel 与新建 channel 的处理方式不同

对于新建 channel：

• 创建时就要带全量字段

对于既有 channel：

• 不能假设历史字段完整
• 必须走 update 纠偏

如果 live host 上出现“有 model_mapping 但没有 model_pricing”，先别急着怀疑当前代码。先确认在线 CRM 进程是不是旧版本。

阶段 4：验证 access

4.1 必须分三层落证据

每次 onboarding 至少保留这三层：

1. account 单体视角

   • GET /api/v1/admin/accounts/:id
   • GET /api/v1/admin/accounts/:id/models

2. group / 普通用户聚合视角

   • GET /v1/models

3. completion 视角

   • POST /v1/chat/completions

任何时候都不要用前一层去替代后一层。

4.2 当前 completion-gated 判定标准

对外宣称 ready 之前，至少要满足：

1. /v1/models 命中目标 smoke_test_model
2. /v1/chat/completions 返回成功

否则最多只能说：

• 模型暴露对了
• 还不能说真实调用链路对了

4.3 upstream 直探的意义

当 host chat 失败时，必须做 upstream 直探，目的是把问题分成两类：

1. host_compatibility_gap

   • host /chat/completions 失败
   • upstream /chat/completions 成功

2. upstream_key_quota_issue

   • upstream 自己就失败

这一步非常关键，因为它决定后续是修控制面、提宿主 issue，还是换 key。

阶段 5：固化 artifact 与经验

5.1 哪些 artifact 算“最终有效证据”

只有这类证据值得长期保留：

1. latest-head
2. fresh-host
3. 同时包含 import/access/status/reconcile/rollback 或至少 import + access + completion
4. 已能解释失败分类或通过结论

中间大量半失败、参数错误、旧进程产物，不要全部纳入版本库。

5.2 文档必须同步的三处

每次完成一次新的 provider onboarding 或宿主版本重适配，至少同步：

1. docs/EXECUTION_BOARD.md
2. docs/SOURCE_OF_TRUTH.md
3. 本文或 docs/REAL_HOST_ACCEPTANCE_LEARNINGS.md

同步原则：

• 执行板写当前真相
• 真相索引写当前优先证据
• playbook / learnings 写可复用方法和误判点

宿主版本变更时的稳定重验流程

如果 sub2api 宿主版本升级了，不要立刻重跑全套试错。按下面顺序来。

第一步：先验证宿主契约有没有变

重点确认 6 个点：

1. channel create/update 的字段契约有没有变
2. accounts/:id/test 是否仍接受显式模型
3. /v1/models 的普通用户认证语义有没有变
4. /v1/chat/completions 的普通用户认证语义有没有变
5. subscription key/group/balance 前置有没有变
6. admin bearer/api-key 认证入口有没有变

如果这一步没确认，后面所有“导入失败”都没有解释力。

第二步：只挑一个最稳定的 provider 先复验

推荐顺序：

1. 先挑一条历史上最稳定、completion 已验证通过的 provider
2. 先跑 subscription
3. 再跑 self_service

原因很简单：

• 这样可以先区分“宿主整体契约变了”还是“某个 provider 自己有问题”

第三步：再放大到 provider matrix

当基线 provider 通过后，再去补：

1. 新 provider
2. 较不稳定中转
3. 多 key / replacement account / reconcile / rollback 场景

新增 provider 的推荐最短路径

如果目标是“尽快把一个新 provider 接入并完成真实验收”，建议按这个顺序：

1. 准备 provider JSON
2. 明确 smoke_test_model
3. 明确 model_mapping 与 model_pricing
4. 用临时 pack 跑 dry-run
5. 跑一轮 fresh-host subscription
6. 验证三层证据
7. 跑 upstream /models 与 /chat/completions
8. 若通过，再补 self_service
9. 固化 artifact
10. 更新文档板面

不要一开始就：

• 同时改 pack、脚本、Go 逻辑、多个 provider
• 同时在多个宿主环境上跑
• 同时把 self_service 与 subscription 混成一个结论

常见失败与最短定位法

现象 1：/accounts/:id/models 正确，但 /v1/models 错

优先检查：

1. key/group 绑定
2. subscription 分配
3. 普通用户余额
4. probe key 语义是否用错

现象 2：/v1/models 正确，但 /chat/completions 失败

优先检查：

1. host /chat/completions
2. upstream /chat/completions
3. 21-summary.json

现象 3：provider 导入成功，但 account probe 失败

优先检查：

1. provider.SmokeTestModel 是否真的传到了 /accounts/:id/test
2. SSE type=error 是否被正确解析
3. 宿主默认模型是否回退到了 GPT

现象 4：CRM 显示 self_service broken，但用户 key 直打宿主已经通

优先检查：

1. gateway probe 是否错误用了 x-api-key
2. 在线 CRM 进程是否已切到最新修复版本

现象 5：刚升级宿主后，最前面的 create-host/probe-host 就失败

优先检查：

1. host bearer token 是否过期
2. host admin auth 契约是否变更
3. 不要先把它归因为 provider 本身问题

推荐沉淀模板

每新增一个 provider，建议至少补这 6 项记录：

1. provider 名称与 base_url
2. smoke_test_model
3. subscription 是否通过
4. self_service 是否通过
5. upstream /models 与 /chat/completions 是否稳定
6. 当前已知限制或宿主兼容性差异

最后结论

把新增 provider 做稳定，不在于“多快把 key 导进宿主”，而在于这 4 件事是否同时完成：

1. pack 定义完整
2. access gate 真实闭环
3. upstream 失败能分层归因
4. 经验和证据能复用

如果只完成前两项，系统还只是“能跑一次”。 只有四项都完成，后续宿主升级、换 key、补 provider 时才会稳定且快。