fix fresh-host acceptance and document real-host debugging learnings

docs/REAL_HOST_ACCEPTANCE_LEARNINGS.md

@@ -32,6 +32,12 @@
    - 真正使用的是 CRM 在宿主侧创建/查找出来的 managed key（`sk-relay-*` 风格）
    - 因此 subscription 验收如果直接拿调用方原始 probe key 去打 `/v1/models`，出现 `403 not assigned to any group` 并不代表 CRM 主链路失败，而是 probe key 用错了
 
+4. self_service 场景的 gateway probe 认证语义已经确认
+   - 真实宿主的普通用户 gateway key 访问 `/v1/models` / `/v1/chat/completions` 时，使用的是 `Authorization: Bearer <gateway-key>`
+   - 不能把这条普通用户 gateway key 当成宿主管理 API key 再塞进 `x-api-key`
+   - latest-head 最后一个真实阻断就是这里：CRM 的 `CheckGatewayAccess` / `CheckGatewayCompletion` 之前错误地把 self_service 的普通用户 key 放进了 `x-api-key`
+   - 修复后，latest-head `self_service` 标准 fresh-host 验收 `artifacts/real-host-acceptance/20260521_210403` 已真实收口到 `self_service_ready`
+
 4. group 聚合视角与 account 单体视角必须分开看
    - `GET /api/v1/admin/accounts/:id/models` 是 account 单体视角
    - `GET /v1/models` 是普通用户 key + group 聚合视角
@@ -94,6 +100,7 @@
 经验结论：
 - 若只做了 key/group 绑定但没余额，`/v1/models` 可能从 403 进入 `INSUFFICIENT_BALANCE`
 - 这不是 CRM 导入逻辑失败，而是宿主运营前置未完成
+- 若普通用户 key 直打宿主 `/v1/models` / `/v1/chat/completions` 已经 `200`，但 CRM 的 self_service closure 仍显示 `401/403 broken`，优先检查 CRM 的 gateway probe 是否错误地复用了 `x-api-key` 语义，而不是先怀疑宿主前置
 
 ### subscription
 
@@ -158,6 +165,11 @@
    - 若脚本仍打到旧 relaymgr 宿主，会看到 managed user / key / subscription 状态为空或串台
    - 需要确保脚本明确指向 fresh host 对应的 `{postgres,redis}` 容器
 
+7. fresh-host bearer token 过期时，最前面的 host 注册/探测也会伪装成 CRM 侧 502
+   - latest-head `self_service` 收尾时，脚本最前面的 `POST /api/hosts` 曾直接返回 `502`
+   - 继续往里看，upstream detail 才显示 `TOKEN_EXPIRED`
+   - 这类现象不要先误判成 CRM 新代码挂了；应先刷新 fresh-host 管理员 bearer token，再继续验收
+
 6. 把 `/v1/models` 已通误认为 completion 也一定通
    - 这不成立
    - 当前最新真相就是：DeepSeek / MiniMax 的 `/v1/models` 可以 200，但 `/v1/chat/completions` 仍可能因为 host 兼容性或上游 quota 问题失败
@@ -213,6 +225,11 @@
 - 上游 key/quota
 - 不要先回退归因为 CRM 导入失败
 
+### 现象 D：普通用户 key 直打宿主 `/v1/models` 与 `/v1/chat/completions` 都是 200，但 CRM 的 `self_service` access/status 仍是 broken
+优先判断：
+- CRM 的 gateway probe 是否错误使用了 `x-api-key` 而不是 `Authorization: Bearer`
+- 当前 online CRM 进程是否真的已经切到包含该修复的新二进制
+
 ### 进一步缩圈：DeepSeek `chat/completions` 当前更像宿主兼容层问题，而不是 key 失效
 
 2026-05-21 新增的直接证据链：
@@ -265,6 +282,8 @@
    - 目标 Postgres 容器
    - 目标 Redis 容器
 
+5. latest-head `self_service` 验收通过后，如果 `reconcile` 仍是 `drifted`，应优先把它解释为 shared fresh-host 的历史残留资源噪音，而不是主链路未打通；判断时先看 `05-import.json` / `07-access-status.json` 的 ready 结果，再看 `09-reconcile.json` 的 `summary.access_status`
+
 ## 凭据与可用性判断矩阵
 
 先记住：本项目里最容易混淆的不是 API 本身，而是“看起来都像 key，但其实职责完全不同”的几类凭据。