docs(readme): consolidate truth-index and docs navigation

This commit is contained in:
phamnazage-jpg
2026-05-21 09:16:45 +08:00
parent ca1d448cc0
commit 8ba72efe95
8 changed files with 559 additions and 35 deletions

View File

@@ -1,9 +1,20 @@
# Sub2api-CN-Relay-Manager 生产收口板
日期2026-05-18
当前 GateAPPROVED按 PRD 首版范围放行;代码与真实宿主 fresh redeploy 复验均已满足,且已补充 reconcile host-scope 新一轮 acceptance artifact
日期2026-05-20
当前 GateBLOCKED代码门禁已通过`scripts/import_remote43_provider.sh` 的 managed-probe / 本机 `PACK_PATH` 修复已关闭历史 `401 Unauthorized` 假阴性;但 2026-05-21 latest-head fresh host completion smoke 仍未通过DeepSeek `artifacts/real-host-acceptance/20260521_064403_remote43_deepseek_key_import` 与 MiniMax `artifacts/real-host-acceptance/20260521_064454_remote43_minimax_key_import` 都已达到 `subscription_ready``/v1/models`=200`/v1/chat/completions` 仍返回 502。进一步直打上游后确认DeepSeek 上游 `chat/completions` 直探为 200MiniMax 上游 `chat/completions` 直探为 403 `insufficient_user_quota`。因此当前不允许宣称“完全验收/APPROVED”
目标:达到可上线代码质量,并把剩余风险明确收敛为外部环境验收项与已接受 P2 技术债务。
## 2026-05-21 校准说明(最新真相)
- 401 假阴性已关闭:`artifacts/real-host-acceptance/20260521_064403_remote43_deepseek_key_import``20260521_064454_remote43_minimax_key_import``09-models.headers.txt` 已恢复 `HTTP 200`
- fresh-host DB 侧状态也已对齐:脚本指向正确的 `sub2api-fresh-deepseek-20260519_115244-{postgres,redis}-1` 后,`08-subscription-group-state.json` 已能看到真实的 managed user / subscription / key 绑定。
- 新主阻断不是 auth/tooling而是 completion smoke两条 provider 在 host `/v1/chat/completions` 仍返回 `502 upstream_error`
- 上游直探分流证明:
- DeepSeek 上游 `/chat/completions` = `HTTP 200`host 侧 502 属于真实兼容性问题。
- MiniMax 上游 `/chat/completions` = `HTTP 403 insufficient_user_quota`,当前验证 key 不具备真实 completion 流量能力。
- 汇总证据:`artifacts/real-host-acceptance/20260521_064910_completion_smoke_calibration.md`
- 调通细节与经验沉淀:`docs/REAL_HOST_ACCEPTANCE_LEARNINGS.md`
## 当前门控结论
| 维度 | 状态 | 证据 |
@@ -21,9 +32,10 @@
| Local runtime smoke | ✅ PASS | `go build ./cmd/{server,cli}``GET /healthz``GET /api/hosts` |
| Local OCI image | ✅ PASS | `docker build -f Dockerfile.local -t sub2api-cn-relay-manager:local .` |
| Real-host acceptance tooling | ✅ READY | `docs/REAL_HOST_ACCEPTANCE_RUNBOOK.md` + `scripts/real_host_acceptance.sh` |
| `self_service` 真实宿主 fresh redeploy 复验 | PASS | `artifacts/real-host-acceptance/20260518_redeploy_matrix`普通用户 key 绑定标准 group 且用户余额=10 后,`04-self-after-balance.headers.txt` 显示 `HTTP/1.1 200 OK` |
| `subscription` 真实宿主 fresh redeploy 复验 | ✅ PASS | `artifacts/real-host-acceptance/20260518_redeploy_matrix`subscription group + 用户订阅分配 + key 绑定后,`06-subscription-after-assign.headers.txt` 显示 `HTTP/1.1 200 OK` |
| `self_service`/`subscription` reconcile host-scope 复验 | ✅ PASS | `artifacts/real-host-acceptance/20260518_reconcile_hostscope_self_service` / `artifacts/real-host-acceptance/20260518_reconcile_hostscope_subscription`:已补齐 host-scoped `07/08/08a/09/10/11` 证据链batch detail / status / resources 不再跨宿主串台 |
| `self_service` 真实宿主 fresh redeploy 复验 | ⚠️ HISTORICAL PASS | `artifacts/real-host-acceptance/20260518_redeploy_matrix`历史 fresh redeploy host 可打通;当前不再作为唯一真相来源 |
| `subscription` 真实宿主 latest-head fresh host 复验 | ✅ PASS | MiniMax`artifacts/real-host-acceptance/20260521_011544_remote43_minimax_key_import`DeepSeek`artifacts/real-host-acceptance/20260521_011717_remote43_deepseek_key_import`;两条 provider 均 `subscription_ready` |
| stale CRM / channel pricing 缺口 | ✅ CLOSED | 宿主 `GET /api/v1/admin/channels/5` `/channels/4` 已返回非空 `model_pricing` + `model_mapping` |
| `self_service`/`subscription` reconcile host-scope 复验 | ⚠️ PARTIAL | `artifacts/real-host-acceptance/20260518_reconcile_hostscope_*` 仍证明 host-scope 语义成立;本次 latest-head rerun 主验证点是 stale-process import/access closure而不是重新跑整套 reconcile/rollback |
## 本轮已关闭项
@@ -49,11 +61,12 @@
- 新增 `scripts/real_host_acceptance.sh`,把真实宿主验收固化为可落盘 artifact 的流程
5. 最新真实宿主复验事实
- `artifacts/real-host-acceptance/20260518_redeploy_matrix` 已在 fresh redeploy host 上确认两条访问链路都可打通
- `self_service` 通过条件:普通用户 key 绑定标准 group且用户具备可用余额
- `subscription` 通过条件subscription 类型 group + 普通用户订阅分配 + key/group 绑定
- 当前真实差异已经收敛为“宿主运营前置条件”而不是“代码级阻塞
- `artifacts/real-host-acceptance/20260518_reconcile_hostscope_self_service` / `20260518_reconcile_hostscope_subscription` 进一步补强了 reconcile / batch detail 的 host-scope 语义证据
- `artifacts/real-host-acceptance/20260521_011544_remote43_minimax_key_import``batch_id=7``access_status=subscription_ready``gateway.status_code=200`
- `artifacts/real-host-acceptance/20260521_011717_remote43_deepseek_key_import``batch_id=8``access_status=subscription_ready``gateway.status_code=200`
- 宿主 admin 侧直接复核MiniMax `/api/v1/admin/channels/5` 与 DeepSeek `/api/v1/admin/channels/4` 都已具备 `billing_model_source=channel_mapped``restrict_models=true`、非空 `model_pricing` / `model_mapping`
- 说明当前真实差异已不再是“代码没有把模型映射/定价写进 channel”而是“验收脚本 direct probe 仍可能误报 401
- `self_service` 通过条件仍是:普通用户 key 绑定标准 group且用户具备可用余额
- `subscription` 通过条件仍是subscription 类型 group + 普通用户订阅分配 + key/group 绑定
## 剩余项P2 / 运营前置,不阻塞按 PRD 首版范围上线)
@@ -68,13 +81,14 @@
- 无内置 scheduler/jobs当前通过手动 reconcile + 外部 cron 补偿
- CLI `run*` 真实链路函数未做系统性 mock 单测
- 标准多阶段 `Dockerfile` 在受限网络下仍依赖容器内联网拉取 Go modules本地部署默认走 `scripts/build_local_image.sh`
- `scripts/import_remote43_provider.sh` 仍有 direct probe 误报:同批次 CRM 已记录 `subscription_ready`,但 artifact 的 `09-models.headers.txt` / `11-chat.headers.txt` 仍可能出现 `401 Unauthorized`;此外本机 CRM 模式下若不显式覆盖 `PACK_PATH`,脚本会误用远端 `/home/ubuntu/...` 路径触发 `stat pack path ... no such file or directory`
## 最短上线闭环
1.`docs/REAL_HOST_ACCEPTANCE_RUNBOOK.md` 准备真实宿主普通用户与可复用凭据
2. 按目标模式完成 key/group/billing(or subscription) 绑定
3. 使用 `scripts/build_local_image.sh``scripts/real_host_acceptance.sh` 复跑并归档现场 artifact
4. 对于符合这些前置条件的单宿主场景,本项目已可按 PRD 首版范围放行
3. 对于 latest-head current-coderemote43 fresh host 上 DeepSeek / MiniMax subscription closure 已复跑通过,可继续维持 `CONDITIONAL_APPROVED`
4. 如需把 tooling 也一并收口,再补修 `scripts/import_remote43_provider.sh` 的 direct probe auth 与本机 `PACK_PATH` 参数化
## 禁止错误结论