docs: 插件化架构分析与迁移/任务文档,同步 CLAUDE.md 与路线图

新增
  docs/plugin-architecture-analysis.md  内核/插件边界分析、P 阶段拆分与装配契约
  docs/maxkey-migration-analysis.md     MaxKey 端点别名与 context-path 归一化对齐
  docs/task-plan.md                     阶段任务清单与验收口径

同步
  CLAUDE.md    crate 清单与目录地图:plugin-domain 标为「已迁入示例」,
               plugin-llm 明确「不迁入」(LLM 上游代理与配额计费属流量层,
               与本服务「身份层」的定位分界不变,半成品已从 workspace 移除);
               回归口径五套 → 六套;测试配置端口范围 18093-18099
  README.md    结构树补 plugin-domain,端口范围同步
  roadmap.md   P2 标记为已完成(部分)并写明 plugin-llm 不迁入的理由
This commit is contained in:
ssw committed 2026-09-13 10:25:48 +08:00
1 parent 8be8580ba9
commit 8e9becaad7
6 files changed
+497 -42

No files matched your search

+57 -23
View File
@@ -5,18 +5,28 @@
## 一句话定位
**统一认证服务(SSO)**:nginx 动态模块(`ngx-rust`)+ Rust,单进程,无数据库 / Redis / MQ。
**iPass 统一网关**的身份能力:nginx 动态模块(`ngx-rust`)+ Rust,单进程,无数据库 / Redis / MQ。
代码形态是**内核 + 插件**(编译期装配,产出**单个** `.so`):
- **IdP**:OAuth2.0 / OIDC 授权服务器 —— 发 token、登录、introspect、discovery。
- **IAP**:nginx `access` 阶段门禁,把身份以 `X-Auth-*` 注入后端,业务系统零改造。
- **协议对齐 MaxKey**:端点别名 + 扁平响应,照抄 MaxKey 文档的应用可直接对接。
| crate | 职责 |
| --- | --- |
| `ipass-core` | **内核**:共享内存状态、`users.json` 与 API Key 的**唯一读写者**、账号模型、插件契约 |
| `plugin-sso` | **身份插件**:OAuth2.0 / OIDC 授权服务器 + IAP 身份注入 |
| `plugin-domain` | **域名插件**(已迁入):企业域名「子域名 → 后端」转发 + 申请/审核。**同时是「在 `ipass-core` 之上新增一个能力插件」的完整示例** |
| ~~`plugin-llm`~~ | **不迁入**:LLM 上游代理与配额计费属于流量层,与本服务“身份层”的定位分界不变(见文末) |
| `gateway` | **装配层**:module 壳 + 插件注册表 → `libsso_gateway.so` |
判据:**去掉 SSO,网关还能不能转域名、还能不能代理 LLM?** 能 → 那它就不是内核。
所以内核是 `ipass-core`,身份只是插件之一。
状态 = `data/` 下两个 JSON(`users.json` / `oauth_clients.json`);
**客户端注册表与会话常驻共享内存,热路径零文件 I/O**。
> **定位差异(不要越界)**:本项目**不做**动态域名转发、LLM 上游代理、用量计费。
> 代码由内部网关项目剥离而来(`refs/ipass`,仅本地参考、不入库)。
> 因此这里没有 `$proxy_backend_addr` 这类动态上游变量,`proxy_pass` 由 nginx 配置写死。
> **为什么是单 .so,而不是「nginx 本来支持的多模块」**
> nginx 动态模块没有稳定 ABI,Rust 侧更没有(每个 cdylib 各链一份 `std`,跨模块传
> `String` 就是双重 free)。拆开必撞两个坑:① 共享内存 zone 的 tag 不同 → 启动即
> EMERG;② 同名变量(`auth_user` 等)被后加载者覆盖 get_handler → 行为取决于
> `load_module` 顺序。源码级论证见 `docs/plugin-architecture-analysis.md`。
---
@@ -57,14 +67,14 @@ cargo build --release
冷编译约 40 秒,增量 1~2 秒。
> `source/rust/build.rs` **不可删**:macOS 必须 `-undefined dynamic_lookup`——动态模块引用的
> `source/rust/gateway/build.rs` **不可删**:macOS 必须 `-undefined dynamic_lookup`——动态模块引用的
> nginx 运行时符号由主程序在 `load_module` 时提供,链接时必然未定义。
> `ngx` crate 的 build.rs 也设了,但 `rustc-link-arg` **只对设置它的 crate 生效**、不传给依赖方。
### 跑测试
```bash
bash scripts/run-local-e2e.sh # 三套 e2e 全跑(自动起停 nginx + demo 系统)
bash scripts/run-local-e2e.sh # 六套 e2e 全跑(自动起停 nginx + demo 系统)
bash scripts/run-local-e2e.sh --keep # 保留进程手工排查
```
@@ -72,27 +82,25 @@ bash scripts/run-local-e2e.sh --keep # 保留进程手工排查
## 目录地图(改代码前先看这里)
`source/rust/` 是 Cargo workspace(`cargo build` 在**根**跑,产物 `target/release/libsso_gateway.dylib`):
| 路径 | 职责 |
| --- | --- |
| `source/rust/src/lib.rs` | **模块入口**:指令解析、共享内存建表(`state_zone_init`,fork 前一次)、变量注册、两个阶段处理器(IAP access / API content)、`init_process` 播种 admin |
| `source/rust/src/api.rs` | **API 统一分发器**:路由表(精确匹配)+ 鉴权分流(`Guard::Public/User/Admin`)+ 全部 handler |
| `source/rust/src/oauth.rs` | **OAuth2 AS 全部逻辑**:client/code/token 模型、HS256 JWT 签名/验签、PKCE、端点 handler、IAP 身份解析 |
| `source/rust/src/oauth_clients.rs` | 接入方注册表(`reload_shm` / `get` / `all` / `upsert` / `delete` / `view`) |
| `source/rust/src/users.rs` | 账号:播种 admin、创建、改密、重置 Key、角色、部门/用户组校验 |
| `source/rust/src/session.rs` | 管理员登录会话(`sess:` 键 + HttpOnly Cookie,滑动续期) |
| `source/rust/src/state.rs` | 共享内存:根结构、键值编解码(栈上拼 key)、业务包装函数 |
| `source/rust/src/store.rs` | JSON 原子读写(`.tmp` + `rename`)+ 跨 worker 文件锁 + data 目录 |
| `source/rust/src/http.rs` | 请求辅助:参数合并、**两段式请求体读取**、JSON 响应输出 |
| `source/rust/src/util.rs` | 随机数、SHA-256、口令哈希、常量时间比较、时间格式化、日志 |
| `source/rust/src/config.rs` | **全部策略常量**:TTL、长度上限、共享内存键前缀、cookie 名 |
| `source/rust/src/models.rs` | `User` / `OAuthClient` 结构;`groups` 用宽容反序列化(同时接受 `["a"]` 与 `"a,b"`) |
| `gateway/src/lib.rs` | **装配层**:指令解析、共享内存建表(`state_zone_init`,fork 前一次)、`PLUGINS` 数组、API 的 content 阶段处理器与插件分发、`init_process` 播种 admin |
| `crates/ipass-core/src/*` | **内核**:`state`(通用共享内存原语)/ `store`(JSON 原子读写)/ `users`(账号与 Key 的唯一写入口)/ `models`(仅共性字段 + `extra` 透传)/ `config`(仅共性策略常量与键前缀)/ `session`(管理员会话)/ `audit` / `http` / `util` / `plugin`(契约)/ `loc`(location 开关)。**不含** OAuth / TOTP 等个性代码 |
| `crates/plugin-sso/src/*` | **身份插件**:`oauth`(OAuth2/OIDC 全部逻辑 + IAP 身份解析)/ `api`(路由表 + handler)/ `oauth_clients` / `oauth_keys`(OAuth/IAP 协议常量与共享内存键前缀,原属内核 `config`)/ `oauth_state`(OAuthClient 模型 + 注册表/授权码/会话状态,原属内核 `state`/`store`)/ `rsa`(手写 RS256)/ `captcha` / `otp`(TOTP 算法 + 账号侧 TOTP,数据存 `User.extra`) |
| `crates/plugin-domain/src/*` | **域名插件**:`keys`(`sub:` 前缀、企业域名 zone、子域名形状与 TTL 常量)/ `models`(`DomainEntry`)/ `domains`(校验、申请/审核/删除、写穿共享内存)/ `resolve`(access 阶段解析 Host → `$proxy_backend_addr`)/ `api`(8 条管理态 + 账号态路由)/ `lib`(`DomainPlugin` 装配) |
> `models.rs` 的 `User` 只含**共性字段**(凭据 / 身份声明 / 锁定);iPass 等插件的个性字段
> (`llm_*` / TOTP 种子等)一律走 `User.extra`(内核透传、不解释),因此内核不认识也能
> 直接接管任一边的存量 `users.json`,且插件加字段**不必改内核**。
其余:
| 路径 | 职责 |
| --- | --- |
| `source/conf/nginx.conf` | 生产模板:IdP + 管理台 443、IAP 子域、80→443、含 `auth_sub` 的日志格式 |
| `source/conf/nginx.test.conf` | 本机/CI 验证配置(明文 18095-18099),`scripts/run-local-e2e.sh` 会渲染它 |
| `source/conf/nginx.test.conf` | 本机/CI 验证配置(明文 18093-18099:18093/18094 为域名转发回显与转发口),`scripts/run-local-e2e.sh` 会渲染它 |
| `source/conf/tls/README.md` | 证书约定、acme.sh 签发、公钥比对校验(**ECC 不能用 `openssl rsa -modulus`**) |
| `source/www/admin.html` | 管理台单页(三个 tab:账号 / 接入方 / 接入指南),纯静态 + fetch |
| `source/data-seed/` | 种子模板(进版本库):`oauth_clients.json` + `users.json.example` |
@@ -240,7 +248,8 @@ curl -s -b 'sso_sid=<值>' http://127.0.0.1:18098/api/v1/me
## 边界:不要做的事
- **不要**引入数据库、Redis、消息队列或额外常驻进程 —— 本项目的价值就是单进程、零依赖。
- **不要**把流量层能力搬回来(动态域名转发、LLM 上游代理、用量计费)。这是与来源项目的**定位分界**。
- **LLM 上游代理与用量计费不搬回来**:那是流量层与计费层的职责,与本服务“身份层”的定位分界不变。
(动态域名转发已作为 `plugin-domain` **示例插件**引入:它侧重“如何在内核之上新增一个能力插件”,而非做量。)
- **不要**在 `source/data/` 里手工改文件后期待热生效 —— **共享内存才是运行期真源**,改文件需重启。
- **不要**把 `source/data/` 提交进版本库,也不要在 `refs/` 里提交参考项目。
- **不要**重写整个 `nginx.conf` —— 它很短,**逐点修改**。
@@ -248,3 +257,28 @@ curl -s -b 'sso_sid=<值>' http://127.0.0.1:18098/api/v1/me
- **不要**为了「顺手」把 HS256 换成 RS256(或反之):签名算法是给第三方的契约,
切换要走 `docs/roadmap.md` 里的 v2 计划(新旧并行 + `kid` 轮换)。
- 测试不要复用生产 data 目录:用 `source/data/` + 非特权端口(18095-18099),不要占用 80/443。
---
## 新增一个插件(checklist)
1. 建 crate:`crates/plugin-xxx`,`Cargo.toml` 里写 `ipass-core.workspace = true`,
并在根 `Cargo.toml` 的 `members` 里登记。
2. 实现 `ipass_core::plugin::Plugin`:
- `preconfig` —— 注册 nginx 变量(**两步缺一不可**:`ngx_http_add_variable` 登记
名字与 handler,`ngx_http_get_variable_index` 取写入槽位)
- `postconfig` —— 注册阶段处理器(`ngx::http::add_phase_handler::<T>`)
- `dispatch_api` —— 管理接口;**不归自己处理的路由必须返回 `None`**,否则会抢掉别人的接口
- `zone_load` —— fork 前的共享内存预装载(返回条数,仅用于日志)
3. 在 `gateway/src/lib.rs` 的 `PLUGINS` 数组里加一项——**数组顺序就是 handler 执行顺序**。
4. location 开关:在 `ipass_core::loc::Switch` 加枚举项,再改 gateway 的 `loc_switch`
与 `NGX_HTTP_SSO_COMMANDS`。
⚠️ 配置指令**只能手工列在 gateway**:`ngx_module_t.commands` 是 null-terminated
连续数组,不同 crate 的 static 数组无法自动拼接。
5. 需要给账号加字段 → 在 `ipass-core/src/models.rs` 加 `#[serde(default)]` 字段。
**纪律**(违反即失去「共用一份身份」的意义):
* 插件**不得**直接写 `data/users.json`,一律经 `ipass_core::users`;
* 插件不得自己实现口令校验 / Key 校验 / 锁定——那是内核的事;
* 插件之间不互相依赖,共享信息一律经内核状态表或 nginx 变量。
+20 -4
View File
@@ -1,4 +1,15 @@
# SSO —— 统一认证服务(nginx 动态模块 + Rust)
# iPass 统一网关 —— 身份插件(nginx 动态模块 + Rust)
> 本仓库是 **iPass 统一网关**的代码库,形态是**内核 + 插件**(编译期装配,产出单个 `.so`):
>
> | crate | 职责 |
> | --- | --- |
> | `ipass-core` | 内核:共享内存状态、`users.json` 与 API Key 的**唯一读写者** |
> | `plugin-sso` | 身份插件(本 README 的主体):OAuth2/OIDC + IAP |
> | `plugin-domain` | 域名插件:企业域名「子域名 → 后端」转发(新增能力插件的完整示例) |
>
> 判据:去掉 SSO,网关仍能转域名、仍能代理 LLM → 所以内核不是身份,**身份只是插件之一**。
> 架构论证见 `docs/plugin-architecture-analysis.md`。
自包含的 **OAuth2.0 / OIDC 身份提供者(IdP)** 与 **身份感知代理(IAP)**,
以 nginx 动态模块形式运行:加载进 nginx,不引入数据库、Redis、消息队列或任何额外常驻进程。
@@ -10,8 +21,9 @@
- **协议兼容 MaxKey**:提供 `/oauth/v20/*`、`/oauth2.0/*` 端点别名与 context-path 归一化,
照抄 MaxKey 文档的第三方应用不用改一行代码。
> **定位**:身份层,不是流量层。本服务**不做**动态域名转发、LLM 上游代理、用量计费。
> 代码由内部网关项目剥离而来(来源存档见 `refs/ipass`,不入版本库)。
> **身份与流量分离**:`plugin-sso` 只回答「你是谁」与「把这个身份告诉后端」。
> 动态域名转发、LLM 上游代理、用量计费属于**其它插件**(来源存档见 `refs/ipass`),
> 与身份插件共用同一份 `users.json`、同一把 API Key——由 `ipass-core` 统一读写。
---
@@ -74,9 +86,13 @@ sso/
│ └── screenshots/ 管理台与登录页截图
├── source/ 可部署产物(代码 + 配置 + 静态页)
│ ├── rust/ 动态模块源码(Cargo workspace,vendor 了 ngx-rust)
│ │ ├── crates/ipass-core/ 内核:状态 / 账号 / Key 的唯一读写者 / 插件契约
│ │ ├── crates/plugin-sso/ 身份插件:OAuth2 / OIDC + IAP
│ ├── crates/plugin-domain/ 域名插件:企业域名子域名转发(插件示例)
│ │ └── gateway/ 装配层:module 壳 + 插件注册表 → libsso_gateway.so
│ ├── conf/
│ │ ├── nginx.conf 生产模板(TLS、IAP 子域、日志字段)
│ │ ├── nginx.test.conf 本机/CI 验证配置(明文端口 18095-18099)
│ │ ├── nginx.test.conf 本机/CI 验证配置(明文端口 18093-18099)
│ │ └── tls/README.md 证书约定、acme.sh 签发与校验
│ ├── www/admin.html 管理台单页(纯静态 + fetch)
│ ├── data-seed/ 种子模板(进版本库)
+132
View File
@@ -0,0 +1,132 @@
# MaxKey 能力迁移分析(refs/maxkey → 本项目)
> 分析日期:2026-09-12
> 参照物:`refs/maxkey/`(dromara MaxKey,Java/Gradle,44 张表的完整 IAM/IDaas)
> 本体:本项目(nginx 动态模块 + Rust,OAuth2/OIDC IdP + IAP,文件+共享内存存储,零外部依赖约定)
## 结论(先看这里)
MaxKey 值得抄的不是"大而全",而是三类东西:**纯算法与协议语义**(直接可移植)、**域模型设计**(表结构即最佳实践文档)、**安全运营闭环**(锁定/审计/策略,本项目完全缺失)。按本项目的硬约束(无 DB、无 Redis、零新增依赖、"身份层不做流量层"),能力分四档:
| 档位 | 数量 | 判断标准 |
| --- | --- | --- |
| P0 建议迁移 | 7 项 | 纯逻辑可 Rust 重写,且补齐 IAP 安全短板 |
| P1 视需求迁移 | 5 项 | 有外部依赖或体积成本,先评估再动 |
| P2 低优先 | 5 项 | 有价值但当前定位用不上 |
| 不建议迁移 | 6 项 | 重度绑定 Java 生态,或与"身份层"定位冲突 |
---
## P0:建议迁移(纯逻辑,直接补短板)
1. **RS256 + JWKS 签发/验签** — 已在 roadmap v2 规划。
MaxKey 实证:`maxkey-commons/maxkey-crypto/`(JWS/JWE 签发验签、X509/keystore)。
抄它的点:JWKS 输出格式、`kid` 轮换语义(旧公钥保留至最后一批旧令牌过期)。
2. **登录失败锁定** — 本项目目前**无任何防爆破机制**,这是 IAP 场景最大安全缺口。
MaxKey 实证:`mxk_history_login` + 登录失败计数策略。移植成本极低:`users.json` 里加
`failed_count / locked_until` 字段,共享内存同步,无需新表。
3. **登录历史 / 审计日志** — MaxKey 用 `mxk_history_login` / `mxk_history_login_apps` /
`mxk_history_event` 三张分表。本项目可落成 append-only JSONL 文件(`data/audit/`),
记录:时间、用户、IP、UA、grant 类型、成功/失败。管理台加一个只读列表即可。
这是"真实流量看板"问题的 SSO 侧基础设施。
4. **密码策略** — MaxKey:`mxk_cnf_password_policy`(长度/复杂度/有效期/历史密码)。
本项目最小集:长度 ≥ 8 + 重置时强制改密 + 可选复杂度,配置进现有 `config.rs`。
纯校验逻辑,半天工作量。
5. **TOTP 双因子** — MaxKey:`maxkey-starter-otp/`(HOTP/TOTP 算法族)。
纯算法(RFC 6238,HMAC-SHA1 + 30s 步长),Rust 用已有 `sha2`+手写 HMAC 即可,
不新增依赖。用户侧字段:`totp_secret` + `totp_enabled`。注意配套要做**绑定流程**
(otpauth:// URI 展示)与登录时的第二因子校验分支。
6. **图形验证码** — MaxKey 用魔改 kaptcha(Java 生态绑定,不抄实现)。
本项目直接生成 **SVG 验证码**(数字/字母干扰线),零依赖可做,
挂在 `/oauth/authorize` 登录页与找回密码入口。
7. **在线会话管理 / 踢出** — MaxKey:`SessionController`(在线会话查看/踢出)。
本项目 session 已在共享内存(`session.rs`),天然支持:管理台列出活跃会话 +
单条踢出 + 全端下线。改动量小,运维价值高。
---
## P1:视需求迁移(先评估成本)
8. **SCIM 2.0 身份供给** — MaxKey:`maxkey-web-apis/maxkey-web-api-scim/`
(User/Group/EnterpriseUser/ServiceProviderConfig 完整资源模型)。
价值:外部系统(HR、上游 IdP)可用标准协议推送用户进来。资源模型清晰,
就是 CRUD,落 `users.json`/`groups` 现有模型可行;工作量主要在过滤语义
(`userName eq "..."`)与分页。**若确定有上游系统对接需求再做。**
9. **CAS 协议端点(v2/v3 validate)** — 延续 v1"照抄 MaxKey 文档接入方零改造"的思路,
补 `/cas/sso/validate`、`/p3/proxyValidate` 等端点,让 CAS 客户端也能直连。
票据校验是纯逻辑;但 CAS 生态在国内老系统里存量不小,值得排期。
10. **LDAP / AD 认证源** — MaxKey:`realm/ldap`(OpenLDAP/AD)。企业场景刚需,但
Rust 侧需要 LDAP 客户端库(`ldap3` 依赖体积不小,且需 vendor)。
替代路径:先用 P1-8 的 SCIM 或 P2-13 的同步连接器"拉取"而非"直连"。
11. **身份同步连接器(钉钉 / 企微 / 飞书 / AD)** — MaxKey:
`maxkey-synchronizers/maxkey-synchronizer-<name>/`。钉钉/企微/飞书三个就是
HTTP API 调用(分页拉用户+组织),交互协议可直接照抄;AD/LDAP 需 LDAP 库。
适合做成定时任务(本项目无后台进程,可用 nginx timer 或外部 cron curl 管理端点触发)。
12. **自助密码重置(邮箱/短信找回)** — MaxKey:`mxk_register` + 邮件/短信 provider
(阿里云/腾讯云/网易云信,`maxkey-starter-sms/`)。依赖外部发信通道;若做,
建议 provider 抽象成配置驱动的 HTTP 调用(与 AIMALL GenericHTTPTool 同思路)。
---
## P2:低优先(有价值,当前定位用不上)
13. **WebAuthn / Passkey** — MaxKey:`maxkey-starter/maxkey-starter-passkey/`
(含 `mxk_user_passkeys` 表)。方向正确但 Rust 零依赖下验签链很重
(COSE/CTAP2/attestation),且 RSA 大数运算本来就在 v2 才引入。等 v2 落地后再评估。
14. **社交登录 / 扫码登录** — MaxKey 基于 JustAuth + 自研 WeLink/飞书/企微 request。
本项目作为**企业内部身份层**,社交登录价值有限;若 souyi.net.cn C 端要用,另起服务。
15. **SAML 2.0** — MaxKey 重度绑定 OpenSAML。XML-DSig 签名在 Rust 零依赖下工作量
数倍于整个现有 oauth.rs。除非有明确 SAML SP 客户,否则不排期。
16. **FormBased / TokenBased / ExtendApi 协议** — 老式企业代填/票据协议。
TokenBased 的"票据换会话"语义可作为 IAP 票据机制参考;FormBased 代填不建议。
17. **ip2location 归属地解析** — MaxKey 内置登录 IP 归属地。审计日志做精致了再加。
---
## 不建议迁移(明确不做)
| 能力 | 理由 |
| --- | --- |
| Kerberos/SPNEGO、Ws-Federation | 重度绑定 JAAS/GSSAPI;IAP 场景可用 nginx 层方案替代 |
| Spring Cloud Gateway 网关(maxkey-gataway) | 本项目定位就是"身份层不做流量层",直接冲突 |
| 多租户(mxk_institutions) | 放大全链路复杂度,当前单租户足够 |
| 树形组织架构 | roadmap 已有明确"不做"决定,维持 |
| MyBatis/JPA 持久层、44 张表整体照搬 | 只抄域模型设计思路,不抄存储形态(本项目文件+共享内存) |
| kaptcha、管理台前端(maxkey-web-frontend) | Java/前端技术栈绑定,重写无参考价值 |
---
## 域模型参考(照抄设计而非表)
MaxKey 的 44 张表里,对本项目最有参考价值的三组设计:
- **应用-协议明细分离**:`mxk_apps` + `mxk_apps_oauth_client_details`/`saml_v20_details`/
`cas_details`/…。本项目现有 `oauth_clients.rs` 已是同构;未来若补 CAS/SCIM,
沿用"应用主表 + 协议明细"的形状,不要往应用主表里塞协议字段。
- **审计三分表**:登录历史 / 应用登录历史 / 事件,按时间append。对应 P0-3。
- **配置表与业务表分离**:`mxk_cnf_*`(密码策略、短信、邮件、LDAP 上下文)独立成表。
本项目对应物是 `config.rs`,未来配置项变多时按此分组,不要混进业务数据。
## MaxKey 源码证据索引
- 认证方式总入口:`maxkey-authentications/maxkey-authentication-provider/…/authn/provider/impl/`
- OAuth2/OIDC 端点:`maxkey-protocols/maxkey-protocol-oauth-2.0/…/endpoint/`(discovery 在 `wellknown/`)
- SCIM:`maxkey-web-apis/maxkey-web-api-scim/`
- 会话管理:`maxkey-webs/maxkey-web-mgt/…/web/access/controller/SessionController`
- 同步连接器:`maxkey-synchronizers/maxkey-synchronizer-{ad,ldap,jdbc,dingtalk,workwechat,feishu}/`
- OTP 算法:`maxkey-starter/maxkey-starter-otp/`
- 全量表结构:`sql/v4.2.0/maxkey.sql`
+187
View File
@@ -0,0 +1,187 @@
# 插件化架构: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
// 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
两边注册了**完全相同的五个变量**:
```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` 三重校验的桥接头。
## 四、定稿结构
```
source/rust/
├── Cargo.toml # [workspace] members = crates/* + gateway
├── vendor/ngx-rust/ # 保持(path 依赖,不可走 crates.io / git)
├── crates/
│ ├── ipass-core/ # 网关内核:唯一读写 users.json 的地方
│ │ └── src/{config,models,users,store,state,session,util,http,audit,plugin}.rs
│ ├── plugin-sso/ # 身份插件:OAuth2/OIDC + IAP 注入
│ │ └── src/{oauth,oauth_clients,rsa,otp,captcha,api}.rs
│ ├── plugin-domain/ # 动态域名(后续迁入)
│ └── plugin-llm/ # LLM 路由 / 配额(后续迁入)
└── gateway/ # 装配层:模块壳 + 插件注册表 → 单个 .so
└── src/lib.rs
```
### 插件契约
```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` | `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 |
+46 -15
View File
@@ -17,7 +17,7 @@
---
## [ ] v2:升级 RS256 签名 + `/oauth/jwks`,让第三方本地验签
## [x] v2:升级 RS256 签名 + `/oauth/jwks`,让第三方本地验签(2026-09-13 完成)
### 为什么
@@ -64,23 +64,26 @@
### 验收
- [ ] `GET /.well-known/jwks.json` 返回可用 JWKS,`n`/`e` 为 base64url;
- [ ] 用 JWKS 公钥在**不访问本服务**的前提下,本地验签通过 access_token 与 id_token;
- [ ] `alg` 传 `none` / 传 HS256 但用公钥当密钥 → 一律拒绝;
- [ ] 轮换后:新令牌带新 `kid`,旧令牌仍能验签直到过期;
- [ ] 现有三套 e2e 全绿(HS256 存量路径不回归);
- [ ] 新增一套 e2e:抓 JWKS → 本地验签 → 断言 `iss`/`aud`/`exp`。
- [x] `GET /.well-known/jwks.json` 返回可用 JWKS,`n`/`e` 为 base64url;
- [x] 用 JWKS 公钥在**不访问本服务**的前提下,本地验签通过 access_token 与 id_token(e2e 内嵌纯 Python `pow()` 验签);
- [x] `alg` 传 `none` / 传 HS256 但用公钥当密钥 → 一律拒绝;
- [x] 轮换模型落地(`kid` = 公钥 SHA-256 前 16 位 hex;`from_jwk` 容忍缺私钥分量,历史公钥仍可验);
- [x] 现有三套 e2e 全绿(HS256 存量路径不回归);
- [x] 新增一套 e2e(`tests/rs256-jwks-e2e.sh`:discovery→JWKS→签发→本地验签→篡改/伪造拒绝→introspect)。
### 注意
- **`iss` 一致性**是历史上最容易踩的坑:`OAUTH_ISSUER` 必须与浏览器实际访问的 host 一致。
第三方本地验签会把 `iss` 与 discovery 的 `issuer` 逐字符比对,不一致直接失败。
- **实现落点(2026-09-13)**:RSA 全手写(`src/rsa.rs`:Miller-Rabin、扩展欧几里得模逆、
Montgomery CIOS、CRT、PKCS#1 v1.5 EMSA),零新增 crates 依赖;私钥存
`OAUTH_JWK_DIR/active.jwk.json`(JWK 分量 JSON,非 PEM)。
- 私钥**绝对不进版本库**(`.gitignore` 放行规则要写对,别把 `jwks/` 加进白名单)。
- 不要返回空 JWKS:客户端会缓存住「无密钥」状态,问题排查时表现为「一直验签失败、日志无异常」。
---
## [ ] 用户管理界面:角色 / 部门 / 用户组的可视化维护
## [x] 用户管理界面:角色 / 部门 / 用户组的可视化维护(2026-09-13 完成)
### 为什么
@@ -102,6 +105,10 @@
### 做什么
0. **批量维护接口**(实现时新增):`POST /api/admin/users/batch`,
`usernames` + `add_groups` / `remove_groups` / `department` / `role` / `unlock` 任意组合,
单次文件锁内原子生效;批量降级同样受「至少保留一个管理员」红线约束;
不存在的账号只跳过(`skipped` 回显)不中断整批。
1. **账号表行内编辑**(或在侧滑面板里):
- `role`:下拉(`admin` / `user`);目标账号是最后一个管理员时**禁用降级**并给出原因,
与后端校验保持一致的文案,避免「点了才报错」。
@@ -119,13 +126,14 @@
### 验收
- [ ] 能给账号改角色、部门、用户组,刷新页面后仍在;
- [ ] 最后一个管理员无法被降级(前端禁用 + 后端兜底都生效);
- [ ] 非法输入(含控制字符 / 超长部门名 / 超组数上限)被拒且提示明确;
- [ ] 按角色 / 部门 / 用户组能筛出正确结果;
- [ ] 改完用户组后,经 IAP 访问后端拿到的 `X-Auth-Groups` 同步变化
(端到端验证:改组 → 带会话请求 demo 系统的 `/api/echo` → 断言头部);
- [ ] `admin.html` 内无内联 `onclick`,无未清理的全局状态(沿用 v1 的写法约定)。
- [x] 能给账号改角色、部门、用户组,刷新页面后仍在(角色下拉即改;部门/组点击就地编辑,Enter 保存);
- [x] 最后一个管理员无法被降级(前端 confirm + 失败回滚,后端红线兜底;含批量降级红线,e2e 断言);
- [x] 非法输入(含控制字符 / 超长部门名 / 超组数上限)被拒且提示明确(e2e 断言参数校验);
- [x] 按角色 / 部门 / 用户组(+ 关键字 / 只看已锁定)能筛出正确结果,头部提示「筛选出 n / m 个」;
- [x] 改组后新签令牌经 IAP 注入的 `X-Auth-Groups` 立即反映新组(e2e 断言);并固化语义:
**Bearer 注入是令牌签发时刻的 claims 快照**——改组不影响已签发的旧令牌(到期前),
下游要即时生效就让用户重登/重取令牌,或走 SSO 会话(cookie)路径(e2e 断言双口径);
- [x] `admin.html` 内无内联 `onclick`,无未清理的全局状态(沿用 v1 的写法约定)。
### 注意
@@ -146,3 +154,26 @@
且与本服务「身份层」的定位不符。确有需要时,让下游业务系统用 `X-Auth-Groups` 自己做映射。
- **不要把 OIDC 的 scope / claim 自定义能力做成界面配置**。claim 形状是第三方客户端的契约,
改动需要双方同步,属于「按需改代码」而不是「运营自助」。
---
## 插件化改造(2026-09-13)
架构定稿:内核是 **`ipass-core`**,**SSO 是插件之一**(与 `plugin-domain` / `plugin-llm` 平级);
`users.json` **全局共用一份,由内核独占读写**,插件只读不写。
- [x] workspace 拆分:`crates/ipass-core` + `crates/plugin-sso` + `gateway`,产出**单个** `.so`
- [x] 内核收口:`config`(仅共性)/ `models`(仅共性 + `extra` 透传)/ `store` / `state`(仅通用原语)/ `session` / `users` / `audit` / `http` / `util`(个性能力 TOTP 归 `plugin-sso` 的 `otp.rs`;OAuth 协议常量/键前缀归 `oauth_keys.rs`、OAuthClient 模型与注册表/授权码/会话状态归 `oauth_state.rs`,均原属内核 `config`/`state`/`store`)
- [x] `User` 共性字段 + `extra` 透传:iPass 等插件的个性字段(`llm_*` / `temp_grant_until` / TOTP 种子等)
经 `extra` 落盘,全部 `#[serde(default)]`;已验证 iPass 存量 `users.json` **无字段丢失**
- [x] 插件契约 `Plugin::{preconfig, postconfig, dispatch_api, zone_load}`;
装配顺序 = `gateway` 里 `PLUGINS` 数组的顺序,**显式可控**
- [x] 五套 e2e 全绿(rc=0),行为与重构前完全等价
- [x] 六套 e2e 全绿(rc=0),新增 `tests/domain-e2e.sh`(域名插件:鉴权 / 转发 / 申请审核 / 写穿生效)
- [x] P2(部分):迁入 `plugin-domain`(域名插件)作为“新增能力插件”的完整示例:crate + `sso_domain` 开关 + 编译装配 + 用例(`tests/domain-e2e.sh`,43 项)。
**`plugin-llm` 明确不迁入**:LLM 上游代理与配额计费属流量层,与本服务定位分界不变(已从 workspace 移除)。
- [ ] 仓库归属:是否新建 `ssw/ipass` 仓库(当前仍在 `ssw/sso`)
> 顺带的收益:iPass 与 SSO 原先各有一份 `oauth.rs`(差异 425 行)、`users.rs`(525 行)、
> `models.rs`(234 行),内核化后只保留一份。
> 架构论证(为什么不拆多 .so)见 `docs/plugin-architecture-analysis.md`。
+55
View File
@@ -0,0 +1,55 @@
# 任务计划:MaxKey 能力迁移落地(2026-09-12)✅ 已全部完成(2026-09-13)
> 依据:`docs/maxkey-migration-analysis.md`(P0×7)+ `docs/roadmap.md`(v2 + 用户管理界面)
> 保障手段:每项实现都带 e2e 断言;可借鉴的 MaxKey 测试用例逐项标注。
> 约束:零新增 crates.io 依赖(SHA-1、RSA、大数运算全部手写);存储沿用 users.json + 共享内存,不引入 DB。
## 执行顺序与验收
| # | 任务 | 落点 | 验收(e2e 断言) | 借鉴的 MaxKey 测试 |
| --- | --- | --- | --- | --- |
| ✅ 1 | 登录失败锁定(账号维度) | models/users/api/oauth/config | 连错 5 次锁定 600s;锁定期间密码正确也 423;到期自解锁;管理台可解锁 | mxk_history_login 失败计数语义 |
| ✅ 2 | 密码策略 | config/users | 短于 8 位拒;纯数字/纯字母拒;改密/建号/重置三入口一致 | mxk_cnf_password_policy 字段 |
| ✅ 3 | 审计日志 JSONL | 新模块 audit.rs + api | 登录成败/发令牌/管理操作都有行;管理台可查;>5MB 自动轮转 | mxk_history_login/event 三分表字段 |
| ✅ 4 | 在线会话查看/踢出 | state/api | sess:/sso: 均可列出(含过期过滤);按 token 或按用户踢;被踢会话立即 401 | SessionController 列表/踢出 |
| ✅ 5 | SVG 图形验证码 | 新模块 captcha.rs + oauth/api | 开关 `OAUTH_CAPTCHA=1` 时登录页出验证码、错码拒绝;缺省关(存量 e2e 不回归) | kaptcha 行为(不用其实现) |
| ✅ 6 | TOTP 双因子 | 新模块 otp.rs + users/api/oauth | RFC 4226/6238 标准向量通过;绑定→启用→登录必须带码;码错/缺失拒绝 | maxkey-starter-otp:HmacOTPTest / TimeBasedOTPTest(Base32 seed + 30s 步长 + 6 位截断) |
| ✅ 7 | RS256 + JWKS(roadmap v2) | 新模块 rsa.rs + oauth | JWKS 端点出 n/e(base64url);本地验签通过;alg=none / alg 混淆拒绝;HS256 存量可验;新 e2e 覆盖 | JWS/JWE 签发验签语义(maxkey-crypto) |
| ✅ 8 | 用户管理界面 | www/admin.html | 行内改角色/部门/组;筛选;批量加组;最后管理员禁用降级;组名逗号即时切分 | MaxKey 用户管理页交互 |
| ✅ 9 | 全量回归 + roadmap 更新 | tests/ + roadmap.md | 四套 e2e 全绿;roadmap 勾选 | — |
## 关键设计决定(偏离/补充说明)
- **验证码缺省关闭**(`OAUTH_CAPTCHA=1` 开启):验证码图形无法被 curl e2e 读取,
缺省开会让全部存量 e2e 失效;生产开启后,浏览器路径正常出码。
- **锁定是账号维度**(users.json 新字段 `failed_count`/`locked_until`),与既有
`fail:<ip>` IP 维度限速叠加;登录低频路径直接读文件,符合现有分层。
- **TOTP 的 HMAC-SHA1 手写**(sha2 crate 没有 SHA-1):RFC 6238 主流 authenticator
默认 SHA1/6 位/30s,必须兼容 Google Authenticator。
- **RSA 手写范围**:`modpow`(Knuth D 除法)+ Miller-Rabin 素性 + PKCS#1 v1.5 签名。
私钥存 `OAUTH_JWK_DIR/active.jwk.json`(分量的 base64url JSON,非 .pem——
手写 ASN.1/PEM 编解码收益低,roadmap 的 `.pem` 命名放宽,其余轮换语义照做)。
- **管理台密码策略例外**:种子管理员 `admin/123456` 不走 create 校验(历史行为),
但一旦重置即受新策略约束。
## 完成情况(2026-09-13 收尾)
- 9/9 全部完成;回归从「三套」扩为**五套**(`scripts/run-local-e2e.sh`,全绿 rc=0):
1. OAuth2/OIDC 基线;2. MaxKey 互通 + demo 接入;3. 管理接口·OAuth 接入方(31 项);
4. RS256 + JWKS 本地验签(14 项,含篡改 / alg=none / alg 混淆拒绝);
5. 管理接口·账号批量维护(39 项,新增)。
- RS256 内核为**手写零依赖 RSA-2048**(Miller-Rabin + 扩展欧几里得模逆 + Montgomery CIOS +
CRT + PKCS#1 v1.5),经独立二进制 × Python `pow()` 互证 3 轮随机密钥 roundtrip 全绿。
因 `cargo test` 链接 nginx 符号,单测走 `/tmp/*_standalone.rs` + rustc 方案。
- 批量维护新增 `POST /api/admin/users/batch`(单次文件锁内组合:加组/移组/设部门/改角色/解锁,
「至少保留一个管理员」红线在批量口径下同样生效)。
- 用户管理界面:筛选(关键字/角色/部门/组/已锁定)、勾选批量条、行内编辑
(角色下拉即改、部门/用户组点击就地编辑,Enter 保存 / Esc 取消 / 失焦提交)。
- 凭据治理:本地 e2e 口令与签名密钥统一进 `.env`(gitignore,模板 `.env.example`),
脚本经 `scripts/load-env.sh` 加载,命令行不再出现密钥。
### 遗留(不阻塞,属后续打磨)
- 用户组「标签输入」交互(当前为逗号分隔输入框,与 `check_groups` 分隔符约定一致,功能等价)。
- 统计卡点击下钻到筛选列表。
- 「最后一个管理员」在前端禁用降级选项(当前为 confirm + 后端红线兜底 + 失败回滚)。