- source/rust → rust/ - source/conf → conf/ - source/www → www/ - source/data-seed → data-seed/ - source/data → data/ - scripts/ 保留(语义不对应 ipass deploy/) - /build/ 加入 .gitignore(本机 nginx 源码树) - README.md 目录树同步 + build 路径 /tmp/sso-build → ./build - Cargo.toml path 依赖 '../../deps/ipass' → '../deps/ipass' - CLAUDE.md 同步路径示例 cargo check 通过(52s);release build 通过(1m26s),产物 libsso_gateway.dylib
196 lines
9.8 KiB
Markdown
196 lines
9.8 KiB
Markdown
# 插件化架构:iPass 统一网关(core + 插件)
|
||
|
||
> 问题:iPass 有「动态域名 + LLM 路由」,SSO 有「身份 / Key / OAuth」,
|
||
> nginx 本来就支持多模块——能不能做成插件模式,共用一个用户基础认证与 Key,其它由插件来做?
|
||
>
|
||
> **定稿(2026-09-13)**:
|
||
> 1. 内核是 **`ipass-core`(网关内核)**,**SSO 是其中一个插件**,与 `domain`、`llm` 平级。
|
||
> 身份不是内核——内核只回答「请求是谁、状态存哪、配置怎么装配」。
|
||
> 2. **`users.json` 全局共用一份,由 `ipass-core` 独占读写**,插件只读不写。
|
||
> 3. 插件是 **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 模块」,不是插件生态:
|
||
|
||
1. **模块必须与 nginx 二进制同源**。动态模块的 `ngx_module_t` 带 `version` /
|
||
`signature`(含 `NGX_MODULE_SIGNATURE` 一长串编译期特性位),不匹配直接拒绝加载。
|
||
2. **Rust 没有稳定 ABI**。每个 cdylib 静态链进自己的一份 `std`。跨 `.so` 传递
|
||
`Box` / `String` / `Vec` 意味着「A 的分配器分配、B 的分配器释放」→ 双重 free。
|
||
3. **加载顺序影响行为**(下一节有源码级证据)。
|
||
|
||
## 三、如果硬上多 .so,会踩的三个坑(已在 nginx 1.30.4 源码核对)
|
||
|
||
### 坑 1:共享内存 zone 的 tag 必须相同,否则启动即失败
|
||
|
||
`src/core/ngx_cycle.c`:
|
||
|
||
```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` 地址**:
|
||
|
||
```rust
|
||
// 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
|
||
|
||
两边注册了**完全相同的五个变量**:
|
||
|
||
```rust
|
||
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`**(不报错、不新建)。而两边注册后都做:
|
||
|
||
```rust
|
||
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/ipass` git 子模块(`ipass/ipass`)提供,不再内置。
|
||
|
||
```
|
||
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 路由 / 配额(已在子模块内)
|
||
```
|
||
|
||
### 插件契约
|
||
|
||
```rust
|
||
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)]`,存量文件可直接接管:
|
||
|
||
| 来源 | 字段 |
|
||
| --- | --- |
|
||
| 共用 | `username` `display_name` `role` `salt` `pwd_hash` `api_key` `email` `department` `groups` `created_at` |
|
||
| SSO | `failed_count` `locked_until` `totp_secret` `totp_enabled` |
|
||
| 域名 | `temp_grant_until` |
|
||
| LLM | `allowed_models` `llm_rpm` `llm_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 全绿 |
|
||
| ~~P2'~~ | ~~迁入 plugin-llm~~ —— **已决定不迁入**:LLM 上游代理与配额计费属流量层,与本服务定位分界不变(已从 workspace 移除) | — |
|
||
| 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` | `rust/src/lib.rs:451` |
|
||
| ipass 的 zone tag = `&ngx_http_ipass_module` | `refs/ipass/rust/src/lib.rs:824` |
|
||
| 两边注册同名 `$auth_*` 且覆盖 get_handler | `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 |
|