docs: 文档与注释系统性对齐插件化现状 + 清理前身实现引用

- readme §16 补 1.0.10-1.0.13 四条变更记录;§12.6 tag 表补 1.0.9-1.0.13
- readme §5 架构图更新为插件化结构(PLUGINS 注册表/四开关/四表)
- readme §11 补 api-proxies.json 数据模型小节;§8 管理台表格补 API 代理行
- readme/CLAUDE.md 测试断言数对齐 262(102+160);三个 JSON 改四个
- CLAUDE.md LLM 落点表改 crates/plugin-llm 路径;发版补 git push 前置教训
- 清理全部前身实现引用(readme 三处、CLAUDE.md 性能章节、util.rs 注释)
- PLUGIN_ARCHITECTURE.md 增补 1.0.13 sso 合流记录
This commit is contained in:
admin committed 2026-09-13 18:27:28 +08:00
1 parent ee05b27a36
commit db99ce1521
14 files changed
+173 -123

No files matched your search

+36 -38
View File
@@ -11,14 +11,7 @@ DNS 只配一条泛解析 `*.yourdomain.com` → 本网关;**子域名 → 后
定位覆盖**动态域名、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/` 目录是重写时的遗留副本,归档里已有权威版本;确认无引用后可删(**删前先问**)。
状态 = `data/` 下四个 JSON 文件;**映射/会话/Key 索引全部常驻共享内存,热路径零文件 I/O**。
## 构建与依赖(Rust 版 —— 踩过的坑都在这)
@@ -131,7 +124,7 @@ gateway 只剩:模块壳(7 条指令 + `ModuleConfig` 开关 + 变量/装载
| 路径 | 职责 |
| --- | --- |
| `conf/nginx.conf` | 转发 server、LLM server、管理 server、默认 403 server;`ipass_state` / `ipass_data_dir` / 三个 `subdomain_*` 开关 |
| `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` | 子域名映射表 + 申请记录 |
@@ -140,7 +133,6 @@ gateway 只剩:模块壳(7 条指令 + `ModuleConfig` 开关 + 变量/装载
| `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 的差异 |
| `archive/openresty-lua-20260910/` | 旧 Lua 版归档,**只读参考,勿再修改** |
**插件化后的三条新纪律**(完整版见 `docs/plugin/PLUGIN_ARCHITECTURE.md` §6):
@@ -166,13 +158,14 @@ gateway 只剩:模块壳(7 条指令 + `ModuleConfig` 开关 + 变量/装载
- **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) 扫描。
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` 里另写一套。
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)`。
@@ -198,9 +191,9 @@ POST /openai/v1/chat/completions Authorization: Bearer sk_<本网关签
| 位置 | 职责 |
| --- | --- |
| `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` 鉴权全通过之后** |
| `crates/plugin-llm/src/llm.rs` | 热路径:slot 解析、Bearer 提取、身份查询、OpenAI 兼容错误体、三个变量的 get_handler |
| `crates/plugin-llm/src/upstreams.rs` | 上游校验/读写/写穿共享内存,是域名插件在 LLM 侧的翻版;`models` 登记 + `available()` / `models_flat()` 模型发现 |
| `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` | 上游白名单;**空 = 不限**(老数据没有该字段,反序列化即空表) |
@@ -274,7 +267,7 @@ location 与 80 端口 LLM server 是两份拷贝,改一处记得同步另一
| query 参数丢失 | 变量形式的 `proxy_pass` 不会自动追加 args,靠 `llm::upstream_uri` 拼好 |
**本机验证夹具**:`tests/llm/`,由 `bash tests/run.sh llm` 一并起假上游(18999)、LLM 网关(18090)
与**管理端口 18091**(跑 `/api/v1/*` 账号态断言)后跑断言。当前规模:网关 **90 条** + LLM **111 条**
与**管理端口 18091**(跑 `/api/v1/*` 账号态断言)后跑断言。当前规模:网关 **102 条** + LLM **160 条**
(`bash tests/run.sh all`,期望失败 0)。
`tests/llm/upstream.py` 会把收到的 `path` / `auth` / `host` / `body` 记到 `.run/llm/upstream.log`
@@ -296,24 +289,24 @@ carol `llm_rpm=2`、dave `llm_daily=2`(限流断言用)。夹具上游含 **
| 变量 `proxy_pass`,不走模块 | 隔离「变量转发」本身开销 | 同上 |
| shm 未命中(随机 Host / 扫描) | 查表未命中即 404,**无文件 I/O** | **与命中同量级**(旧版这里是 25× 慢) |
**换语言不提升热路径** —— 命中路径的开销测不出来,Lua 版在这一点上的结论仍然成立。
收益来自两个结构变化,而不是「Rust 比 LuaJIT 快」:
**换语言不提升热路径** —— 命中路径的开销测不出来,重构前版本在这点上的结论仍然成立。
收益来自两个结构变化,而不是换实现语言带来的解释器/编译器差异:
1. **miss 路径归零**。旧版 miss = 同步读文件 + `cjson` 解码 + O(n) 线性扫描,
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` 是安全默认。
### 迁移依据(旧版 Lua 实测,保留作决策记录)
### 迁移依据(重构前实测,保留作决策记录)
单 openresty 容器、`ab -k -c 50`、12 核宿主机(前三条 ±20% 噪声,视为同一水平带):
单 worker 容器、`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%**) |
| 字面量 `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** |
@@ -327,13 +320,13 @@ carol `llm_rpm=2`、dave `llm_daily=2`(限流断言用)。夹具上游含 **
| 方案 | 说明 | 吞吐 |
| --- | --- | --- |
| **配置全量放内存** | shm 查表,miss = 不存在,**零 I/O** | **~13.9k rps** |
| 旧版 · 小表(3 条 / 812B) | miss → 读文件 + cjson + 线性扫描 | ~7.7k rps(**1.8× 慢**) |
| 旧版 · 小表(3 条 / 812B) | miss → 读文件 + JSON 解码 + 线性扫描 | ~7.7k rps(**1.8× 慢**) |
| 旧版 · 大表(1000 条 / 266KB) | 同上,表变大 | ~543 rps(**25× 慢**) |
下表是当时针对**旧版 Lua** 得出的四点实施结论,**现在都已在 Rust 版落实**——
保留它是为了说明当前设计为什么长这样,别按 Lua 的写法去理解:
下表是当时针对**重构前**得出的四点实施结论,**现在都已在 Rust 版落实**——
保留它是为了说明当前设计为什么长这样:
| 结论(Lua 语境) | Rust 版对应实现 |
| 结论 | Rust 版对应实现 |
| --- | --- |
| 全量装载只跑一次,别每个 worker 各跑一遍 | 装载放在 `state_zone_init`(nginx 在 **fork 之前**回调一次),`init_process` 只负责播种 admin |
| 必须跨 worker 共享,不能用模块级容器 | `ngx_shared_memory_add` + `SlabPool` + `RbTreeMap`;**锁也分配在共享内存里**(`RwLock` 在 slab 上),否则跨 worker 不互斥 |
@@ -359,10 +352,12 @@ carol `llm_rpm=2`、dave `llm_daily=2`(限流断言用)。夹具上游含 **
**改配置/接口时的硬规矩**
- **新增接口三步**:① 在 `api.rs` 写 handler,返回统一用 `http::ok/fail`;
② 在 `route()` 表加一行,`Guard` 选 `Public` / `User` / `Admin`;
③ 涉及域名/Key/上游变更的,**必须调对应的 `sync_shm`**——漏了就等于没生效(无回源兜底)。
鉴权由分发器统一兜底,**不要在单个 handler 里重复实现**。
- **新增接口三步**:① 在对应 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 实际装载」。**别丢掉返回值**——
@@ -495,6 +490,9 @@ DRY_RUN=1 bash deploy/release.sh 1.0.3 # 只构建不推送
`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**。
@@ -567,7 +565,7 @@ curl -s -H "$T" -H 'Content-Type: application/json' -d '{}' $A/rollback
夹具**在仓库里**(`tests/`),不再放 `/tmp` —— 那儿的脚本一重启就没了,也没法 review。
```bash
bash tests/run.sh # 全部:域名网关 90 条 + LLM 代理 111 条
bash tests/run.sh # 全部 262 项:域名网关 102 条 + LLM 代理 160 条
bash tests/run.sh gateway # 只跑域名网关
bash tests/run.sh llm # 只跑 LLM 代理(自动起假上游)
```
@@ -579,8 +577,8 @@ bash tests/run.sh llm # 只跑 LLM 代理(自动起假上游)
| 路径 | 作用 |
| --- | --- |
| `tests/run.sh` | 统一入口:编译 + 渲染配置 + 起停 + 跑断言 |
| `tests/gateway/e2e.sh` | **90 条断言**:鉴权会话 / 账号(含展示名)/ 申请审核 / 免审 / 越权隔离 / Key 重置 / 上游多模型与用量 / **自动子域名(`i`+8位+`dm`)与点击复制** / 管理端与清理 |
| `tests/llm/e2e.sh` | **111 条断言**:鉴权 / 白名单 / 停用摘除 / **Key 替换** / 路径拼接(含版本段去重)/ SSE / 限流 / HTTPS / **模型发现** / **账号态用量** / **管理员用量与删账号清用量** /**base_url 端口自适应** |
| `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,随时可删** |
**两条不许破的线**:
+3 -4
View File
@@ -1,9 +1,8 @@
# ipass-gateway —— 多阶段构建
#
# 与旧版(官方 openresty 镜像)的区别:这里必须自己编译 nginx。
# 原因见 CLAUDE.md:ngx-rust 官方明确要求「针对生产上真正要用的那份 nginx 源码 +
# 完全相同的 configure 参数」编译模块,否则 bindgen 看到的符号/API 与实际运行时不一致。
# OpenResty 的 nginx 打了大量补丁,不属于受支持组合,因此本项目改用官方 nginx。
# 这里必须自己编译 nginx。原因见 CLAUDE.md:ngx-rust 官方明确要求「针对生产上
# 真正要用的那份 nginx 源码 + 完全相同的 configure 参数」编译模块,否则 bindgen
# 看到的符号/API 与实际运行时不一致。
# ---------------------------------------------------------------------------
# 构建阶段:编译 nginx + 编译 Rust 动态模块
+1 -1
View File
@@ -4,7 +4,7 @@
# export ADMIN_INIT_PASSWORD='<初始管理员密码>' # 仅首次启动、users.json 不存在时生效
# docker compose up -d --build
#
# 与旧版(官方 openresty 镜像)的区别:镜像需要自己构建(编译 nginx + Rust 模块),
# 镜像需要自建(编译 nginx + Rust 模块):
# 因此用 build 而不是 image。conf 仍为只读挂载,data 可写。
services:
gateway:
+6 -7
View File
@@ -1,13 +1,12 @@
# ============================================================================
# iPass 山海关(ipass-gateway)—— vanilla nginx + Rust 动态模块
#
# 与旧 OpenResty 版的差异:
# * 不再需要 lua_package_path / lua_shared_dict / init_worker_by_lua
# * 共享内存由 ipass_state 指令创建,模块内部管理
# * 管理 API 由 ipass_api 指令开启(content 阶段)
# * 转发热路径由 ipass_proxy 指令开启(access 阶段)
# * 共享内存由 ipass_state 指令创建,模块内部管理
# * 管理 API 由 ipass_api 指令开启(content 阶段)
# * 转发热路径由 ipass_proxy 指令开启(access 阶段)
# * LLM 代理由 ipass_llm / API 代理由 ipass_apix(access 阶段)
#
# 阶段处理器是 http 级的,所以**必须**靠上面两个开关按 location 收敛,
# 阶段处理器是 http 级的,所以**必须**靠 location 开关收敛,
# 否则管理台自己也会被转发逻辑 404 掉。
# ============================================================================
@@ -57,7 +56,7 @@ http {
# 模板见 conf/tls/llm.conf.example,说明见 conf/tls/README.md
include /usr/local/nginx/conf/tls/*.conf;
# ========== 共享内存(替代旧版的 lua_shared_dict 三件套)==========
# ========== 共享内存(一张表,前缀区分用途)==========
# 一张表同时承载:转发映射 / 管理会话 / 登录失败计数。
# 容量实测约 124 B/条,10m 足够放约 8 万条。
ipass_state state 10m;
+5
View File
@@ -214,3 +214,8 @@ gateway 保留:7 条指令解析(`ModuleConfig` 四开关 + `loc_switch` 注
- [x] 下行鉴权/配额与记账原语下沉 core;用量解读归 plugin-llm;apix 记账走
`plugin_llm::stats`(单一写入口)
- [x] `/api/admin/trend` 留 gateway(组合根)
**1.0.13 增补(2026-09-13)**:sso 上游化建议 4 条已合入内核——`User.extra` flatten
(插件字段透传)+ `users::update_extra`、`state::split_value` 改 `rposition`、
`state::iter_prefix_ex`。逐条采纳/撤回理由见 `SSO_UPSTREAM_DECISIONS.md`;
契约(trait / Switch / CoreExt)不变。
+95 -40
View File
@@ -145,39 +145,39 @@ DNS:*.yourdomain.com ──(泛解析,只配一次,永不修改)──▶
DNS: *.yourdomain.com → 本网关 IP(泛解析,只配一次)
│
▼
┌──────────────────────────────────┐
│ nginx :80 + Rust 动态模块 │
└───────────────┬──────────────────┘
│ 按 Host 分流(模块自己解析 Host)
┌──────────────────────────┴──────────────────────────┐
▼ ▼
Host = mdm.mayishangshu.cn:18098 Host = <任意>.yourdomain.com
┌──────────────────────────────────┐ ┌──────────────────────────────┐
│ /admin 管理台(多页 HTML) │ │ 模块 access 阶段 │
│ /api/v1/* 账号态 (X-API-Key)│ │ │ │
│ /api/admin/* 管理员态(登录会话)│ │ ▼ │
│ │ │ │ domains.rs: 查 sub: 共享内存 │
│ ▼ │ │ (全量常驻,miss = 不存在) │
│ api.rs 统一分发(content 阶段, │ │ 校验 status=approved │
│ 先异步读请求体) │ │ 且 temp 未过期 │
│ ├─ users.rs 账号/Key/授权 │ │ │ │
│ ├─ domains.rs 申请/审核/过期 │ │ ▼ │
│ └─ session.rs 管理员会话 │ │ 写 $proxy_backend_addr │
│ │ │◀──────────┤ ▼ │
│ ▼ │ sync_shm proxy_pass http://$proxy_backend│
│ data/users.json(持久化副本) │ (写穿) └──────────────────────────────┘
│ data/domains.json │
└──────────────────────────────────┘
┌───────────────────────────────────────┐
│ nginx :80 + libipass_gateway.so │
│ gateway 装配根:7 条 ipass_* 指令 + │
│ PLUGINS 注册表 + dispatch_api 统一 404│
└───────────────┬───────────────────────┘
│ location 开关收敛(阶段处理器是 http 级的)
┌──────────────────────────┼───────────────────────────────┐
▼ ▼ ▼
Host = mdm…:18098 Host = lm…:18098/<slot>/… Host = <任意>.yourdomain.com
ipass_api on(content) ipass_llm / ipass_apix on ipass_proxy on(access)
┌────────────────────┐ ┌────────────────────────┐ ┌───────────────────────────┐
│ CorePlugin(内核) │ │ LlmPlugin / ApixPlugin │ │ DomainPlugin │
│ 身份端点+会话 │ │ ukey: 鉴权 + 配额 │ │ 查 sub: 共享内存 │
│ 先异步读请求体 │ │ up:/ax: 定上游 │ │ (全量常驻,miss = 不存在)│
│ 再按 PLUGINS 顺序 │ │ 换上游真 Key 后转发 │ │ 校验 status=approved │
│ 分发,无人认领 404 │ │ (下游不接触厂商 Key) │ │ 且 temp 未过期 │
└─────────┬──────────┘ └───────────┬────────────┘ │ 写 $proxy_backend_addr │
│ │ └────────────┬──────────────┘
│ sync_shm(写穿) │ sync_shm │
▼ ▼ ▼
data/ 四表:users.json / domains.json / llm-upstreams.json / api-proxies.json(持久化副本)
```
设计要点:
- **共享内存才是运行期唯一真源**,`data/*.json` 是它的持久化副本。
三个表(转发映射 / 账号 Key / LLM 上游)在 fork 前一次性装载进共享内存,
**热路径零文件 I/O**;未命中就等于「不存在」,不存在任何回源读文件的兜底路径。
各表在 fork 前一次性装载进共享内存,**热路径零文件 I/O**;
未命中就等于「不存在」,不存在任何回源读文件的兜底路径。
- 所有写操作都会**同时更新共享内存与文件**(写穿),因此**审批一通过就立即生效**,且重启后配置不丢。
- 代价:手改 `data/*.json` 不再热生效,需重启。
- 转发侧只做一件事:查表 → 设置 `$proxy_backend_addr`。任何异常都只导致 404,不影响网关本身。
- **插件化边界**:依赖方向只能 plugin → core,内核不 import 插件;插件数据反向流只走装配根
(`CoreExt` 回填 / `on_delete` 钩子)。详见 `docs/plugin/PLUGIN_ARCHITECTURE.md`。
---
@@ -223,9 +223,7 @@ subdomain/
│ ├── domains.json # 子域名映射表 + 申请记录
│ ├── llm-upstreams.json # LLM 上游表(含厂商真 Key)
│ └── api-proxies.json # API 代理表(含供应商真 Key)
├── logs/ # 日志(容器内软链到 stdout/stderr)
└── archive/
└── openresty-lua-20260910/ # 旧 OpenResty+Lua 版归档(只读参考)
└── logs/ # 日志(容器内软链到 stdout/stderr)
```
容器内路径映射(见 `compose.yml`):
@@ -300,6 +298,7 @@ docker compose logs -f # 看到「已创建初始管理员 admin」即为
| **账号管理** | 新建账号(含展示名、临时授权权限);账号列表:复制/重置 API Key、授权或取消「临时授权权限」、改密码、设置可用上游与限流、删除账号 |
| **LLM 上游** | 新建/编辑/启停/删除上游;模型清单维护;每行 slot 旁有 **OpenAI / Anthropic 两枚复制地址按钮**(按当前 Host 自动生成、已处理 `/v1` 拼接去重,点一下即复制,客户端拿去当 `base_url`,不用自己猜路径);**健康徽标**(`ok` 绿 / `failed` 红 / `unknown` 灰,打开面板自动探测,**测试**按钮可手动刷新) |
| **用量统计** | 区间切换(7/14/30/90 天)+ **趋势视角**(全局 / 按账号 / 按 API 组)+ 两张明细表(今日 / 累计 / **入 token / 出 token** / 最近调用 / 分上游明细)+ 指标可切换的排名图 |
| **API 代理** | 外部 API 供应商资产挂到网关下(复用 `sk_` 鉴权 + 配额 + 用量):**列表页 + 弹出卡片编辑**(`IP.modal`),代理增删启停 / 复制地址(含示例 `?q=关键词`)/ 免费预估测试;供应商 Key 只回显掩码 |
趋势与 token 口径(与 §15 用量统计一致):
@@ -471,7 +470,7 @@ LLM 代理读 `Authorization: Bearer`。重置 Key 会同时影响两个入口
- `type`:`temp`(临时)/ `long`(长期)
- `status`:`pending`(待审)/ `approved`(已放行)/ `rejected`(已驳回);「已过期」是运行时计算出的状态,不落盘
- `reviewed_by == "auto"` 表示凭临时授权权限免审放行,其余为管理员账号名
- 三个文件都是**原子写**(先写 `.tmp` 再 rename),并加了跨 worker 互斥锁,避免并发覆盖
- 四个文件都是**原子写**(先写 `.tmp` 再 rename),并加了跨 worker 互斥锁,避免并发覆盖
### `data/llm-upstreams.json`
@@ -510,6 +509,34 @@ LLM 代理读 `Authorization: Bearer`。重置 Key 会同时影响两个入口
- `enabled: false` 会立即从共享内存摘除,等价于停用(配置保留便于恢复)
- **该文件含上游厂商真实密钥,敏感级别等同 `users.json`**
### `data/api-proxies.json`
```json
{
"items": {
"web-search": {
"asset_id": "searxng-search",
"supplier": "provider-x",
"base": "https://api.example.com",
"key": "ak_<供应商真实密钥>",
"name": "网页搜索",
"desc": "按关键词搜索并返回结果",
"params": ["q"],
"enabled": true,
"note": "",
"created_at": 1789037728
}
}
}
```
- 每条代理 = 挂在网关下的一个外部 API 供应商资产,账号用**同一把** `sk_` Key 调
`GET /apix/<slug>?<参数>`;网关**从 query 拼请求体**(`asset_id` 由服务端决定,
调用方只能选参数),换成 `key` 后转发(详见 §15.1)
- `base` / `key` / `supplier` 每条自带,无平台级凭据;`params` 是给调用方看的
参数清单(转发时不过滤);`enabled: false` 立即从共享内存摘除
- **该文件含供应商真实密钥,敏感级别等同 `users.json`**;管理台只回显掩码
---
## 12. 运维
@@ -530,8 +557,8 @@ cp -a data /path/to/backup/
```
**关于缓存**:映射命中后写入共享内存,TTL 600 秒(临时域名取剩余有效期与 600 秒的较小值)。
通过管理台或 API 的增删改都会主动失效对应缓存,**立即生效**;
如果你直接手工编辑了 `data/domains.json`,需要 `docker compose restart` 让共享内存清空(或等 TTL 到期)。
通过管理台或 API 的增删改都会**写穿共享内存**,**立即生效**;
如果你直接手工编辑了 `data/domains.json`,需要 `docker compose restart`(共享内存是运行期真源,改文件不热生效)。
**关于扩容**:共享内存和 JSON 文件都是**单实例内**的,多副本部署时各副本状态不共享。
当前定位是单实例出口;如需高可用,应把 `domains.json` 换成 Redis/etcd 之类的共享存储。
@@ -720,6 +747,8 @@ DRY_RUN=1 bash deploy/release.sh 1.0.3 # 只构建不推送
(控制面的回滚判重已改为按**镜像 id** 而非 tag 名比较,但 tag 本身仍应保持不可变。)
- 脚本用 `docker manifest inspect` 探测远端,**同名 tag 已存在即拒绝发版**(需先 `docker login`)。
- 脚本先校验 `git status` 干净,保证 **tag ↔ commit** 一一对应(提交里记下 tag)。
⚠️ **脚本不校验是否已 push**——1.0.12 曾发版成功但代码没推到 Gitea,远端看不到。
**发版前先 `git push`**,或直接走 `bash deploy/agent.sh release <tag>`(推荐,一条龙)。
- 本机构建必须走经典构建器(脚本已内置 `DOCKER_BUILDKIT=0`):buildx 写 activity 会被沙箱拦 rename。
| tag | 内容 |
@@ -733,6 +762,11 @@ DRY_RUN=1 bash deploy/release.sh 1.0.3 # 只构建不推送
| `ipass-1.0.6` | **子域名规则固化为 `i`+8 位随机数+`dm`**(规则真源在 `config.rs`,经 `subdomain_rule` 下发给面板;API 不传 `subdomain` 即自动生成、撞车重试)+ **域名列表点完整域名即复制**(带端口,跟随调用方)+ **管理台布局改为自适应**(去掉 1180px 居中锁;表单另限宽 1100px)。digest `96c0e952…`,commit `12f20dd`。 |
| `ipass-1.0.7` | **LLM token 级计量 + 对话审计日志**:body filter 旁路(FFI 全局符号注册,单 .so 无需额外 C 模块)解析 SSE 尾部 `usage` → `utt:`/`utms:` 键,用量接口增加 tokens 维度;log 阶段请求体归档到 `audit/`(data 兄弟目录,**10 GiB 容量阈值**触发式清理);LLM location 去掉 `proxy_request_buffering off`(与 body 落盘互斥,SSE 由 `proxy_buffering off` 保障)。控制面更新后自动挂审计卷。digest `5cd68ec4…`,commit `401f9be`。**注意:需先更新控制面(§12.5 自更新脚本)再 update,否则新容器缺审计挂载。** |
| `ipass-1.0.8` | **管理台图表 + 单页拆分多页**。后端新增日桶 `ud:`/`udu:`/`uds:`(趋势数据源,TTL 90 天)与 `GET /api/admin/trend`;前端拆为 `login` + `overview`/`review`/`domains`/`users`/`upstreams`/`usage` 六页 + `assets/`(自绘 SVG 图表,零第三方依赖)。`/admin` 仍进总览;`agent.sh verify` 增加「趋势返回 7 天序列」作为换新证据。回归 227 条(网关 102 + LLM 125)。 |
| `ipass-1.0.9` | **新增「API 代理」板块**(见 §15.1 与 §16 续7):`/apix/<slug>` 把外部 API 供应商资产挂到网关下,复用 `sk_` 鉴权 + 配额 + 用量统计。 |
| `ipass-1.0.10` | 修复管理台登录页因会话探测 401 被通用兜底重定向的自刷新死循环(`/api/admin/session` 排除出 401 兜底)。commit `dbee9ff`。 |
| `ipass-1.0.11` | **API 代理去「市场」概念**:每条代理自带 `supplier`/`base`/`key`,无平台级凭据;管理台编辑改弹出卡片(`IP.modal`)。commit `1fb83e4`。 |
| `ipass-1.0.12` | **插件化重构**:workspace 化(ipass-core + 三插件 crate + gateway 唯一 cdylib),行为完全等价,262 项回归全绿。commit `ddd4172`。架构见 `docs/plugin/PLUGIN_ARCHITECTURE.md`。 |
| `ipass-1.0.13` | 采纳 sso 上游化建议 4 条(`User.extra` flatten / `split_value` rposition / `iter_prefix_ex` / `users::update_extra`)。commit `ee05b27`,评估记录 `docs/plugin/SSO_UPSTREAM_DECISIONS.md`。 |
---
@@ -1021,6 +1055,29 @@ GET /apix/search?q=nginx Authorization: Bearer sk_<本网关签
## 16. 变更记录
- **2026-09-13(续11)插件化重构(`ipass-1.0.12`)**
- 单 crate 拆为 **workspace**:`ipass-core`(内核)+ `plugin-domain` / `plugin-llm` / `plugin-apix`
三个插件 crate(一律 rlib)+ `gateway`(**唯一 cdylib**,产物仍为 `libipass_gateway.so`)。
指令名、conf、`data/*.json` 零变化,行为完全等价。
- 契约:`Plugin` trait(`dispatch_api` 不认领返回 `None`,404 由 gateway 统一发)、
`loc::Switch` 并集注入、`CoreExt` 扩展注册表(身份端点的插件数据由 gateway 回填)、
`users::on_delete` 钩子(删账号连带清理插件键空间)、`ctx_index` 注入(插件挂请求级状态)。
- 下行鉴权/配额下沉 `core::auth`(LLM 与 apix 两条链路共用);记账原语下沉 `core::usage`,
用量解读归 plugin-llm,apix 记账走同一写入口(slot 带 `api/` 前缀);`/api/admin/trend` 留 gateway。
- 架构真源:`docs/plugin/PLUGIN_ARCHITECTURE.md`(as-built)。
- **2026-09-13(续10)采纳 sso 上游化建议 4 条(`ipass-1.0.13`,commit `ee05b27`)**
- `User.extra` flatten(插件字段透传,存量数据零破坏)+ `users::update_extra`;
- `state::split_value` 改 `rposition`(payload 内含 `0x1f` 不再被截断,真 bug);
- `state::iter_prefix_ex`(返回 `(key, payload, exp)`,能力补齐)。
- 评估与撤回记录:`docs/plugin/SSO_UPSTREAM_DECISIONS.md`
(A6-1 密码最短长度 6→8 会破坏测试边界用例,撤回)。
- **2026-09-13(续9)API 代理去「市场」概念(`ipass-1.0.11`)**
- 每条代理自带 `supplier` / `base` / `key`,不再有平台级凭据与目录直拉面板;
管理台编辑改**弹出卡片**(`IP.modal`),修示例地址拼接。
- **2026-09-13(续8)修复管理台登录死循环(`ipass-1.0.10`)**
- 登录页会话探测的 401 被 core.js 通用兜底当作会话过期重定向回登录页,形成自刷新死循环;
将 `/api/admin/session` 排除出通用 401 兜底。
- **2026-09-13(续7)新增「API 代理」板块:把外部免费 API 供应商挂到网关下(`ipass-1.0.9`)**
- 新增 `rust/src/apix.rs` + 模块:`/apix/<slug>?<参数>` → 供应商 `POST /api/v1/ai/request`,
网关**从 query 拼体**(`asset_id` 由服务端决定,调用方只能选参数),`sk_` 下行 Key 换成供应商 Key 后转发。
@@ -1208,18 +1265,17 @@ GET /apix/search?q=nginx Authorization: Bearer sk_<本网关签
状态目录固定为 `tests/.run/*/data/` —— 跑回归**不会接触生产 `data/`**。
- 新增 LLM 侧断言 34 条:Key 替换 / 路径拼接 / 白名单 / 停用摘除 / SSE 不缓冲 / 限流 / HTTPS。
其中「Key 是否真被替换」读的是**假上游实际收到的请求头**,而不是网关自己的响应。
- **2026-09-10 全量重写为 vanilla nginx + Rust 动态模块**(取代下面的 OpenResty+Lua 实现)
- 业务逻辑(账号 / 域名 / 审核 / 会话 / JSON 原子存储 / 全部 API / LLM 代理)从 Lua 平移进 Rust 模块,
**接口路径、请求/响应格式、`data/*.json` 字段与口令哈希算法全部保持兼容**,前端 `admin.html` 无需改动。
- **2026-09-10 全量重写为 vanilla nginx + Rust 动态模块**(取代重构前的实现)
- 业务逻辑(账号 / 域名 / 审核 / 会话 / JSON 原子存储 / 全部 API / LLM 代理)从重构前实现平移进 Rust,
**接口路径、请求/响应格式、`data/*.json` 字段与口令哈希算法全部保持兼容**,前端管理台无需改动。
- 换掉了「文件是真源、共享内存只是缓存」的语义:**共享内存成为运行期真源**,
三个表在 fork 前一次性装载,热路径零文件 I/O,miss 不再回源读文件。
写操作全部写穿(shm + 文件),因此**审批通过即刻生效**,且重启不丢配置。
(动机:旧版随机 Host 未命中场景实测比命中慢 **25 倍**,且同步文件 I/O 迫使 `worker_processes 1`。)
- `worker_processes 1` → `auto`;Nginx 由官方 OpenResty 镜像改为**自编译 vanilla nginx**。
- 新增 `rust/src`(13 个源文件,另含 `build.rs`)、`Dockerfile` 两段构建、vendored `ngx-rust`。
- `worker_processes 1` → `auto`;Nginx 改为**自编译 vanilla nginx**(自编译是 ngx-rust 模块对运行环境的要求——见 Dockerfile 注释)。
- 新增 `rust/` workspace(`crates/{ipass-core, plugin-domain, plugin-llm, plugin-apix}` + `gateway` cdylib)、`Dockerfile` 两段构建、vendored `ngx-rust`。
- 本地回归:`tests/gateway/e2e.sh` 共 **55 条断言**(`bash tests/run.sh gateway`),
覆盖全部接口 + 转发即时生效/失效 + 越权隔离。
- 旧实现完整归档于 `archive/openresty-lua-20260910/`(含 `SHA256SUMS` 与 tarball,刻意排除 `data/`)。
- **2026-09-10 LLM API 代理**
- 新增 `lm.mayishangshu.cn:18098` 统一出口:客户端用与域名接口**同一把** API Key 鉴权,
网关换成上游真实密钥后转发,下游不接触厂商 Key。
@@ -1234,12 +1290,11 @@ GET /apix/search?q=nginx Authorization: Bearer sk_<本网关签
- 新增账号体系:多账号 + 每账号随机 API Key + 角色(`admin` / `user`)。
- 新增「临时授权权限」(6 小时,管理员勾选授予):持有者在申请临时域名时**免审直接放行**。
- 新增临时/长期域名区分与审核流:无权限的临时域名、以及全部长期域名进入管理员审核队列。
- 新增管理台单页 `www/admin.html`:登录、审核队列、全部域名、账号管理。
- 新增 API 分发器 `lua/api.lua`,用户态(API Key)与管理态(登录会话)分权。
- 新增管理台单页(登录、审核队列、全部域名、账号管理),用户态(API Key)与管理态(登录会话)分权。
- 数据落盘从单个扁平映射 `proxy_config.json` 迁移为 `data/users.json` + `data/domains.json`(原 `test` / `testa` 两条映射已迁移为 admin 名下的长期域名)。
- 转发链路新增:状态与有效期校验、缓存 TTL 按剩余有效期收敛、写操作主动失效缓存。
- 安全加固:口令加盐迭代哈希、常量时间比较、`HttpOnly`+`SameSite` 会话、登录限速、只读挂载、默认拒绝。
- **2026-09-10 整理**
- 校验规则修正:原先的校验正则误用了 Lua 语法(`%w`/`%d`)却交给 PCRE 的 `ngx.re` 执行,已改为 PCRE 语法。
- 校验规则修正:原先的校验正则误用了 Perl 风格语法(`%w`/`%d`)却交给 PCRE 的 `ngx.re` 执行,已改为 PCRE 语法。
- 管理台 `[hidden]` 失效修复(author 样式的 `display` 会盖掉 UA 的 `display:none`)。
- 补齐 `.gitignore`;清理 `.DS_Store`;`resolver` 改为国内可用 DNS。
+4 -4
View File
@@ -32,10 +32,10 @@ nginx-sys = { path = "vendor/ngx-rust/nginx-sys" }
# 业务层依赖:全部是纯 Rust 实现,不引入任何系统库或常驻依赖
serde = { version = "1", features = ["derive"] }
serde_json = "1" # 替代 cjson;空 Vec/Vec<Map> 天然序列化为 [] / {},与旧版一致
sha2 = "0.10" # 替代 resty.sha256;算法与旧版逐位一致(迭代加盐 SHA-256)
getrandom = "0.2" # 替代 resty.random;不可退化成可预测伪随机(API Key 由它生成)
libc = "0.2" # 仅用于 localtime_r / time(旧版由 os.date / ngx.time 提供)
serde_json = "1" # 序列化为紧凑 JSON;空 Vec/Vec<Map> 自动产出 [] / {}
sha2 = "0.10" # 迭代加盐 SHA-256;hash_password 算法已用独立 Python 实现逐位核对过
getrandom = "0.2" # 不可退化成可预测伪随机(API Key / salt 由它生成)
libc = "0.2" # 仅用于 localtime_r(取本地时区)
# 内核 crate(插件/gateway 一律引用它,方向只能是 plugin → core)
ipass-core = { path = "crates/ipass-core" }
+5 -4
View File
@@ -1,10 +1,11 @@
//! 内核策略常量(唯一真源)。
//!
//! 与旧 OpenResty 版的 `lua/config.lua` 一一对应:**改策略只改这里**,
//! 不要散落到各模块里,否则行为会出现多处真源。
//! 内核策略常量(唯一真源)。
//!
//! 插件自有常量在各自 crate(plugin-domain/config.rs、plugin-llm/config.rs);
//! 这里只留「身份 / 会话 / 配额 / 两条下行链路共用」的部分。
//! **改策略只改这里**,不要散落到各模块里,否则行为会出现多处真源。
//!
//! 插件自有常量在各自 crate(plugin-domain/config.rs、plugin-llm/config.rs、
//! plugin-apix/config.rs);这里只留「身份 / 会话 / 配额 / 两条下行链路共用」的部分。
/// 管理员授予的「临时授权权限」有效时长(秒)
pub const TEMP_GRANT_TTL: i64 = 6 * 3600;
+2 -2
View File
@@ -1,10 +1,10 @@
//! 管理员登录会话。
//!
//! 会话存在共享内存里:**nginx 重启即全部失效**,这是预期行为
//! (旧版用 `lua_shared_dict admin_sessions`,同样如此)。
//! ——管理会话不需要跨重启延续。
//!
//! Cookie 为 `ipass_admin_session=<64 位 hex>`,HttpOnly + SameSite=Strict,
//! 每次校验命中都会滑动续期(与旧版一致)。
//! 每次校验命中都会滑动续期。
use crate::config::{COOKIE_NAME, SESSION_TTL};
use crate::state;
+4 -6
View File
@@ -1,8 +1,7 @@
//! 共享内存状态层。
//!
//! 这是「配置放内存」的落点,替代旧版的 `lua_shared_dict proxy_cache /
//! admin_sessions / lua_locks` 三个字典。全部派生状态集中在一张
//! `RbTreeMap` 里,用键前缀区分用途:
//! 这是「配置放内存」的落点:所有派生状态集中在**一张** `RbTreeMap`,
//! 用键前缀区分用途:
//!
//! ```text
//! sub:<subdomain> → <backend> \x1f <expires_at> 转发映射
@@ -12,9 +11,8 @@
//!
//! ## 为什么过期时间写在 value 里,而不是靠字典的 TTL
//!
//! 旧版 `lua_shared_dict` 自带 `set(key, val, ttl)` 自动回收;`RbTreeMap`
//! 是纯数据结构,没有 TTL。因此把到期时刻编码进 value,读取时判断——
//! 语义上反而更精确(到期即失效,不受回收延迟影响)。
//! 共享内存是裸 `RbTreeMap`,没有 TTL 自动回收。把到期时刻编码进 value,
//! 读取时判断——语义上反而更精确(到期即失效,不受回收延迟影响)。
//!
//! ## 为什么锁必须放进共享内存
//!
+3 -3
View File
@@ -1,8 +1,8 @@
//! JSON 文件存储层:原子写 + 跨 worker 互斥。
//!
//! 与旧版 `lua/store.lua` 语义一致——**状态就是几个 JSON 文件**,不引入数据库。
//! 差别只有一处:互斥锁从 `resty.lock`(基于 lua_shared_dict)换成共享内存里的
//! `RwLock`,因为新版已经有一块共享内存了,不必再造一个字典。
//! **状态就是几个 JSON 文件**,不引入数据库。互斥锁在共享内存里的 `RwLock`
//! ——内核本来就要持一块共享内存(state zone),文件锁复用同一块 slab pool,
//! 不必再单独造字典。
//!
//! 所有写操作统一走 `update_*`,流程固定为:
//!
+1 -1
View File
@@ -1,6 +1,6 @@
//! 账号体系:管理员与普通账号共用一张表。
//!
//! 对应旧版 `lua/users.lua`。数据结构见 `models::User`。
//! 账号数据见 `models::User`。
//!
//! 「临时授权权限」= 该账号申请**临时域名**时可跳过管理员审核、直接放行。
//! 注意它只对 temp 生效,long 域名无论谁申请都要审核。
+2 -1
View File
@@ -1,6 +1,7 @@
//! 通用工具:时间 / 随机 / 摘要 / 口令哈希 / 常量时间比较 / 格式化 / 参数解码。
//!
//! 对应旧版的 `lua/util.lua`。其中 `hash_password` 的算法**必须逐位一致**,
//! 其中 `hash_password` 的算法**必须逐位一致**(口径沿用自重构前实现,
//! 存量 `users.json` 才能正常登录),
//! 否则旧的 `data/users.json` 里的口令哈希将全部失效。
use sha2::{Digest, Sha256};
+6 -12
View File
@@ -1,18 +1,12 @@
//! iPass 山海关(ipass-gateway)—— nginx + Rust 动态模块(v2)
//! iPass 山海关(ipass-gateway)—— nginx + Rust 动态模块
//!
//! 尚数网 统一网关(动态域名 / LLM API 路由及未来各类统一出口能力)。
//! 本模块承担原 OpenResty + Lua 版的**全部**职责:
//!
//! | 旧版(Lua) | 新版(Rust) |
//! |------------------------------------|-------------------------|
//! | `lua_shared_dict proxy_cache` | `state` 共享内存映射表 |
//! | `lua_shared_dict admin_sessions` | `state` 会话键 |
//! | `lua_shared_dict lua_locks` | `state` 文件写锁 |
//! | `store.lua`(cjson + resty.lock) | `store` + serde_json |
//! | `users.lua` / `domains.lua` | `users` / `domains` |
//! | `api.lua` 路由表 | `api` 精确匹配路由表 |
//! | `proxy.lua` 转发热路径 | `ResolveHandler` |
//! | —(新增能力) | `LlmHandler` LLM 代理 |
//! 插件化定型后(2026-09-13),本 crate 仅作"装配壳":模块入口、7 条
//! `ipass_*` 指令、`ModuleConfig` 开关、`ApiHandler` content 阶段两段式读体
//! 后按 PLUGINS 顺序分发、trend 组合端点、state_zone_init 三表装载、
//! `init_process` 播种 admin + 审计目录启动巡检。具体业务实现都在
//! `crates/ipass-core` 与三个 `plugin-*` crate 里。
//!
//! ## 三条热路径
//!