Files
ipass__ipass/CLAUDE.md
T
admin bfa3cf8ff8 feat(llm): 上游多账号路由 + 账号级负载统计 (1.0.14)
一个 slot 挂多把上游账号 Key,解决厂商「单账号额度/并发受限」与
「同一用户缓存命中」两个矛盾诉求。

多账号路由 (plugin-llm)
- models: Upstream.accounts[] (auth/note/resets) + 上游级
  exhaust_status/exhaust_markers;顶层 auth 保留兼容(accounts 为空时合成单账号)
- upstreams::pick_account:粘性绑定 ukb:<key> 优先 → 无绑定时
  FNV-1a(下游 Key) % 可用数 冷分散 → 绑定账号冷却则重新分散 → 全冷却取最早恢复
  * 分散避开厂商单账号 agent 并发上限;落点固定保住 prompt/token 缓存
- cool_until_until 天锚定冷却:boundary = day0 + ceil(已过/窗口)*窗口,
  封顶次日 0 点(MiniMax 5h 窗口、24=5*4+4 → 末段 20:00-24:00 只有 4h 随天重置)
- 耗尽双检测 (log 阶段):$upstream_status 命中 exhaust_status,或
  usage_filter 流式扫到 marker → $llm_acct 定位本次账号 → 写冷却 uac:
- shm: up:/upa:/uac:/ukb:/upe: 五类前缀;$llm_acct 变量 (NOCACHEABLE)

账号级负载统计(问题发现与跟踪)
- 新增 uda:<slot>:<idx>:<day>(请求/token)与 uex:(耗尽次数) 日桶,
  复用内核 usage::bump_day —— 无数据库、无新进程(项目红线)
- 计数点只在 log 阶段一次;pick_account 会被 $llm_target/$llm_auth/$llm_acct
  三个变量各触发一次,放进那里会三倍计数
- view() 投影带每账号 load 与 account_trend + trend_labels(日期由后端算)
- 管理台「上游」页密钥列:各 Key 今日请求/token/耗尽 + 负载比例条 +
  14 天迷你趋势(自绘 SVG,零第三方依赖)+ 冷却/耗尽徽标 + 上游合计

测试与验证
- 回归 279 条全绿(网关 102 + LLM 177),新增 6 条多账号/负载断言
- 假上游新增 UPSTREAM_FAIL_AUTH 模拟账号额度耗尽;靶机验证 Key 真被替换
- 前端以真实 admin.css + upstreams.js 渲染路径做无头浏览器断言:
  比例条与负载成比例(412 vs 96 → 100%/23%)、每账号 14 条块、
  悬停峰值日期与数据逐位吻合、单账号/无账号兜底正常、无横向溢出、零 JS 错误

文档
- 新增 docs/llm/MULTI_ACCOUNT_ROUTING.md(数据模型/路由/冷却数学/shm 布局/负载统计)
- readme §11 数据模型 + §15 上游配置 + §15 用量统计 + §12.6 tag 表 + §16 变更记录
- 修正 docs/llm/*.md 中插件化前的过时路径(rust/src/* → crates/plugin-llm/src/*)
2026-09-14 11:57:08 +08:00

664 lines
49 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.
# CLAUDE.md
给 AI 协作者(Claude Code / WorkBuddy 等)的项目说明。人读文档见 `readme.md`。
## 一句话定位
**尚数网 统一网关**(产品名 iPass 山海关):vanilla nginx + **Rust 动态模块**,单容器。
DNS 只配一条泛解析 `*.yourdomain.com` → 本网关;**子域名 → 后端** 的映射热更新,
**新增映射无需改 DNS、无需 reload Nginx**。
上面再加一层治理:账号 + 随机 API Key + 临时/长期域名 + 审核流 + 临时授权权限(6h 免审)+ 临时域名 6h 自动过期。
定位覆盖**动态域名、LLM API 路由及未来各类统一出口能力**;另有一条 `lm.mayishangshu.cn:18098/<slot>/...` 作为 LLM 统一出口(同一把 API Key 鉴权,下游永远拿不到厂商真 Key)。
技术栈:自编译 vanilla nginx + Rust 动态模块(`ngx-rust`)。无数据库、无 Redis、无消息队列、无额外常驻进程。
状态 = `data/` 下四个 JSON 文件;**映射/会话/Key 索引全部常驻共享内存,热路径零文件 I/O**。
## 构建与依赖(Rust 版 —— 踩过的坑都在这)
### 硬约定:`ngx` 必须 vendor,不能用 crates.io,也不能用 git 依赖
1. **crates.io 会直接编译失败**。`ngx = "0.5"`(crates.io **0.5.1**)只发布了配置阶段接口
`HttpModule`;请求阶段 API `add_phase_handler` / `HttpPhase` / `HttpRequestHandler`
**尚未发版**,报 `unresolved imports ngx::http::HttpPhase`。这些 API 只在 master 分支。
2. **git 依赖会永久挂起(最隐蔽的坑)**。`ngx-rust` 挂了一个指向**完整 nginx 仓库**的 submodule:
```
.gitmodules → [submodule "nginx-src/nginx"] url = https://github.com/nginx/nginx.git
```
cargo 解析 git 依赖时会自动 `update_submodules`,去克隆几十 MB 的 nginx 仓库。国内网络下卡死——
**实测 cargo 5 分钟 0% CPU、无网络活动、无产物**,`sample` 抓栈停在
`GitSource::block_until_ready → GitCheckout::update_submodules → fetch → wait4`。
3. **正解**:源码 vendor 到 `rust/vendor/ngx-rust/`(已剥离 `.git`,748K),`Cargo.toml` 用
`path` 依赖;`[workspace] exclude = ["vendor/ngx-rust"]` 处理嵌套 workspace。离线可编译、无子模块。
### 本机构建(不跑 Docker,秒级迭代)
先准备一棵 **只 configure、不必 make** 的 nginx 源码树(bindgen 只要头文件):
```bash
curl -sL -o nginx-1.30.4.tar.gz https://nginx.org/download/nginx-1.30.4.tar.gz # 实测 34 KB/s,约 40s
tar -xzf nginx-1.30.4.tar.gz && cd nginx-1.30.4
./configure --prefix=/tmp/ngxbuild/prefix \
--without-http_rewrite_module --without-http_gzip_module \
--without-http_uwsgi_module --without-http_scgi_module --without-http_grpc_module \
--without-http_ssi_module --without-http_userid_module --without-http_autoindex_module \
--without-http_geo_module --without-http_split_clients_module --without-http_referer_module \
--with-http_realip_module --with-http_ssl_module
```
然后:
```bash
cd rust
NGINX_SOURCE_DIR=/tmp/ngxbuild/nginx-1.30.4 \
NGINX_BUILD_DIR=/tmp/ngxbuild/nginx-1.30.4/objs \
LIBCLANG_PATH=/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib \
cargo build
```
实测:增量 1~2 秒,冷编译约 37 秒。产物 `target/debug/libipass_gateway.dylib`。
workspace 化后可按 crate 迭代(秒级,不动 gateway):
`cargo build -p plugin-llm` / `-p ipass-core` / `-p plugin-apix` / `-p plugin-domain`。
> 注意:上表的 configure **关掉了 rewrite 模块**,所以本机测试配置里**不能用 `set` / `return`**。
> 生产 `Dockerfile` 的 configure 带 rewrite 模块(未 `--without`),`conf/nginx.conf` 可正常使用它们。
### `rust/build.rs` 不可删
macOS 必须 `-undefined dynamic_lookup`:动态模块的 nginx 运行时符号(`ngx_palloc` /
`ngx_http_add_variable` / `ngx_shared_memory_add` …)由 nginx 主程序在 `load_module` 时提供,
链接时必然未定义。`ngx` crate 的 build.rs 也设了这两项,但 `rustc-link-arg` **只对设置它的 crate
生效**、不会传给依赖方,所以本 crate 必须自己再设一次,否则报
`ld: symbol(s) not found for architecture x86_64`。
### crates 源
开发机已配 `~/.cargo/config.toml` 指向 `rsproxy.cn` 镜像。crates.io 官方源在国内会「响应头很快、
实际连接悬挂」,未配镜像时 cargo 可能长时间停在 0% CPU 的下载阶段。换机器先确认该文件存在。
## 目录地图(改代码前先看这里)
**2026-09-13 起插件化**:单 crate 拆为 workspace——`ipass-core`(内核)+ 三个插件
crate + `gateway`(唯一 cdylib)。契约与边界见 `docs/plugin/PLUGIN_ARCHITECTURE.md`;
**给内核加插件**用技能 `ipass-core-add-plugin`。产物名、指令名、conf、`data/*.json`
全部不变。
```
rust/
├── Cargo.toml # workspace 根:members + [workspace.dependencies] + [profile.release]
├── vendor/ngx-rust/ # vendored ngx-rust(path 依赖,别换 crates.io/git)
├── crates/ipass-core/ # 内核:能单独跑网关的部分
├── crates/plugin-domain/ # 域名插件(sub: 键空间)
├── crates/plugin-llm/ # LLM 插件(up:/ust:/ums:/ud:… 键空间)
├── crates/plugin-apix/ # API 代理插件(ax: 键空间)
└── gateway/ # 装配根 + 唯一 cdylib(模块壳 + PLUGINS 注册表 + trend)
```
`ipass-core` 内部模块:
| 模块 | 职责 |
| --- | --- |
| `state.rs` | 共享内存:根结构、键值编解码(栈上拼 key)、业务包装函数 |
| `store.rs` | JSON 原子读写(`.tmp` + `rename`)+ 跨 worker 文件锁 + data 目录(插件数据文件走 `path_in_data` 自管) |
| `users.rs` | 账号唯一写入口:播种 admin、`ukey:` 索引写穿、`on_delete` 钩子注册表 |
| `session.rs` | 管理员登录会话(`sess:` 键 + HttpOnly Cookie,滑动续期) |
| `auth.rs` | **下行链路共用契约**:`downstream_key` / `identity`(查 `ukey:`)/ `check_quota`(`rl:`+`st:`,先增后判)/ OpenAI 兼容错误体——LLM 与 apix 两个 access handler 都调它 |
| `usage.rs` | **记账原语**(无业务语义):窗口读数 + 日桶的 bump/read,键前缀由调用方传 |
| `plugin.rs` | `Plugin` trait + `ctx_index` 注入(插件在 `r->ctx` 挂请求级状态用) |
| `loc.rs` | `Switch` 并集 + 注入式 location 开关查询(未实现变体保守 false) |
| `api.rs` | 身份类端点(login/logout/session/users/me)+ `Guard/Actor/run_guarded` 守卫 + `CoreExt` 扩展注册表(gateway 回填插件数据) |
| `config.rs` | 内核策略常量 + `sess:/fail:/ukey:/rl:/st:` 前缀;插件自有常量在各自 crate |
| `http.rs` / `util.rs` | 请求辅助(两段式读体、JSON 响应)/ 随机数、SHA-256、口令哈希、日志 |
三个插件的模块布局(均为 rlib,只有 gateway 是 cdylib):
| crate | 模块 | 键空间 |
| --- | --- | --- |
| `plugin-domain` | `domains`(申请/审批/写穿)、`resolve`(ResolveHandler + `$proxy_backend_addr`)、`api`、`config/models/store` | `sub:` |
| `plugin-llm` | `llm`(slot 解析/变量求值)、`upstreams`(CRUD/写穿/健康/**多账号路由**/账号负载)、`usage_filter`(body filter 抓 usage+耗尽 marker,走 `loc::enabled`+`ctx_index`)、`llm_audit`(对话审计落盘)、`stats`(用量账本+趋势)、`handlers`(Llm/LlmHealth/Audit)、`api`、`config/models/store` | `up:` `upa:` `uac:` `ukb:` `upe:` `uh:` `ust:` `ums:` `utt:` `utms:` `ud:` `udu:` `uds:` `uda:` `uex:` |
| `plugin-apix` | `apix`(slug/拼体/写穿)、`handlers`(ApiProxyHandler)、`api`、`config/models/store` | `ax:` |
gateway 只剩:模块壳(7 条指令 + `ModuleConfig` 开关 + 变量/装载装配循环)、
`ApiHandler`(读体后按 PLUGINS 顺序分发、统一 404)、`/api/admin/trend`
(需 users+upstreams+apix 三方名册,属组合根)。
其余:
| 路径 | 职责 |
| --- | --- |
| `conf/nginx.conf` | 转发 server、LLM server、管理 server、默认 403 server;`ipass_state` / `ipass_data_dir` + 四个 location 开关(`ipass_proxy` / `ipass_llm` / `ipass_apix` / `ipass_api`) |
| `www/` | 管理台(多页,纯静态 + fetch):`login.html` + `overview/review/domains/users/upstreams/usage/apix.html` + `assets/`(共享 CSS/JS/图表)。每页 `<base href="/admin/">`,见「管理台多页」 |
| `data/users.json` | 账号表(含口令哈希与 API Key) |
| `data/domains.json` | 子域名映射表 + 申请记录 |
| `data/llm-upstreams.json` | LLM 上游表(**含真实厂商密钥**) |
| `data/api-proxies.json` | API 代理表(**含真实供应商密钥**) |
| `logs/access.log` | 已扩展字段:`backend=$proxy_backend_addr` |
| `tests/` | **本机回归夹具**(`bash tests/run.sh [gateway\|llm\|all]`):`*.conf.in` 模板 + 断言脚本 + LLM 假上游;`tests/.run/` 是运行目录,已 gitignore。详见「本机验证夹具」 |
| `docs/plugin/PLUGIN_ARCHITECTURE.md` | **插件化架构(as-built)**:契约、边界解法、装配清单、与 sso 的差异 |
**插件化后的三条新纪律**(完整版见 `docs/plugin/PLUGIN_ARCHITECTURE.md` §6):
1. **插件绝不自行 404**:`dispatch_api` 不认领返回 `None`,404 由 gateway 统一发。
2. **插件不认识 gateway**:location 开关查 `loc::enabled(r, Switch::X)`,
请求级状态挂 `core::plugin::ctx_index()` 定位的 `r->ctx` 槽——别引用 gateway 私有类型。
3. **插件数据反向流只走装配根**:身份端点需要的插件数据经 `CoreExt` 由 gateway 回填;
删账号清理经 `users::on_delete` 钩子注册;**别在内核里 import 插件**。
容器内路径:模块装在 `/usr/local/nginx/modules/`;data 默认 `/usr/local/nginx/data`(`ipass_data_dir` 可覆盖)
——**这是容器内路径,不要在宿主机上按它找文件**(compose 把它挂到宿主 `./data`)。
## 核心机制(理解这五条就够)
1. **请求分流靠「location 开关 + 阶段」**。阶段处理器注册在 http 主配置上(全局生效),
**必须靠 location 指令收敛**(`ipass_proxy` / `ipass_api` / `ipass_llm`),
否则管理台与 API 也会走转发逻辑并被 404。三条路径:
- **转发**(access,`ipass_proxy on`):查 `sub:` → 写 `$proxy_backend_addr` →
`proxy_pass http://$proxy_backend_addr`;查不到直接 404。
子域名由**模块自己从 `Host` 头解析**(`subdomain_of()`),不依赖 nginx 正则 server_name 的捕获组——
所以本机测试配置可以没有 PCRE。
- **LLM**(access,`ipass_llm on`):查 `ukey:` 鉴权 + `up:` 定上游 → 填 `$llm_target/$llm_host/$llm_auth`。
- **API**(content,`ipass_api on`):**先异步读请求体**再分发(access 阶段拿不到 body,见「两段式读体」)。
- **API 代理**(access,`ipass_apix on`):查 `ukey:` 鉴权 + `ax:` 定供应商资产 → 填 `$apix_target/$apix_host/$apix_key/$apix_body`;
**请求体由网关从 query 拼**(`asset_id` 服务端决定),GET 经 `proxy_method POST` + `proxy_set_body` 转带体请求。
2. **共享内存是唯一真源,JSON 文件只是持久化副本**(**与重构前版本相反**)。
重构前是「文件是真源、shm 只是 600s 缓存」,代价是每次 miss 都要同步读文件 + 全表 JSON 解码 + O(n) 扫描。
现在**所有写操作同时写 shm 与文件**(write-through),miss 就等于「不存在」,
热路径永远零文件 I/O。**所以写穿不是优化,而是正确性要求**:漏掉 `sync_shm` 等于配置没生效。
- ⚠️ 语义代价:绕过 API 直接改 `data/*.json` **不再热生效**,需重启或走管理接口。
3. **免审判定只有一处**:`plugin-domain` 的 `domains::apply()` 里
`auto = dtype == "temp" && user.has_temp_permission(now)`。
改审批策略**只能改这里**,不要在身份端点或 api 层里另写一套。
4. **改 Key / 删域名必须摘掉旧索引**。`users::sync_shm` / `domains::sync_shm` 负责推 `ukey:` / `sub:`;
**重置 API Key 必须先摘旧 `ukey:`**,否则被换掉的 Key 照样能通过 LLM 鉴权(本项目踩过)。
5. **口令哈希必须与旧版逐位一致**:`sha256(salt + ":" + password)` 之后再迭代 1000 轮 `sha256(x + salt)`。
改 `HASH_ROUNDS` 或拼接顺序会让存量 `users.json` 全部登录失败(已用独立 Python 实现逐字节核对过)。
## LLM API 代理(2026-09-10 新增)
**一句话**:`lm.mayishangshu.cn:18098/<slot>/...` 是 LLM 统一出口。客户端用**与域名接口同一把**
API Key(`users.json` 里的 `sk_...`)鉴权,网关换成上游真实密钥后转发——下游永远拿不到厂商 Key。
```text
POST /openai/v1/chat/completions Authorization: Bearer sk_<本网关签发>
→ access 阶段 LlmHandler(靠 ipass_llm 开关收敛)
① 取 URL 第一段 → slot = openai
② 查 ukey:<key> → 身份 + 白名单(纯内存,不读 users.json)
③ 查 up:<slot> → 上游 base + 上游真 Key(纯内存)
④ 通过则放行;$llm_target / $llm_host / $llm_auth
由 proxy_pass 求值时经 get_handler 填充(与 $proxy_backend_addr 同构)
→ 转发到上游(下游 Key 被替换成上游真 Key,不落上游)
```
**落点**
| 位置 | 职责 |
| --- | --- |
| `crates/plugin-llm/src/llm.rs` | 热路径:slot 解析、Bearer 提取、身份查询、OpenAI 兼容错误体、三个变量的 get_handler |
| `crates/plugin-llm/src/upstreams.rs` | 上游校验/读写/写穿共享内存,是域名插件在 LLM 侧的翻版;`models` 登记 + `available()` / `models_flat()` 模型发现;**多账号路由**(`pick_account` 粘性 + FNV-1a 冷分散 + 天锚定冷却 `cool_until_until`)与**账号级负载**(`uda:`/`uex:` 日桶,`view()` 投影) |
| `crates/plugin-llm/src/stats.rs` | 用量账本(`ust:` 每账号 / `ums:` 每账号×上游,请求级、只读 shm)与 `overview()` 投影;**唯一写点在 `LlmHandler` 鉴权全通过之后** |
| `data/llm-upstreams.json` | 上游表(**含真实密钥**);`base` 可带路径,`auth` 是完整的 Authorization 值,`models` 仅供模型发现 |
| `conf/nginx.conf` | `lm.mayishangshu.cn:18098` server;SSE 三件套 + `proxy_ssl_server_name` |
| `users.json` → `allowed_models` | 上游白名单;**空 = 不限**(老数据没有该字段,反序列化即空表) |
**三条硬约束**
1. **鉴权不许走 `users::find_by_key`**。它每次同步读 `users.json` 并全表 JSON 解码——管理接口
低频无所谓,但 LLM 每个请求都吃这个代价(见「性能基线」:这类 I/O 足以把吞吐打到 1/25)。
热路径只查 `ukey:` 共享内存键,由 `users::sync_shm` 写穿维持;**重置 Key 必须先摘旧索引**,
否则被换掉的 Key 照样能用。
2. **access 阶段返回 `NGX_OK` 等于放行**。鉴权失败必须返回状态码,否则 `proxy_pass` 照样执行——
表现为「客户端收到 401,上游却被调用了一次」,白烧额度且上游账单上看不出这是被拒的请求。
实测踩过,见 `llm::fail`。
3. **不按请求体里的 `model` 路由**。access 阶段读不到 body(要 content 阶段异步读),按 model 分流
就得放弃 `proxy_pass`、自建 upstream,代价差一个数量级。上游一律由 URL 前缀决定。
**限流与配额(按 Key)**:`llm_rpm`(默认 60)/ `llm_daily`(默认 0=不限),配置编码进
`ukey:` payload(4 行格式:`user\nallowed\nrpm\ndaily`),**改 User 限流字段必须走
`users::set_llm_limits`(内含 sync_shm 写穿)**,直接改 json 不重启不生效。计数器在
`rl:<user>` / `st:<user>`(每账号固定单键,value=`<窗id>:<计数>`,读时比对窗 id 跨窗归零;
不要改成「每窗一个键」,shm 键会无限累积)。`bump_window` 跨 worker 无互斥,近似计数——
对限流可接受,别为它上写锁把热路径串行化。429 必须区分 `rate_limit_error`(SDK 退避)
与 `insufficient_quota`。是请求级不是 token 级:SSE 关缓冲透传就拿不到响应体里的 usage,
token 计费与零依赖红线冲突,别轻易许诺。
**模型发现(2026-09-12)**:上游的 `models` 只是**登记清单**。网关本地应答 `/v1/models`
(LLM 域名下,OpenAI `{object:"list",...}` 形状)与 `/api/v1/models`(管理端口,统一响应体 + `base_url`),
**不转发上游**。判断顺序关键:`llm::is_models_probe` 必须在**解析 slot 之前**,否则 `/v1/models`
会被当成 `slot=v1` 直接 404。**绝不按 `model` 字段路由**(同硬约束 3)——模型名与 slot 是两套东西。
**用量统计(2026-09-12)**:`stats::record` 只统计**真正转发出去**的请求,401/403/404/429 不计,
所以它在 `check_quota` 之后、`NGX_DECLINED` 之前调用,**挪位置就改变了语义**。与配额计数 `st:`
**刻意分开**(配额宁可多算防滥用,用量要准对账),别想着合并。计数只在 shm(`ust:` 每账号、
`ums:` 每账号×上游)、重启归零、不落盘——要持久化就得加文件,与红线冲突。
**删账号必须调 `stats::forget`**:用量键是按前缀扫出来出报表的,不清就会让已删账号继续挂在用量榜上
(与「删账号必须摘 `ukey:`」同类,只是影响面在报表不在鉴权,最容易漏)。
**路径拼接去重(2026-09-12 修复)**:`llm::join_target(base, path)` 在 base 路径段与请求路径开头
重复时只保留一份——上游 `base` 带 `/v1`、客户端又带 `/v1` 时,少这一步就会拼成 `/v1/v1/...`
→ 上游 **404 且响应体为空**,而网关侧日志一切正常,极难排查。`upstreams::base_url` 对外回显的
`base_url` 必须同样**保留上游路径**,否则发给客户端的地址本身就错。
**`base_url` 的端口必须自适应(2026-09-12 修复)**:它跟随调用方 `Host` 头里的端口
(`http::host_port`)。三个域名共用宿主 **88**,而 88 ≠ 443 —— 地址里不带端口会落到 443 上的
**出口 SSL 设备**,实测返回 `HTTP 200` + 一个 HTML 登录页(最难察觉的一种失败:状态码正常、
内容完全不对,客户端表现为「鉴权失败」或「响应不是 JSON」)。反过来写死 `:88` 又会在
443 反代部署下把客户端指向另一个端口。**别再改成任何一种写死形式。**
**账号展示名**:`users.json` 的 `display_name` 是**纯展示字段**(`users::view` 额外回一个 `name` =
展示名优先、空则回落账号名)。**不参与鉴权、不进 `ukey:` payload**,热路径看不到它,别当身份用。
**HTTPS(可选)**:`conf/tls/*.conf` 被 `conf/nginx.conf` include,空目录 = 没配、不影响启动;
模板 `conf/tls/llm.conf.example`。`compose.yml` 已映射 443。**生产 Dockerfile 必须带
`--with-http_ssl_module`**(2026-09-10 补上,此前没编,443 server 在容器里会起不来);
本机 `/tmp/ngxbuild` 的 nginx 也已重编带 ssl(回归的 HTTPS 组靠它)。TLS 是独立 server 块,
location 与 80 端口 LLM server 是两份拷贝,改一处记得同步另一处。
**排障**
| 现象 | 原因 |
| --- | --- |
| 全站 401 | `ukey:` 索引没装载 → 看启动日志「已装载 N 个账号 Key」;Key 刚重置则旧 Key 立即失效 |
| 某账号一直 403 | `allowed_models` 非空且不含该 slot;记住空表 = 不限 |
| 404 但上游明明配了 | `enabled: false` 会被摘除;或手改了 json 没重启(热路径无回源兜底) |
| 上游 404 且**响应体为空** | 上游 `base` 带 `/v1` 而客户端也带 `/v1` → 拼成 `/v1/v1/...`;查 `llm::join_target` 的去重分支 |
| `/v1/models` 反而 404 | `is_models_probe` 的位置错了:**必须在解析 slot 之前**,否则被当成 `slot=v1` |
| 用量一直是 0 | 被拒的请求(401/403/404/429)**不计用量**;或 `stats::record` 被挪出了"鉴权全通过之后" |
| 删了账号还在用量榜上 | 没调 `stats::forget`(清 `ust:` / `ums:` 前缀) |
| 账号负载数是真实值的 3 倍 | `bump_acct_load` 被放进了 `pick_account` —— `$llm_target`/`$llm_auth`/`$llm_acct` 三个变量各触发一次。**只能在 log 阶段记一次** |
| 某把 Key 耗尽后一直在冷却 / 迟迟不恢复 | `resets` 填成滚动时长(`now+5h`)而非天锚定周期;MiniMax 视角的 5h 窗口末段只有 4h(见 `upstreams::cool_until_until`) |
| 同一下游 Key 每次换上游账号 | 粘性绑定 `ukb:` 没写(下行 Key 缺失时本就不写);或该 Key 哈希落点恰好在冷却账号上 |
| 流式退化成一次性返回 | `proxy_buffering off` 丢了 |
| 上游报 Host / 证书错 | `proxy_set_header Host $llm_host` 或 `proxy_ssl_server_name on` 丢了 |
| query 参数丢失 | 变量形式的 `proxy_pass` 不会自动追加 args,靠 `llm::upstream_uri` 拼好 |
**本机验证夹具**:`tests/llm/`,由 `bash tests/run.sh llm` 一并起假上游(18999)、LLM 网关(18090)
与**管理端口 18091**(跑 `/api/v1/*` 账号态断言)后跑断言。当前规模:网关 **102 条** + LLM **177 条**
(`bash tests/run.sh all`,期望失败 0)。
`tests/llm/upstream.py` 会把收到的 `path` / `auth` / `host` / `body` 记到 `.run/llm/upstream.log`
——**验证「Key 是否真的被替换」最直接的手段**,只看网关自己的响应是看不出来的。
夹具账号(`tests/llm/fixtures/`,**合成数据**):alice 白名单=`openai`、bob 空白名单=不限、
carol `llm_rpm=2`、dave `llm_daily=2`(限流断言用)。夹具上游含 **`deepseeklike`**(`base` 自带 `/v1`),
专测**版本段去重**。run.sh 会自动生成自签证书 + 渲染 443 server(端口 18443)跑 HTTPS 组——
前提是本机 nginx 带 `http_ssl_module`,否则该组自动跳过。**勿复用生产 `data/`。**
夹具重置一律用 **`cp` 覆盖写**(`tests/gateway/fixtures/`、`tests/llm/fixtures/`),
**不要 `rm` 运行目录里的 json**——本机安全钩子会拦 `rm`,残留脏数据会导致大面积假失败。
## 性能基线(实测,勿凭直觉优化)
### Rust 版(当前架构)
| 路径 | 说明 | 结论 |
| --- | --- | --- |
| shm 命中(本项目热路径) | access 阶段查 `sub:` + 变量 `proxy_pass` | 与字面量 `proxy_pass` **同水平,差异在噪声内** |
| 变量 `proxy_pass`,不走模块 | 隔离「变量转发」本身开销 | 同上 |
| shm 未命中(随机 Host / 扫描) | 查表未命中即 404,**无文件 I/O** | **与命中同量级**(旧版这里是 25× 慢) |
**换语言不提升热路径** —— 命中路径的开销测不出来,重构前版本在这点上的结论仍然成立。
收益来自两个结构变化,而不是换实现语言带来的解释器/编译器差异:
1. **miss 路径归零**。旧版 miss = 同步读文件 + JSON 解码 + O(n) 线性扫描,
随机 Host 场景实测比命中**慢 25 倍**(见下表);新版配置全量常驻 shm,miss 就是「查不到」。
2. **可以开多 worker**。旧版 miss 的同步文件 I/O 会阻塞整个 worker,只能 `worker_processes 1`
(实测单 worker 是全局瓶颈);新版热路径无阻塞 I/O,`worker_processes auto` 是安全默认。
### 迁移依据(重构前实测,保留作决策记录)
单 worker 容器、`ab -k -c 50`、12 核宿主机(前三条 ±20% 噪声,视为同一水平带):
| 路径 | 说明 | 吞吐 |
| --- | --- | --- |
| 字面量 `proxy_pass` | 静态反代基线 | ~12.6k rps |
| 变量 `proxy_pass`,无动态语言 | 隔离变量转发本身的开销 | ~11.1k rps |
| **shm 命中(旧版热路径)** | `proxy_pass $backend_addr` | **~11.3k rps** |
| 缓存未命中:读 546B + JSON 解码 + 扫描 | `domains.resolve` 的真实成本 | ~5.7k rps(**-50%**) |
| 缓存未命中:读 265KB / 1000 条 | 同上,表变大 | ~566 rps(**-95%**) |
| 裸 `ngx.shared` get | 单次 | **0.073 µs/op** |
> ⚠️ **这段历史里曾有一句「不要为此写 nginx C 扩展模块」——已被推翻,不要拿它反对当前架构。**
> 那句话只看了命中路径。补测随机 Host(未命中)场景后结论反转,**这才是改 Rust 的依据**。
### 未命中路径放大:随机子域名(扫描 / 长尾)场景
用**随机 Host**(每个请求都未命中)压,差距被放大到 25 倍:
| 方案 | 说明 | 吞吐 |
| --- | --- | --- |
| **配置全量放内存** | shm 查表,miss = 不存在,**零 I/O** | **~13.9k rps** |
| 旧版 · 小表(3 条 / 812B) | miss → 读文件 + JSON 解码 + 线性扫描 | ~7.7k rps(**1.8× 慢**) |
| 旧版 · 大表(1000 条 / 266KB) | 同上,表变大 | ~543 rps(**25× 慢**) |
下表是当时针对**重构前**得出的四点实施结论,**现在都已在 Rust 版落实**——
保留它是为了说明当前设计为什么长这样:
| 结论 | Rust 版对应实现 |
| --- | --- |
| 全量装载只跑一次,别每个 worker 各跑一遍 | 装载放在 `state_zone_init`(nginx 在 **fork 之前**回调一次),`init_process` 只负责播种 admin |
| 必须跨 worker 共享,不能用模块级容器 | `ngx_shared_memory_add` + `SlabPool` + `RbTreeMap`;**锁也分配在共享内存里**(`RwLock` 在 slab 上),否则跨 worker 不互斥 |
| shm 开销约 124 B/条,`10m` ≈ 8 万条 | `ipass_state state 10m`;表涨到数万条再考虑调大 |
| 写 shm 必须判返回值(`no memory` 要有降级);临时域名过期不能只靠 shm 自身 exptime | `state::put` 返回 `bool`,调用方必须处理;`expires_at` 随 value 一起存(`<payload>\x1f<expires_at>`),由 `get_live` 判过期 |
| 写操作必须「写穿」,miss 不再回源 | 所有写操作同时更新 shm 与文件(`sync_shm` / `reload_shm`) |
| 语义代价:文件从「真源」降为「启动快照」,手改文件不再热生效,需要显式 reload 入口 | 已接受此代价;当前**没有** reload 入口,改文件后需重启(`docker compose restart`) |
复现:独立容器 + 非 80 端口 + `ab -k`(固定 Host)或随机 Host 脚本,**勿在生产 `data/` 上跑**,
**合成数据的 backend 不要照抄生产内网地址**(否则测试流量会真的打到内网机器上,本项目踩过)。
## 硬约定(改代码必须遵守)
**安全与生命周期**
- **不要在 worker 里 panic**。`Cargo.toml` 设了 `panic = "abort"`——一次 panic 直接打死整个 worker
(不是 500,是 worker 进程消失)。热路径禁止 `unwrap()` / `expect()` / 数组越界索引,
错误一律走 `Result` + 显式降级。管理接口也照此办理。
- **不要在 worker 里起子进程或 shell**(`std::process::Command`、`libc::system`)。
文件落盘靠 `store` 的原子写(`.tmp` + `rename`)就够了。
- **热路径禁止同步文件 I/O**。转发/LLM 只查共享内存;`users::find_by_key` 会读文件 + 全表解码,
**只能用在管理接口**,不要顺手用在 LLM 鉴权上(见「LLM API 代理」硬约束 1)。
**改配置/接口时的硬规矩**
- **新增接口三步**:① 在对应 crate 的 `api.rs` 写 handler(身份类进 `ipass-core`,
业务类进所属插件 crate),返回统一用 `http::ok/fail`;
② 在该 crate 的 `route()` 表加一行,`Guard` 选 `Public` / `User` / `Admin`;
③ 涉及域名/Key/上游/代理变更的,**必须调对应的 `sync_shm`**——漏了就等于没生效(无回源兜底)。
鉴权由 gateway 分发器统一兜底,**不要在单个 handler 里重复实现**;
插件 handler 不认领时返回 `None`,**绝不自行 404**。
- **所有写操作必须同时更新 shm 与 JSON 文件**。只写一边会出现「重启后配置回滚」或「改了不生效」。
- **写共享内存失败必须出声**。`state::put_*` 返回 `false`(zone 满 / 分配失败)时,三处 `sync_shm`
会 `log_err`(带对象标识与后果),三处 `reload_shm` 会核对「期望条数 vs 实际装载」。**别丢掉返回值**——
热路径没有回源兜底,写失败就是「刚建好却调不通,日志里什么都没有」,属于最难查的一类形态。
- **`env ADMIN_INIT_PASSWORD;` 必须在 `conf/nginx.conf` 的 main 上下文**。少了这行 nginx 会剥离环境变量,
模块读到的初始密码恒为空(靠 `INIT_ADMIN_PASSWORD` 播种 admin 的逻辑就依赖它)。
- **新增 location 用 `$proxy_backend_addr` 时**,变量注册已在 `lib.rs` 的 **preconfiguration** 完成;
不要在 request 阶段才 `add_variable`,那时 `proxy_pass http://$xxx` 已经解析失败。
- **两段式读体只服务于 API**。`client_body_buffer_size` 必须大于最大 API 请求体,
否则超出的部分落到临时文件而 `collect_body` 只读内存 buf → **body 被静默截断**(表现为 JSON 解析失败)。
当前管理 server 设 1m,够用;调大请求体时记得同步调它。
- **JSON 空数组必须序列化成 `[]`**。`serde_json` 对空 `Vec` 本来就输出 `[]`,
但**别用 `json!({})` 或手动构造去顶替列表字段**——前端直接 `.map/.filter`,拿到 `{}` 会报错。
- **改 `rust/` 或 `conf/` 后必须重启 nginx**(`docker compose restart`)。动态模块在 `load_module` 时载入,
reload 不会重新加载 `.so`;`data/` 是写穿语义,重启后从文件重建。
- **子域名规则有两处耦合,改一处必须改另一处**:`config.rs` 的 `ENTERPRISE_ZONE`(+ 前缀/后缀/位数)
与 `conf/nginx.conf` 企业域名 server 的 `server_name ~^(?<subdomain>.+dm)\.mayishangshu\.cn$;`。
**后缀 `dm` 不是命名偏好**——正则要求捕获组以 `dm` 结尾,否则域名建出来也匹配不上转发 server。
规则经 `GET /api/admin/domains` 的 `subdomain_rule` 下发给面板,前端不硬编码;
`subdomain` 留空即自动生成(`domains::gen_subdomain`),管理台与 API 共用 `domains::create_by_admin`。
- **前端隐藏元素必须靠 `[hidden]{display:none!important}` 兜底**:author 样式的 `display`
会盖掉 UA 的 `display:none`(本项目踩过)。
**发版**
- **镜像 tag 只增不改**:`ipass-1.0.0` → `1.0.1` → `1.0.2` …… 每有一次改动就 +1,走
`bash deploy/release.sh <tag>`;**绝不覆盖已推送过的 tag**(覆盖会让远端内容与本地缓存 /
`rollback-*` 标签错位 → 回滚选错镜像)。详见「发版(本机)」一节。
## 凭据与授权(不要再向用户索要)
**凭据只有一个入口:仓库根 `.env`**(已被 `.gitignore` 忽略,`git check-ignore -v .env` 可随时复核)。
开工第一步先加载:
```bash
set -a; . ./.env; set +a
```
随后一切取变量,不要写死、也不要问用户:
| 用途 | 变量 |
| :--- | :--- |
| 远程控制面 | `$IPASS_AGENT_HOST` + `Authorization: Bearer $IPASS_AGENT_TOKEN` |
| 管理台登录 | `$IPASS_ADMIN_USER` / `$IPASS_ADMIN_PASSWORD` |
| 三个域名 | `$IPASS_MDM_HOST` / `$IPASS_LLM_HOST` / `$IPASS_ENTERPRISE_SUFFIX`,宿主端口 `$IPASS_PUBLIC_PORT` |
| 发版 | `$IPASS_REGISTRY` / `$IPASS_IMAGE_TAG` |
| 源码仓库 | `$IPASS_GITEA` |
硬约定:
- **不要把 `.env` 内容打印到输出**(`cat .env` / `env | grep IPASS` 之类一律不要);需要时只取单个变量。
- **上游厂商真 Key 不复制到本地**:真源在线上 `data/llm-upstreams.json`,控制面 `/data?file=upstreams`
只回 `has_auth` 布尔(**故意不回值**)。要换 Key 就在面板/控制面里改线上那份。
- **命令免授权白名单**:`.workbuddy/settings.local.json`(本机、不入库,`/permissions` 可查看与增删)。
已放行本项目常用命令(`cd`/`ls`/`git` 只读/`bash deploy`/`docker build|push`/内网 `curl`/`python3` …);
破坏性命令(`rm` / `sudo` / `docker rm` / `git push --force` / `git reset --hard`)显式 `deny`,仍会被硬拦。
- 白名单是**本机**配置:换机器要重拷 `.env` 与 `.workbuddy/settings.local.json`。
### ⚠️ 含凭据的命令**不要手敲**,一律走 `deploy/agent.sh`
**安全策略里有一条:可疑的 bash 命令即使已加进 `allow` 白名单,仍需人工批准**
(内置文档 `cli/security.md`「命令注入检测」)。`curl -H "Authorization: Bearer …"`、
`. ./.env`、从环境取口令这类形态正好命中——表现是**每次都弹「凭证授权」**;用户拒绝时
命令会**静默无输出**,极易误判成服务故障(实测踩过一次:`/update` 根本没发出去)。
所以:**凭据永远不出现在命令行上**。控制面/验收全部封在 `deploy/agent.sh` 里,
只需放行 `Bash(bash deploy/agent.sh:*)` 一条:
```bash
bash deploy/agent.sh status # 容器状态 + 镜像 digest + 数据摘要
bash deploy/agent.sh update [tag] # 拉镜像 + 重建容器(缺省用 .env 的 IPASS_IMAGE_TAG)
bash deploy/agent.sh wait <job-id> # 轮询任务直到结束并打印日志
bash deploy/agent.sh release 1.0.7 # 构建推送 → 更新 → 验收,一条龙
bash deploy/agent.sh verify # 正式环境验收(登录+页面标记+subdomain_rule)
bash deploy/agent.sh rollback [tag] # 回滚
```
> **另一条更彻底的路子**(尚未启用):开启 **bash 沙箱**
> (`sandbox.enabled: true` + `autoAllowBashIfSandboxed: true`)可从根上减少审批。
> 注意两个前提:① 官方文档说 `docker` 与沙箱不兼容,需放进 `excludedCommands`;
> ② 测试用 nginx `listen 18080;`(绑 0.0.0.0)与沙箱冲突,要先改成
> `listen 127.0.0.1:…` 并开 `network.allowLocalBinding`。**开工前先确认这两条**,再开。
## 常用操作
```bash
cd <项目根>
# ---- 生产:容器 ----
docker compose up -d # 启动(首次会播种 admin)
docker compose restart # ★ 改完 rust/ 或 conf/ 后必须重启(不是 reload)
docker compose logs -f
# ---- 开发:本机直接跑(不跑 Docker,改一行 1~2 秒出结果)----
cd rust && NGINX_SOURCE_DIR=../build/ngxbuild/nginx-1.30.4 \
NGINX_BUILD_DIR=../build/ngxbuild/nginx-1.30.4/objs \
LIBCLANG_PATH=/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib \
cargo build
# 产物:rust/target/debug/libipass_gateway.dylib
# 管理台
open https://mdm.mayishangshu.cn:18098/admin # 初始 admin / 123456(或 ADMIN_INIT_PASSWORD)
# 账号态:用 API Key 申请域名
KEY=sk_xxx
curl -s -H "X-API-Key: $KEY" -H 'Content-Type: application/json' \
-d '{"subdomain":"demo","backend":"192.168.1.7:89","type":"temp"}' \
https://mdm.mayishangshu.cn:18098/api/v1/domains/apply
# 管理员态:登录取 Cookie 后调用
curl -s -c /tmp/c.txt -H 'Content-Type: application/json' \
-d '{"username":"admin","password":"123456"}' \
https://mdm.mayishangshu.cn:18098/api/admin/login
curl -s -b /tmp/c.txt https://mdm.mayishangshu.cn:18098/api/admin/domains
# 不带 DNS 直接验证转发(本机联调最省事)
curl -H "Host: demo.yourdomain.com" http://127.0.0.1/
```
### 发版(本机):`deploy/release.sh` —— **tag 只增不改**
```bash
bash deploy/release.sh 1.0.2 # 构建 → 打 tag → 推送 → 打印远程更新命令
bash deploy/release.sh 1.0.2 # 再跑:远端同名 tag 已存在 → 拒绝
DRY_RUN=1 bash deploy/release.sh 1.0.3 # 只构建不推送
```
- 对外 tag 形如 `ipass-1.0.0` / `ipass-1.0.1` / …:**每有一次改动就 +1 推新 tag,
绝不覆盖已推送过的 tag**。同名 tag 覆盖会让远端 `pull` 到的内容与本地缓存 / 已打的
`rollback-*` 标签错位 → 回滚选错镜像,也没法从 tag 判断线上是哪一版。
- 脚本用 `docker manifest inspect` 探测远端,**同名 tag 存在即拒发**(需先 `docker login`);
发版前校验 `git status` 干净,保证 **tag ↔ commit** 一一对应。
⚠️ **脚本不校验是否已 push**——1.0.12 发版成功但代码没推到 Gitea,远端看不到(实测踩过)。
**发版前先 `git push`**;日常一律走 `bash deploy/agent.sh release <tag>` 一条龙
(构建 → push CR → 远程更新 → 验收)。
- 本机必须走经典构建器(脚本已内置 `DOCKER_BUILDKIT=0`):buildx 写 activity 会被沙箱拦 rename。
- 发完之后在 .11 上更新走下一节的控制面,**`image` 显式填新 tag**。
### 生产更新(.11):`deploy/update-ipass.sh`
镜像推到 Aliyun CR 后,在 .11 上跑这一个脚本即可(**不要手写 `docker run` 参数**):
```bash
bash update-ipass.sh --check # 只体检:打印探测到的容器/端口/数据目录
bash update-ipass.sh # 前台更新
bash update-ipass.sh --bg # 后台更新(日志 ~/ipass-update-<时间>.log)
```
设计要点(都是踩过坑才这么写的,改脚本时别退回去):
- **端口/挂载/网络一律从旧容器复刻**,读 `docker inspect` 的 `HostConfig` 而**不是** `docker port`
—— 后者对「已停止/未启动」容器返回空,会让端口静默回落成 18098。
- **端口映射必须按 `host:container` 去重**:inspect 里同一映射可能同时含 IPv4/IPv6 两项,
重复 `-p` 直接 `address already in use`。
- **`--bg` 必须 `setsid` / `start_new_session`**:只 `nohup &` 时,脚本被父进程组回收,
表现是「删完旧容器就停住,新容器没起来」(数据没事,但服务是断的)。
- 数据目录 `chown 65534:65534`(worker 是 nobody),否则写穿 JSON 失败。
- 动手前 `tar` 备份 + 旧镜像打 `rollback-<时间>` 标签,收尾打印回滚命令。
- 旧容器若是 compose 创建,脚本会提示「已用 docker run 接管」。
> 验证脚本本身:本机用 `NAME=ipass-dt HOST_PORT=<高位> DATA_DIR=/tmp/... SKIP_PULL=1`
> 跑一遍即可(`SKIP_PULL=1` 用本地镜像,避免误部署旧 tag)。
### 远程控制面(更推荐):`deploy/ipass-agent.py`
跑在 **.11 上的常驻 HTTP 服务**(默认 `:18099`),把上面那套动作变成接口,**AI 可以直接
远程 pull / 更新 / 回滚 / 看日志**,形成「本机构建推送 → 远程更新 → 远程自验证」闭环,
不必每次找人登服务器。单文件、仅标准库、Bearer token 鉴权。
```bash
# 在 .11 上
python3 ipass-agent.py --check # 探测(不动任何东西)
python3 ipass-agent.py --bg # 后台常驻,日志 ~/ipass-agent.log
python3 ipass-agent.py --stop
# 在本地(AI 用)
A=http://192.168.1.11:18099; T='Authorization: Bearer <token>'
curl -s -H "$T" $A/status
curl -s -H "$T" -H 'Content-Type: application/json' -d '{"image":"<镜像>"}' $A/update # → job id
curl -s -H "$T" $A/jobs/<id>?offset=0 # 增量拉执行日志
curl -s -H "$T" -H 'Content-Type: application/json' -d '{}' $A/rollback
```
- **异步任务模型**:变更类 `POST` 立刻返回 `{"job":id}`,日志从 `/jobs/<id>?offset=N` 增量取;
**同时只允许一个变更任务**(并发第二个 → 409),因为两个 update 并发删容器会互相踩。
- **HTTP/1.1 必须先把请求体读掉再应答**(哪怕是 401):不读的话残包会被当成下一个请求的
请求行 → 响应串包。改 Handler 时别把 `_read_body()` 从 `_dispatch` 开头挪走。
- 端口/挂载/env/网络/重启策略从旧容器 `docker inspect` 复刻;动手前自动备份 + 打 rollback 标签。
- **受管容器锁(别退回「信任调用方传的 name」)**:`update` / `restart` / `rollback` 只允许作用于
「受管容器」——`--name` 指定者优先,否则自动探测到的 ipass 容器;两者都没有时退化为主机名
前缀白名单 `ipass*`(`ensure_managed()`)。传别的容器名 → **403 且不建任务**。同机通常还跑着
别的 nginx(.11 上有 `invoicehelper-nginx`、`d15-nginx-1`),没这道锁 = 把删/起容器的能力
开到整台机器。
- `/data` 对 `api_key` 脱敏,但 `domains.json` 原样返回 —— 服务等价 docker 权限,**必须设 token
且只在内网监听**,绝不上公网。
- 本机自测夹具做法:造 `ipass-dt` 容器(高位端口 + `/tmp` 数据目录),`--port` 用 18449,
`IPASS_AGENT_TOKEN=xxx` 固定 token,`POST /update` 带 `skip_pull:true` + 本地镜像。
再顺手造一个**非 ipass 名**的容器(如 `victim-app`)验证守卫:对它发 restart / update / rollback
应**全部 403**,且它的 `docker inspect -f '{{.State.StartedAt}}'` **前后一字不变**。
注意 `echo "$JSON" | python3` 在 **zsh 下会把 `\r` 还原成真回车**导致 JSON 解析报错 ——
那是测试命令的问题,不是服务的 bug(用文件或 `printf '%s'` 传)。
## 本机验证夹具(改完必跑)
夹具**在仓库里**(`tests/`),不再放 `/tmp` —— 那儿的脚本一重启就没了,也没法 review。
```bash
bash tests/run.sh # 全部 262 项:域名网关 102 条 + LLM 代理 160 条
bash tests/run.sh gateway # 只跑域名网关
bash tests/run.sh llm # 只跑 LLM 代理(自动起假上游)
```
`run.sh` 干的事:`cargo build` → 把 `tests/*/nginx.conf.in` 渲染成 `tests/.run/*/nginx.conf`
(`@MODULE@` / `@REPO@` / `@RUN@` 换成绝对路径)→ 起 nginx(18080 转发 / 18081 靶机 /
18082 管理 / 18090 LLM / 18091 LLM 管理)→ 跑断言 → 收尾停进程。**期望输出「失败 0」。**
| 路径 | 作用 |
| --- | --- |
| `tests/run.sh` | 统一入口:编译 + 渲染配置 + 起停 + 跑断言 |
| `tests/gateway/e2e.sh` | **102 条断言**:鉴权会话 / 账号(含展示名)/ 申请审核 / 免审 / 越权隔离 / Key 重置 / 上游多模型与用量 / **自动子域名(`i`+8位+`dm`)与点击复制** / 管理端与清理 |
| `tests/llm/e2e.sh` | **160 条断言**:鉴权 / 白名单 / 停用摘除 / **Key 替换** / 路径拼接(含版本段去重)/ SSE / 限流 / HTTPS / **模型发现** / **账号态用量** / **管理员用量与删账号清用量** /**base_url 端口自适应** |
| `tests/.run/` | 运行目录(渲染出的配置、`data/`、`logs/`、cookie)——**已 gitignore,随时可删** |
**两条不许破的线**:
1. 状态目录永远是 `tests/.run/*/data/`,**绝不碰生产 `data/`**(配置由模板渲染时就写死成独立目录)。
2. `.in` 模板**不能直接交给 nginx**(占位符没替换会 `load_module` 失败);要手工起就自己先 `sed` 一遍。
> ⚠️ **写这类脚本时的引号陷阱(本脚本曾因此假绿,浪费了一轮排查)**
> ```bash
> # ✗ 错:命令替换里再套双引号转义 —— bash 会二次去转义,`{a,b}` 触发花括号展开,
> # JSON 被拆成两个词,服务端只收到半截 body(如 `"id":"d_xxx"` 和 `"action":"approve"` 分两次发出)
> curl ... -d "{\"id\":\"$ID\",\"action\":\"approve\"}"
>
> # ✓ 对:在顶层用单引号拼接成变量,再整体引用
> BODY=$(jbody id "$ID" action approve) # jbody 是脚本里的安全构造器
> curl ... -d "$BODY"
> ```
> 危险点在于**报错会伪装成业务 bug**:服务端返回「参数缺失」,看着像后端解析问题。
> 判别手法:在服务端把收到的 body 原样打出来(本项目就是这么定位的),
> 或直接对比 `Content-Length` 与预期长度。脚本里的【0】自检断言就是为这类问题设的回归闸。
### 真域名实测实例(/tmp/ipass_real)
回归全绿后,用**真实域名 + 真实证书 + 18098** 做端到端验证:
```bash
# 配置是 conf/nginx.conf 的本机渲染版(路径指向仓库、data 隔离在 /tmp/ipass_real/data)
ADMIN_INIT_PASSWORD='<自定>' build/ngxbuild/nginx-1.30.4/objs/nginx \
-c /tmp/ipass_real/nginx.conf -p /tmp/ipass_real
```
- 独立 data(`/tmp/ipass_real/data`):`users.json` 置 `{}` 启动即 seed admin;
`llm-upstreams.json` 配假上游(`127.0.0.1:18999` mock 会打印收到的 Authorization,
用来证明「网关 Key → 上游 Key」真的被替换)。
- 验证清单:`openssl s_client` 看 SAN/有效期 → `mdm` 登录 + 会话 → `lm` 发请求看 Key 替换 →
企业域名申请-审核-转发(审核接口要登录会话 Cookie,不是 X-API-Key)。
- **该实例无守护**:进程退出不会自动拉起(2026-09-11 曾静默退出过一次,日志只有优雅 exit),
打不开先 `lsof -iTCP:18098 -sTCP:LISTEN` 查监听,再重启。
- 证书管理(acme.sh → conf/tls 同步、reload 生效、ECC 配对检查)见 readme §12.2 与 `conf/tls/README.md`。
## 排障速查
| 现象 | 原因 / 处置 |
| --- | --- |
| `403 {"code":403,...}` | Host 不匹配 `*.yourdomain.com`,落到了默认 server |
| `404 子域名未配置、已过期或后端不可达` | ①`sub:` 里没有该子域名(`domains.json` 里有没有?没生效就是漏了 `sync_shm`)②有但 `status != approved` ③是 temp 且已过 `expires_at` ④后端连不上 → 看 `logs/error.log` |
| **改了代码但行为没变** | 90% 是**没重启**。动态模块 `load_module` 时载入,reload 不重载 `.so`;容器里还要确认挂进去的是新编译的 `.so` |
| **worker 进程静默消失 / 全站 502** | worker 里 panic 了(`panic = "abort"`)。看 `logs/error.log` 的 `panic` 栈,多半是热路径 `unwrap()` |
| **API 收到「参数缺失」,但同一请求手敲 curl 正常** | 请求体被截断。见「本机验证夹具」的引号陷阱;或 `client_body_buffer_size` 小于请求体 |
| 管理台登录后仍显示登录框 | `[hidden]` 兜底 CSS 丢了 |
| 管理接口 `401` | 会话 Cookie 缺失/过期(重启会清空会话,属预期);`/api/v1/*` 的 401 是 `X-API-Key` 不对 |
| 用户接口 `401` 但 Key 看着没错 | Key 可能刚被重置;旧 Key 立即失效(`ukey:` 旧索引已摘) |
| LLM 全站 `401` | 启动日志没有「已装载 N 个账号 Key」→ `ukey:` 没装载;或上游未配 |
| 审核通过了却不生效 | 写操作忘了 `sync_shm`(新版**没有**缓存 TTL 兜底,漏了就是永久不生效,直到重启) |
| `429 登录失败次数过多` | 同一 IP 5 分钟内失败满 10 次,等窗口过期(`LOGIN_FAIL_TTL`)或重启 |
| 编译报 `unresolved imports ngx::http::HttpPhase` | 用到了 crates.io 的 `ngx` 0.5.1。必须用 `rust/vendor/ngx-rust`(见「构建与依赖」) |
| `cargo build` 卡住 5 分钟 0% CPU | 又把 `ngx` 改回 git 依赖了 —— 它挂的 submodule 会去克隆完整 nginx 仓库 |
| 链接报 `ld: symbol(s) not found` | `rust/build.rs` 的 `-undefined dynamic_lookup` 被删了(macOS 必需) |
| 后端是 hostname 却连不上 | `resolver` 是否可达(当前 `223.5.5.5 119.29.29.29`) |
| 内网设备用公网 IP 打不开「指向自己」的端口映射 | hairpin 自环:路由器对「目标=发起者自己」的回环处理不通,对**其他**内网机器的映射正常。绕行:经内网代理机 TCP 中转(`:88 → 18098`),外网带 `:88` 访问(详见 readme §12.3) |
| 疑似证书问题,但 `conf/tls` 里的证书没过期 | 先 `openssl s_client -servername <域名>` 看浏览器/链路**实际**收到的证书;acme.sh 签发产物在 `~/.acme.sh/`,**与 `conf/tls/` 是两份**,续期后必须拷贝过去再 reload |
| 更新脚本「删完旧容器就停住,新容器没起来」 | 后台方式没真正脱离会话。必须 `setsid` / `start_new_session`,仅 `nohup &` 会被父进程组连带杀掉。数据在 `DATA_DIR` 未受影响,按打印的回滚命令起回来 |
| 更新后端口变了 / 外部访问不通 | 旧容器处于停止态时 `docker port` 返回空 → 端口回落成默认值。要读 `docker inspect` 的 `HostConfig.PortBindings` |
| 更新时报 `address already in use` | 端口参数重复(inspect 里同一映射含 IPv4/IPv6 两项),按 `host:container` 去重 |
> 线上日志字段:`logs/access.log` 的 `backend=$proxy_backend_addr` 直接给出命中的后端;
> 模块自身的装载/审核/删除动作打在 `logs/error.log`(`[ipass]` / `[api]` 前缀)。
## 边界:不要做的事
- 不要引入数据库、Redis、消息队列或额外常驻进程 —— 本项目的价值就是单容器、零依赖。
- 不要在 `readme.md` / `CLAUDE.md` 里写真实 API Key、账号口令或内网拓扑明细。
- 不要把 `data/`(含口令哈希与全部 Key)提交进版本库;`logs/`、`.DS_Store`、`.workbuddy/` 已忽略。
- 不要重写整个 `nginx.conf` —— 它很短,**逐点修改**。
- 不要以为手改 `data/*.json` 会热生效 —— **共享内存才是运行期真源**,改文件需重启(见「核心机制」第 2 条)。
- 不要把 LLM 厂商真 Key 写进 `data/llm-upstreams.json` 之外的任何地方,也不要提交该文件。
- 未确认需求前不要动 `data/domains.json` 与 `data/users.json`,那会直接影响线上转发与登录。
- 测试时不要复用生产 `data/` 目录:起独立容器 + 独立 data 目录 + 非 80 端口,用 `curl -H "Host: ..."` 验证,
不要改 `/etc/hosts` 或占用 80。