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

真实宿主验收速查清单

日期：2026-05-21

用途：

• 给后续每次 real-host 验收直接复用
• 只保留最短闭环，不展开历史背景
• 如果你当前是在“新增 provider”或“宿主版本升级后重新适配”，先看：PROVIDER_ONBOARDING_PLAYBOOK.md
• 详细解释仍看：REAL_HOST_ACCEPTANCE_RUNBOOK.md 与 REAL_HOST_ACCEPTANCE_LEARNINGS.md

0. 先确认你看的是真相文档

按顺序先读：

1. docs/SOURCE_OF_TRUTH.md
2. docs/EXECUTION_BOARD.md
3. docs/PRODUCTION_CLOSURE_BOARD.md

禁止：

• 直接拿历史 review/task board 顶部 gate 当当前状态
• 直接拿历史 PASS artifact 当 latest-head 当前真相

1. 环境前置检查

每次验收前先确认 4 件事：

1. 在线 CRM 进程是不是最新提交对应进程
2. PACK_PATH 是不是 CRM 进程本机可读路径
3. CRM_HOST_BASE 是不是 CRM 到宿主真实可达地址
4. 验收脚本命中的 Postgres/Redis/host 是不是目标 fresh host，而不是旧环境

若这 4 项没先确认，后续结论一律不可信。

2. channel 宿主契约检查

对每个导入 provider，必须确认 channel 最终同时具备：

• model_mapping
• model_pricing
• restrict_models=true
• billing_model_source=channel_mapped

补充规则：

• model_mapping 真实宿主接口是按 platform 嵌套结构
• model_pricing[].platform 不能留空
• existing channel 不能只复用名字，必须执行纠偏更新

一句话：

• 新建即完整
• 已存在可纠偏

3. access / key 语义检查

self_service

必须同时满足：

1. 普通用户已创建
2. 普通用户 key 已创建
3. key 已绑定目标 standard group
4. 用户有可用余额

subscription

必须同时满足：

1. 普通用户已创建
2. 普通用户 key 已创建
3. 目标 group 是 subscription 类型
4. 用户有 active subscription
5. key 已绑定该 subscription group

关键规则：

• subscription 场景最终 probe key 是宿主 managed key
• 不是外部传入原始 ACCESS_API_KEY

4. 每次都要落的三层证据

不能只看一层，必须分开留证据：

1. account 视角

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

2. 普通用户 / managed key 视角

   • GET /v1/models

3. completion 视角

   • POST /v1/chat/completions

禁止混用：

• accounts/:id/models 正确 ≠ /v1/models 正确
• /v1/models 正确 ≠ /v1/chat/completions 正确
• admin API 成功 ≠ 普通用户链路成功

5. 最短诊断顺序

如果验收失败，按这个顺序查：

1. 先查环境

   • CRM 进程版本/启动时间
   • PACK_PATH
   • CRM_HOST_BASE
   • fresh host 目标是否打对

2. 再查宿主落库

   • account credentials.model_mapping
   • GET /api/v1/admin/accounts/:id/models
   • channel model_mapping/model_pricing/restrict_models/billing_model_source

3. 最后查普通用户流量

   • /v1/models
   • /v1/chat/completions

6. 常见现象 → 优先判断

现象 A：/accounts/:id/models 对，但 /v1/models 403

优先判断：

• key 没绑 group
• subscription 没分配
• 用错了原始 probe key，没用 managed key
• self_service 缺余额

现象 B：模型列表返回成 GPT 系，而不是目标 provider 模型

优先判断：

• account credentials.model_mapping 没落对
• channel 缺 model_pricing
• channel 缺 restrict_models=true
• channel 缺 billing_model_source=channel_mapped
• 在线 CRM 还是旧进程

现象 C：/v1/models 已 200，但 /v1/chat/completions 失败

优先判断：

• host provider 兼容性
• 上游 key/quota
• 不要先回退归因为 CRM 导入失败

7. 一次验收的最小通过标准

至少同时满足：

1. import 成功，且 batch/provider 不为 failed
2. account /models 返回目标模型
3. channel 回读包含完整 routing/pricing 字段
4. /v1/models 返回目标模型

若要宣称“真实可用通过”，还必须再加： 5. /v1/chat/completions 成功

8. 一句话红线

• 不要把 /v1/models 当 completion 成功
• 不要把 account 成功当普通用户成功
• 不要把原始 ACCESS_API_KEY 当 subscription 最终 probe key
• 不要看到旧 artifact 就直接判定 current-code 失效
• 不要在没核对在线 CRM 进程版本前下 live 结论