Files
ssw__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

29 KiB
Raw Blame History

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 会直接报错)。

修法:内核开「账号删除钩子」注册表。

// 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,下沉三件套:

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 不用再改):

// 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:取并集

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 处装配(少任一处 = 「代码全对但功能不生效」)

// 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 装载

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)

  • 只做 iPass 自身插件化;ssw/sso 的仓库归属留到 P5
  • 身份端点(登录 / 会话 / 账号管理 / me)由 ipass-core 直接收口,经 CorePlugin 装配
  • 单 .so + crate 级插件(不做运行时多 .so)
  • ukey: 鉴权与 rl: 配额下沉 core(两条下行链路共用)
  • stats 按「记账原语 / 业务解读」切开,原语进 core
  • 指令名与 .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