# tests —— 本机回归夹具 改完 `rust/` 或 `conf/` 后跑这里,别靠手敲 curl 试。 ```bash bash tests/run.sh # 全部(域名网关 108 条 + LLM 代理 262 条 = 370) bash tests/run.sh gateway # 只跑域名网关(108 条断言) bash tests/run.sh llm # 只跑 LLM 代理(262 条断言) ``` 脚本会自动 `cargo build`,起 nginx,跑断言,收尾停进程。**期望输出「失败 0」。** ## 上线后验证(真实环境,不是本机夹具) 上面跑的是**假上游**;`deploy/agent.sh verify` 又只验管理台,**不发真实 LLM 请求**。 要确认「新版在线上真能干活」,用这个把三步合起来一键跑(`agent.sh release` 第 3/4 步就是它): ```bash bash tests/live_check.sh # 三步全跑(key 默认 ~/ssw.txt) bash tests/live_check.sh ~/.keys/ipass.txt # 指定 key 文件 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=` 形式(带 `#` 注释行也认)——**取整行会拿到 `sk=sk_xxx` → 全量 401**,脚本内部已处理;全程不打印 Key 原文。 延迟参考:deepseek/qwen/minimax 1~2.6s,**glm 7~12s**,别拿 glm 当超时基线。 三个 apix 探针的固定坑(写脚本时踩过,改条目时留意): 1. **必须伪装 UA**:供应商边缘(souyi 走 Cloudflare)会拦 `Python-urllib/3.x` → `403 error code: 1010`;换 curl UA 立刻 200。看着像 IP 被封,其实是 UA。 2. **passthrough 的 tail 是 `/apixp/` 之后的全部**:上游 `/health` 对应 `/apixp/ocr/health`;`usage_hint` 里的 `/` 要换成 slug(`/ocr/base64` → `/apixp/ocr/ocr/base64`),照抄会得到上游 404。 3. **vendor 的参数只放白名单值**:accel 只放行 GitHub/Gitee/GitLab,给 `example.com` 会 `400 target host not allowed`(链路其实是通的,属 ⚠️)。 ## 目录 | 路径 | 作用 | | --- | --- | | `run.sh` | 统一入口:编译 → 渲染配置 → 起进程 → 跑断言 → 收尾 | | `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/`(vendor) + `/apixp/`(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"`) | | `llm/nginx.conf.in` | LLM 代理测试配置模板(18090 网关 + **18091 管理端口**,供账号态 `/api/v1/*` 断言) | | `llm/upstream.py` | 假上游(18999):**记录它实际收到的 path / auth / host / body**;`//v1/models` 原样透传 | | `llm/sse_test.py` | 流式探针:输出 `CHUNKS` / `FIRST` / `TOTAL`,判断 SSE 有没有被缓冲 | | `llm/e2e.sh` | **262 条断言**:鉴权 / 白名单 / 停用摘除 / **Key 替换** / 路径拼接(含版本段去重)/ SSE / **模型发现** / **账号态用量** / **管理员用量总览与删账号清用量** / **统计落盘与重启恢复** | | `llm/fixtures/*.json` | 固定账号与上游表(**合成数据**,见下) | | `.run/` | 运行目录(生成的 `nginx.conf`、`data/`、`logs/`、`cookie.jar`)—— 已 gitignore | ## 三条不要踩的线 1. **绝不碰生产 `data/`**。两套配置的 `ipass_data_dir` 都指向 `tests/.run/*/data/`, 由 `run.sh` 渲染时写入,是独立目录。跑测试不需要也不应该动仓库根的 `data/`。 2. **不要直接把 `.in` 模板交给 nginx**。占位符没替换,`load_module` 会失败。 要手工起就自己 `sed` 一遍,或者直接用 `run.sh`。 3. **`.run/` 里的是运行产物**,可以随时删;删了下次跑会重建。 ## 为什么 `llm/` 侧一定要看靶机日志 网关返回 200 **不代表**上游收到了正确的头。本项目要证的是「下游那把 `sk_...` 被换成了上游真 Key」——这只有读 `upstream.py` 记下的 `auth` 才能证。 所以 `llm/e2e.sh` 里最关键的两条断言是: ``` sse_test.py → 首块 < 0.5s 到达(证明 proxy_buffering off 生效) 靶机 auth → Bearer sk-UPSTREAM-REAL-SECRET 且不含 sk_alice_ ``` ## fixtures 说明 `llm/fixtures/users.json` 与 `llm-upstreams.json` 是**合成夹具**: `pwd_hash` 多为占位、`api_key` 是 `aaaa…` / `bbbb…`、上游 `auth` 是 `sk-UPSTREAM-REAL-SECRET` 这类明显假值。它们**不是**任何环境的真实凭据, 刻意入库,好让 LLM 侧回归在干净机器上一把跑通。 两个例外值得知道: - `admin` 账号的 `pwd_hash` 是**按项目算法真算出来的**(口令 `123456`)—— 【10】要真登录管理台才能查用量、删账号。算法见 `rust/src/util.rs::hash_password`: `x = sha256(salt + ":" + pwd)`,再迭代 1000 轮 `x = sha256(x + salt)`。 改口令就照它重算,别写成占位(写错的表现是「登录 401」)。 - `deepseeklike` 上游的 `base` **自带 `/v1`**,专测**版本段去重** (少这一步会拼成 `/v1/v1/...` → 上游 404 且响应体为空)。 真实凭据只在仓库根的 `data/*.json`(已 gitignore,绝不入库)。 ## 写这类脚本的引号陷阱(曾因此假绿,浪费一轮排查) ```bash # ✗ 错:命令替换里再套双引号转义 —— bash 二次去转义,`{a,b}` 触发花括号展开, # JSON 被拆成两个词,服务端只收到半截 body(如 `"id":"d_xxx"` 和 `"action":"approve"` 分两次发出) curl ... -d "{\"id\":\"$ID\",\"action\":\"approve\"}" # ✓ 对:在顶层用函数拼成变量,再整体引用 BODY=$(jbody id "$ID" action approve) curl ... -d "$BODY" ``` 危险点在于**报错会伪装成业务 bug**:服务端返回「参数缺失」,看着像后端解析问题。 判别手法:在服务端把收到的 body 原样打出来,或对比 `Content-Length` 与预期长度。 `gateway/e2e.sh` 开头的【0】自检断言就是为这类问题设的回归闸。