- 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
29 KiB
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,内核落地(行为零变化)
rust/Cargo.toml→ 变 workspace 根:members = ["crates/ipass-core", "gateway"],exclude = ["vendor/ngx-rust"],依赖全部上移到[workspace.dependencies]。- 建
crates/ipass-core,迁入config(共性裁剪)/models(仅User)/state/store/session/util/http/users。 - 建
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并集、Plugintrait 签名与 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. 风险与纪律
- P3 是主战场。边界切错会让内核长出 LLM 语义(难事后拆),或形成 core↔plugin 循环
(cargo 直接报错,不会静默——这点比运行时问题好排查)。开工前先按 §4 三条把
auth.rs/usage.rs/on_delete建好,再动搬移。 [profile.release]只能在 workspace 根。panic="abort"(防 panic 跨 FFI)、lto、codegen-units=1、strip一项丢了都是线上隐患。[features] export-modules+ngx::ngx_modules!宏属于 gateway。[lib] crate-type的"cdylib"也只给 gateway;插件一律["rlib"](不要为了「顺便能测」给插件加 cdylib)。loc::Switch未实现的变体必须保守false。返回true会让未装配的能力意外开门。data/*.json零格式变化:已核对User/Upstream/ApiProxy/ApiProxyStore/DomainEntry的字段全部带#[serde(default)](含default_llm_rpm/default_llm_daily/default_true三个函数缺省),存量文件可直接被新.so接管。但要在 P0 单独做一次 「新旧解析对拍」(同一份data/跑改造前/后的构建,比对内存装载条数与账号数), 这是唯一可能出现「账号全部消失」类事故的地方。- 热路径永不回源:插件的每请求决策只能读共享内存;任何写操作必须先落文件、
再写穿 shm,且写 shm 失败必须
log_err。迁移时逐插件核对sync_shm调用点, 漏一处 = 「刚配好却 404」。 ngx依赖必须走vendor/ngx-rust的 path 依赖:crates.io 的ngx = "0.5"没有请求阶段 API(add_phase_handler/HttpPhase未发版);git 依赖会去克隆 submodule 而卡死。 workspace 化后统一放[workspace.dependencies],各 crate 用.workspace = true。- 别在 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并集与Plugintrait 已对齐——本方案已按对齐设计)
附:查证位置
| 论断 | 位置 |
|---|---|
| 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 |