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

# 真实宿主验收经验与已调通细节

日期：2026-05-21

## 目的

这份文档不替代 `docs/REAL_HOST_ACCEPTANCE_RUNBOOK.md`，而是把已经在线下真实打通过、以及多次踩坑后确认的细节沉淀下来，避免后续重复误判。

建议阅读顺序：
1. `docs/EXECUTION_BOARD.md` —— 看当前 gate 与最新真相
2. `docs/REAL_HOST_ACCEPTANCE_RUNBOOK.md` —— 看标准执行步骤
3. 本文 —— 看调试经验、误判点、诊断顺序

## 已经确认打通的事实

1. account 视角模型暴露可以正确落库
   - CRM 在 account 创建/导入时写入 `credentials.model_mapping`
   - 宿主 `GET /api/v1/admin/accounts/:id/models` 已能返回目标 provider 模型，而不是一律回退到 GPT 默认集合
   - DeepSeek / MiniMax 都已在 live 验收中确认

2. channel 视角模型映射与定价可以正确落库
   - channel 创建时需要同时下发：
     - `model_mapping`
     - `model_pricing`
     - `restrict_models=true`
     - `billing_model_source=channel_mapped`
   - 对既有 channel，CRM 需要走 `UpdateChannel` 做纠偏；这一点已在 latest-head fresh rerun 上确认生效
   - 旧现象“MiniMax channel 有 model_mapping 但没有 pricing”已经被 `ca1d448` 修复并完成 live 验证

3. subscription 场景的真实 probe key 语义已经确认
   - closure 最终用于宿主 `/v1/models` 探测的，不是外部传入的原始 `access_api_key`
   - 真正使用的是 CRM 在宿主侧创建/查找出来的 managed key（`sk-relay-*` 风格）
   - 因此 subscription 验收如果直接拿调用方原始 probe key 去打 `/v1/models`，出现 `403 not assigned to any group` 并不代表 CRM 主链路失败，而是 probe key 用错了

4. group 聚合视角与 account 单体视角必须分开看
   - `GET /api/v1/admin/accounts/:id/models` 是 account 单体视角
   - `GET /v1/models` 是普通用户 key + group 聚合视角
   - 二者语义不同，不能互相替代
   - 正确诊断顺序应该是：
     1) 先看 account models 是否正确
     2) 再看 managed key 视角 `/v1/models` 是否正确
     3) 最后才看 completion smoke 是否通过

## 宿主源码再次确认的设计逻辑

这部分不是基于 artifact 推断，而是直接对照 `sub2api-official-fresh` 宿主源码确认：

1. channel admin handler 的真实入参契约
   - `backend/internal/handler/admin/channel_handler.go`
   - `model_mapping` 的真实结构是 `map[string]map[string]string`
   - `model_pricing` 是独立数组字段，不会从 `model_mapping` 自动推导
   - `billing_model_source` 合法值包括 `channel_mapped`
   - `restrict_models` 是独立布尔开关

2. channel pricing platform 为空时，宿主会回退到 `anthropic`
   - create/update handler 都会在入参 platform 为空时补默认值
   - repository `createModelPricingExec` 也会把空 platform 写成 `anthropic`
   - 这意味着 CRM 若不给 OpenAI-compatible provider 显式写 platform，宿主会按 anthropic 语义处理，不能接受
   - 因此 CRM 当前策略必须是：
     1) 先用 provider platform
     2) 若调用侧仍为空，再回退 `openai`

3. gateway `/v1/models` 与 completion 共享同一套 API key middleware 前置校验
   - `backend/internal/server/middleware/api_key_auth.go`
   - 它先校验：
     - key 有效
     - user active
     - IP 限制
     - group / subscription / balance 前置
   - 所以 `/v1/models` 的 403/429 通常首先反映的是 key/group/subscription/balance 约束，而不等同于 account/channel 落库失败

4. subscription group 的 key 绑定条件与 standard group 不同
   - `backend/internal/service/api_key_service.go`
   - standard group：走 `user.CanBindGroup(...)`
   - subscription group：走 `GetActiveByUserIDAndGroupID(...)`
   - 也就是说，subscription 场景里“group 已存在”或“allowed_groups 已写入”都不够，必须有 active subscription

5. user 自助创建 key 与 admin 绑定 group 是两步
   - `backend/internal/handler/api_key_handler.go` + `api_key_service.go`
   - user 侧 `POST /api/v1/api-keys` 可创建带 `custom_key` 的 key
   - CRM managed key 流程里，先以普通用户身份创建 key，再用 admin `PUT /api/v1/admin/api-keys/:id` 绑定 group
   - 这与我们当前 `EnsureSubscriptionAccess` 的两阶段实现一致

## 已调通的宿主侧前置动作

### self_service

至少满足：
1. 普通用户已真实创建
2. 普通用户 key 已生成且可用
3. 该 key 已绑定目标标准 group
4. 用户具备可用余额

经验结论：
- 若只做了 key/group 绑定但没余额，`/v1/models` 可能从 403 进入 `INSUFFICIENT_BALANCE`
- 这不是 CRM 导入逻辑失败，而是宿主运营前置未完成

### subscription

至少满足：
1. 普通用户已真实创建
2. 普通用户 key 已生成且可用
3. 目标 group 是 `subscription` 类型
4. 普通用户已完成 subscription 分配
5. 普通用户 key 已绑定该 subscription group

经验结论：
- 只有管理员主体、只有 group、或者只有 subscription 记录都不够
- 必须把“普通用户 + key + group + subscription”整条链补齐，`/v1/models` 才会稳定通过

## 已确认的高频误判点

1. 把 `/accounts/:id/models` 和 `/v1/models` 混为一谈
   - 前者对，后者错，不代表 account 落库失败；往往是 key/group/subscription 问题

2. 用错 probe key
   - subscription 场景拿原始 `access_api_key` 直打宿主 `/v1/models`，很容易得到 403
   - 这时应先回到 closure 结果或 managed access 证据，而不是先否定产品链路

3. 旧 CRM 进程误导当前结论
   - live 行为必须先确认运行中的 CRM 进程是否真的包含最新提交
   - 之前 MiniMax existing channel 没自动补 `model_pricing`，最终确认根因就是在线 CRM 进程早于修复提交 `ca1d448`
   - 如果看到“有 `model_mapping` 但 `model_pricing=[]`”，不要立刻判定 current-code 仍未执行 `UpdateChannel`；先核对该 artifact 是否本来就是旧进程产物

### MiniMax `model_pricing=[]` 误判的已确认根因时间线

1. 旧进程先创建了半成品 channel
   - 证据：`artifacts/real-host-acceptance/20260520_222713_crm18100_live_model_mapping_validation/summary.json`
   - 其中 MiniMax `host_channel.data.id=5`
   - `model_mapping` 已有值，但 `model_pricing=[]`
   - 且 `created_at=updated_at=2026-05-20T20:39:23Z`
   - 这说明当时只是旧逻辑创建了 channel，没有发生后续 `UpdateChannel` 纠偏

2. 新代码已经具备纠偏能力，但必须由新进程实际执行
   - `ca1d448` 之后，代码路径已改为：
     - 新建 channel 时直接携带完整 `model_pricing`
     - 命中既有 channel 时执行 `UpdateChannel`
   - 所以判断“修复是否生效”时，不能只看仓库 HEAD，必须看 18100 监听进程的真实启动时间与实际 DB

3. 当前 18100 新进程已在 live host 上完成纠偏
   - 18100 新进程启动时间：`2026-05-21 01:08`
   - 当前真实 DB：`/tmp/sub2api-relay-manager-realhost-18100.db`
   - 当前 host admin 直查 `GET /api/v1/admin/channels/5` 可见：
     - `model_pricing` 非空
     - `model_mapping` 仍正确
     - `updated_at=2026-05-21T06:45:00Z`
   - 这证明新进程已经真正执行过 `UpdateChannel`，MiniMax 既有 channel 已被纠偏

4. 最终结论
   - “MiniMax channel 有 mapping 但无 pricing”不是 current-code 仍缺失 `UpdateChannel`
   - 真相是：旧 artifact 反映的是旧 CRM 进程产物；切到新进程并 fresh rerun 后，该问题已被 live 修复

4. `PACK_PATH` 使用了 operator 机器的概念路径，而不是 CRM 进程本机可读路径
   - 当 CRM 改在本机运行时，继续传远端 `/home/ubuntu/...` 会直接触发 `stat pack path ... no such file or directory`
   - 这个报错属于验收 harness / 环境参数问题，不是 import 业务逻辑问题

5. remote43/fresh-host 的 Postgres/Redis 容器目标写错
   - 若脚本仍打到旧 relaymgr 宿主，会看到 managed user / key / subscription 状态为空或串台
   - 需要确保脚本明确指向 fresh host 对应的 `{postgres,redis}` 容器

6. 把 `/v1/models` 已通误认为 completion 也一定通
   - 这不成立
   - 当前最新真相就是：DeepSeek / MiniMax 的 `/v1/models` 可以 200，但 `/v1/chat/completions` 仍可能因为 host 兼容性或上游 quota 问题失败

## 推荐诊断顺序

### 一、先确认是不是环境/脚本问题

1. 确认当前运行 CRM 的提交版本与启动时间
2. 确认 `PACK_PATH` 是 CRM 本机可读路径
3. 确认 `CRM_HOST_BASE` 是否与实际 CRM 到 host 的可达地址一致
4. 确认脚本命中的 Postgres/Redis 容器属于目标 fresh host，而不是旧环境

### 二、再确认导入数据是否正确写入宿主

1. account
   - `GET /api/v1/admin/accounts/:id`
   - 看 `credentials.model_mapping`
2. account models
   - `GET /api/v1/admin/accounts/:id/models`
3. channel
   - `GET /api/v1/admin/channels/:id`
   - 看：
     - `model_mapping`
     - `model_pricing`
     - `restrict_models`
     - `billing_model_source`

### 三、最后再确认普通用户访问链路

1. self_service：看普通用户 key/group/balance
2. subscription：看 managed key / allowed_groups / user_subscriptions
3. 宿主 `/v1/models`
4. 宿主 `/v1/chat/completions`

## 如何解释常见现象

### 现象 A：`/accounts/:id/models` 正确，但 `/v1/models` 返回 403
优先判断：
- 普通用户 key 没绑定 group
- subscription 场景用错了原始 probe key
- subscription 分配或 allowed_groups 未完成

### 现象 B：`/v1/models` 返回 GPT 系模型，而不是目标国产模型
优先判断：
- account `credentials.model_mapping` 是否落库
- channel 是否同时具备 `model_mapping + model_pricing + restrict_models + billing_model_source=channel_mapped`
- 是否误打到了旧 CRM 进程

### 现象 C：`/v1/models` 已 200，但 `/v1/chat/completions` 返回 502
优先判断：
- host 侧 provider 兼容性问题
- 上游 provider key/quota 问题
- 不要再把问题回退归因为 CRM 导入或 access closure

## 当前建议固化到后续文档/脚本的规则

1. 所有真实宿主验收结论都要同时记录：
   - account 视角结果
   - managed key 视角 `/v1/models` 结果
   - completion smoke 结果

2. 任何“MiniMax/DeepSeek 没生效”的结论前，必须先检查在线 CRM 是否为最新提交

3. 任何 subscription 验收脚本都不应默认把外部 `access_api_key` 当最终 probe key

4. 任何 fresh-host 验收脚本都必须参数化：
   - `PACK_PATH`
   - `CRM_HOST_BASE`
   - 目标 Postgres 容器
   - 目标 Redis 容器

## 凭据与可用性判断矩阵

先记住：本项目里最容易混淆的不是 API 本身，而是“看起来都像 key，但其实职责完全不同”的几类凭据。

| 凭据/身份 | 属于谁 | 主要用途 | 正确验证方式 | 不能直接证明什么 | 最常见误判 |
|---|---|---|---|---|---|
| 供应链 key / 上游 key | 供应商账号 / 中转账号 | 写入 host account `credentials.api_key`，供宿主向上游 provider 发请求 | 1. account 创建成功 2. `POST /api/v1/admin/accounts/:id/test` 成功 3. `GET /api/v1/admin/accounts/:id/models` 返回目标模型 | 不能直接证明普通用户一定能看到模型，也不能直接证明 `/v1/chat/completions` 一定可用 | 把 account `/test` 成功误说成“普通用户已可用” |
| 普通用户 key | 宿主普通用户 | 走宿主网关访问 `/v1/models`、`/v1/chat/completions` | 1. key/group 绑定正确 2. `GET /v1/models` 返回目标模型 3. 推荐继续测 `/v1/chat/completions` | 不能直接证明供应链 account 本身健康 | 把普通用户 403 直接归因为供应链 key 无效 |
| subscription 原始外部 `ACCESS_API_KEY` | 调用方传入的外部 probe key | subscription 请求输入，可能只用于触发流程，不一定是最终探测 key | 不能单独用它判断最终 gateway closure；必须先确认是否被 managed key 覆盖 | 不能直接代表最终 subscription 场景的普通用户访问结果 | 拿它直打 `/v1/models` 收到 403，就误判 CRM 主链路失败 |
| managed key (`sk-relay-*`) | CRM 在宿主侧创建/查找的托管普通用户 key | subscription 场景最终 gateway probe / managed 普通用户访问 | 1. managed user / key 已创建 2. group/subscription 已绑定 3. `GET /v1/models` 返回目标模型 4. 推荐继续测 `/v1/chat/completions` | 不能直接证明上游 provider 一定有 quota 或 host completion 一定兼容 | 把它和外部原始 `ACCESS_API_KEY` 混为一谈 |
| host admin token / bearer | 宿主管理员 | 创建 group/channel/plan/account、分配 subscription、读取 admin API | 看 admin API 是否能成功执行管理动作 | 不能直接证明普通用户访问已可用 | 以为“管理接口全成功 = 普通用户链路也成功” |

### 一眼区分规则

1. 供应链 key
   - 验证的是“上游供应商 account 是否健康”
   - 不直接验证普通用户访问
2. 普通用户 key
   - 验证的是“宿主网关路径是否对普通用户开放”
   - 不直接验证上游供应链是否健康
3. subscription 原始外部 key
   - 只是一种流程输入
   - 不一定等于最终探测 key
4. managed key
   - 才是 subscription 场景里更接近“最终真实普通用户访问”的 key
5. admin token
   - 只证明管理面可用
   - 不证明用户面可用

### 两套最小判断口径

#### 口径 A：供应链账号是否成功
看：
1. account 是否创建成功
2. `/api/v1/admin/accounts/:id/test` 是否成功
3. `/api/v1/admin/accounts/:id/models` 是否返回目标模型

#### 口径 B：普通用户是否真的可用
看：
1. key/group/subscription/balance 前置是否到位
2. `/v1/models` 是否返回目标模型
3. `/v1/chat/completions` 是否成功

### 明确禁止的混用

- ❌ 用 account `/test` 成功替代普通用户 `/v1/models`
- ❌ 用 `/v1/models` 成功替代 `/v1/chat/completions`
- ❌ 用外部原始 `ACCESS_API_KEY` 替代 subscription managed key
- ❌ 用 admin API 成功替代普通用户链路成功
- ❌ 看到普通用户 403 就直接判定供应链 key 不可用

## FAQ：新增模型 / 新增供应链账号 / 普通用户访问

### 1. “新增模型参数”到底指什么？

这里至少分四层，不能混成一句“模型加上了”：

1. pack/provider 定义层
   - `base_url`
   - `default_models`
   - `smoke_test_model`
   - `channel_template.model_mapping`
2. host 落库层
   - account `credentials.model_mapping`
   - channel `model_mapping`
   - channel `model_pricing`
   - `restrict_models`
   - `billing_model_source`
3. 模型暴露层
   - `GET /api/v1/admin/accounts/:id/models`
   - `GET /v1/models`
4. completion 层
   - `POST /v1/chat/completions`

经验结论：
- 前三层正确，不等于第四层一定正确
- 当前项目最新真相就是：模型暴露层大体已经打通，但 completion 层仍可能受 host 兼容性或上游 quota 影响

### 2. “新增供应链账号成功”到底以什么为准？

建议区分三档成功标准：

1. 窄口径成功（只看供应链 account）
   - account 创建成功
   - `POST /api/v1/admin/accounts/:id/test` 成功
   - `GET /api/v1/admin/accounts/:id/models` 返回目标模型
2. 完整接入成功（看普通用户是否能看到模型）
   - 上述 account 条件成立
   - 普通用户或 managed key 的 `GET /v1/models` 返回目标模型
3. 业务可用成功（看真实调用）
   - 上述条件都成立
   - `POST /v1/chat/completions` 成功

经验结论：
- 如果你只说“供应链账号成功”，默认最多只能代表前两档
- 如果要说“模型完全可用”，必须把 completion smoke 也过掉

### 3. 新增供应链账号时，系统会不会自动补 group / channel / plan？

会，但要分资源类型看：

1. group
   - 一定会先 ensure
   - 不存在就创建，存在就复用
2. channel
   - 一定会先 ensure
   - 不存在就创建，存在就 `UpdateChannel` 纠偏
3. plan
   - 只在 `subscription` 模式下需要
   - 不存在就创建，存在就复用
4. account
   - 最后创建，并绑定到目标 `group_ids`

经验结论：
- 新增供应链账号不是“只加 account”
- 它本质上是“确保资源面完整后再挂 account”

### 4. 新增模型时，哪些字段必须同时对齐？

至少要对齐：
- provider `base_url`
- `default_models`
- `smoke_test_model`
- `channel_template.model_mapping`
- account `credentials.model_mapping`
- channel `model_mapping`
- channel `model_pricing`
- `restrict_models=true`
- `billing_model_source=channel_mapped`

经验结论：
- 少了 `model_mapping`，模型列表可能回退到默认集合
- 少了 `model_pricing`，`/v1/models` 可能看起来没问题，但实际聊天流量可能仍失败
- 只修 account 不修 channel，或者只修 channel 不修 account，都会留下半通不通的假阳性

### 5. 如果是“中转 URL / relay URL”，而且不在宿主官方已知库里，标准会不会不一样？

本项目的标准本质不变，但前提是：
- 这个 provider 必须先在本项目的 pack/provider manifest 中被正确定义

也就是说：
- “不在宿主官方库里”没关系
- “没有在本项目 pack 中定义”才不行

只要 manifest 正确提供了：
- `base_url`
- `default_models`
- `smoke_test_model`
- `channel_template.model_mapping`

系统就仍然可以自动做：
- account 创建
- account `/test`
- account `/models`
- 普通用户 `/v1/models`
- completion smoke（如果你把这一步也纳入验收）

经验结论：
- 系统不是“任意 URL 自动猜测器”
- 系统是“pack/provider 驱动的导入与验证器”

### 6. 只要 `/v1/models` 成功，是不是就说明新模型已经完全可用了？

不是。

`/v1/models` 成功，只能证明：
- 普通用户或 managed key 访问路径至少已经看到了模型列表

它不能自动证明：
- provider 上游有 quota
- host 对该 provider 的 completion 兼容性没问题
- `POST /v1/chat/completions` 一定能成功

经验结论：
- `/v1/models = 200` 是“模型暴露通过”
- `/v1/chat/completions = 200` 才更接近“模型可用通过”

### 7. 新增供应链账号后，普通用户 key 的 group 信息要不要更新？

通常要，取决于 access mode。

#### self_service
- 普通用户 key 必须绑定目标标准 group
- 如果新模型落在新的 group，而 key 没绑定过去，普通用户就看不到或用不到它
- 若目标 group 是标准计费组，通常还需要余额

#### subscription
- 目标 group 必须是 `subscription` 类型
- 普通用户必须完成 subscription 分配
- 普通用户 key 必须绑定该 group
- 当前 closure 最终优先使用宿主 managed key，而不是外部原始 `access_api_key`

经验结论：
- “新增了供应链模型”不等于“所有普通用户 key 自动获得访问权”
- 最终是否能访问，取决于 key/group/subscription 这条链是否同步完成

### 8. 新增供应链账号后，如果普通用户看不到模型，优先查哪里？

建议按这个顺序查：

1. account 视角
   - `GET /api/v1/admin/accounts/:id`
   - `GET /api/v1/admin/accounts/:id/models`
2. channel 视角
   - `GET /api/v1/admin/channels/:id`
   - 看 `model_mapping/model_pricing/restrict_models/billing_model_source`
3. 普通用户视角
   - `GET /v1/models`
4. completion 视角
   - `POST /v1/chat/completions`
5. 环境与运行时
   - CRM 是否是最新提交
   - `PACK_PATH` 是否正确
   - `CRM_HOST_BASE` 是否正确

经验结论：
- 不要一上来就看普通用户 403/502
- 先查 account 和 channel 落库，更容易快速定位根因

### 9. 什么时候应该判定是“运营前置没做”，而不是“导入代码失败”？

常见场景：

1. `self_service`
   - key 没绑 group
   - 用户没余额
2. `subscription`
   - group 不是 subscription 类型
   - user subscription 没写入
   - key 没绑 group
3. probe key 用错
   - subscription 场景拿外部原始 key 去打 `/v1/models`
4. 脚本参数错
   - `PACK_PATH` 错
   - 命中错的 Postgres/Redis 容器
   - probe auth 用错

经验结论：
- 如果 account `/models` 已对、channel 落库也对，但普通用户流量不对，优先怀疑运营前置或 harness 参数
- 不要立即重开“导入代码失效”的结论

### 10. 新增供应链账号或模型后，哪些结果可以算“已确认”，哪些只能算“部分确认”？

#### 可算“已确认”
- account 已创建
- account `/test` 成功
- account `/models` 返回目标模型
- channel 落库包含完整 routing/pricing 字段
- 普通用户 `/v1/models` 返回目标模型

#### 只能算“部分确认”
- 只有 import API 返回成功
- 只有 batch status 成功
- 只有 account 创建成功但还没测 `/models`
- 只有 `/v1/models` 成功但没测 `/v1/chat/completions`

经验结论：
- “新增模型成功”这句话必须说明你指的是哪一层成功
- 最容易误导人的说法，就是把“导入成功”直接说成“模型可用成功”

### 11. 如果新增供应链账号是复用旧 channel，而不是新建 channel，需要特别注意什么？

特别注意两件事：

1. 旧 channel 不能只复用名字
   - 必须做配置纠偏
   - 至少要补齐 `model_mapping + model_pricing + restrict_models + billing_model_source`
2. 不能默认“有 model_mapping 就够了”
   - 这正是之前 MiniMax live 问题踩过的坑

经验结论：
- 旧 channel 复用比新建更危险
- 因为它最容易留下“看起来有模型，实际上定价/路由没补齐”的半漂移状态

### 12. 如果我要把“新增模型/新增供应链账号”做成标准验收 checklist，最小应包含哪些项？

最小 checklist：

1. provider manifest 已更新
   - `base_url`
   - `default_models`
   - `smoke_test_model`
   - `channel_template.model_mapping`
2. import 成功
   - group/channel/(subscription: plan)/accounts 已生成或被正确复用
3. account 验证成功
   - `/test`
   - `/models`
4. channel 回读成功
   - `model_mapping`
   - `model_pricing`
   - `restrict_models`
   - `billing_model_source`
5. 普通用户路径验证成功
   - `/v1/models`
6. 业务路径验证成功（推荐）
   - `/v1/chat/completions`
7. 若失败，明确归类
   - provider definition drift
   - host compatibility
   - upstream quota/key 问题
   - key/group/subscription/balance 前置问题
   - harness 参数问题

## 相关证据入口

- 当前执行真相：`docs/EXECUTION_BOARD.md`
- 当前收口真相：`docs/PRODUCTION_CLOSURE_BOARD.md`
- 标准操作步骤：`docs/REAL_HOST_ACCEPTANCE_RUNBOOK.md`
- 关键 live 证据：
  - `artifacts/real-host-acceptance/20260520_222713_crm18100_live_model_mapping_validation`
  - `artifacts/real-host-acceptance/20260521_011544_remote43_minimax_key_import`
  - `artifacts/real-host-acceptance/20260521_011717_remote43_deepseek_key_import`
  - `artifacts/real-host-acceptance/20260521_064910_completion_smoke_calibration.md`