docs: sync truth docs, frontend audits, and runbooks
This commit is contained in:
phamnazage-jpg
@@ -34,11 +34,23 @@
|
||||
## 前置条件
|
||||
|
||||
### 控制面
|
||||
|
||||
- `sub2api-cn-relay-manager` 已启动
|
||||
- `CRM_BASE_URL` 可访问，例如 `http://127.0.0.1:8080`
|
||||
- 已设置 `CRM_ADMIN_TOKEN`
|
||||
|
||||
### 入口一致性（SSH 隧道/容器端口/CRM 注册 host 三层核对）
|
||||
|
||||
在跑任何验收步骤前，先做三层核对防止端口漂移或旧进程残留：
|
||||
|
||||
1. **本机端口** — 确认 SSH 隧道进程在运行，目标端口正确转发到远程（`ss -tlnp | grep :PORT`）
|
||||
2. **远端容器/进程** — 确认目标容器或独立进程在预期端口上运行（`docker ps` / `fuser PORT/tcp`）
|
||||
3. **CRM 注册的 host** — 调 CRM hosts API，确认注册的 host `base_url`、`version` 与上两步一致
|
||||
|
||||
若任一层不一致，停止验收，先修复映射关系。详见 `REAL_HOST_ACCEPTANCE_CHECKLIST.md §1` 第 5 项。
|
||||
|
||||
### 真实宿主
|
||||
|
||||
- 已知真实宿主 `HOST_BASE_URL`
|
||||
- 已知宿主管理认证：
|
||||
- `HOST_API_KEY` 或
|
||||
@@ -56,6 +68,7 @@ bash ./scripts/test/test_real_host_scripts.sh
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- 当前推荐显式用 `bash` 调起，确保在不同机器上不会因为脚本执行位差异把 harness 回归误报成逻辑失败。
|
||||
- 只有这一步通过后，再继续真实宿主验收。
|
||||
|
||||
@@ -67,6 +80,7 @@ scripts/deploy/build_local_image.sh
|
||||
```
|
||||
|
||||
默认输出：
|
||||
|
||||
- 二进制：`bin/sub2api-cn-relay-manager`
|
||||
- 镜像：`sub2api-cn-relay-manager:local`
|
||||
|
||||
@@ -83,6 +97,7 @@ bash ./scripts/deploy/setup_remote43_patched_stack.sh
|
||||
```
|
||||
|
||||
脚本会：
|
||||
|
||||
- 把本地 pack 镜像到 `/tmp/openai-cn-pack-<stack>` 并同步到 remote43 同路径
|
||||
- 把当前本地 `main` 分支打成 `git bundle`，并在 remote43 固定维护仓库工作副本：
|
||||
- `/home/ubuntu/sub2api-cn-relay-manager-git-current`
|
||||
@@ -94,6 +109,7 @@ bash ./scripts/deploy/setup_remote43_patched_stack.sh
|
||||
- `local tunnel script`
|
||||
|
||||
说明：
|
||||
|
||||
- 以后 provider 草稿发布链默认依赖这个固定 repo 根，不再依赖人工创建的时间戳 checkout 目录。
|
||||
|
||||
后续按脚本输出执行：
|
||||
@@ -170,6 +186,7 @@ scripts/acceptance/real_host_acceptance.sh
|
||||
```
|
||||
|
||||
hook 执行时会额外导出：
|
||||
|
||||
- `BATCH_ID`
|
||||
- `BATCH_DETAIL_FILE`（若非 dry-run，会指向 `05a-batch-detail-pre-access.json`）
|
||||
- `PROVIDER_ID`
|
||||
@@ -180,6 +197,7 @@ hook 执行时会额外导出：
|
||||
- `ARTIFACT_DIR`
|
||||
|
||||
标准产物会新增：
|
||||
|
||||
- `05a-batch-detail-pre-access.json`
|
||||
- `05b-after-import-hook.stdout.txt`
|
||||
- `05b-after-import-hook.stderr.txt`
|
||||
@@ -227,11 +245,13 @@ ARTIFACT_INCLUDE_SECRETS=0
|
||||
```
|
||||
|
||||
含义：
|
||||
|
||||
- `safe`：主 artifact 目录只允许落脱敏后的验收证据，可作为仓库内长期保留材料。
|
||||
- `debug`：允许额外生成本地敏感调试材料；这类材料不得作为默认主证据提交或长期保留。
|
||||
- `ARTIFACT_INCLUDE_SECRETS=1` 只允许用于本地短时调试；一旦开启，产物不再默认视为可入库证据。
|
||||
|
||||
`safe` 模式下的硬规则：
|
||||
|
||||
- 不落完整 upstream / managed / user API key
|
||||
- 不落完整 bearer token
|
||||
- 不落可直接复用的 SQL 明文 key 语句
|
||||
@@ -239,6 +259,7 @@ ARTIFACT_INCLUDE_SECRETS=0
|
||||
- header 文件必须去掉 `Authorization` / `Cookie` / `Set-Cookie` / `x-api-key`
|
||||
|
||||
默认文件顺序：
|
||||
|
||||
- `01-create-host.json`
|
||||
- `02-probe-host.json`
|
||||
- `03-install-pack.json`
|
||||
@@ -254,6 +275,7 @@ ARTIFACT_INCLUDE_SECRETS=0
|
||||
- `11-rollback.json`（若未跳过）
|
||||
|
||||
remote43 / 本地缩圈脚本若需要额外证据，会在同目录追加：
|
||||
|
||||
- `00-local-key-source.json`（只保留 redacted key 指纹/前后缀）
|
||||
- `01-runtime-context.json`（仅保留 hash 后的 user/admin/managed 身份）
|
||||
- `05-subscription-access-prep.summary.json`（替代默认明文 SQL）
|
||||
@@ -268,7 +290,8 @@ remote43 / 本地缩圈脚本若需要额外证据，会在同目录追加：
|
||||
- 历史目录迁移脚本当前已覆盖两层：
|
||||
1. 固定命名标准 artifact（runtime-context / key-source / redis invalidation / group-state / sql summary / headers）
|
||||
2. 复杂业务快照与 JSON-in-string 字段（`summary.json`、`99-summary.json`、`99-semantic-summary.json`、`05a-batch-detail-pre-access.json`、`07-access-status.json`、`10-batch-detail.json` 以及其中的 `DetailsJSON/details_json/probe_summary_json`）
|
||||
- 若迁移后仍看到类似 `00-managed-key-corrected.txt` 的手工 probe 文本，它们属于非标准人工产物，当前仍建议迁到 `artifacts/real-host-acceptance-sensitive/` 或直接删除。
|
||||
- 若迁移后仍看到类似 `00-managed-key-corrected.txt` 的手工 probe 文本，它们属于非标准人工产物，当前仍建议迁到 `artifacts/real-host-acceptance-sensitive/` 或直接删除。
|
||||
|
||||
## 通过标准
|
||||
|
||||
至少同时满足：
|
||||
@@ -296,6 +319,7 @@ remote43 / 本地缩圈脚本若需要额外证据，会在同目录追加：
|
||||
- 用同一条普通用户访问链路请求 `POST /v1/chat/completions`
|
||||
|
||||
注意：
|
||||
|
||||
- `GET /api/v1/admin/accounts/:id/models` 正确，不等于普通用户 `/v1/models` 一定正确
|
||||
- `/v1/models` 正确，也不等于 `/v1/chat/completions` 一定正确
|
||||
- 这三层必须分开记证据、分开下结论
|
||||
@@ -337,35 +361,46 @@ SKIP_ROLLBACK=1 scripts/acceptance/real_host_acceptance.sh
|
||||
19. fresh-host 管理员 bearer token 过期时，最前面的 `POST /api/hosts` / `probe-host` 可能直接表现成 CRM 侧 `502`。遇到这类现象，先刷新 host bearer token，再继续验收，不要先把它归因为最新代码故障。
|
||||
20. shared fresh-host 上若 `05-import.json` / `07-access-status.json` 已经 ready，而 `09-reconcile.json` 仍是 `status=drifted`，优先把它解释为历史残留资源噪音；PRD 首版放行判断应以 import/access 闭环是否打通为主。
|
||||
21. 如果 CRM 本身运行在本机，而宿主运行在远端 SSH 隧道后面，必须同时明确 2 个地址：
|
||||
- `CRM_HOST_BASE`：本地 CRM 实际访问宿主时使用的地址，例如 `http://127.0.0.1:18089`
|
||||
- `REMOTE_HOST_BASE`：远端 SSH 会话内部访问宿主时使用的地址，例如 `http://127.0.0.1:18097`
|
||||
- 两者不能混用；混用后 `POST /api/hosts` 往往会先在 `get host version` / `probe host capabilities` 处直接变成 `500`
|
||||
|
||||
- `CRM_HOST_BASE`：本地 CRM 实际访问宿主时使用的地址，例如 `http://127.0.0.1:18089`
|
||||
- `REMOTE_HOST_BASE`：远端 SSH 会话内部访问宿主时使用的地址，例如 `http://127.0.0.1:18097`
|
||||
- 两者不能混用；混用后 `POST /api/hosts` 往往会先在 `get host version` / `probe host capabilities` 处直接变成 `500`
|
||||
|
||||
22. 如果远端同时存在 `relaymgr` 和 `fresh-host` 两套容器栈，不要手填 `REMOTE_PG_CONTAINER` / `REMOTE_REDIS_CONTAINER` 到旧的 relaymgr 容器。优先按目标宿主端口自动解析同栈的 `postgres/redis`；否则最容易回到“错库取 key 导致统一 401”。
|
||||
23. 若同一个 provider 已在本地 CRM 状态库里跑过多个宿主样本，尾部查询必须带 `host_id`：
|
||||
- `GET /api/providers/{provider}/status`
|
||||
- `GET /api/providers/{provider}/access/status`
|
||||
- `POST /api/providers/{provider}/access/preview`
|
||||
- 否则很容易在最后一步收到 `provider exists on multiple hosts; host_id is required`
|
||||
|
||||
- `GET /api/providers/{provider}/status`
|
||||
- `GET /api/providers/{provider}/access/status`
|
||||
- `POST /api/providers/{provider}/access/preview`
|
||||
- 否则很容易在最后一步收到 `provider exists on multiple hosts; host_id is required`
|
||||
|
||||
24. 不要把“隧道端口还在 LISTEN”误判成“链路可用”。
|
||||
- 若 `curl -I --max-time 5 $CRM_HOST_BASE/healthz` 完全收不到 header
|
||||
- 就应先判定为 tunnel 失活或远端链路异常
|
||||
- 这类现象会在 `03-import.body.json` 中表现为 `get host version ... context deadline exceeded`
|
||||
|
||||
- 若 `curl -I --max-time 5 $CRM_HOST_BASE/healthz` 完全收不到 header
|
||||
- 就应先判定为 tunnel 失活或远端链路异常
|
||||
- 这类现象会在 `03-import.body.json` 中表现为 `get host version ... context deadline exceeded`
|
||||
|
||||
25. 当前 artifact 安全模式默认是 `safe`：
|
||||
- 主目录 `artifacts/real-host-acceptance/` 只能保留脱敏后证据
|
||||
- 若为了缩圈必须看原始 SQL / headers / token 相关细节，应显式切到 `ARTIFACT_SECURITY_MODE=debug` 并把产物视为本地敏感材料，不进入仓库主证据区
|
||||
|
||||
- 主目录 `artifacts/real-host-acceptance/` 只能保留脱敏后证据
|
||||
- 若为了缩圈必须看原始 SQL / headers / token 相关细节，应显式切到 `ARTIFACT_SECURITY_MODE=debug` 并把产物视为本地敏感材料，不进入仓库主证据区
|
||||
|
||||
## 建议固定执行的快速诊断顺序
|
||||
|
||||
1. 先看环境
|
||||
- CRM 是否是最新提交对应的在线进程
|
||||
- `PACK_PATH` 是否是 CRM 本机可读路径
|
||||
- `CRM_HOST_BASE` 是否与 CRM 到 host 的实际访问地址一致
|
||||
- 如果走 SSH 隧道，`CRM_HOST_BASE` 是否真的可在本机 `curl -I --max-time 5` 读到响应
|
||||
- 若脚本还要在 SSH 会话里执行 host probe，`REMOTE_HOST_BASE` 是否与远端主机看到的地址一致
|
||||
|
||||
- CRM 是否是最新提交对应的在线进程
|
||||
- `PACK_PATH` 是否是 CRM 本机可读路径
|
||||
- `CRM_HOST_BASE` 是否与 CRM 到 host 的实际访问地址一致
|
||||
- 如果走 SSH 隧道，`CRM_HOST_BASE` 是否真的可在本机 `curl -I --max-time 5` 读到响应
|
||||
- 若脚本还要在 SSH 会话里执行 host probe，`REMOTE_HOST_BASE` 是否与远端主机看到的地址一致
|
||||
|
||||
2. 再看宿主落库
|
||||
- account `credentials.model_mapping`
|
||||
- `GET /api/v1/admin/accounts/:id/models`
|
||||
- channel `model_mapping/model_pricing/restrict_models/billing_model_source`
|
||||
|
||||
- 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`
|
||||
|
||||
Reference in New Issue
Block a user