Files
ssw__ipass/docs/plugin/PLUGIN_ARCHITECTURE.md
admin dfbfe5cf6c docs(me+plugin): 登记 /api/v1/me 能力目录扩展点(1.0.16)
CLAUDE.md
- 「核心机制」补第 6 条:/api/v1/me 是插件装饰扩展点,不是写死端点;
  加新字段往 decorate_me 里塞,不要另开 v1 端点(避免老客户端脚本被破坏,
  也避免能力目录被拆成 N 个调用)
- 提示协作者给同事/文档/SDK 展示能力时直接讲 me

docs/plugin/PLUGIN_ARCHITECTURE.md
- §2.3 更新 decorate_me 签名为 (User, port)(1.0.16 引入):传 &User 让
  装饰零额外 shm 查询就能做权限收敛(upstreams 按 allowed_models 过滤);
  port 从 Host 头取(不写死是已知坑)
- 新增「decorate_me = 能力目录的承载点」子段:拍板决策 + 当前塞入字段表
  (domains / llm_usage / policy / upstreams / apix)+ 新增字段的纪律
- §6 纪律补第 7 条:能力目录走 decorate_me,不要另开 /api/v1/catalog
- §7 已拍板补 1.0.16 一条 "me 承载能力目录"

不动代码,仅文档同步。
2026-09-14 17:25:10 +08:00

257 lines
15 KiB
Markdown
Raw Permalink 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]) {} // 账号列表装饰
// 1.0.16 起:传 &User(不仅是 username),让装饰零额外 shm 查询就完成权限收敛
// ——upstreams 按 allowed_models 过滤就是靠这里拿白名单。
// port 从请求 Host 头取(http::host_port),让 view_all 能拼出正确的
// `https://lm.mayishangshu.cn:88/...` base_url(部署在 88 必须带端口,
// 443 反代又不能带,见 CLAUDE.md「`base_url` 端口必须自适应」)。
fn decorate_me(&self, _user: &User, _port: &str, _view: &mut Value) {}
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 更干净。
#### `decorate_me` = 能力目录的承载点(1.0.16 拍板)
`/api/v1/me` **不是写死的端点**,它的所有插件侧数据都来自 `decorate_me`。
拍板决策:**给同事展示能力(域名 / LLM 上游 / API 代理)时往 `decorate_me` 里塞,
不要另开 `/api/v1/catalog` 这类聚合端点**。原因:
- 老 3 个 v1 端点(`/api/v1/{domains,upstreams,apix}`)保留不破坏既有客户端脚本
- 一个 me = 身份 + 域名 + LLM 上游 + API 代理 + 用量 + 策略,同事拿一把 key 一个请求拿全
- 上游白名单过滤靠 `User.allowed_models` 在装饰里就地完成,**不用让客户端先拉 me 再拉
upstreams 自己过滤**
当前 GatewayExt 在 `decorate_me` 里塞的字段:
| 字段 | 来源 | 过滤/筛选 |
| --- | --- | --- |
| `domains` | `plugin_domain::domains::by_owner(user)` | 仅本人 |
| `llm_usage` | `plugin_llm::stats::user(name, now)` | 仅本人 |
| `policy` | core + plugin_domain config 常量 | — |
| `upstreams` | `plugin_llm::upstreams::view_all(&available(&user.allowed_models), port)` | **enabled + 白名单** |
| `apix` | `plugin_apix::apix::view_all(&enabled(), port)` | **仅 enabled** |
⚠️ **新增装饰字段时一律在 `view` 之前算好 `port`**,并明确标注「从 Host 头取、不写死」——
硬编码端口是已知坑(CLAUDE.md「`base_url` 端口必须自适应」实测踩过)。
### 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` 全绿**(**当前 281**:网关 102 + LLM 179);
单 crate 迭代 `cargo build -p plugin-llm`(秒级)。
7. **能力目录走 `decorate_me`,不要另开 `/api/v1/catalog`**。1.0.16 拍板:
同事拿 key 一个 me 拿全(域名 + LLM 上游 + API 代理 + 用量 + 策略),
老 3 个 v1 端点保留不破坏。新增插件侧能力展示字段一律往 `decorate_me` 里塞,
别再另开 v1 端点把能力目录拆成 N 个调用。
---
## 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(组合根)
- [x] **`/api/v1/me` 承载能力目录(1.0.16)**:网关通过 `decorate_me` 把 domains /
upstreams / apix 一次性塞进 me,老 3 个 v1 端点保留不破坏
**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)不变。