Files
ssw__ipass/docs/plugin/PLUGIN_ARCHITECTURE.md
T
admin db99ce1521 docs: 文档与注释系统性对齐插件化现状 + 清理前身实现引用
- readme §16 补 1.0.10-1.0.13 四条变更记录;§12.6 tag 表补 1.0.9-1.0.13
- readme §5 架构图更新为插件化结构(PLUGINS 注册表/四开关/四表)
- readme §11 补 api-proxies.json 数据模型小节;§8 管理台表格补 API 代理行
- readme/CLAUDE.md 测试断言数对齐 262(102+160);三个 JSON 改四个
- CLAUDE.md LLM 落点表改 crates/plugin-llm 路径;发版补 git push 前置教训
- 清理全部前身实现引用(readme 三处、CLAUDE.md 性能章节、util.rs 注释)
- PLUGIN_ARCHITECTURE.md 增补 1.0.13 sso 合流记录
2026-09-13 18:27:28 +08:00

222 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# iPass 插件化架构(as-built,2026-09-13 定型)
> 本文由《插件化改造方案》(PLUGINIZATION_PLAN.md)**转正**而来:改造已全部落地
> (P0–P4 提交序列 + P5 文档),行为完全等价——`data/*.json` 零变化、
> `conf/nginx.conf` 一条指令不改、262 项回归全绿(gateway 102 + llm 160)。
> 论证过程与现状量测数据见 git 历史(`74aeefe` 起 P0–P4 各提交)。
>
> 参照实现:`ssw/sso`(为什么不能拆多 `.so` 的论证见其
> `docs/plugin-architecture-analysis.md`)。**已拍板:`ssw/sso` 的 `plugin-sso`
> 不迁入 iPass**——iPass 的身份端点已由 `ipass-core` 收口,未来若与 sso 合流,
> 身份端点再从 `CorePlugin` 移交即可(`Switch` 并集与 trait 签名均已对齐)。
---
## 0. 一句话判据:什么进内核
> **去掉这个插件,网关还能不能跑?** 能 → 它不是内核。
| 能力 | 归属 | 理由 |
| --- | --- | --- |
| 共享内存唯一 zone / 文件写锁 | **core** | 只能有一份,多份就失去「热路径零文件 I/O」的意义 |
| `data/users.json` 读写、`ukey:` Key 索引 | **core** | 一处吊销处处生效;插件各写一份等于没共用 |
| 账号模型 `User` | **core** | 域名审批、LLM 配额、API 代理都挂在同一账号上 |
| 会话 / 登录失败锁定 | **core** | 与账号强绑定;且是**所有插件端点的公共前置** |
| 身份类 HTTP 端点(login/session/users/me) | **core**(`CorePlugin`) | 已拍板由 core 收口 |
| `sk_` Key 下行鉴权 + `rl:`/`st:` 配额 | **core**(`auth.rs`) | **两条下行链路(LLM + API 代理)共用** |
| 记账原语(窗口读数 / 日桶,无业务语义) | **core**(`usage.rs`) | 趋势数据 LLM 与 apix 共用;内核删账号钩子需要 |
| 动态域名映射与审批 | plugin-domain | 独立业务 |
| LLM 路由 / 上游 / 计量 / 审计 / 用量解读 | plugin-llm | 独立业务 |
| 外部 API 供应商资产代理 | plugin-apix | 独立业务 |
---
## 1. 目标结构(已落地)
```
rust/
├── Cargo.toml # [workspace](members + 统一依赖 + [profile.release])
├── vendor/ngx-rust/ # path 依赖(不可走 crates.io / git,见 Cargo.toml 注释)
├── crates/
│ ├── ipass-core/ # 内核:状态 / 账号 / 契约 / 身份端点 / 下行鉴权 / 记账原语
│ │ └── src/{lib,config,models,state,store,session,util,http,
│ │ users,auth,usage,plugin,loc,api}.rs
│ ├── plugin-domain/ # 动态域名:domains/resolve/api + sub: 键空间
│ │ └── src/{lib,config,models,store,domains,resolve,api}.rs
│ ├── plugin-llm/ # LLM:llm/upstreams/usage_filter/llm_audit/stats/handlers/api
│ │ └── src/{lib,config,models,store,llm,upstreams,usage_filter,llm_audit,stats,handlers,api}.rs
│ └── plugin-apix/ # API 代理:apix/handlers/api + ax: 键空间
│ └── src/{lib,config,models,store,apix,handlers,api}.rs
└── gateway/ # 唯一 cdylib:模块壳 + PLUGINS 注册表 + trend 组合端点
└── src/{lib,api}.rs
```
**关键不变式:仓库里只有一个 `cdylib`(gateway),产物仍是 `libipass_gateway.so`。**
插件一律 `crate-type = ["rlib"]`。理由(nginx 1.30.4 源码层面核对):共享内存 zone 的
tag 不同会在 `ngx_cycle.c` 直接 EMERG;同名变量会被后加载者劫持 `get_handler`;
Rust 无稳定 ABI,跨 `.so` 传 `String` 即双重 free。
`[profile.release]`(含 `panic="abort"`)**只能在 workspace 根**——member 里写会被
cargo 静默忽略,panic 丢了 abort 就可能跨 FFI 边界展开。
---
## 2. 契约层(内核与插件之间唯一的接口)
### 2.1 `Plugin` trait(`core/plugin.rs`)
```rust
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 / body filter
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 的指令数组是 null 结尾的连续数组,跨 crate 无法拼接。
7 条 `ipass_*` 指令由 gateway 集中声明——**指令解析归壳、行为归插件**。
* `dispatch_api` 语义:「不认领返回 `None`,让下一个插件试」,**绝不自行 404**;
404 由 gateway 在全部插件都返回 `None` 后统一发出。
* 另有 `core::plugin::{set_ctx_index, ctx_index}`:gateway 在 postconfiguration 开头把
自己的 `ctx_index` 注入内核,插件用它挂在 `r->ctx` 上挂请求级状态
(如 plugin-llm 的 usage_filter 扫描窗口)。未注入时插件**放弃**请求级状态,绝不越界写。
### 2.2 `loc::Switch`(`core/loc.rs`):取并集
```rust
pub enum Switch { Api, Iap, Domain, Proxy, Llm, Apix }
// iPass 用 Api/Proxy/Llm/Apix;Iap/Domain 为 sso 预留,恒 false
```
gateway 在 preconfiguration 注入查询实现(`set_switch_fn`),**未实现/未注入的变体一律
保守返回 `false`**——返回 `true` 会让未装配的能力意外开门(sso 踩过的坑)。
fn 指针按 usize 原子存取(access 热路径每请求都要查,不能用 Mutex)。
### 2.3 `CoreExt`(`core/api.rs`):身份端点的插件数据回填【方案落地时新增】
身份端点(`/api/admin/users`、`/api/v1/me`、删账号连带回收)天然需要插件侧数据
(域名数、LLM 用量、白名单校验),而内核不认识任何插件——直接引用会形成
core→plugin 循环依赖。解法是**扩展注册表**:
```rust
pub trait CoreExt: Sync {
fn decorate_admin_users(&self, views: &mut [Value]) {} // 账号列表装饰
fn decorate_me(&self, username: &str, view: &mut Value) {} // me 装饰
fn reclaim_on_delete(&self, username: &str) -> usize { 0 } // 删账号连带回收
fn validate_slots(&self, slots: &[String]) -> Result<(), String> { Ok(()) }
}
```
由 **gateway 作为装配根**实现(`GatewayExt`,组合 plugin-domain 与 plugin-llm 的数据),
preconfiguration 时 `set_ext(&GatewayExt)` 注入。这是方案对原设计的一处修正:
原方案把「删账号连带回收域名」塞在 on_delete 钩子里,落地时发现账号列表装饰/
me 装饰/白名单校验同样反向依赖插件数据,统一收进 CoreExt 更干净。
### 2.4 `users::on_delete` 钩子(`core/users.rs`)
删账号时内核只清自己的键(`ukey:`/`sess:`/`fail:`),插件键空间由插件注册清理器:
gateway 的 `state_zone_init` 里 `users::on_delete(plugin_llm::stats::forget)`。
内部按函数指针去重,nginx reload 重复执行安全。
---
## 3. 三个边界问题的最终解法
### ① core↔plugin 循环依赖 → `on_delete` 钩子 + `CoreExt` 注册表
内核删账号不认识 `ust:`/`ums:`;身份端点不认识域名数。方向一律是**插件 → 内核**,
反向数据流只能走 gateway 装配根回填(§2.3、§2.4)。
### ② apix 复用 llm 的鉴权/配额 → 下沉 `core/auth.rs`
`ukey:` 鉴权与 `rl:`/`st:` 配额是「去掉 llm 还要(apix 要)、去掉 apix 还要(llm 要)」
⇒ 共用 ⇒ 放内核:`downstream_key` / `identity` / `check_quota` / `fail`(OpenAI 兼容
错误体)。apix 与 llm 的 access handler 都调它,**无插件间依赖**。
### ③ 用量账本 → 原语进 core、解读进 plugin-llm、记账入口唯一
* `core/usage.rs`:`Usage`/`TokenUsage`/`DayBucket` 类型 + `bump/read/bump_t/read_t/
bump_day/day_bucket`——只认「前缀 + 名字 + 计数」,无业务语义。
* `plugin_llm::stats`:键前缀(`ust:`/`ums:`/`utt:`/`utms:`/`ud:`/`udu:`/`uds:`)与
`record`/`add_tokens`/`forget`/`trend`/`overview` 等解读。
* **apix 记账走 `plugin_llm::stats::record`**(slot 带 `api/` 前缀共用同一片键空间)——
这形成了 plugin-apix → plugin-llm 的依赖。刻意保留:账本写入口必须唯一,
两份写入口迟早漂移;方案原文设想的「record 下沉 core」会把 `ust:`/`ums:` 键名
语义带进内核,两害相权取其轻。
* **`/api/admin/trend` 留在 gateway**【方案落地时的第二处修正】:日桶键带日窗 id、
按前缀扫不出来,趋势接口需要 users + upstreams + apix **三方名册**——跨插件组合
逻辑属于装配根职责,不属于任何一个插件。
---
## 4. 装配清单(gateway = 装配根)
```rust
static PLUGINS: &[&dyn Plugin] = &[
&ipass_core::api::CorePlugin, // 身份端点必须先认领
&plugin_domain::DomainPlugin, // $proxy_backend_addr + ResolveHandler + sub:
&plugin_llm::LlmPlugin, // llm_* 三变量 + Llm/LlmHealth/Audit 三 handler + body filter + up:…uh:
&plugin_apix::ApixPlugin, // apix_* 六变量 + ApiProxyHandler + ax:
&GatewayRoutes, // 仅剩 /api/admin/trend(组合根)
];
```
gateway 保留:7 条指令解析(`ModuleConfig` 四开关 + `loc_switch` 注入)、
`ApiHandler`(content 阶段两段式读体后按 PLUGINS 顺序分发 + 统一 404)、
`state_zone_init`(users/llm/apix 三表装载 + on_delete 注册)、`init_process`
(播种 admin + plugin_llm 审计目录启动巡检)、`ipass_audit_dir` 指令
(转调 `plugin_llm::llm_audit::set_dir`)。
**新增一个插件 = 加一个 crate + 在 gateway 动 5 处**(见技能
`ipass-core-add-plugin`):`PLUGINS` 注册、`loc_switch`/`ModuleConfig`(如需新开关)、
指令数组(如需新指令)、zone 装载日志、Cargo 依赖。
---
## 5. 与 sso 参考实现的差异(有意偏离,最终版)
| # | sso 做法 | iPass 做法 | 原因 |
| --- | --- | --- | --- |
| 1 | `rl:` 配额归 plugin-llm | 归 **core** `auth.rs` | iPass 有 LLM + apix 两条共用配额的链路 |
| 2 | `stats` 整体在插件 | 拆:原语进 core `usage.rs`,解读进 plugin-llm | 内核删账号要摘用量索引 |
| 3 | 身份端点在 plugin-sso | 身份端点在 **core**(`CorePlugin` + `CoreExt`) | 已拍板;**plugin-sso 不迁入**(2026-09-13 拍板) |
| 4 | 指令 `sso_*` | 保持 `ipass_*` | conf 与测试零改动 |
| 5 | `Switch { Api, Iap, Domain, Llm }` | 并集 `{Api, Iap, Domain, Proxy, Llm, Apix}` | 契约点一次到位 |
| 6 | 无 | `users::on_delete` 钩子 + `CoreExt` 注册表 + `ctx_index` 注入 | 内核不认识插件的键空间与请求数据 |
| 7 | 无 trend 组合端点概念 | `/api/admin/trend` 留 gateway | 三方名册,装配根职责 |
| 8 | `libsso_gateway.dylib` | 仍是 `libipass_gateway.so` | Dockerfile 产物路径不变 |
---
## 6. 纪律(长期有效)
1. **热路径永不回源**:插件每请求决策只读共享内存;写操作必须先落文件、再写穿 shm,
写 shm 失败必须 `log_err`。逐插件核对 `sync_shm` 调用点,漏一处 = 「刚配好却 404」。
2. **插件绝不自行 404**:`dispatch_api` 不认领返回 `None`。
3. **`loc::Switch` 未实现变体保守 `false`**。
4. **`ngx` 走 `vendor/ngx-rust` path 依赖**;插件 rlib、gateway cdylib;
`[profile.release]` 只在 workspace 根。
5. **`data/*.json` 持久化格式零变化**:所有字段带 `#[serde(default)]`,改字段先想存量文件。
6. **验证 = `bash tests/run.sh all` 262 项全绿**;单 crate 迭代
`cargo build -p plugin-llm`(秒级)。
---
## 7. 已拍板(2026-09-13,最终)
- [x] 只做 iPass 自身插件化;**`ssw/sso` 的 `plugin-sso` 不迁入**(原「待拍板」项关闭;
若未来合流,身份端点从 `CorePlugin` 移交,trait/Switch 已对齐)
- [x] 身份端点由 `ipass-core` 收口,插件侧数据经 `CoreExt` 由 gateway 回填
- [x] 单 `.so` + crate 级插件;指令名与 `.so` 名不变
- [x] 下行鉴权/配额与记账原语下沉 core;用量解读归 plugin-llm;apix 记账走
`plugin_llm::stats`(单一写入口)
- [x] `/api/admin/trend` 留 gateway(组合根)
**1.0.13 增补(2026-09-13)**:sso 上游化建议 4 条已合入内核——`User.extra` flatten
(插件字段透传)+ `users::update_extra`、`state::split_value` 改 `rposition`、
`state::iter_prefix_ex`。逐条采纳/撤回理由见 `SSO_UPSTREAM_DECISIONS.md`;
契约(trait / Switch / CoreExt)不变。