Files
ipass__ipass/docs/plugin/PLUGINIZATION_PLAN.md
T
admin 74aeefee58 refactor(plugin): P0-P2 插件化落地 —— workspace 化 + ipass-core + plugin-domain
- P0: rust/ 改 workspace(ipass-core 内核 + gateway 唯一 cdylib),
  [profile.release] 上移根、依赖收敛 workspace.dependencies;
  users::delete 的 stats::forget 依赖改为 on_delete 钩子注册表
- P1: 契约层 core/plugin.rs(Plugin trait)+ core/loc.rs(Switch 并集 +
  set_switch_fn,未实现变体保守 false);gateway PLUGINS 分发循环,
  不认领统一 404(插件绝不自行 404)
- P2: 身份端点下沉 core/api.rs(CorePlugin + CoreExt 扩展注册表,
  gateway 作装配根回填域名数/用量/连带回收/白名单校验);
  plugin-domain crate(domains + DomainEntry + sub: 前缀 + ResolveHandler
  + $proxy_backend_addr + 域名类端点含 purge)
- 行为等价:conf/nginx.conf、Dockerfile、tests 零改动,262 回归全绿
- 方案文档 docs/plugin/PLUGINIZATION_PLAN.md
2026-09-13 11:43:22 +08:00

529 lines
29 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# iPass 插件化改造方案(core + 编译期插件)
> 参照实现:`ssw/sso`(`[email protected]: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.<zone>/*` | access | `ipass_proxy` | `ResolveHandler` | `lib.rs` + `domains.rs` |
| `lm.<zone>/<slot>/*` | access | `ipass_llm` | `LlmHandler` | `lib.rs` + `llm.rs` |
| `lm.<zone>/apix/<slug>` | access | `ipass_apix` | `ApiProxyHandler` | `lib.rs:323` + `apix.rs` |
| `mdm.<zone>/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<Vec<fn(&str)>> = 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<String>; // 原 llm::downstream_key
pub fn identity(key: &str) -> Option<(String, Vec<String>, i64, i64)>; // 原 llm::identity,读 ukey:
pub fn check_quota(r: *mut ngx_http_request_t, user: &str, rpm: i64, daily: i64)
-> Option<Status>; // 原 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<Status> { 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/<slug>` 用 **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` |