- 新增 git submodule deps/ipass(指向 ipass/ipass,pin 9c46e27),内核与通用能力插件统一收归子模块 - 删除仓库内 crates/ipass-core、vendor/ngx-rust、crates/plugin-domain - source/rust/Cargo.toml 改为 members=[plugin-sso, gateway] + exclude=[../../deps/ipass],ngx/nginx-sys/ipass-core 改为 ../../deps/ipass/... 的 path 依赖 - gateway 移除 plugin-domain 装配:PLUGINS=[SsoPlugin, CorePlugin],去除 ipass_proxy 指令 / domain 开关 / set_flag_domain - plugin-sso 新增 compat.rs 兼容层,重建被主线内核移除的 4 个 http 辅助函数(body_object/json_body/send_ct/redirect),scim/cas/portal/reset.rs 改走 crate::compat - 删除 tests/domain-e2e.sh,run-local-e2e.sh 的域名测试调用一并移除(e2e 由 7 套降为 6 套) - 更新 README/CLAUDE/docs 反映子模块结构;构建已验证:cargo build --release 通过,产出 libsso_gateway.dylib
9.8 KiB
插件化架构:iPass 统一网关(core + 插件)
问题:iPass 有「动态域名 + LLM 路由」,SSO 有「身份 / Key / OAuth」, nginx 本来就支持多模块——能不能做成插件模式,共用一个用户基础认证与 Key,其它由插件来做?
定稿(2026-09-13):
- 内核是
ipass-core(网关内核),SSO 是其中一个插件,与domain、llm平级。 身份不是内核——内核只回答「请求是谁、状态存哪、配置怎么装配」。users.json全局共用一份,由ipass-core独占读写,插件只读不写。- 插件是 Rust crate 级(编译期装配,产出单个
.so),不是运行时加载多个动态模块。
一、为什么是 ipass-core,而不是 sso-core
内核的职责应该是「所有插件都要用、且只有一份才有意义」的东西:
| 能力 | 归属 | 理由 |
|---|---|---|
| 共享内存状态表 / 文件写锁 | core | 只能有一个 zone;多份就失去「热路径零文件 I/O」的意义 |
users.json 读写与 Key 索引 |
core | 一处吊销处处生效;插件各写一份就等于没共用 |
账号模型 User |
core | 身份是全局概念,域名审批与 LLM 配额都要挂在同一个账号上 |
| 会话 / 登录失败锁定 / 审计 | core | 与账号强绑定,跨插件共享 |
| OAuth2 / OIDC 签发与校验 | plugin-sso | 一种认证协议,不是网关必需品 |
| IAP 身份注入 | plugin-sso | 同上 |
| 动态域名映射与审批 | plugin-domain | 独立业务 |
| LLM 路由 / 配额 / 计费 | plugin-llm | 独立业务 |
一句话判据:去掉 SSO,网关还能不能转域名、还能不能代理 LLM? 能 → 那它就不是内核。
二、「nginx 支持多模块」≠ 插件 ABI
三个硬约束决定了多 .so 只能算「同源编译的多个 C 模块」,不是插件生态:
- 模块必须与 nginx 二进制同源。动态模块的
ngx_module_t带version/signature(含NGX_MODULE_SIGNATURE一长串编译期特性位),不匹配直接拒绝加载。 - Rust 没有稳定 ABI。每个 cdylib 静态链进自己的一份
std。跨.so传递Box/String/Vec意味着「A 的分配器分配、B 的分配器释放」→ 双重 free。 - 加载顺序影响行为(下一节有源码级证据)。
三、如果硬上多 .so,会踩的三个坑(已在 nginx 1.30.4 源码核对)
坑 1:共享内存 zone 的 tag 必须相同,否则启动即失败
src/core/ngx_cycle.c:
if (tag != shm_zone[i].tag) {
ngx_conf_log_error(NGX_LOG_EMERG, cf, 0,
"the shared memory zone \"%V\" is "
"already declared for a different use", &shm_zone[i].shm.name);
return NULL; // ← 直接启动失败
}
而两边现在传的都是自己模块的 ngx_module_t 地址:
// source/rust/src/lib.rs:451
ngx_shared_memory_add(cf, &raw mut name, size, (&raw mut ngx_http_sso_module).cast())
// refs/ipass/rust/src/lib.rs:824
ngx_shared_memory_add(cf, &raw mut name, size, (&raw mut ngx_http_ipass_module).cast())
现在一行不改,同进程加载必然冲突。 想共用就得把 tag 改成约定值(例如都传 NULL),
且 size 必须一致(或后者传 0 表示不校验)。
坑 2:同名变量会被后加载者「劫持」getter
两边注册了完全相同的五个变量:
static AUTH_VAR_NAMES: [&str; 5] = ["auth_user","auth_email","auth_groups","auth_sub","auth_token"];
src/http/ngx_http_variables.c:同名 + NGX_HTTP_VAR_CHANGEABLE 时
ngx_http_add_variable 返回已存在的那个 v(不报错、不新建)。而两边注册后都做:
unsafe { (*var).get_handler = Some(auth_var_get); } // 覆盖
ngx_http_get_variable_index 对同名又返回同一个 slot。结果是:
$auth_user取哪个模块的 handler、以及 access 阶段谁最后写入该 slot, 完全取决于load_module的先后顺序。
这类 bug 不报错,只会「某些部署下身份对、某些部署下身份错」。
坑 3:跨 .so 复用 Rust 结构是 UB
ShmRoot { map: RwLock<RbTreeMap<..>>, file_lock: RwLock<()> } 是 Rust 布局。
两个 .so 各自编译,只要 rustc 版本 / 优化级别 / 结构定义有任一差异,
字段偏移或 RwLock 内部表示就可能对不上 → 静默内存损坏。
要跨模块共享只能换成 #[repr(C)] + magic + version + size 三重校验的桥接头。
四、定稿结构
2026-09-21 起:本仓库只持有 SSO 身份插件 + 装配层,内核与通用能力插件统一由
deps/ipassgit 子模块(ipass/ipass)提供,不再内置。
source/rust/ # 本仓库的 Cargo workspace
├── Cargo.toml # members = [crates/plugin-sso, gateway];ipass-core/ngx-rust 走 deps/ipass 的 path 依赖
├── crates/
│ └── plugin-sso/ # 身份插件:OAuth2/OIDC + IAP 注入(本仓库唯一业务 crate)
│ └── src/{oauth,oauth_clients,oauth_keys,oauth_state,rsa,otp,captcha,api,scim,cas,ldap,sync,reset,geo,portal,compat}.rs
└── gateway/ # 装配层:模块壳 + 插件注册表 → 单个 .so
└── src/lib.rs
deps/ipass/ # git 子模块 → ipass/ipass(内核 + 通用插件,本仓库不再内置)
└── rust/
├── Cargo.toml # 独立 workspace(resolver=2),ipass-core 解析 ngx/nginx-sys 的 [workspace.dependencies]
├── vendor/ngx-rust/ # path 依赖,不可走 crates.io / git
└── crates/
├── ipass-core/ # 网关内核:唯一读写 users.json 的地方
│ └── src/{config,models,users,store,state,session,util,http,audit,plugin,loc,api}.rs
├── plugin-domain/ # 动态域名(已在子模块内)
└── plugin-llm/ # LLM 路由 / 配额(已在子模块内)
插件契约
pub trait Plugin {
fn name(&self) -> &'static str;
fn commands(&self) -> &[ngx_command_t]; // 配置指令(sso_api / ipass_proxy / ipass_llm ...)
fn preconfig(&self, cf) -> bool; // 注册 nginx 变量
fn postconfig(&self, cf) -> bool; // 注册 phase handler
fn api_routes(&self) -> &[Route]; // 管理接口
fn access(&self, r) -> Option<Status>; // access 阶段(可选)
}
装配层按声明顺序依次调用 → handler 顺序显式可控(这正是多 .so 方案里最难保证的一点)。
共享内存键前缀(现状已天然不冲突,直接沿用)
| 归属 | 前缀 |
|---|---|
| core | sess: fail: ukey: |
| plugin-sso | sso: oac: ocl: |
| plugin-domain | sub: |
| plugin-llm | up: rl: st: ust: ums: |
ukey:(API Key → 身份索引)归 core:Key 由 core 签发与吊销,索引就必须由 core 维护, 否则会出现「Key 已重置但旧索引还在」的窗口。
五、users.json:共用一份,core 独占读写
-
物理上只有一份
data/users.json;插件只读,写入一律经ipass_core::users -
Schema 取并集,所有新增字段
#[serde(default)],存量文件可直接接管:来源 字段 共用 usernamedisplay_namerolesaltpwd_hashapi_keyemaildepartmentgroupscreated_atSSO failed_countlocked_untiltotp_secrettotp_enabled域名 temp_grant_untilLLM allowed_modelsllm_rpmllm_daily -
groups用宽容反序列化(接受["rd","eng"]与"rd,eng"): 只认数组会让外部目录导出的users.json整体反序列化失败,表现为「账号全部消失」 -
Schema 版本与迁移逻辑由 core 负责;插件不得自行扩展
User字段, 需要扩展时在 core 里加#[serde(default)]字段
六、落地路径
| 阶段 | 内容 | 验收 |
|---|---|---|
| P0 | 建 workspace;config/models/store/state/session/users/audit 迁入 core;User 取并集 | run-local-e2e.sh 五套全绿 |
| P1 | 插件 trait + 路由注册表;sso 完成插件化;handler 顺序显式化 | 仅编 --features sso 与全量都能跑通 |
| P2 | 迁入 plugin-domain(从 refs/ipass 移植,去掉其重复的 oauth/users) |
域名 e2e 全绿 |
| — | ||
| P3 | (可选)确需独立发版时才做 C ABI bridge,按第三节三条纪律执行 | — |
七、遗留待定
- 仓库归属:当前在
ssw/sso仓库内改造,产品名已变为「iPass 统一网关」, 是否新建ssw/ipass仓库并迁移,由你定。 refs/ipass目前是带本地.git的存档副本(无 remote、不入本仓库版本控制), P2 移植时按「新代码为准、旧实现仅作参考」处理。
附:本次查证用到的源码位置
| 论断 | 位置 |
|---|---|
| zone tag 不同 → EMERG 启动失败 | src/core/ngx_cycle.c → ngx_shared_memory_add |
| 同名 + CHANGEABLE → 返回已有变量而非新建 | src/http/ngx_http_variables.c → ngx_http_add_variable |
sso 的 zone tag = &ngx_http_sso_module |
source/rust/src/lib.rs:451 |
ipass 的 zone tag = &ngx_http_ipass_module |
refs/ipass/rust/src/lib.rs:824 |
两边注册同名 $auth_* 且覆盖 get_handler |
source/rust/src/lib.rs:254-262、refs/ipass/rust/src/lib.rs:89 |
| 键前缀全景 | refs/ipass/rust/src/config.rs:66-101 |
| 代码重复量(oauth 425 / users 525 / models 234 / state 150 行差异) | 两仓库同名文件 diff |