# iPass 插件化改造方案(core + 编译期插件) > 参照实现:`ssw/sso`(`git@192.168.1.18:13300/ssw/sso.git`)——它是从本项目衍生的插件式版本, > 已跑通「内核 + 插件 + 单 `.so` 装配」并留有两份可直接复用的文档: > `docs/plugin-architecture-analysis.md`(为什么不拆多 `.so`)与 > `.workbuddy/skills/ipass-core-add-plugin/SKILL.md`(怎么加一个插件)。 > > **本方案只做 iPass 自身的插件化**(已拍板):与 `ssw/sso` 的仓库归属、身份插件是否并入, > 留到 P5 再定。**身份端点(登录 / 会话 / 账号管理)由 `ipass-core` 直接收口**(已拍板)。 > > 目标:**行为完全等价**重构——`data/*.json` 一个字节不改、`conf/nginx.conf` 一条指令不改、 > 现有 262 项回归全绿;换来的是「加一个能力 = 加一个 crate + 在 gateway 加 5 处装配」。 --- ## 0. 一句话判据:什么进内核 > **去掉这个插件,网关还能不能跑?** 能 → 它不是内核。 推论: | 能力 | 归属 | 理由 | | --- | --- | --- | | 共享内存唯一 zone / 文件写锁 | **core** | 只能有一份,多份就失去「热路径零文件 I/O」的意义 | | `data/users.json` 读写、`ukey:` Key 索引 | **core** | 一处吊销处处生效;插件各写一份等于没共用 | | 账号模型 `User` | **core** | 域名审批、LLM 配额、API 代理都要挂在同一账号上 | | 会话 / 登录失败锁定 | **core** | 与账号强绑定;且是**所有插件端点的公共前置** | | 身份类 HTTP 端点(`/api/admin/login`、`/api/admin/users*`、`/api/v1/me`) | **core** | 同上;已拍板由 core 收口 | | `sk_` Key 下行鉴权 + `rl:` 配额 | **core** | **两条下行链路(LLM + API 代理)共用**,见 §4② | | 动态域名映射与审批 | plugin-domain | 独立业务 | | LLM 路由 / 上游 / 配额计费 / 对话审计 / 用量趋势 | plugin-llm | 独立业务 | | 外部 API 供应商资产代理 | plugin-apix | 独立业务 | --- ## 1. 现状量测(改造前) ``` rust/ 单 crate,7035 行,产出 libipass_gateway.so ├── Cargo.toml [package] ipass-gateway v2.0.0 │ [lib] crate-type = ["cdylib","rlib"] ← 必须留 cdylib(nginx 要) ├── build.rs ├── vendor/ngx-rust/ path 依赖(不可走 crates.io / git,见 Cargo.toml 注释) └── src/ 17 个模块 ``` | 文件 | 行 | 依赖(`use crate::`) | | --- | --- | --- | | `config.rs` | 232 | — | | `models.rs` | 219 | — | | `state.rs` | 362 | config | | `store.rs` | 196 | config models state | | `session.rs` | 57 | config state util | | `util.rs` | 354 | config | | `http.rs` | 223 | util | | `users.rs` | 405 | config models state **stats** store util | | `domains.rs` | 485 | config models state store util | | `upstreams.rs` | 397 | config models state store util | | `llm.rs` | 442 | config state upstreams util | | `llm_usage.rs` | 275 | — | | `llm_audit.rs` | 200 | config store util | | `stats.rs` | 585 | config state util | | `apix.rs` | 563 | config http models state store util | | `api.rs` | 1018 | **除 lib 外全部**(apix config domains http models session state stats upstreams users util) | | `lib.rs` | 1022 | 模块壳:7 条指令 + 6 个 phase handler + 10 个变量注册 | **三条热路径 + 一条管理通道**(全部注册在 `lib.rs`,靠 location 开关收敛): | 入口 | 阶段 | 开关 | handler | 现状落点 | | --- | --- | --- | --- | --- | | `*dm./*` | access | `ipass_proxy` | `ResolveHandler` | `lib.rs` + `domains.rs` | | `lm.//*` | access | `ipass_llm` | `LlmHandler` | `lib.rs` + `llm.rs` | | `lm./apix/` | access | `ipass_apix` | `ApiProxyHandler` | `lib.rs:323` + `apix.rs` | | `mdm./api/*` | content | `ipass_api` | `ApiHandler` | `lib.rs` + `api.rs` | 另有 log 阶段两个旁路 handler:`LlmHealthHandler`(上游健康标记)、`AuditHandler`(对话审计 + token 计量);以及 `llm_usage::install()`(body filter 抓上游响应里的 usage)。 **共享内存键前缀全景**(`config.rs:78-166`)——已天然按域分片,是插件划分的现成依据: | 前缀 | 归属 | 含义 | | --- | --- | --- | | `sess:` `fail:` `ukey:` | **core** | 会话 / 登录失败计数 / Key→身份索引 | | `rl:` | **core**(本方案调整,见 §4②) | 配额窗口 | | `sub:` | plugin-domain | 子域名 → 后端 | | `up:` `st:` `ust:` `ums:` `utt:` `utms:` `ud:` `udu:` `uds:` `uh:` | plugin-llm | 上游 / 上游状态 / 用量账本 / 趋势日桶 / 健康标记 | | `ax:` | plugin-apix | 代理 slug → 供应商资产 | --- ## 2. 目标结构 ``` rust/ ├── Cargo.toml # [workspace](成员 + 统一依赖 + [profile.release]) ├── vendor/ngx-rust/ # 保持不动(path 依赖) ├── crates/ │ ├── ipass-core/ # 内核:状态 / 账号 / 装配契约 / 身份端点 │ │ └── src/ │ │ ├── config.rs # 仅共性常量 + sess:/fail:/ukey:/rl: 前缀 │ │ ├── models.rs # User(全字段 serde(default)) │ │ ├── state.rs # 唯一 shm zone + 泛型原语 │ │ ├── store.rs # JSON 原子写 + 文件写锁 + data_dir │ │ ├── usage.rs # 【拆自 stats.rs】通用记账原语(无 LLM 语义) │ │ ├── auth.rs # 【新】下行 sk_ 鉴权 + rl: 配额(两条链路共用) │ │ ├── users.rs # 账号唯一写入口 + on_delete 钩子 │ │ ├── session.rs # 会话 │ │ ├── plugin.rs # 【新】Plugin 契约 │ │ ├── loc.rs # 【新】Switch 枚举 + 注入式开关查询 │ │ ├── http.rs / util.rs # 请求响应原语 / 通用工具 │ │ └── api.rs # 【拆自 api.rs】身份类端点 + CorePlugin │ ├── plugin-domain/ # 动态域名 │ │ └── src/{lib,keys,models,domains,resolve,api}.rs │ ├── plugin-llm/ # LLM 路由 / 配额计费 / 审计 / 用量趋势 │ │ └── src/{lib,keys,models,llm,upstreams,usage_filter,audit,stats,resolve,api}.rs │ └── plugin-apix/ # 外部 API 供应商资产代理 │ └── src/{lib,keys,models,apix,resolve,api}.rs └── gateway/ # 唯一 cdylib:模块壳 + PLUGINS 注册表 └── src/lib.rs ``` **关键不变式:仓库里只有一个 `cdylib`(gateway)。** 插件一律 `crate-type = ["rlib"]`。 理由(已在 nginx 1.30.4 源码层面核对,详见 sso 的 `plugin-architecture-analysis.md`): 动态模块 `ngx_module_t` 带编译期签名,必须与 nginx 同源;共享内存 zone 的 tag 不同会在 `ngx_cycle.c` 直接 EMERG 启动失败;同名变量会被后加载者劫持 `get_handler`(不报错、 只在某些部署下身份错);Rust 无稳定 ABI,跨 `.so` 传 `String` 即双重 free。 ### 2.1 规模预估 | 目标 crate | 行数(约) | 说明 | | --- | --- | --- | | `ipass-core` | ~2350 | 含身份端点 | | `plugin-domain` | ~650 | | | `plugin-llm` | ~2100 | 最大的一块 | | `plugin-apix` | ~700 | | | `gateway` | ~450 | 只留壳 | | **合计** | **~6250 + 契约胶水 ≈ 7000** | 与现状 7035 吻合,无逻辑膨胀 | --- ## 3. 逐文件归属(改造清单) | 现文件 | 行 | 目标 | 备注 | | --- | --- | --- | --- | | `config.rs` | 232 | **拆** | 共性(`SESSION_TTL` `HASH_ROUNDS` `COOKIE_NAME` `LOGIN_MAX_FAIL` `INIT_ADMIN_*` `USERNAME_*` `PASSWORD_MIN_LEN` `DISPLAY_NAME_MAX_LEN` `DEFAULT_DATA_DIR`)→ core;`TEMP_DOMAIN_TTL` `SUBDOMAIN_*` `RESERVED_SUBDOMAINS` → domain;`UPSTREAM_*` `LLM_*` `AUDIT_*` `TREND_*` → llm;`APIX_*` → apix | | `models.rs` | 219 | **拆** | `User` → core;`Upstream`(73-115)→ llm;`ApiProxy`/`ApiProxyStore`(117-165)→ apix;`DomainEntry`(167-)→ domain | | `state.rs` | 362 | core | 原样 | | `store.rs` | 196 | core | 原样 | | `session.rs` | 57 | core | 原样 | | `util.rs` | 354 | core | 原样 | | `http.rs` | 223 | core | 原样 | | `users.rs` | 405 | core | **摘掉 `stats::forget` 依赖**(§4①),`&mut pub` 化为 `on_delete` 钩子 | | `stats.rs` | 585 | **拆** | 记账原语 → `core/usage.rs`;`trend`/`overview`/`user_models`/`tokens_user` 等解读 → `plugin-llm/stats.rs`(§4③) | | `domains.rs` | 485 | plugin-domain | 含 `sync_shm`/`reload_shm` | | `llm.rs` | 442 | plugin-llm | `downstream_key` / `identity` / `check_quota` 移出 → `core/auth.rs`(§4②) | | `upstreams.rs` | 397 | plugin-llm | 原样 | | `llm_usage.rs` | 275 | plugin-llm | 改名 `usage_filter.rs`;`install()` 无参,可在插件 `postconfig` 内直接调 | | `llm_audit.rs` | 200 | plugin-llm | 原样 | | `apix.rs` | 563 | plugin-apix | 管理 API 部分拆到 `api.rs` | | `api.rs` | 1018 | **拆四处** | 见下表 | | `lib.rs` | 1022 | gateway + 各插件 | 壳留 gateway;6 个 handler 与 10 个变量注册下放 | ### `api.rs` 的端点归属(1018 行拆四处) | 端点 | 归属 | 依据 | | --- | --- | --- | | `/api/admin/login` `/logout` `/session` | **core** `api.rs` | 会话是内核职责 | | `/api/admin/users` `/users/{create,display,key,grant,password,delete,models,limits}` | **core** | 账号是内核职责 | | `/api/admin/purge` | **core** | 清理的是会话/失败计数 | | `/api/v1/me` | **core** | 账号态自我查询 | | `/api/admin/domains` `/domains/{review,create,delete}`、`/api/v1/domains` `/domains/{apply,delete}` | plugin-domain | | | `/api/admin/upstreams` `/upstreams/{save,delete,test}`、`/api/admin/usage` `/trend`、`/api/v1/upstreams` `/models` `/usage` | plugin-llm | | | `/api/admin/apix` `/apix/{save,delete,test}`、`/api/v1/apix` | plugin-apix | | `Guard`(`Public`/`User`/`Admin`)与 `Actor` 是**四份 route 表共用**的类型 → 连同 `user_or_401`、`admin_or_403` 之类守卫一起下沉到 `core/auth.rs`,各插件引用而非各写一份。 --- ## 4. 三个必须先解决的边界问题 这三处是「直接按目录切文件」会撞墙的地方,也是本方案与 sso 参考实现**刻意不同**的地方。 ### ① `users::delete` → `stats::forget`:内核反向依赖插件 `users.rs:372` 在删除账号时调用 `stats::forget(&stats_name)` 摘掉用量索引。 若 `stats` 随 plugin-llm 走,就形成 **core → plugin-llm 的循环依赖**(cargo 会直接报错)。 **修法:内核开「账号删除钩子」注册表。** ```rust // crates/ipass-core/src/users.rs static ON_DELETE: Mutex> = Mutex::new(Vec::new()); /// 插件注册「账号被删除时我需要清理什么」。在 zone 装载后、接请求前调用一次。 pub fn on_delete(f: fn(&str)) { /* push */ } pub fn delete(username: &str, operator: &str) -> Result<(), String> { // ... 原有逻辑:文件 + ukey:/sess:/fail: 写穿(core 自己的键,不需要钩子) for f in hooks() { f(username); } // 插件各清各的键空间 Ok(()) } ``` plugin-llm 暴露 `pub fn install_hooks() { users::on_delete(stats::forget); }`, 由 `gateway` 的 `state_zone_init` 在插件 `zone_load` 之后统一调用。 > 这条钩子同时解决了「键按前缀分域」惯例下的一个通用问题:**删除账号要摘几个前缀, > 取决于装了哪些插件**——只有注册表能让内核在不认识插件的前提下做对。 ### ② `ApiProxyHandler` 复用 `llm::identity` / `llm::check_quota`:插件间依赖 `lib.rs:344/352/383`——API 代理热路径调用 LLM 的三个函数完成「取下行 Key → 查身份 → 查配额」。若 llm 与 apix 平级,就是 plugin-apix → plugin-llm 的依赖,破坏「插件平级」。 **判据**:`ukey:` 鉴权与 `rl:` 配额,是「**去掉 llm 还要(apix 要)、去掉 apix 还要(llm 要)、 两个都去掉才不要**」——典型的**共用 ⇒ 放内核**。 **修法:新建 `crates/ipass-core/src/auth.rs`**,下沉三件套: ```rust pub fn downstream_key(r: *mut ngx_http_request_t) -> Option; // 原 llm::downstream_key pub fn identity(key: &str) -> Option<(String, Vec, i64, i64)>; // 原 llm::identity,读 ukey: pub fn check_quota(r: *mut ngx_http_request_t, user: &str, rpm: i64, daily: i64) -> Option; // 原 llm::check_quota,读 rl: ``` 同时把 `rl:` 前缀从 `config.rs` 的 LLM 段移到 core 段。 > sso 的参考实现把 `rl:` 划给 plugin-llm,是因为 sso **没有 apix 这条链路**。 > iPass 有两条共用配额的下行链路,所以这里必须与 sso 不同——这是本方案对参考实现的 > 第一处有意偏离。 ### ③ `stats.rs` 585 行:记账原语 vs 业务解读 整块搬进 plugin-llm 会让 core 的 `users` 钩子无处落(见①),整块留 core 又会让内核长出 LLM 语义(`token` / `模型` / `趋势` 这些词不该出现在内核里)。 **修法:按「回答什么问题」切开。** | 部分 | 目标 | 回答的问题 | | --- | --- | --- | | `record` / `add_tokens` / `forget` / 前缀扫描薄封装 | `core/usage.rs` | 「给这个键 +1」「这个键还有什么」——**纯键值操作,不含业务语义** | | `trend()` / `overview()` / `user_models()` / `tokens_user()` / `all_users()`、日桶聚合 | `plugin-llm/stats.rs` | 「这些数字代表什么」——**业务解读** | `core/usage.rs` 只认「前缀 + 名字 + 计数」,不认识 `ust:` 与 `ums:` 的区别;日桶 (`ud:`/`udu:`/`uds:`)的 TTL 与保留策略由 plugin-llm 传入。 --- ## 5. 契约层(内核与插件之间唯一的接口) ### 5.1 `Plugin` trait 沿用 sso 的形态,**签名保持一致**(P5 若与 sso 合流,trait 不用再改): ```rust // crates/ipass-core/src/plugin.rs 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 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 的 `ngx_module_t.commands` 是 null 结尾的**连续**数组, 不同 crate 的 `static` 数组无法拼接。配置指令由 gateway 集中声明,插件通过 `loc::Switch` 查询自己所在 location 是否开启——**指令解析归壳、行为归插件**。 `dispatch_api` 的语义是「不认领就返回 `None`,让下一个插件试」,**绝不自行 404** (否则后注册的插件永远收不到请求)。404 由 gateway 在全部插件都返回 `None` 后统一发出。 ### 5.2 `loc::Switch`:取并集 ```rust pub enum Switch { Api, // 该 location 暴露管理 API + 身份端点 Iap, // 预留(iPass 无用,sso 用;合流时不用改 core) Domain, // 预留(同上) Proxy, // 该 location 走「子域名 → 后端」转发 ← iPass 用 Llm, // 该 location 走 LLM 代理 ← iPass 用 Apix, // 该 location 走 API 代理 ← iPass 用 } ``` `Switch` 是内核与插件之间**唯一的契约点**,宁可多留两个变体,也不要在 P5 合流时做破坏性改动。 gateway 注入查询实现(`set_switch_fn`),**未实现的变体一律保守返回 `false`** (sso 已踩过这个坑:`Switch::Llm => false`,绝不能误开)。 ### 5.3 gateway 的 5 处装配(少任一处 = 「代码全对但功能不生效」) ```rust // gateway/src/lib.rs use plugin_apix::ApixPlugin; // ① use plugin_domain::DomainPlugin; use plugin_llm::LlmPlugin; static PLUGINS: &[&dyn Plugin] = &[ &ipass_core::api::CorePlugin, // 身份端点必须先认领 &DomainPlugin, &LlmPlugin, &ApixPlugin, ]; // ② 顺序 = 装配顺序 struct ModuleConfig { api: bool, proxy: bool, llm: bool, apix: bool } // ③ // Merge::merge 里补 4 个 if;指令数组长度不变(7 + empty = 8)+ set_flag_* 4 个 fn loc_switch(r: &mut Request, s: Switch) -> bool { // ④ match s { Switch::Api => c.api, Switch::Proxy => c.proxy, Switch::Llm => c.llm, Switch::Apix => c.apix, Switch::Iap | Switch::Domain => false, // 未实现:保守 false } } // ⑤ preconfiguration 里只留 loc::set_switch_fn(loc_switch),其余全部下放插件 ``` ### 5.4 指令名与 conf:**一个字都不用改** iPass 现有 7 条指令 `ipass_state` / `ipass_data_dir` / `ipass_audit_dir` / `ipass_proxy` / `ipass_api` / `ipass_llm` / `ipass_apix`,**与插件划分恰好 1:1**,全部保持原名, 数组长度仍是 8。模块名仍是 `ngx_http_ipass_module`,`.so` 仍是 `libipass_gateway.so`。 > 这是 iPass 相对 sso 参考实现的**结构性优势**:sso 的指令都叫 `sso_*`(`sso_api` / > `sso_iap` / `sso_domain`),搬到 iPass 要全部改名并同步 conf;iPass 侧零改动。 > 连带收益:`conf/nginx.conf`、`tests/gateway/nginx.conf.in`、`tests/llm/nginx.conf.in` > **全部不动**,回归基线直接可比。 ### 5.5 变量注册下放 | 变量 | 现位置 | 目标 | | --- | --- | --- | | `$proxy_backend_addr` | `lib.rs:660-676` | plugin-domain `preconfig` | | `$llm_target` `$llm_host` `$llm_auth` | `lib.rs:680-691` | plugin-llm `preconfig` | | `$apix_target` `$apix_host` `$apix_key` `$apix_body` `$apix_probe_target` `$apix_probe_body` | `lib.rs:694-711` | plugin-apix `preconfig` | > 下放后天然更安全:三组变量分属三个 crate,不会像 sso 那样两个 `.so` 注册同名 > `$auth_*` 再互相劫持 get_handler。 **`$upstream_status` 的索引预取**(`lib.rs:739-747`,依赖 `upstream` 内建模块已注册该变量) → plugin-llm 的 `postconfig`。插件 `postconfig` 在 gateway 自己的 `postconfig` 之前执行, 而内建模块的 `preconfiguration` 早已跑完,时序安全。 ### 5.6 phase handler 下放 | handler | 阶段 | 目标 | | --- | --- | --- | | `ResolveHandler` | access | plugin-domain `postconfig` | | `LlmHandler` | access | plugin-llm `postconfig` | | `ApiProxyHandler` | access | plugin-apix `postconfig` | | `LlmHealthHandler` | log | plugin-llm `postconfig` | | `AuditHandler` | log | plugin-llm `postconfig`(同处调 `usage_filter::install()`) | | `ApiHandler` | content | **留 gateway**——统一收口后按 `PLUGINS` 顺序分发 | ### 5.7 shm 装载 ```rust extern "C" fn state_zone_init(zone, _data) -> ngx_int_t { state::init_zone(zone)?; users::reload_shm(); // ① 内核自有的 ukey: 索引(不是插件能力) for p in PLUGINS { p.zone_load(); } // ② 各插件装自己的表 plugin_llm::install_hooks(); // ③ 注册 on_delete 钩子(§4①) NGX_OK } ``` > `users::reload_shm()`(`users.rs:93`)装的是 `ukey:` Key → 身份索引,**属内核**, > 不能靠某个插件的 `zone_load` 顺带完成——否则「核心索引是否装载」会依赖插件是否装配。 --- ## 6. 与 sso 参考实现的差异(有意偏离) | # | sso 做法 | iPass 做法 | 原因 | | --- | --- | --- | --- | | 1 | `rl:` 配额归 plugin-llm | 归 **core** `auth.rs` | iPass 有 LLM + apix **两条**共用配额的链路(§4②) | | 2 | `stats` 整体在插件 | **拆**:原语进 core `usage.rs`,解读进 plugin-llm | 内核删账号要摘用量索引(§4①③) | | 3 | 身份端点全在 plugin-sso | 身份端点在 **core**(`CorePlugin`) | 已拍板;iPass 无 SSO 插件(§0) | | 4 | 指令 `sso_*`,迁移需改名 | 保持 `ipass_*` | 指令与插件 1:1,conf 零改动(§5.4) | | 5 | `Switch { Api, Iap, Domain, Llm }` | 取**并集** `{Api, Iap, Domain, Proxy, Llm, Apix}` | 契约点一次到位,避免 P5 破坏性改动 | | 6 | 无 | 新增 `users::on_delete` 钩子 | 内核不认识插件的键空间(§4①) | | 7 | 无 `plugin-llm`(明确不迁入) | **要** plugin-llm | iPass 的本体就是域名 + LLM + apix | | 8 | `libsso_gateway.dylib` | 仍是 `libipass_gateway.so` | Dockerfile 产物路径不变 | --- ## 7. 落地路径(每阶段独立可回滚) ### P0 · 建 workspace,内核落地(**行为零变化**) 1. `rust/Cargo.toml` → 变 workspace 根:`members = ["crates/ipass-core", "gateway"]`, `exclude = ["vendor/ngx-rust"]`,依赖全部上移到 `[workspace.dependencies]`。 2. 建 `crates/ipass-core`,迁入 `config`(共性裁剪)/ `models`(仅 `User`)/ `state` / `store` / `session` / `util` / `http` / `users`。 3. 建 `gateway`,`lib.rs` 整体搬过去——**此时所有业务模块仍留在 gateway**, 先证明「产物名、路径、行为全部不变」。 **验收**:`target/release/libipass_gateway.so` 同名同路径; `bash deploy/... ` 容器可起;`bash tests/run.sh all` **262 项全绿**。 > ⚠️ 最容易漏的一处:`[profile.release]`(`opt-level`/`lto`/`codegen-units`/`panic="abort"`/ > `strip`)**必须在 workspace 根**——member 里写会被 cargo 忽略。`panic="abort"` 丢了 > 就意味着 panic 可能跨 FFI 边界展开。 ### P1 · 契约层 新增 `core/plugin.rs`(`Plugin` trait)与 `core/loc.rs`(`Switch` + `set_switch_fn`/`enabled`); gateway 实现 `loc_switch`、把 `PLUGINS` 数组与分发循环接上(此时 `PLUGINS` 只有 `CorePlugin`)。 **验收**:编译通过、262 全绿(契约层不改变行为)。 ### P2 · 拆 plugin-domain(最小、最独立,用来验证流程) 迁 `domains.rs` + `DomainEntry` + `sub:` 前缀 + 域名类端点 + `ResolveHandler` + `$proxy_backend_addr` 注册 + `TEMP_DOMAIN_TTL`/`SUBDOMAIN_*`/`RESERVED_SUBDOMAINS`。 **验收**:`tests/gateway` 102 项全绿(含域名审批 / 写穿生效 / 通配符转发)。 ### P3 · 拆 plugin-llm(最大,前置换算在下沉 core) 前置三件事:**`auth.rs` 下沉**(§4②)、**`usage.rs` 拆分**(§4③)、**`on_delete` 钩子**(§4①)。 然后迁 `llm` / `upstreams` / `llm_usage` / `llm_audit` / `stats`(解读部分)+ LLM 类端点 + 三个 handler + `up:`…`uh:` 全部前缀 + `llm_*` 三变量。 **验收**:`tests/llm` 160 项全绿(含流式、模型发现、配额、用量趋势、审计落盘)。 ### P4 · 拆 plugin-apix 迁 `apix.rs` + `ax:` 前缀 + apix 类端点 + `ApiProxyHandler` + `apix_*` 六变量。 **验收**:apix 用例全绿(现混在 `tests/llm` 内);手工确认两点—— `/apix/` 用 **lm host**、`/_apix_probe/` 在 **mdm server**(`mdm` 上打 `/apix/` 应是 nginx 404)。 ### P5 · 收尾 + 文档 + 技能;**(可选)**与 ssw/sso 的关系 - 文档:`CLAUDE.md`(crate 清单 + 目录地图 + 回归套数)、`readme.md` §6 目录结构、 本文件转正为 `docs/plugin/PLUGIN_ARCHITECTURE.md`(P2 的论证部分直接引用 sso 的 `plugin-architecture-analysis.md`,不重复写)。 - 技能:把 sso 的 `.workbuddy/skills/ipass-core-add-plugin/SKILL.md` 改造为 iPass 版 (改 crate 名、指令名、e2e 路径;保留「5 处装配缺一不可」「症状 → 根因」两张表)。 - **待定**:是否把 `sww/sso` 的 `plugin-sso` 并入 iPass(届时 `CorePlugin` 的身份端点 移交 plugin-sso,或 plugin-sso 直接实现同一批路由)。P0–P4 的设计已为此留好口子 (`Switch` 并集、`Plugin` trait 签名与 sso 一致)。 --- ## 8. 周边影响面 | 文件 | 是否要改 | 说明 | | --- | --- | --- | | `Dockerfile` | **不改** | `COPY rust/ ./` + 在 workspace 根 `cargo build --release`,产物仍是 `target/release/libipass_gateway.so` | | `conf/nginx.conf` | **不改** | 指令名与 `.so` 名不变(§5.4) | | `compose.yml` | **不改** | | | `deploy/release.sh` `deploy/agent.sh` `deploy/ipass-agent.py` | **不改** | 镜像 tag / 产物路径 / 端口不变 | | `tests/run.sh` + `tests/*/nginx.conf.in` | **不改** | 套数与端口不变 | | `tests/*/fixtures/*.json` | **不改** | 持久化格式零变化(§9⑤) | | `.gitignore` `.dockerignore` | **不改** | `vendor/` 仍在 `rust/vendor/` | | `www/` 管理台 | **不改** | API 路径全部保持原样 | | 迭代命令 | **变** | 单 crate 快速迭代:`cargo build -p plugin-llm`(几十秒 vs 全量 ~1.5 分钟) | --- ## 9. 风险与纪律 1. **P3 是主战场**。边界切错会让内核长出 LLM 语义(难事后拆),或形成 core↔plugin 循环 (cargo 直接报错,不会静默——这点比运行时问题好排查)。开工前先按 §4 三条把 `auth.rs` / `usage.rs` / `on_delete` 建好,再动搬移。 2. **`[profile.release]` 只能在 workspace 根**。`panic="abort"`(防 panic 跨 FFI)、 `lto`、`codegen-units=1`、`strip` 一项丢了都是线上隐患。 3. **`[features] export-modules` + `ngx::ngx_modules!` 宏属于 gateway**。`[lib] crate-type` 的 `"cdylib"` 也只给 gateway;插件一律 `["rlib"]`(不要为了「顺便能测」给插件加 cdylib)。 4. **`loc::Switch` 未实现的变体必须保守 `false`**。返回 `true` 会让未装配的能力意外开门。 5. **`data/*.json` 零格式变化**:已核对 `User`/`Upstream`/`ApiProxy`/`ApiProxyStore`/ `DomainEntry` 的字段全部带 `#[serde(default)]`(含 `default_llm_rpm` / `default_llm_daily` / `default_true` 三个函数缺省),存量文件可直接被新 `.so` 接管。**但要在 P0 单独做一次 「新旧解析对拍」**(同一份 `data/` 跑改造前/后的构建,比对内存装载条数与账号数), 这是唯一可能出现「账号全部消失」类事故的地方。 6. **热路径永不回源**:插件的每请求决策只能读共享内存;任何写操作必须**先落文件、 再写穿 shm**,且写 shm 失败必须 `log_err`。迁移时逐插件核对 `sync_shm` 调用点, 漏一处 = 「刚配好却 404」。 7. **`ngx` 依赖必须走 `vendor/ngx-rust` 的 path 依赖**:crates.io 的 `ngx = "0.5"` 没有请求阶段 API(`add_phase_handler`/`HttpPhase` 未发版);git 依赖会去克隆 submodule 而卡死。 workspace 化后统一放 `[workspace.dependencies]`,各 crate 用 `.workspace = true`。 8. **别在 P2 顺手把 plugin-llm 建一半**:`members` 里列了但目录缺 `Cargo.toml`/`lib.rs` 会让整个 workspace 编不过。要么做完,要么从 `members` 摘掉并把目录移到 `/tmp` 备份。 --- ## 10. 已拍板 / 待拍板 **已拍板(2026-09-13)** - [x] 只做 iPass 自身插件化;`ssw/sso` 的仓库归属留到 P5 - [x] 身份端点(登录 / 会话 / 账号管理 / `me`)由 `ipass-core` 直接收口,经 `CorePlugin` 装配 - [x] 单 `.so` + crate 级插件(不做运行时多 `.so`) - [x] `ukey:` 鉴权与 `rl:` 配额下沉 core(两条下行链路共用) - [x] `stats` 按「记账原语 / 业务解读」切开,原语进 core - [x] 指令名与 `.so` 名保持不变(conf 与测试零改动) **待拍板** - [ ] P5:是否把 `plugin-sso` 并入 iPass(并入后身份端点移交,`CorePlugin` 退化为纯库) - [ ] 是否同步把 `ssw/sso` 的 core 与本项目的 `ipass-core` 收敛为同一份( 需先确认两边 `Switch` 并集与 `Plugin` trait 已对齐——本方案已按对齐设计) --- ## 附:查证位置 | 论断 | 位置 | | --- | --- | | 17 模块 / 7035 行 | `rust/src/*.rs`(`wc -l`) | | 模块依赖图 | 各文件 `use crate::` 汇总(§1 表) | | 7 条指令 + 长度 8 | `rust/src/lib.rs:752-810` | | `ModuleConfig` 四开关 + `Merge` | `rust/src/lib.rs:563-594` | | 6 个 phase handler 注册点 | `rust/src/lib.rs:716-749` | | 10 个变量注册 | `rust/src/lib.rs:655-711` | | `$upstream_status` 索引预取 | `rust/src/lib.rs:739-747` | | `state_zone_init` 三表装载 | `rust/src/lib.rs:956-975` | | `ApiProxyHandler` 调 llm 三件套 | `rust/src/lib.rs:344` `:352` `:383` | | `users::delete` → `stats::forget` | `rust/src/users.rs:372` | | `users::reload_shm` 装 `ukey:` | `rust/src/users.rs:93-113` | | `llm_usage::install()` 无参 | `rust/src/llm_usage.rs:59-64` | | 键前缀全景 | `rust/src/config.rs:78-166` | | 持久化结构全部 `serde(default)` | `rust/src/models.rs`(`User` 23-48、`Upstream` 82-93、`ApiProxy` 135-161、`DomainEntry` 179-187) | | 为什么不拆多 `.so` | `ssw/sso` → `docs/plugin-architecture-analysis.md` | | 加插件的 5 处装配 / 排错表 | `ssw/sso` → `.workbuddy/skills/ipass-core-add-plugin/SKILL.md` |