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 承载能力目录" 不动代码,仅文档同步。
15 KiB
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)
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):取并集
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 循环依赖。解法是扩展注册表:
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 = 装配根)
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. 纪律(长期有效)
- 热路径永不回源:插件每请求决策只读共享内存;写操作必须先落文件、再写穿 shm,
写 shm 失败必须
log_err。逐插件核对sync_shm调用点,漏一处 = 「刚配好却 404」。 - 插件绝不自行 404:
dispatch_api不认领返回None。 loc::Switch未实现变体保守false。ngx走vendor/ngx-rustpath 依赖;插件 rlib、gateway cdylib;[profile.release]只在 workspace 根。data/*.json持久化格式零变化:所有字段带#[serde(default)],改字段先想存量文件。- 验证 =
bash tests/run.sh all全绿(当前 281:网关 102 + LLM 179); 单 crate 迭代cargo build -p plugin-llm(秒级)。 - 能力目录走
decorate_me,不要另开/api/v1/catalog。1.0.16 拍板: 同事拿 key 一个 me 拿全(域名 + LLM 上游 + API 代理 + 用量 + 策略), 老 3 个 v1 端点保留不破坏。新增插件侧能力展示字段一律往decorate_me里塞, 别再另开 v1 端点把能力目录拆成 N 个调用。
7. 已拍板(2026-09-13,最终)
- 只做 iPass 自身插件化;
ssw/sso的plugin-sso不迁入(原「待拍板」项关闭; 若未来合流,身份端点从CorePlugin移交,trait/Switch 已对齐) - 身份端点由
ipass-core收口,插件侧数据经CoreExt由 gateway 回填 - 单
.so+ crate 级插件;指令名与.so名不变 - 下行鉴权/配额与记账原语下沉 core;用量解读归 plugin-llm;apix 记账走
plugin_llm::stats(单一写入口) /api/admin/trend留 gateway(组合根)/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)不变。