Files
ipass__ipass/tests/README.md
T

127 lines
8.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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=<key>` 形式(带 `#` 注释行也认)——**取整行会拿到
`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/<slug>` 之后的全部**:上游 `/health` 对应
`/apixp/ocr/health`;`usage_hint` 里的 `/<tail>` 要换成 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/<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"`) |
| `llm/nginx.conf.in` | LLM 代理测试配置模板(18090 网关 + **18091 管理端口**,供账号态 `/api/v1/*` 断言) |
| `llm/upstream.py` | 假上游(18999):**记录它实际收到的 path / auth / host / body**;`/<slot>/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】自检断言就是为这类问题设的回归闸。