docs(tests): README 同步目录驱动 + 三态口径 + 退出码语义

This commit is contained in:
admin committed 2026-09-17 08:42:59 +08:00
1 parent 762d308745
commit 42a316b964
1 file changed
+25 -7
+25 -7
View File
@@ -13,18 +13,35 @@ bash tests/run.sh llm # 只跑 LLM 代理(262 条断言)
## 上线后验证(真实环境,不是本机夹具)
上面跑的是**假上游**;`deploy/agent.sh verify` 又只验管理台,**不发真实 LLM 请求**。
要确认「新版在线上真能干活」,用这个把两半合起来一键跑:
要确认「新版在线上真能干活」,用这个把三步合起来一键跑(`agent.sh release` 第 3/4 步就是它):
```bash
bash tests/live_check.sh # 真实流量 + 环境验收(key 默认 ~/ssw.txt)
bash tests/live_check.sh # 三步全跑(key 默认 ~/ssw.txt)
bash tests/live_check.sh ~/.keys/ipass.txt # 指定 key 文件
bash tests/live_check.sh --models-only # 只跑真实流量(4 slot × OpenAI/Anthropic + /v1/models)
bash tests/live_check.sh --models-only # 只跑 LLM 真实流量
bash tests/live_check.sh --apix-only # 只跑 apix 探针
bash tests/live_check.sh --verify-only # 只跑 deploy/agent.sh verify
```
**探针全部目录驱动**:要验什么不写死,从 `/api/v1/me`(mdm host + `X-API-Key` 头)
动态拉——upstreams × models 全展开逐个真调,apix 条目逐个探。管理台改了配置,
验证自动跟上;**拉不到目录退出码 2**(验证失效不许假绿,也不许被当成新版故障)。
**三态口径**(`me_catalog.py`,两个探针共享):
- ❌ **网关侧故障** → 影响退出码,release 自动回滚。归属判据是**三重**的:
错误体形态 + HTTP 码 ∈ {400,401,403,404,429} + `error.code` ∈ 网关码全集——
智谱的 401 体也是 `{"error":{"code","message"}}` 形状,光看形态会把欠费误判成发版故障。
- ⚠️ **上游/厂商侧**(欠费 402、不可达 502/504、WAF 拦截、探针参数被拒、
**HTTP 200 但 body 软错误**)→ 汇总逐条列出**如实反馈**,但不染红发版——
网关正常转发、一方账号没钱了不是新镜像的锅。
- 网关 429(探针打太快/配额)→ GW_WARN,同样如实列出不回滚。
`live_check.sh` 退出码(release 按它决定回滚,别改语义):`0` 通过 / `1` 网关侧
故障(回滚镜像+恢复数据)/ `2` 验证不可用(**不回滚**,修验证入口后手动重跑)。
Key 文件可以是裸 key,也可以是 `sk=<key>` 形式(带 `#` 注释行也认)——**取整行会拿到
`sk=sk_xxx` → 全量 401**,脚本内部已处理;全程不打印 Key 原文。
延迟参考:deepseek/qwen/minimax 1~2.6s,**glm 7~11s**,别拿 glm 当超时基线。
延迟参考:deepseek/qwen/minimax 1~2.6s,**glm 7~12s**,别拿 glm 当超时基线。
三个 apix 探针的固定坑(写脚本时踩过,改条目时留意):
@@ -41,9 +58,10 @@ Key 文件可以是裸 key,也可以是 `sk=<key>` 形式(带 `#` 注释行
| 路径 | 作用 |
| --- | --- |
| `run.sh` | 统一入口:编译 → 渲染配置 → 起进程 → 跑断言 → 收尾 |
| `live_check.sh` | **上线后验证**:真实流量(`test_models.py`)+ 正式环境验收(`deploy/agent.sh verify`) |
| `test_models.py` | 真实流量探针:4 slot × OpenAI/Anthropic 调用 + `/v1/models` 模型发现(打的是线上 `lm.mayishangshu.cn:88`,**不是本机夹具**;失败退出码 1) |
| `apix_check.py` | apix 探针:`/apix/<slug>`(vendor) + `/apixp/<slug>`(passthrough) 是否真转发。**只有「网关侧没生效」才算失败**(无效 Key 预检 + 错误体归属判定),上游业务拒绝/供应商 WAF 只告警 |
| `live_check.sh` | **上线后验证**三步入口:LLM 真实流量 + apix 探针 + 环境验收(退出码 0/1/2,release 按它决定是否回滚) |
| `me_catalog.py` | 探针共享模块:拉 `/api/v1/me` 能力目录 + **三态判定**(网关/上游/告警归属、200 软错误识别)。新增错误体形态先扩 `GW_ERR_CODES` |
| `test_models.py` | LLM 真实流量探针:目录驱动(upstreams × models 全展开 × OpenAI/Anthropic)+ `--list-models` 模型发现(打线上 `lm.mayishangshu.cn:88`,**不是本机夹具**;❌ 退 1,拉不到目录退 2) |
| `apix_check.py` | apix 探针:目录驱动逐条探 `/apix/<slug>`(vendor) + `/apixp/<slug>`(passthrough),含**无效 Key 预检**(证 location+鉴权活着)。只有「网关侧没生效」判失败,上游拒单/WAF 如实告警 |
| `gateway/nginx.conf.in` | 域名网关测试配置**模板**(占位符 `@MODULE@` / `@REPO@` / `@RUN@`) |
| `gateway/e2e.sh` | **108 条断言**:鉴权会话 / 账号 / 申请审核 / 免审 / 越权隔离 / Key 重置 / **自动子域名(`i`+8位+`dm`)与点击复制** / 管理台与清理 |
| `gateway/backend/index.html` | 转发靶机内容(断言里检查 `"from":"backend"`) |