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 承载能力目录" 不动代码,仅文档同步。
257 lines
15 KiB
Markdown
257 lines
15 KiB
Markdown
# 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)不变。
|