# 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//...` 作为 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/图表)。每页 ``,见「管理台多页」 | | `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//...` 是 LLM 统一出口。客户端用**与域名接口同一把** API Key(`users.json` 里的 `sk_...`)鉴权,网关换成上游真实密钥后转发——下游永远拿不到厂商 Key。 ```text POST /openai/v1/chat/completions Authorization: Bearer sk_<本网关签发> → access 阶段 LlmHandler(靠 ipass_llm 开关收敛) ① 取 URL 第一段 → slot = openai ② 查 ukey: → 身份 + 白名单(纯内存,不读 users.json) ③ 查 up: → 上游 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:` / `st:`(每账号固定单键,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 一起存(`\x1f`),由 `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 ~^(?.+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**(覆盖会让远端内容与本地缓存 / `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 # 轮询任务直到结束并打印日志 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 ` 一条龙 (构建 → 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 ' 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/?offset=0 # 增量拉执行日志 curl -s -H "$T" -H 'Content-Type: application/json' -d '{}' $A/rollback ``` - **异步任务模型**:变更类 `POST` 立刻返回 `{"job":id}`,日志从 `/jobs/?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。