1. me_catalog.py 把 .env 约定的**裸主机名**当完整 URL 用:release 里
agent.sh source .env 后子进程继承,live_check 两步探针 ValueError 崩退 1,
被三态口径判成「网关侧故障」触发自动回滚(1.1.1 实测,健康版本差点被回)。
现在补 scheme + IPASS_PUBLIC_PORT;探针脚本未捕获异常统一退 2(验证不可用),
崩溃永远不该触发回滚。
2. rollback 参数键位漂移:远端控制面对 release 发的 {"tag":...} 报「需要显式传
tag」→ 自动回滚 job 失败。agent.sh 的 rollback/回滚体改 python 拼 JSON 并
tag/image 双写;ipass-agent 1.0.4 的 op_rollback 两种键都认、短 tag/裸版本
用受管容器仓库段补全;release 版本闸门抬到 1.0.4(自动回滚必须先证明可用)。
3. 线上默认 tag 迁出 .env → deploy/image.conf(非秘密、入库):release 成功
自动回写 + commit,不再需要人肉同步;.env 的 IPASS_IMAGE_TAG 仅临时覆盖。
另修 agent.sh upstream-test:旧契约(slot 塞 body、无探测体)换成面板同款
(query slot + 第一个登记模型),实测 minimax 200。
57 KiB
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 依赖
-
crates.io 会直接编译失败。
ngx = "0.5"(crates.io 0.5.1)只发布了配置阶段接口HttpModule;请求阶段 APIadd_phase_handler/HttpPhase/HttpRequestHandler尚未发版,报unresolved imports ngx::http::HttpPhase。这些 API 只在 master 分支。 -
git 依赖会永久挂起(最隐蔽的坑)。
ngx-rust挂了一个指向完整 nginx 仓库的 submodule:.gitmodules → [submodule "nginx-src/nginx"] url = https://github.com/nginx/nginx.gitcargo 解析 git 依赖时会自动
update_submodules,去克隆几十 MB 的 nginx 仓库。国内网络下卡死—— 实测 cargo 5 分钟 0% CPU、无网络活动、无产物,sample抓栈停在GitSource::block_until_ready → GitCheckout::update_submodules → fetch → wait4。 -
正解:源码 vendor 到
rust/vendor/ngx-rust/(已剥离.git,748K),Cargo.toml用path依赖;[workspace] exclude = ["vendor/ngx-rust"]处理嵌套 workspace。离线可编译、无子模块。
本机构建(不跑 Docker,秒级迭代)
先准备一棵 只 configure、不必 make 的 nginx 源码树(bindgen 只要头文件):
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
然后:
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(用量账本+趋势)、stats_persist(统计落盘/恢复,1.0.18)、handlers(Llm/LlmHealth/Audit)、api、config/models/store |
up: upa: uac: ukb: upe: uh: ust: ums: utt: utms: ud: udu: uds: uda: uex: spr: |
plugin-apix |
apix(slug/拼体/写穿)、handlers(ApiProxyHandler)、api、config/models/store |
ax: |
gateway 只剩:模块壳(8 条指令(含 1.0.44 ipass_probe_min)+ 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):
- 插件绝不自行 404:
dispatch_api不认领返回None,404 由 gateway 统一发。 - 插件不认识 gateway:location 开关查
loc::enabled(r, Switch::X), 请求级状态挂core::plugin::ctx_index()定位的r->ctx槽——别引用 gateway 私有类型。 - 插件数据反向流只走装配根:身份端点需要的插件数据经
CoreExt由 gateway 回填; 删账号清理经users::on_delete钩子注册;别在内核里 import 插件。
容器内路径:模块装在 /usr/local/nginx/modules/;data 默认 /usr/local/nginx/data(ipass_data_dir 可覆盖)
——这是容器内路径,不要在宿主机上按它找文件(compose 把它挂到宿主 ./data)。
核心机制(理解这五条就够)
- 请求分流靠「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转带体请求。
- 转发(access,
- 共享内存是唯一真源,JSON 文件只是持久化副本(与重构前版本相反)。
重构前是「文件是真源、shm 只是 600s 缓存」,代价是每次 miss 都要同步读文件 + 全表 JSON 解码 + O(n) 扫描。
现在所有写操作同时写 shm 与文件(write-through),miss 就等于「不存在」,
热路径永远零文件 I/O。所以写穿不是优化,而是正确性要求:漏掉
sync_shm等于配置没生效。- ⚠️ 语义代价:绕过 API 直接改
data/*.json不再热生效,需重启或走管理接口。
- ⚠️ 语义代价:绕过 API 直接改
- 免审判定只有一处:
plugin-domain的domains::apply()里auto = dtype == "temp" && user.has_temp_permission(now)。 改审批策略只能改这里,不要在身份端点或 api 层里另写一套。 - 改 Key / 删域名必须摘掉旧索引。
users::sync_shm/domains::sync_shm负责推ukey:/sub:; 重置 API Key 必须先摘旧ukey:,否则被换掉的 Key 照样能通过 LLM 鉴权(本项目踩过)。 - 口令哈希必须与旧版逐位一致:
sha256(salt + ":" + password)之后再迭代 1000 轮sha256(x + salt)。 改HASH_ROUNDS或拼接顺序会让存量users.json全部登录失败(已用独立 Python 实现逐字节核对过)。 /api/v1/me是插件装饰扩展点,不是写死的端点。ipass_core::api::CoreExt::decorate_me是身份端点的唯一装饰入口,由装配根(gateway)实现并把User与port一起传进来—— 装饰能零额外 shm 查询就完成权限收敛(如 upstreams 按allowed_models过滤)。 加新字段给同事发现能力时,往decorate_me里塞,别另开 v1 端点:- 老 3 个 v1 端点(
/api/v1/{domains,upstreams,apix})保留不破坏既有客户端脚本 - me 一个响应 = 身份 + 域名 + LLM 上游 + API 代理 + 用量 + 策略;同事拿一把 key 一个 me 拿全
- 给前端 / 文档 / SDK 展示时也直接讲 me,不要再分别介绍三个端点
- 老 3 个 v1 端点(
LLM API 代理(2026-09-10 新增)
一句话:lm.mayishangshu.cn:18098/<slot>/... 是 LLM 统一出口。客户端用与域名接口同一把
API Key(users.json 里的 sk_...)鉴权,网关换成上游真实密钥后转发——下游永远拿不到厂商 Key。
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 兼容错误体、四个 $llm_* 变量的 get_handler(共享、每次求值各调一次 pick,故 pick 保持纯决策) |
crates/plugin-llm/src/upstreams.rs |
上游校验/读写/写穿共享内存,是域名插件在 LLM 侧的翻版;models 登记 + available() / models_flat() 模型发现;多账号路由(pick_account 粘性 + FNV-1a 冷分散 + 探测闭环冷却:uac: 值 |
<backoff>:<next_probe>:<hard_cap>,到期放一个无绑定真实请求去探测,2xx 即 clear_cool 回队、 |
|
失败 mark_exhausted 内 re-arm 翻倍;pick 必须保持纯决策——副作用归 log 阶段, |
|
四个 $llm_* 变量各求值一次 pick。1.0.44 删除天锚定边界计算,resets 只存不路由)、账号级负载(uda:/uex: 日桶,view() 投影)、normalize_auth(裸 key 自动补 Bearer ,写入 upsert + 读出 read_upa 双处应用) |
|
crates/plugin-llm/src/stats.rs |
用量账本(ust: 每账号 / ums: 每账号×上游,请求级、只读 shm)与 overview() 投影;唯一写点在 LlmHandler 鉴权全通过之后 |
crates/plugin-llm/src/stats_persist.rs |
统计落盘/恢复(1.0.18):快照 data/llm-stats.json、白名单 PREFIXES、退出钩子 + 周期落盘、put-if-absent 恢复、spr:last 恢复记录 / spd:last 落盘记录(都在 shm、都别放进程内静态量) |
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 |
上游白名单;空 = 不限(老数据没有该字段,反序列化即空表) |
三条硬约束
- 鉴权不许走
users::find_by_key。它每次同步读users.json并全表 JSON 解码——管理接口 低频无所谓,但 LLM 每个请求都吃这个代价(见「性能基线」:这类 I/O 足以把吞吐打到 1/25)。 热路径只查ukey:共享内存键,由users::sync_shm写穿维持;重置 Key 必须先摘旧索引, 否则被换掉的 Key 照样能用。 - access 阶段返回
NGX_OK等于放行。鉴权失败必须返回状态码,否则proxy_pass照样执行—— 表现为「客户端收到 401,上游却被调用了一次」,白烧额度且上游账单上看不出这是被拒的请求。 实测踩过,见llm::fail。 - 不按请求体里的
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:
刻意分开(配额宁可多算防滥用,用量要准对账),别想着合并。
删账号必须调 stats::forget:用量键是按前缀扫出来出报表的,不清就会让已删账号继续挂在用量榜上
(与「删账号必须摘 ukey:」同类,只是影响面在报表不在鉴权,最容易漏)。
统计落盘 / 恢复(1.0.18,发版不再清零):ust: ums: utt: utms: ud: udu: uds: uda:
uex: uh: 此前只活在共享内存,进程退出即消失 → 每次发版用量与趋势从 0 重长。
现在由 stats_persist.rs 落一个 JSON 快照 data/llm-stats.json(与 users.json 同级),
两个落盘点互补:worker 退出钩子(gateway::exit_process,覆盖发版 / docker stop,零丢失)
- 记账后按间隔节流落盘(默认 60 秒,覆盖
SIGKILL/OOM/断电)。 启动时gateway::init_process调restore(),put-if-absent → 多 worker 天然幂等、绝不把计数恢复成 N 倍。 ⚠️ 新增统计类键前缀必须同步stats_persist::PREFIXES,漏加不报错、只在发版后表现为「这一列从 0 开始」。 恢复结果发布到 shm(spr:last)而不是进程内静态量——否则接口落到哪个 worker 就报哪个数。 「上次落盘时刻」同理(spd:last,1.0.19):maybe_dump挂在记账路径、每 worker 各算各的, 用静态量会出现「日志落了 10 次、状态页说本进程还没落过」;放 shm 后顺带把周期落盘收敛成「全局每间隔一次」。 接口:GET /api/admin/stats/persist(状态)、POST /api/admin/stats/dump(强制落一次); 指令ipass_stats_persist <秒>(生产 conf 刻意不写,用默认 60,避免旧镜像 unknown directive 起不来)。 新增统计前缀 = 改PREFIXES;详情与 runbook 见docs/llm/STATS_PERSISTENCE.md。
对话审计(1.0.18 改口径):LLM location 开 client_body_in_file_only clean,
log 阶段单遍扫描 body 临时文件,往 <审计根>/YYYY-MM-DD/meta.jsonl 追加一行:
ts/time/user/slot/status/tin/tout/excerpt/body_hash/body_bytes。
不再复制完整请求体(旧版每请求 700 KB+,QPS 10 一天 600 GB,10 GB 配额 24 分钟就 purge)。
excerpt = 前 100 字节(转义只由 json!() 做一次,自己再转义会双重编码成 "\"{\\\"model…",
消费方全部解析不到——1.0.18 首版踩过);body_hash = 全文 SHA256 前 16 hex
(只哈希前 100 字节会因所有请求开头相同而全量碰撞);body_bytes = 全文字节数。
AUDIT_MAX_BYTES 由 10 GB 改 1 GB。详见 docs/llm/AUDIT_LOG.md。
路径拼接去重(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;记住空表 = 不限 |
| 账号耗尽后迟迟不恢复(1.0.44 探测闭环) | 看 uac: 时间线:agent.sh upstreams 的冷却徽章 hover / view 的 probe_next。到期未被探测 = 一直没有无绑定流量(绑定流量永不劫持,属预期);最长硬顶 30min,过期回队若仍耗尽会被再标 |
| 探测请求吃了 429(用户投诉偶发失败) | 设计如此:恢复只能靠真实请求验证,代价被退避封顶(每账号每轮 ≤1 个无绑定请求)。想更快恢复就调低 ipass_probe_min;想更省就调高 |
| 404 但上游明明配了 | enabled: false 会被摘除;或手改了 json 没重启(热路径无回源兜底) |
| 上游 404 且响应体为空 | 上游 base 带 /v1 而客户端也带 /v1 → 拼成 /v1/v1/...;查 llm::join_target 的去重分支 |
/v1/models 反而 404 |
is_models_probe 的位置错了:必须在解析 slot 之前,否则被当成 slot=v1 |
「测试」报 unknown model 'test'(如 minimax 2013),但健康徽章是正常 |
生产 conf 的 /_upstream_test/ 曾注入 proxy_set_body 最小 dummy 体(1.0.43 空 body 兜底遗留),proxy_set_body 是无条件覆盖——面板发来的「第一个登记模型」探测体被整个换掉,严格校验模型名的厂商全部误报不通。已移除;e2e【11】静态闸钉住,别把注入行加回任何一份 conf |
| 用量一直是 0 | 被拒的请求(401/403/404/429)不计用量;或 stats::record 被挪出了"鉴权全通过之后" |
| 删了账号还在用量榜上 | 没调 stats::forget(清 ust: / ums: 前缀) |
| 发版后用量/趋势全变 0 | 快照没落上:查 data/llm-stats.json 是否存在 / 可写(数据卷),看 error log 有无 [stats] 报错。⚠️ 注意登录会话(sess:)与配额(st:)重启清零是设计如此,别把这两样当成故障 |
restored_keys == 0 但 file_keys > 0 |
快照版本不符 / 解析失败(会改名 .bad 留档)/ 全部过期。看 error log 的 [stats] 行 |
| 某维度发版后从 0 开始、别的维度不丢 | 新加的统计前缀漏加进 stats_persist::PREFIXES(不报错,只在发版后暴露) |
| 账号负载数是真实值的 3 倍 | bump_acct_load 被放进了 pick_account —— $llm_target/$llm_host/$llm_auth/$llm_acct 四个变量各触发一次。只能在 log 阶段记一次(冷却 re-arm / 清冷却同理,见 1.0.44 探测闭环) |
| (冷却恢复)排查之后仍觉得不对 | ⚠️ 历史事故(勿回退):1.0.44 前按 cool_until_until 算重置边界,锚点两次算错(1.0.14 的 28800→北京16:00、1.0.24 的 0→北京08:00,纯 epoch 算术不看容器 TZ),造成「厂商 15:00 重置、网关锁到 18:00」。天锚定与 resets 路由语义已整体删除。详情 docs/llm/MULTI_ACCOUNT_ROUTING.md §五 |
| 同一下游 Key 每次换上游账号 | 粘性绑定 ukb: 没写(下行 Key 缺失时本就不写);或该 Key 哈希落点恰好在冷却账号上 |
| 流式退化成一次性返回 | proxy_buffering off 丢了 |
| 上游报 Host / 证书错 | proxy_set_header Host $llm_host 或 proxy_ssl_server_name on 丢了 |
| 上游回 1004 / "Please carry the API secret key" | 账号 auth 存成裸 key(无 Bearer )。plugin-llm 1.0.15+ 的 normalize_auth 会兜底(upsert 写入 + read_upa 读出双处应用),但首选排查是 bash deploy/agent.sh upstreams 看掩码:旧镜像只回脱敏后的掩码看不出问题,新镜像掩码为空会显式标 **空** |
| query 参数丢失 | 变量形式的 proxy_pass 不会自动追加 args,靠 llm::upstream_uri 拼好 |
本机验证夹具:tests/llm/,由 bash tests/run.sh llm 一并起假上游(18999)、LLM 网关(18090)
与管理端口 18091(跑 /api/v1/* 账号态断言)后跑断言。当前规模:网关 108 条 + LLM 262 条
(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,残留脏数据会导致大面积假失败。
⚠️ 本机 safe-delete 钩子会拦「批量删除」:同一个 agent turn 里累计删除超过 50 个文件后,
后续所有删除静默失效(日志里只有 SAFE_DELETE_BULK_CONFIRM_REQUIRED)。表现为「清理没报错但没生效」。
要复位状态就用 mv(rename 不算删除)——tests/run.sh 清上一轮的 data/llm-stats.json
就是 mv 到 .run/llm/stale/。清不掉的后果很隐蔽:上一轮的 ust:/ud:/uh: 会被启动时的
restore() 灌进本轮(carol 用量 2 变 6、「上游健康初始状态」unknown 变 ok),
看起来像统计功能有 bug,实际是测试间的状态泄漏。
性能基线(实测,勿凭直觉优化)
Rust 版(当前架构)
| 路径 | 说明 | 结论 |
|---|---|---|
| shm 命中(本项目热路径) | access 阶段查 sub: + 变量 proxy_pass |
与字面量 proxy_pass 同水平,差异在噪声内 |
变量 proxy_pass,不走模块 |
隔离「变量转发」本身开销 | 同上 |
| shm 未命中(随机 Host / 扫描) | 查表未命中即 404,无文件 I/O | 与命中同量级(旧版这里是 25× 慢) |
换语言不提升热路径 —— 命中路径的开销测不出来,重构前版本在这点上的结论仍然成立。 收益来自两个结构变化,而不是换实现语言带来的解释器/编译器差异:
- miss 路径归零。旧版 miss = 同步读文件 + JSON 解码 + O(n) 线性扫描, 随机 Host 场景实测比命中慢 25 倍(见下表);新版配置全量常驻 shm,miss 就是「查不到」。
- 可以开多 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 可随时复核)。
开工第一步先加载:
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;线上默认 tag 在 deploy/image.conf(非秘密、入库)——release 成功后自动回写。$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。 .env是只读的:沙箱会拦写入(sed -i .env→Operation not permitted), 改它只能由用户手动编辑。别用cp备份到/tmp(那是凭据副本,必须立刻删)。- 线上默认 tag 走
deploy/image.conf,不走.env(1.1.1 起):非秘密、入库,agent.sh release成功后自动回写并 commit(提示 git push),裸update以它做缺省。 不再需要提醒用户手动同步任何东西。.env的IPASS_IMAGE_TAG(如设置)仅作临时覆盖。 旧规矩「人肉同步 .env」的事故形态(1.0.14 发完 .env 仍停 1.0.9 → 裸 update 静默降级)不复存在;agent.sh verify的漂移告警保留——打印!说明 release 中途失败没回写,去查那次发版。
⚠️ 含凭据的命令不要手敲,一律走 deploy/agent.sh
安全策略里有一条:可疑的 bash 命令即使已加进 allow 白名单,仍需人工批准
(内置文档 cli/security.md「命令注入检测」)。curl -H "Authorization: Bearer …"、
. ./.env、从环境取口令这类形态正好命中——表现是每次都弹「凭证授权」;用户拒绝时
命令会静默无输出,极易误判成服务故障(实测踩过一次:/update 根本没发出去)。
所以:凭据永远不出现在命令行上。控制面/验收全部封在 deploy/agent.sh 里,
只需放行 Bash(bash deploy/agent.sh:*) 一条:
bash deploy/agent.sh status # 容器状态 + 镜像 digest + 数据摘要
bash deploy/agent.sh update [tag] # 拉镜像 + 重建容器(缺省用 deploy/image.conf)
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; ② 测试用 nginxlisten 18080;(绑 0.0.0.0)与沙箱冲突,要先改成listen 127.0.0.1:…并开network.allowLocalBinding。开工前先确认这两条,再开。
常用操作
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 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 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备份到~/ipass/backup/ipass-data-<时间>.tar.gz(1.0.17 起:从~/根目录挪到子目录,ls ~不再被一堆ipass-data-backup-*.tar.gz文件刷屏)。update-ipass.sh与ipass-agent.py:backup_data走同一份逻辑,归档同时打包 audit 兄弟目录(1.0.18+ 的对话审计落这里;缺了它备份就丢了"谁在什么时候调过什么" 的证据);audit 不存在则只打包 data。 - 旧镜像不在本地打
rollback-<时间>标签(1.0.17 起:镜像动辄 100 MB+, 本地磁盘会越积越多;阿里云私仓永远保留所有 tag,回滚时docker pull即可), 收尾打印回滚命令:用户显式传 tag,从阿里云拉。 - 审计目录权限:宿主侧首建后必须
chmod 777,否则容器内 nobody worker 写不动, 日志刷[audit] 建日期目录失败 Permission denied、整个审计废掉(实测踩过,1.0.17 修)。 - 旧容器若是 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 鉴权。
# 在 .11 上
python3 ~/ipass/ipass-agent.py --check # 探测(不动任何东西)
python3 ~/ipass/ipass-agent.py --bg # 后台常驻,日志 ~/ipass/ipass-agent.log
python3 ~/ipass/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 tests/run.sh # 全部 370 项:域名网关 108 条 + LLM 代理 262 条
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 |
108 条断言:鉴权会话 / 账号(含展示名)/ 申请审核 / 免审 / 越权隔离 / Key 重置 / 上游多模型与用量 / 自动子域名(i+8位+dm)与点击复制 / 管理端与清理 |
tests/llm/e2e.sh |
262 条断言:鉴权 / 白名单 / 停用摘除 / Key 替换 / 路径拼接(含版本段去重)/ SSE / 限流 / HTTPS / 模型发现 / 账号态用量 / 管理员用量与删账号清用量 /base_url 端口自适应 / 统计落盘与重启恢复 / 探测恢复闭环(标记→到期探测→回队;绑定流量不被劫持;退避翻倍) |
tests/.run/ |
运行目录(渲染出的配置、data/、logs/、cookie)——已 gitignore,随时可删 |
两条不许破的线:
- 状态目录永远是
tests/.run/*/data/,绝不碰生产data/(配置由模板渲染时就写死成独立目录)。 .in模板不能直接交给 nginx(占位符没替换会load_module失败);要手工起就自己先sed一遍。
⚠️ 写这类脚本时的引号陷阱(本脚本曾因此假绿,浪费了一轮排查)
# ✗ 错:命令替换里再套双引号转义 —— 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 做端到端验证:
# 配置是 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:18999mock 会打印收到的 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。