Files
ipass__ipass/CLAUDE.md
T
admin e38237dc4a feat(deploy): 新增 .11 一键更新脚本 + 上游多模型/模型发现/用量统计
功能(本轮 5 项需求的落地):
- 上游可挂多模型:llm-upstreams.json 每上游新增 models 清单(仅用于模型发现,不参与路由)
- 模型发现:GET /v1/models(OpenAI {object:list} 形状,网关本地应答)+ /api/v1/models + /api/v1/upstreams
- 用量统计:/api/admin/usage(管理台「用量统计」Tab)+ /api/v1/usage + /me 的 llm_usage 摘要
  口径:只统计真正转发出去的请求,401/403/404/429 不计;与配额计数 st: 刻意分开
- 账号展示名 display_name(纯展示,不进 ukey:)
- 修复 /v1 版本段重复拼接(llm::join_target)→ 上游 base 自带 /v1 时不再 404 空体
- 修复删账号未清用量键(stats::forget)

部署脚本 deploy/update-ipass.sh:
- 拉镜像 → tar 备份数据 → 删旧容器 → 按旧容器复刻端口/挂载/网络起新容器 → 自检
- 参数从 docker inspect 静态配置读取(docker port 对停止态容器返回空,会让端口静默回落)
- 端口按 host:container 去重(inspect 同一映射含 IPv4/IPv6 两项,重复 -p 会 address already in use)
- --bg 用 setsid/start_new_session 真正脱离会话(仅 nohup & 会被父进程组连带杀掉)
- 旧镜像自动打 rollback-<时间> 标签,收尾打印回滚命令

回归:bash tests/run.sh all → 网关 78 + LLM 75 = 153 条断言全绿。
文档:readme §12.4 / §15 / §16、CLAUDE.md 常用操作 + 排障速查已同步。
2026-09-12 10:09:56 +08:00

36 KiB
Raw Blame History

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。

历史(2026-09-10):原实现是 OpenResty + Lua,已全量重写为 vanilla nginx + Rust 动态模块 (rust/、conf/nginx.conf、Dockerfile、compose.yml)。 旧版完整归档于 archive/openresty-lua-20260910/(含 SHA256SUMS 与 tarball,已刻意排除 data/)。 重写动机与依据见「性能基线」——不要因为 Lua 版跑得动就回退,收益在 miss 路径与多 worker,不在命中路径。

顶层 lua/ 目录是重写时的遗留副本,归档里已有权威版本;确认无引用后可删(删前先问)。

构建与依赖(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 只要头文件):

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。

注意:上表的 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 的下载阶段。换机器先确认该文件存在。

目录地图(改代码前先看这里)

Rust 模块在 rust/src/ —— 一个文件对应旧版一个 lua/*.lua,职责边界刻意保持一致,方便对着归档对照:

路径 职责 旧版对应
rust/src/lib.rs 模块入口:指令解析、共享内存建表与装载(state_zone_init,fork 前一次)、变量注册、三个阶段处理器(转发 access / LLM access / API content)、init_process 播种 admin conf/nginx.conf 的 init 段 + proxy.lua
rust/src/api.rs API 统一分发器:路由表(精确匹配)+ 鉴权分流(Guard::Public/User/Admin)+ 全部 handler api.lua
rust/src/users.rs 账号:播种 admin、创建、改密、重置 Key、授予/撤销临时授权、ukey: 索引写穿 users.lua
rust/src/domains.rs 域名:申请(含免审判定)、审核、过期判定、sub: 写穿、清理 domains.lua
rust/src/upstreams.rs LLM 上游校验/读写/写穿——domains.rs 在 LLM 侧的翻版 (新增)
rust/src/session.rs 管理员登录会话(sess: 键 + HttpOnly Cookie,滑动续期) session.lua
rust/src/state.rs 共享内存:根结构、键值编解码(栈上拼 key)、业务包装函数 (新增)
rust/src/store.rs JSON 原子读写(.tmp + rename)+ 跨 worker 文件锁 + data 目录 store.lua
rust/src/http.rs 请求辅助:参数合并、两段式请求体读取、JSON 响应输出 util.lua(前者)
rust/src/util.rs 随机数、SHA-256、口令哈希、常量时间比较、时间格式化、日志 util.lua(后者)
rust/src/config.rs 全部策略常量:TTL、保留名、长度上限、共享内存键前缀 config.lua
rust/src/models.rs User / DomainEntry 结构与派生判定(effective_status / is_forwardable) (散在 Lua 里)
rust/src/llm.rs LLM 热路径:slot 解析、Bearer 提取、身份查询、上游变量求值 (新增)
rust/vendor/ngx-rust/ vendored 的 ngx-rust(见「构建与依赖」)。不要换成 crates.io 或 git 依赖 —

其余:

路径 职责
conf/nginx.conf 转发 server、LLM server、管理 server、默认 403 server;ipass_state / ipass_data_dir / 三个 subdomain_* 开关
www/admin.html 管理台单页(登录 / 审核队列 / 全部域名 / 账号管理),纯静态 + fetch
data/users.json 账号表(含口令哈希与 API Key)
data/domains.json 子域名映射表 + 申请记录
data/llm-upstreams.json LLM 上游表(含真实厂商密钥)
logs/access.log 已扩展字段:backend=$proxy_backend_addr
tests/ 本机回归夹具(bash tests/run.sh [gateway|llm|all]):*.conf.in 模板 + 断言脚本 + LLM 假上游;tests/.run/ 是运行目录,已 gitignore。详见「本机验证夹具」
archive/openresty-lua-20260910/ 旧 Lua 版归档,只读参考,勿再修改

容器内路径:模块装在 /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,见「两段式读体」)。
  2. 共享内存是唯一真源,JSON 文件只是持久化副本(与旧版正好相反)。 旧版是「文件是真源、shm 只是 600s 缓存」,代价是每次 miss 都要同步读文件 + 全表 JSON 解码 + O(n) 扫描。 现在所有写操作同时写 shm 与文件(write-through),miss 就等于「不存在」, 热路径永远零文件 I/O。所以写穿不是优化,而是正确性要求:漏掉 sync_shm 等于配置没生效。
    • ⚠️ 语义代价:绕过 API 直接改 data/*.json 不再热生效,需重启或走管理接口。
  3. 免审判定只有一处:domains::apply() 里 auto = dtype == "temp" && user.has_temp_permission(now)。 改审批策略只能改这里,不要在 api.rs 里另写一套。
  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。

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,不落上游)

落点

位置 职责
rust/src/llm.rs 热路径:slot 解析、Bearer 提取、身份查询、OpenAI 兼容错误体、三个变量的 get_handler
rust/src/upstreams.rs 上游校验/读写/写穿共享内存,是 domains.rs 在 LLM 侧的翻版;models 登记 + available() / models_flat() 模型发现
rust/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 必须同样保留上游路径,否则发给客户端的地址本身就错。

账号展示名: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: 前缀)
流式退化成一次性返回 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/* 账号态断言)后跑断言。当前规模:网关 78 条 + LLM 75 条 (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× 慢)

换语言不提升热路径 —— 命中路径的开销测不出来,Lua 版在这一点上的结论仍然成立。 收益来自两个结构变化,而不是「Rust 比 LuaJIT 快」:

  1. miss 路径归零。旧版 miss = 同步读文件 + cjson 解码 + O(n) 线性扫描, 随机 Host 场景实测比命中慢 25 倍(见下表);新版配置全量常驻 shm,miss 就是「查不到」。
  2. 可以开多 worker。旧版 miss 的同步文件 I/O 会阻塞整个 worker,只能 worker_processes 1 (实测单 worker 是全局瓶颈);新版热路径无阻塞 I/O,worker_processes auto 是安全默认。

迁移依据(旧版 Lua 实测,保留作决策记录)

单 openresty 容器、ab -k -c 50、12 核宿主机(前三条 ±20% 噪声,视为同一水平带):

路径 说明 吞吐
字面量 proxy_pass 无 Lua,基准 ~12.6k rps
变量 proxy_pass,无 Lua 隔离变量转发本身的开销 ~11.1k rps
shm 命中(旧版热路径) access_by_lua + proxy_pass $backend_addr ~11.3k rps
缓存未命中:读 546B + cjson + 扫描 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 → 读文件 + cjson + 线性扫描 ~7.7k rps(1.8× 慢)
旧版 · 大表(1000 条 / 266KB) 同上,表变大 ~543 rps(25× 慢)

下表是当时针对旧版 Lua 得出的四点实施结论,现在都已在 Rust 版落实—— 保留它是为了说明当前设计为什么长这样,别按 Lua 的写法去理解:

结论(Lua 语境) 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)。

改配置/接口时的硬规矩

  • 新增接口三步:① 在 api.rs 写 handler,返回统一用 http::ok/fail; ② 在 route() 表加一行,Guard 选 Public / User / Admin; ③ 涉及域名/Key/上游变更的,必须调对应的 sync_shm——漏了就等于没生效(无回源兜底)。 鉴权由分发器统一兜底,不要在单个 handler 里重复实现。
  • 所有写操作必须同时更新 shm 与 JSON 文件。只写一边会出现「重启后配置回滚」或「改了不生效」。
  • 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/ 是写穿语义,重启后从文件重建。
  • 前端隐藏元素必须靠 [hidden]{display:none!important} 兜底:author 样式的 display 会盖掉 UA 的 display:none(本项目踩过)。

常用操作

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/

生产更新(.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 备份 + 旧镜像打 rollback-<时间> 标签,收尾打印回滚命令。
  • 旧容器若是 compose 创建,脚本会提示「已用 docker run 接管」。

验证脚本本身:本机用 NAME=ipass-dt HOST_PORT=<高位> DATA_DIR=/tmp/... SKIP_PULL=1 跑一遍即可(SKIP_PULL=1 用本地镜像,避免误部署旧 tag)。

本机验证夹具(改完必跑)

夹具在仓库里(tests/),不再放 /tmp —— 那儿的脚本一重启就没了,也没法 review。

bash tests/run.sh            # 全部:域名网关 78 条 + LLM 代理 75 条
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 78 条断言:鉴权会话 / 账号(含展示名)/ 申请审核 / 免审 / 越权隔离 / Key 重置 / 上游多模型与用量 / 清理
tests/llm/e2e.sh 75 条断言:鉴权 / 白名单 / 停用摘除 / Key 替换 / 路径拼接(含版本段去重)/ SSE / 限流 / HTTPS / 模型发现 / 账号态用量 / 管理员用量与删账号清用量
tests/.run/ 运行目录(渲染出的配置、data/、logs/、cookie)——已 gitignore,随时可删

两条不许破的线:

  1. 状态目录永远是 tests/.run/*/data/,绝不碰生产 data/(配置由模板渲染时就写死成独立目录)。
  2. .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: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。