# iPass 插件化架构(as-built,2026-09-13 定型) > 本文由《插件化改造方案》(PLUGINIZATION_PLAN.md)**转正**而来:改造已全部落地 > (P0–P4 提交序列 + P5 文档),行为完全等价——`data/*.json` 零变化、 > `conf/nginx.conf` 一条指令不改、262 项回归全绿(gateway 102 + llm 160)。 > 论证过程与现状量测数据见 git 历史(`74aeefe` 起 P0–P4 各提交)。 > > 参照实现:`ssw/sso`(为什么不能拆多 `.so` 的论证见其 > `docs/plugin-architecture-analysis.md`)。**已拍板:`ssw/sso` 的 `plugin-sso` > 不迁入 iPass**——iPass 的身份端点已由 `ipass-core` 收口,未来若与 sso 合流, > 身份端点再从 `CorePlugin` 移交即可(`Switch` 并集与 trait 签名均已对齐)。 --- ## 0. 一句话判据:什么进内核 > **去掉这个插件,网关还能不能跑?** 能 → 它不是内核。 | 能力 | 归属 | 理由 | | --- | --- | --- | | 共享内存唯一 zone / 文件写锁 | **core** | 只能有一份,多份就失去「热路径零文件 I/O」的意义 | | `data/users.json` 读写、`ukey:` Key 索引 | **core** | 一处吊销处处生效;插件各写一份等于没共用 | | 账号模型 `User` | **core** | 域名审批、LLM 配额、API 代理都挂在同一账号上 | | 会话 / 登录失败锁定 | **core** | 与账号强绑定;且是**所有插件端点的公共前置** | | 身份类 HTTP 端点(login/session/users/me) | **core**(`CorePlugin`) | 已拍板由 core 收口 | | `sk_` Key 下行鉴权 + `rl:`/`st:` 配额 | **core**(`auth.rs`) | **两条下行链路(LLM + API 代理)共用** | | 记账原语(窗口读数 / 日桶,无业务语义) | **core**(`usage.rs`) | 趋势数据 LLM 与 apix 共用;内核删账号钩子需要 | | 动态域名映射与审批 | plugin-domain | 独立业务 | | LLM 路由 / 上游 / 计量 / 审计 / 用量解读 | plugin-llm | 独立业务 | | 外部 API 供应商资产代理 | plugin-apix | 独立业务 | --- ## 1. 目标结构(已落地) ``` rust/ ├── Cargo.toml # [workspace](members + 统一依赖 + [profile.release]) ├── vendor/ngx-rust/ # path 依赖(不可走 crates.io / git,见 Cargo.toml 注释) ├── crates/ │ ├── ipass-core/ # 内核:状态 / 账号 / 契约 / 身份端点 / 下行鉴权 / 记账原语 │ │ └── src/{lib,config,models,state,store,session,util,http, │ │ users,auth,usage,plugin,loc,api}.rs │ ├── plugin-domain/ # 动态域名:domains/resolve/api + sub: 键空间 │ │ └── src/{lib,config,models,store,domains,resolve,api}.rs │ ├── plugin-llm/ # LLM:llm/upstreams/usage_filter/llm_audit/stats/handlers/api │ │ └── src/{lib,config,models,store,llm,upstreams,usage_filter,llm_audit,stats,handlers,api}.rs │ └── plugin-apix/ # API 代理:apix/handlers/api + ax: 键空间 │ └── src/{lib,config,models,store,apix,handlers,api}.rs └── gateway/ # 唯一 cdylib:模块壳 + PLUGINS 注册表 + trend 组合端点 └── src/{lib,api}.rs ``` **关键不变式:仓库里只有一个 `cdylib`(gateway),产物仍是 `libipass_gateway.so`。** 插件一律 `crate-type = ["rlib"]`。理由(nginx 1.30.4 源码层面核对):共享内存 zone 的 tag 不同会在 `ngx_cycle.c` 直接 EMERG;同名变量会被后加载者劫持 `get_handler`; Rust 无稳定 ABI,跨 `.so` 传 `String` 即双重 free。 `[profile.release]`(含 `panic="abort"`)**只能在 workspace 根**——member 里写会被 cargo 静默忽略,panic 丢了 abort 就可能跨 FFI 边界展开。 --- ## 2. 契约层(内核与插件之间唯一的接口) ### 2.1 `Plugin` trait(`core/plugin.rs`) ```rust pub trait Plugin: Sync { fn name(&self) -> &'static str; fn preconfig(&self, cf: *mut ngx_conf_t) -> bool { true } // 注册 nginx 变量 fn postconfig(&self, cf: *mut ngx_conf_t) -> bool { true } // 注册 phase handler / body filter fn dispatch_api(&self, r: *mut ngx_http_request_t) -> Option { None } fn zone_load(&self) -> usize { 0 } // fork 前预装载 fn log_handler(&self, _r: *mut ngx_http_request_t) -> bool { true } // 保留(与 sso 对齐) } ``` * **刻意没有 `commands()`**:nginx 的指令数组是 null 结尾的连续数组,跨 crate 无法拼接。 7 条 `ipass_*` 指令由 gateway 集中声明——**指令解析归壳、行为归插件**。 * `dispatch_api` 语义:「不认领返回 `None`,让下一个插件试」,**绝不自行 404**; 404 由 gateway 在全部插件都返回 `None` 后统一发出。 * 另有 `core::plugin::{set_ctx_index, ctx_index}`:gateway 在 postconfiguration 开头把 自己的 `ctx_index` 注入内核,插件用它挂在 `r->ctx` 上挂请求级状态 (如 plugin-llm 的 usage_filter 扫描窗口)。未注入时插件**放弃**请求级状态,绝不越界写。 ### 2.2 `loc::Switch`(`core/loc.rs`):取并集 ```rust pub enum Switch { Api, Iap, Domain, Proxy, Llm, Apix } // iPass 用 Api/Proxy/Llm/Apix;Iap/Domain 为 sso 预留,恒 false ``` gateway 在 preconfiguration 注入查询实现(`set_switch_fn`),**未实现/未注入的变体一律 保守返回 `false`**——返回 `true` 会让未装配的能力意外开门(sso 踩过的坑)。 fn 指针按 usize 原子存取(access 热路径每请求都要查,不能用 Mutex)。 ### 2.3 `CoreExt`(`core/api.rs`):身份端点的插件数据回填【方案落地时新增】 身份端点(`/api/admin/users`、`/api/v1/me`、删账号连带回收)天然需要插件侧数据 (域名数、LLM 用量、白名单校验),而内核不认识任何插件——直接引用会形成 core→plugin 循环依赖。解法是**扩展注册表**: ```rust pub trait CoreExt: Sync { fn decorate_admin_users(&self, views: &mut [Value]) {} // 账号列表装饰 fn decorate_me(&self, username: &str, view: &mut Value) {} // me 装饰 fn reclaim_on_delete(&self, username: &str) -> usize { 0 } // 删账号连带回收 fn validate_slots(&self, slots: &[String]) -> Result<(), String> { Ok(()) } } ``` 由 **gateway 作为装配根**实现(`GatewayExt`,组合 plugin-domain 与 plugin-llm 的数据), preconfiguration 时 `set_ext(&GatewayExt)` 注入。这是方案对原设计的一处修正: 原方案把「删账号连带回收域名」塞在 on_delete 钩子里,落地时发现账号列表装饰/ me 装饰/白名单校验同样反向依赖插件数据,统一收进 CoreExt 更干净。 ### 2.4 `users::on_delete` 钩子(`core/users.rs`) 删账号时内核只清自己的键(`ukey:`/`sess:`/`fail:`),插件键空间由插件注册清理器: gateway 的 `state_zone_init` 里 `users::on_delete(plugin_llm::stats::forget)`。 内部按函数指针去重,nginx reload 重复执行安全。 --- ## 3. 三个边界问题的最终解法 ### ① core↔plugin 循环依赖 → `on_delete` 钩子 + `CoreExt` 注册表 内核删账号不认识 `ust:`/`ums:`;身份端点不认识域名数。方向一律是**插件 → 内核**, 反向数据流只能走 gateway 装配根回填(§2.3、§2.4)。 ### ② apix 复用 llm 的鉴权/配额 → 下沉 `core/auth.rs` `ukey:` 鉴权与 `rl:`/`st:` 配额是「去掉 llm 还要(apix 要)、去掉 apix 还要(llm 要)」 ⇒ 共用 ⇒ 放内核:`downstream_key` / `identity` / `check_quota` / `fail`(OpenAI 兼容 错误体)。apix 与 llm 的 access handler 都调它,**无插件间依赖**。 ### ③ 用量账本 → 原语进 core、解读进 plugin-llm、记账入口唯一 * `core/usage.rs`:`Usage`/`TokenUsage`/`DayBucket` 类型 + `bump/read/bump_t/read_t/ bump_day/day_bucket`——只认「前缀 + 名字 + 计数」,无业务语义。 * `plugin_llm::stats`:键前缀(`ust:`/`ums:`/`utt:`/`utms:`/`ud:`/`udu:`/`uds:`)与 `record`/`add_tokens`/`forget`/`trend`/`overview` 等解读。 * **apix 记账走 `plugin_llm::stats::record`**(slot 带 `api/` 前缀共用同一片键空间)—— 这形成了 plugin-apix → plugin-llm 的依赖。刻意保留:账本写入口必须唯一, 两份写入口迟早漂移;方案原文设想的「record 下沉 core」会把 `ust:`/`ums:` 键名 语义带进内核,两害相权取其轻。 * **`/api/admin/trend` 留在 gateway**【方案落地时的第二处修正】:日桶键带日窗 id、 按前缀扫不出来,趋势接口需要 users + upstreams + apix **三方名册**——跨插件组合 逻辑属于装配根职责,不属于任何一个插件。 --- ## 4. 装配清单(gateway = 装配根) ```rust static PLUGINS: &[&dyn Plugin] = &[ &ipass_core::api::CorePlugin, // 身份端点必须先认领 &plugin_domain::DomainPlugin, // $proxy_backend_addr + ResolveHandler + sub: &plugin_llm::LlmPlugin, // llm_* 三变量 + Llm/LlmHealth/Audit 三 handler + body filter + up:…uh: &plugin_apix::ApixPlugin, // apix_* 六变量 + ApiProxyHandler + ax: &GatewayRoutes, // 仅剩 /api/admin/trend(组合根) ]; ``` gateway 保留:7 条指令解析(`ModuleConfig` 四开关 + `loc_switch` 注入)、 `ApiHandler`(content 阶段两段式读体后按 PLUGINS 顺序分发 + 统一 404)、 `state_zone_init`(users/llm/apix 三表装载 + on_delete 注册)、`init_process` (播种 admin + plugin_llm 审计目录启动巡检)、`ipass_audit_dir` 指令 (转调 `plugin_llm::llm_audit::set_dir`)。 **新增一个插件 = 加一个 crate + 在 gateway 动 5 处**(见技能 `ipass-core-add-plugin`):`PLUGINS` 注册、`loc_switch`/`ModuleConfig`(如需新开关)、 指令数组(如需新指令)、zone 装载日志、Cargo 依赖。 --- ## 5. 与 sso 参考实现的差异(有意偏离,最终版) | # | sso 做法 | iPass 做法 | 原因 | | --- | --- | --- | --- | | 1 | `rl:` 配额归 plugin-llm | 归 **core** `auth.rs` | iPass 有 LLM + apix 两条共用配额的链路 | | 2 | `stats` 整体在插件 | 拆:原语进 core `usage.rs`,解读进 plugin-llm | 内核删账号要摘用量索引 | | 3 | 身份端点在 plugin-sso | 身份端点在 **core**(`CorePlugin` + `CoreExt`) | 已拍板;**plugin-sso 不迁入**(2026-09-13 拍板) | | 4 | 指令 `sso_*` | 保持 `ipass_*` | conf 与测试零改动 | | 5 | `Switch { Api, Iap, Domain, Llm }` | 并集 `{Api, Iap, Domain, Proxy, Llm, Apix}` | 契约点一次到位 | | 6 | 无 | `users::on_delete` 钩子 + `CoreExt` 注册表 + `ctx_index` 注入 | 内核不认识插件的键空间与请求数据 | | 7 | 无 trend 组合端点概念 | `/api/admin/trend` 留 gateway | 三方名册,装配根职责 | | 8 | `libsso_gateway.dylib` | 仍是 `libipass_gateway.so` | Dockerfile 产物路径不变 | --- ## 6. 纪律(长期有效) 1. **热路径永不回源**:插件每请求决策只读共享内存;写操作必须先落文件、再写穿 shm, 写 shm 失败必须 `log_err`。逐插件核对 `sync_shm` 调用点,漏一处 = 「刚配好却 404」。 2. **插件绝不自行 404**:`dispatch_api` 不认领返回 `None`。 3. **`loc::Switch` 未实现变体保守 `false`**。 4. **`ngx` 走 `vendor/ngx-rust` path 依赖**;插件 rlib、gateway cdylib; `[profile.release]` 只在 workspace 根。 5. **`data/*.json` 持久化格式零变化**:所有字段带 `#[serde(default)]`,改字段先想存量文件。 6. **验证 = `bash tests/run.sh all` 262 项全绿**;单 crate 迭代 `cargo build -p plugin-llm`(秒级)。 --- ## 7. 已拍板(2026-09-13,最终) - [x] 只做 iPass 自身插件化;**`ssw/sso` 的 `plugin-sso` 不迁入**(原「待拍板」项关闭; 若未来合流,身份端点从 `CorePlugin` 移交,trait/Switch 已对齐) - [x] 身份端点由 `ipass-core` 收口,插件侧数据经 `CoreExt` 由 gateway 回填 - [x] 单 `.so` + crate 级插件;指令名与 `.so` 名不变 - [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)不变。