docs(plugin): P5 收尾 —— 方案转正 PLUGIN_ARCHITECTURE.md + 文档对齐 workspace
- docs/plugin/PLUGINIZATION_PLAN.md 转正为 PLUGIN_ARCHITECTURE.md(as-built): 记录三处方案修正(sso 不迁入已拍板、CoreExt 注册表、trend 留 gateway、 apix 记账走 plugin_llm::stats 单一写入口) - CLAUDE.md:目录地图改 workspace 结构 + 三条插件化新纪律 + 单 crate 迭代命令 - readme.md:§6 目录结构对齐(crate 划分 / apix 页 / 262 项回归) - 新增用户级技能 ipass-core-add-plugin(5 处装配缺一不可 + 症状→根因表)
This commit is contained in:
1 parent
85ea0a1531
commit
ddd4172517
4 files changed
+289
-569
No files matched your search
@@ -61,6 +61,8 @@ LIBCLANG_PATH=/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault
|
|||||||
cargo build
|
cargo build
|
||||||
```
|
```
|
||||||
实测:增量 1~2 秒,冷编译约 37 秒。产物 `target/debug/libipass_gateway.dylib`。
|
实测:增量 1~2 秒,冷编译约 37 秒。产物 `target/debug/libipass_gateway.dylib`。
|
||||||
|
workspace 化后可按 crate 迭代(秒级,不动 gateway):
|
||||||
|
`cargo build -p plugin-llm` / `-p ipass-core` / `-p plugin-apix` / `-p plugin-domain`。
|
||||||
|
|
||||||
> 注意:上表的 configure **关掉了 rewrite 模块**,所以本机测试配置里**不能用 `set` / `return`**。
|
> 注意:上表的 configure **关掉了 rewrite 模块**,所以本机测试配置里**不能用 `set` / `return`**。
|
||||||
> 生产 `Dockerfile` 的 configure 带 rewrite 模块(未 `--without`),`conf/nginx.conf` 可正常使用它们。
|
> 生产 `Dockerfile` 的 configure 带 rewrite 模块(未 `--without`),`conf/nginx.conf` 可正常使用它们。
|
||||||
@@ -81,38 +83,73 @@ macOS 必须 `-undefined dynamic_lookup`:动态模块的 nginx 运行时符号
|
|||||||
|
|
||||||
## 目录地图(改代码前先看这里)
|
## 目录地图(改代码前先看这里)
|
||||||
|
|
||||||
Rust 模块在 `rust/src/` —— **一个文件对应旧版一个 `lua/*.lua`,职责边界刻意保持一致**,方便对着归档对照:
|
**2026-09-13 起插件化**:单 crate 拆为 workspace——`ipass-core`(内核)+ 三个插件
|
||||||
|
crate + `gateway`(唯一 cdylib)。契约与边界见 `docs/plugin/PLUGIN_ARCHITECTURE.md`;
|
||||||
|
**给内核加插件**用技能 `ipass-core-add-plugin`。产物名、指令名、conf、`data/*.json`
|
||||||
|
全部不变。
|
||||||
|
|
||||||
| 路径 | 职责 | 旧版对应 |
|
```
|
||||||
|
rust/
|
||||||
|
├── Cargo.toml # workspace 根:members + [workspace.dependencies] + [profile.release]
|
||||||
|
├── vendor/ngx-rust/ # vendored ngx-rust(path 依赖,别换 crates.io/git)
|
||||||
|
├── crates/ipass-core/ # 内核:能单独跑网关的部分
|
||||||
|
├── crates/plugin-domain/ # 域名插件(sub: 键空间)
|
||||||
|
├── crates/plugin-llm/ # LLM 插件(up:/ust:/ums:/ud:… 键空间)
|
||||||
|
├── crates/plugin-apix/ # API 代理插件(ax: 键空间)
|
||||||
|
└── gateway/ # 装配根 + 唯一 cdylib(模块壳 + PLUGINS 注册表 + trend)
|
||||||
|
```
|
||||||
|
|
||||||
|
`ipass-core` 内部模块:
|
||||||
|
|
||||||
|
| 模块 | 职责 |
|
||||||
|
| --- | --- |
|
||||||
|
| `state.rs` | 共享内存:根结构、键值编解码(栈上拼 key)、业务包装函数 |
|
||||||
|
| `store.rs` | JSON 原子读写(`.tmp` + `rename`)+ 跨 worker 文件锁 + data 目录(插件数据文件走 `path_in_data` 自管) |
|
||||||
|
| `users.rs` | 账号唯一写入口:播种 admin、`ukey:` 索引写穿、`on_delete` 钩子注册表 |
|
||||||
|
| `session.rs` | 管理员登录会话(`sess:` 键 + HttpOnly Cookie,滑动续期) |
|
||||||
|
| `auth.rs` | **下行链路共用契约**:`downstream_key` / `identity`(查 `ukey:`)/ `check_quota`(`rl:`+`st:`,先增后判)/ OpenAI 兼容错误体——LLM 与 apix 两个 access handler 都调它 |
|
||||||
|
| `usage.rs` | **记账原语**(无业务语义):窗口读数 + 日桶的 bump/read,键前缀由调用方传 |
|
||||||
|
| `plugin.rs` | `Plugin` trait + `ctx_index` 注入(插件在 `r->ctx` 挂请求级状态用) |
|
||||||
|
| `loc.rs` | `Switch` 并集 + 注入式 location 开关查询(未实现变体保守 false) |
|
||||||
|
| `api.rs` | 身份类端点(login/logout/session/users/me)+ `Guard/Actor/run_guarded` 守卫 + `CoreExt` 扩展注册表(gateway 回填插件数据) |
|
||||||
|
| `config.rs` | 内核策略常量 + `sess:/fail:/ukey:/rl:/st:` 前缀;插件自有常量在各自 crate |
|
||||||
|
| `http.rs` / `util.rs` | 请求辅助(两段式读体、JSON 响应)/ 随机数、SHA-256、口令哈希、日志 |
|
||||||
|
|
||||||
|
三个插件的模块布局(均为 rlib,只有 gateway 是 cdylib):
|
||||||
|
|
||||||
|
| crate | 模块 | 键空间 |
|
||||||
| --- | --- | --- |
|
| --- | --- | --- |
|
||||||
| `rust/src/lib.rs` | **模块入口**:指令解析、共享内存建表与装载(`state_zone_init`,fork 前一次)、变量注册、三个阶段处理器(转发 access / LLM access / API content)、`init_process` 播种 admin | `conf/nginx.conf` 的 init 段 + `proxy.lua` |
|
| `plugin-domain` | `domains`(申请/审批/写穿)、`resolve`(ResolveHandler + `$proxy_backend_addr`)、`api`、`config/models/store` | `sub:` |
|
||||||
| `rust/src/api.rs` | **API 统一分发器**:路由表(精确匹配)+ 鉴权分流(`Guard::Public/User/Admin`)+ 全部 handler | `api.lua` |
|
| `plugin-llm` | `llm`(slot 解析/变量求值)、`upstreams`(CRUD/写穿/健康)、`usage_filter`(body filter 抓 usage,走 `loc::enabled`+`ctx_index`)、`llm_audit`(对话审计落盘)、`stats`(用量账本+趋势)、`handlers`(Llm/LlmHealth/Audit)、`api`、`config/models/store` | `up:` `uh:` `ust:` `ums:` `utt:` `utms:` `ud:` `udu:` `uds:` |
|
||||||
| `rust/src/users.rs` | 账号:播种 admin、创建、改密、重置 Key、授予/撤销临时授权、`ukey:` 索引写穿 | `users.lua` |
|
| `plugin-apix` | `apix`(slug/拼体/写穿)、`handlers`(ApiProxyHandler)、`api`、`config/models/store` | `ax:` |
|
||||||
| `rust/src/domains.rs` | 域名:申请(含免审判定)、审核、过期判定、`sub:` 写穿、清理 | `domains.lua` |
|
|
||||||
| `rust/src/upstreams.rs` | LLM 上游校验/读写/写穿——`domains.rs` 在 LLM 侧的翻版 | (新增) |
|
gateway 只剩:模块壳(7 条指令 + `ModuleConfig` 开关 + 变量/装载装配循环)、
|
||||||
| `rust/src/session.rs` | 管理员登录会话(`sess:` 键 + HttpOnly Cookie,滑动续期) | `session.lua` |
|
`ApiHandler`(读体后按 PLUGINS 顺序分发、统一 404)、`/api/admin/trend`
|
||||||
| `rust/src/state.rs` | 共享内存:根结构、键值编解码(栈上拼 key)、业务包装函数 | (新增) |
|
(需 users+upstreams+apix 三方名册,属组合根)。
|
||||||
| `rust/src/store.rs` | JSON 原子读写(`.tmp` + `rename`)+ 跨 worker 文件锁 + data 目录 | `store.lua` |
|
|
||||||
| `rust/src/http.rs` | 请求辅助:参数合并、**两段式请求体读取**、JSON 响应输出 | `util.lua`(前者) |
|
|
||||||
| `rust/src/util.rs` | 随机数、SHA-256、口令哈希、常量时间比较、时间格式化、日志 | `util.lua`(后者) |
|
|
||||||
| `rust/src/config.rs` | **全部策略常量**:TTL、保留名、长度上限、共享内存键前缀 | `config.lua` |
|
|
||||||
| `rust/src/models.rs` | `User` / `DomainEntry` 结构与派生判定(`effective_status` / `is_forwardable`) | (散在 Lua 里) |
|
|
||||||
| `rust/src/llm.rs` | LLM 热路径:slot 解析、Bearer 提取、身份查询、上游变量求值 | (新增) |
|
|
||||||
| `rust/vendor/ngx-rust/` | **vendored 的 ngx-rust**(见「构建与依赖」)。**不要**换成 crates.io 或 git 依赖 | — |
|
|
||||||
|
|
||||||
其余:
|
其余:
|
||||||
|
|
||||||
| 路径 | 职责 |
|
| 路径 | 职责 |
|
||||||
| --- | --- |
|
| --- | --- |
|
||||||
| `conf/nginx.conf` | 转发 server、LLM server、管理 server、默认 403 server;`ipass_state` / `ipass_data_dir` / 三个 `subdomain_*` 开关 |
|
| `conf/nginx.conf` | 转发 server、LLM server、管理 server、默认 403 server;`ipass_state` / `ipass_data_dir` / 三个 `subdomain_*` 开关 |
|
||||||
| `www/` | 管理台(多页,纯静态 + fetch):`login.html` + `overview/review/domains/users/upstreams/usage.html` + `assets/`(共享 CSS/JS/图表)。每页 `<base href="/admin/">`,见「管理台多页」 |
|
| `www/` | 管理台(多页,纯静态 + fetch):`login.html` + `overview/review/domains/users/upstreams/usage/apix.html` + `assets/`(共享 CSS/JS/图表)。每页 `<base href="/admin/">`,见「管理台多页」 |
|
||||||
| `data/users.json` | 账号表(含口令哈希与 API Key) |
|
| `data/users.json` | 账号表(含口令哈希与 API Key) |
|
||||||
| `data/domains.json` | 子域名映射表 + 申请记录 |
|
| `data/domains.json` | 子域名映射表 + 申请记录 |
|
||||||
| `data/llm-upstreams.json` | LLM 上游表(**含真实厂商密钥**) |
|
| `data/llm-upstreams.json` | LLM 上游表(**含真实厂商密钥**) |
|
||||||
|
| `data/api-proxies.json` | API 代理表(**含真实供应商密钥**) |
|
||||||
| `logs/access.log` | 已扩展字段:`backend=$proxy_backend_addr` |
|
| `logs/access.log` | 已扩展字段:`backend=$proxy_backend_addr` |
|
||||||
| `tests/` | **本机回归夹具**(`bash tests/run.sh [gateway\|llm\|all]`):`*.conf.in` 模板 + 断言脚本 + LLM 假上游;`tests/.run/` 是运行目录,已 gitignore。详见「本机验证夹具」 |
|
| `tests/` | **本机回归夹具**(`bash tests/run.sh [gateway\|llm\|all]`):`*.conf.in` 模板 + 断言脚本 + LLM 假上游;`tests/.run/` 是运行目录,已 gitignore。详见「本机验证夹具」 |
|
||||||
|
| `docs/plugin/PLUGIN_ARCHITECTURE.md` | **插件化架构(as-built)**:契约、边界解法、装配清单、与 sso 的差异 |
|
||||||
| `archive/openresty-lua-20260910/` | 旧 Lua 版归档,**只读参考,勿再修改** |
|
| `archive/openresty-lua-20260910/` | 旧 Lua 版归档,**只读参考,勿再修改** |
|
||||||
|
|
||||||
|
**插件化后的三条新纪律**(完整版见 `docs/plugin/PLUGIN_ARCHITECTURE.md` §6):
|
||||||
|
|
||||||
|
1. **插件绝不自行 404**:`dispatch_api` 不认领返回 `None`,404 由 gateway 统一发。
|
||||||
|
2. **插件不认识 gateway**:location 开关查 `loc::enabled(r, Switch::X)`,
|
||||||
|
请求级状态挂 `core::plugin::ctx_index()` 定位的 `r->ctx` 槽——别引用 gateway 私有类型。
|
||||||
|
3. **插件数据反向流只走装配根**:身份端点需要的插件数据经 `CoreExt` 由 gateway 回填;
|
||||||
|
删账号清理经 `users::on_delete` 钩子注册;**别在内核里 import 插件**。
|
||||||
|
|
||||||
容器内路径:模块装在 `/usr/local/nginx/modules/`;data 默认 `/usr/local/nginx/data`(`ipass_data_dir` 可覆盖)
|
容器内路径:模块装在 `/usr/local/nginx/modules/`;data 默认 `/usr/local/nginx/data`(`ipass_data_dir` 可覆盖)
|
||||||
——**这是容器内路径,不要在宿主机上按它找文件**(compose 把它挂到宿主 `./data`)。
|
——**这是容器内路径,不要在宿主机上按它找文件**(compose 把它挂到宿主 `./data`)。
|
||||||
|
|
||||||
|
|||||||
@@ -1,528 +0,0 @@
|
|||||||
# iPass 插件化改造方案(core + 编译期插件)
|
|
||||||
|
|
||||||
> 参照实现:`ssw/sso`(`[email protected]:13300/ssw/sso.git`)——它是从本项目衍生的插件式版本,
|
|
||||||
> 已跑通「内核 + 插件 + 单 `.so` 装配」并留有两份可直接复用的文档:
|
|
||||||
> `docs/plugin-architecture-analysis.md`(为什么不拆多 `.so`)与
|
|
||||||
> `.workbuddy/skills/ipass-core-add-plugin/SKILL.md`(怎么加一个插件)。
|
|
||||||
>
|
|
||||||
> **本方案只做 iPass 自身的插件化**(已拍板):与 `ssw/sso` 的仓库归属、身份插件是否并入,
|
|
||||||
> 留到 P5 再定。**身份端点(登录 / 会话 / 账号管理)由 `ipass-core` 直接收口**(已拍板)。
|
|
||||||
>
|
|
||||||
> 目标:**行为完全等价**重构——`data/*.json` 一个字节不改、`conf/nginx.conf` 一条指令不改、
|
|
||||||
> 现有 262 项回归全绿;换来的是「加一个能力 = 加一个 crate + 在 gateway 加 5 处装配」。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 0. 一句话判据:什么进内核
|
|
||||||
|
|
||||||
> **去掉这个插件,网关还能不能跑?** 能 → 它不是内核。
|
|
||||||
|
|
||||||
推论:
|
|
||||||
|
|
||||||
| 能力 | 归属 | 理由 |
|
|
||||||
| --- | --- | --- |
|
|
||||||
| 共享内存唯一 zone / 文件写锁 | **core** | 只能有一份,多份就失去「热路径零文件 I/O」的意义 |
|
|
||||||
| `data/users.json` 读写、`ukey:` Key 索引 | **core** | 一处吊销处处生效;插件各写一份等于没共用 |
|
|
||||||
| 账号模型 `User` | **core** | 域名审批、LLM 配额、API 代理都要挂在同一账号上 |
|
|
||||||
| 会话 / 登录失败锁定 | **core** | 与账号强绑定;且是**所有插件端点的公共前置** |
|
|
||||||
| 身份类 HTTP 端点(`/api/admin/login`、`/api/admin/users*`、`/api/v1/me`) | **core** | 同上;已拍板由 core 收口 |
|
|
||||||
| `sk_` Key 下行鉴权 + `rl:` 配额 | **core** | **两条下行链路(LLM + API 代理)共用**,见 §4② |
|
|
||||||
| 动态域名映射与审批 | plugin-domain | 独立业务 |
|
|
||||||
| LLM 路由 / 上游 / 配额计费 / 对话审计 / 用量趋势 | plugin-llm | 独立业务 |
|
|
||||||
| 外部 API 供应商资产代理 | plugin-apix | 独立业务 |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 1. 现状量测(改造前)
|
|
||||||
|
|
||||||
```
|
|
||||||
rust/ 单 crate,7035 行,产出 libipass_gateway.so
|
|
||||||
├── Cargo.toml [package] ipass-gateway v2.0.0
|
|
||||||
│ [lib] crate-type = ["cdylib","rlib"] ← 必须留 cdylib(nginx 要)
|
|
||||||
├── build.rs
|
|
||||||
├── vendor/ngx-rust/ path 依赖(不可走 crates.io / git,见 Cargo.toml 注释)
|
|
||||||
└── src/ 17 个模块
|
|
||||||
```
|
|
||||||
|
|
||||||
| 文件 | 行 | 依赖(`use crate::`) |
|
|
||||||
| --- | --- | --- |
|
|
||||||
| `config.rs` | 232 | — |
|
|
||||||
| `models.rs` | 219 | — |
|
|
||||||
| `state.rs` | 362 | config |
|
|
||||||
| `store.rs` | 196 | config models state |
|
|
||||||
| `session.rs` | 57 | config state util |
|
|
||||||
| `util.rs` | 354 | config |
|
|
||||||
| `http.rs` | 223 | util |
|
|
||||||
| `users.rs` | 405 | config models state **stats** store util |
|
|
||||||
| `domains.rs` | 485 | config models state store util |
|
|
||||||
| `upstreams.rs` | 397 | config models state store util |
|
|
||||||
| `llm.rs` | 442 | config state upstreams util |
|
|
||||||
| `llm_usage.rs` | 275 | — |
|
|
||||||
| `llm_audit.rs` | 200 | config store util |
|
|
||||||
| `stats.rs` | 585 | config state util |
|
|
||||||
| `apix.rs` | 563 | config http models state store util |
|
|
||||||
| `api.rs` | 1018 | **除 lib 外全部**(apix config domains http models session state stats upstreams users util) |
|
|
||||||
| `lib.rs` | 1022 | 模块壳:7 条指令 + 6 个 phase handler + 10 个变量注册 |
|
|
||||||
|
|
||||||
**三条热路径 + 一条管理通道**(全部注册在 `lib.rs`,靠 location 开关收敛):
|
|
||||||
|
|
||||||
| 入口 | 阶段 | 开关 | handler | 现状落点 |
|
|
||||||
| --- | --- | --- | --- | --- |
|
|
||||||
| `*dm.<zone>/*` | access | `ipass_proxy` | `ResolveHandler` | `lib.rs` + `domains.rs` |
|
|
||||||
| `lm.<zone>/<slot>/*` | access | `ipass_llm` | `LlmHandler` | `lib.rs` + `llm.rs` |
|
|
||||||
| `lm.<zone>/apix/<slug>` | access | `ipass_apix` | `ApiProxyHandler` | `lib.rs:323` + `apix.rs` |
|
|
||||||
| `mdm.<zone>/api/*` | content | `ipass_api` | `ApiHandler` | `lib.rs` + `api.rs` |
|
|
||||||
|
|
||||||
另有 log 阶段两个旁路 handler:`LlmHealthHandler`(上游健康标记)、`AuditHandler`(对话审计 +
|
|
||||||
token 计量);以及 `llm_usage::install()`(body filter 抓上游响应里的 usage)。
|
|
||||||
|
|
||||||
**共享内存键前缀全景**(`config.rs:78-166`)——已天然按域分片,是插件划分的现成依据:
|
|
||||||
|
|
||||||
| 前缀 | 归属 | 含义 |
|
|
||||||
| --- | --- | --- |
|
|
||||||
| `sess:` `fail:` `ukey:` | **core** | 会话 / 登录失败计数 / Key→身份索引 |
|
|
||||||
| `rl:` | **core**(本方案调整,见 §4②) | 配额窗口 |
|
|
||||||
| `sub:` | plugin-domain | 子域名 → 后端 |
|
|
||||||
| `up:` `st:` `ust:` `ums:` `utt:` `utms:` `ud:` `udu:` `uds:` `uh:` | plugin-llm | 上游 / 上游状态 / 用量账本 / 趋势日桶 / 健康标记 |
|
|
||||||
| `ax:` | plugin-apix | 代理 slug → 供应商资产 |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 2. 目标结构
|
|
||||||
|
|
||||||
```
|
|
||||||
rust/
|
|
||||||
├── Cargo.toml # [workspace](成员 + 统一依赖 + [profile.release])
|
|
||||||
├── vendor/ngx-rust/ # 保持不动(path 依赖)
|
|
||||||
├── crates/
|
|
||||||
│ ├── ipass-core/ # 内核:状态 / 账号 / 装配契约 / 身份端点
|
|
||||||
│ │ └── src/
|
|
||||||
│ │ ├── config.rs # 仅共性常量 + sess:/fail:/ukey:/rl: 前缀
|
|
||||||
│ │ ├── models.rs # User(全字段 serde(default))
|
|
||||||
│ │ ├── state.rs # 唯一 shm zone + 泛型原语
|
|
||||||
│ │ ├── store.rs # JSON 原子写 + 文件写锁 + data_dir
|
|
||||||
│ │ ├── usage.rs # 【拆自 stats.rs】通用记账原语(无 LLM 语义)
|
|
||||||
│ │ ├── auth.rs # 【新】下行 sk_ 鉴权 + rl: 配额(两条链路共用)
|
|
||||||
│ │ ├── users.rs # 账号唯一写入口 + on_delete 钩子
|
|
||||||
│ │ ├── session.rs # 会话
|
|
||||||
│ │ ├── plugin.rs # 【新】Plugin 契约
|
|
||||||
│ │ ├── loc.rs # 【新】Switch 枚举 + 注入式开关查询
|
|
||||||
│ │ ├── http.rs / util.rs # 请求响应原语 / 通用工具
|
|
||||||
│ │ └── api.rs # 【拆自 api.rs】身份类端点 + CorePlugin
|
|
||||||
│ ├── plugin-domain/ # 动态域名
|
|
||||||
│ │ └── src/{lib,keys,models,domains,resolve,api}.rs
|
|
||||||
│ ├── plugin-llm/ # LLM 路由 / 配额计费 / 审计 / 用量趋势
|
|
||||||
│ │ └── src/{lib,keys,models,llm,upstreams,usage_filter,audit,stats,resolve,api}.rs
|
|
||||||
│ └── plugin-apix/ # 外部 API 供应商资产代理
|
|
||||||
│ └── src/{lib,keys,models,apix,resolve,api}.rs
|
|
||||||
└── gateway/ # 唯一 cdylib:模块壳 + PLUGINS 注册表
|
|
||||||
└── src/lib.rs
|
|
||||||
```
|
|
||||||
|
|
||||||
**关键不变式:仓库里只有一个 `cdylib`(gateway)。** 插件一律 `crate-type = ["rlib"]`。
|
|
||||||
理由(已在 nginx 1.30.4 源码层面核对,详见 sso 的 `plugin-architecture-analysis.md`):
|
|
||||||
动态模块 `ngx_module_t` 带编译期签名,必须与 nginx 同源;共享内存 zone 的 tag 不同会在
|
|
||||||
`ngx_cycle.c` 直接 EMERG 启动失败;同名变量会被后加载者劫持 `get_handler`(不报错、
|
|
||||||
只在某些部署下身份错);Rust 无稳定 ABI,跨 `.so` 传 `String` 即双重 free。
|
|
||||||
|
|
||||||
### 2.1 规模预估
|
|
||||||
|
|
||||||
| 目标 crate | 行数(约) | 说明 |
|
|
||||||
| --- | --- | --- |
|
|
||||||
| `ipass-core` | ~2350 | 含身份端点 |
|
|
||||||
| `plugin-domain` | ~650 | |
|
|
||||||
| `plugin-llm` | ~2100 | 最大的一块 |
|
|
||||||
| `plugin-apix` | ~700 | |
|
|
||||||
| `gateway` | ~450 | 只留壳 |
|
|
||||||
| **合计** | **~6250 + 契约胶水 ≈ 7000** | 与现状 7035 吻合,无逻辑膨胀 |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3. 逐文件归属(改造清单)
|
|
||||||
|
|
||||||
| 现文件 | 行 | 目标 | 备注 |
|
|
||||||
| --- | --- | --- | --- |
|
|
||||||
| `config.rs` | 232 | **拆** | 共性(`SESSION_TTL` `HASH_ROUNDS` `COOKIE_NAME` `LOGIN_MAX_FAIL` `INIT_ADMIN_*` `USERNAME_*` `PASSWORD_MIN_LEN` `DISPLAY_NAME_MAX_LEN` `DEFAULT_DATA_DIR`)→ core;`TEMP_DOMAIN_TTL` `SUBDOMAIN_*` `RESERVED_SUBDOMAINS` → domain;`UPSTREAM_*` `LLM_*` `AUDIT_*` `TREND_*` → llm;`APIX_*` → apix |
|
|
||||||
| `models.rs` | 219 | **拆** | `User` → core;`Upstream`(73-115)→ llm;`ApiProxy`/`ApiProxyStore`(117-165)→ apix;`DomainEntry`(167-)→ domain |
|
|
||||||
| `state.rs` | 362 | core | 原样 |
|
|
||||||
| `store.rs` | 196 | core | 原样 |
|
|
||||||
| `session.rs` | 57 | core | 原样 |
|
|
||||||
| `util.rs` | 354 | core | 原样 |
|
|
||||||
| `http.rs` | 223 | core | 原样 |
|
|
||||||
| `users.rs` | 405 | core | **摘掉 `stats::forget` 依赖**(§4①),`&mut pub` 化为 `on_delete` 钩子 |
|
|
||||||
| `stats.rs` | 585 | **拆** | 记账原语 → `core/usage.rs`;`trend`/`overview`/`user_models`/`tokens_user` 等解读 → `plugin-llm/stats.rs`(§4③) |
|
|
||||||
| `domains.rs` | 485 | plugin-domain | 含 `sync_shm`/`reload_shm` |
|
|
||||||
| `llm.rs` | 442 | plugin-llm | `downstream_key` / `identity` / `check_quota` 移出 → `core/auth.rs`(§4②) |
|
|
||||||
| `upstreams.rs` | 397 | plugin-llm | 原样 |
|
|
||||||
| `llm_usage.rs` | 275 | plugin-llm | 改名 `usage_filter.rs`;`install()` 无参,可在插件 `postconfig` 内直接调 |
|
|
||||||
| `llm_audit.rs` | 200 | plugin-llm | 原样 |
|
|
||||||
| `apix.rs` | 563 | plugin-apix | 管理 API 部分拆到 `api.rs` |
|
|
||||||
| `api.rs` | 1018 | **拆四处** | 见下表 |
|
|
||||||
| `lib.rs` | 1022 | gateway + 各插件 | 壳留 gateway;6 个 handler 与 10 个变量注册下放 |
|
|
||||||
|
|
||||||
### `api.rs` 的端点归属(1018 行拆四处)
|
|
||||||
|
|
||||||
| 端点 | 归属 | 依据 |
|
|
||||||
| --- | --- | --- |
|
|
||||||
| `/api/admin/login` `/logout` `/session` | **core** `api.rs` | 会话是内核职责 |
|
|
||||||
| `/api/admin/users` `/users/{create,display,key,grant,password,delete,models,limits}` | **core** | 账号是内核职责 |
|
|
||||||
| `/api/admin/purge` | **core** | 清理的是会话/失败计数 |
|
|
||||||
| `/api/v1/me` | **core** | 账号态自我查询 |
|
|
||||||
| `/api/admin/domains` `/domains/{review,create,delete}`、`/api/v1/domains` `/domains/{apply,delete}` | plugin-domain | |
|
|
||||||
| `/api/admin/upstreams` `/upstreams/{save,delete,test}`、`/api/admin/usage` `/trend`、`/api/v1/upstreams` `/models` `/usage` | plugin-llm | |
|
|
||||||
| `/api/admin/apix` `/apix/{save,delete,test}`、`/api/v1/apix` | plugin-apix | |
|
|
||||||
|
|
||||||
`Guard`(`Public`/`User`/`Admin`)与 `Actor` 是**四份 route 表共用**的类型 → 连同
|
|
||||||
`user_or_401`、`admin_or_403` 之类守卫一起下沉到 `core/auth.rs`,各插件引用而非各写一份。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 4. 三个必须先解决的边界问题
|
|
||||||
|
|
||||||
这三处是「直接按目录切文件」会撞墙的地方,也是本方案与 sso 参考实现**刻意不同**的地方。
|
|
||||||
|
|
||||||
### ① `users::delete` → `stats::forget`:内核反向依赖插件
|
|
||||||
|
|
||||||
`users.rs:372` 在删除账号时调用 `stats::forget(&stats_name)` 摘掉用量索引。
|
|
||||||
若 `stats` 随 plugin-llm 走,就形成 **core → plugin-llm 的循环依赖**(cargo 会直接报错)。
|
|
||||||
|
|
||||||
**修法:内核开「账号删除钩子」注册表。**
|
|
||||||
|
|
||||||
```rust
|
|
||||||
// crates/ipass-core/src/users.rs
|
|
||||||
static ON_DELETE: Mutex<Vec<fn(&str)>> = Mutex::new(Vec::new());
|
|
||||||
|
|
||||||
/// 插件注册「账号被删除时我需要清理什么」。在 zone 装载后、接请求前调用一次。
|
|
||||||
pub fn on_delete(f: fn(&str)) { /* push */ }
|
|
||||||
|
|
||||||
pub fn delete(username: &str, operator: &str) -> Result<(), String> {
|
|
||||||
// ... 原有逻辑:文件 + ukey:/sess:/fail: 写穿(core 自己的键,不需要钩子)
|
|
||||||
for f in hooks() { f(username); } // 插件各清各的键空间
|
|
||||||
Ok(())
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
plugin-llm 暴露 `pub fn install_hooks() { users::on_delete(stats::forget); }`,
|
|
||||||
由 `gateway` 的 `state_zone_init` 在插件 `zone_load` 之后统一调用。
|
|
||||||
|
|
||||||
> 这条钩子同时解决了「键按前缀分域」惯例下的一个通用问题:**删除账号要摘几个前缀,
|
|
||||||
> 取决于装了哪些插件**——只有注册表能让内核在不认识插件的前提下做对。
|
|
||||||
|
|
||||||
### ② `ApiProxyHandler` 复用 `llm::identity` / `llm::check_quota`:插件间依赖
|
|
||||||
|
|
||||||
`lib.rs:344/352/383`——API 代理热路径调用 LLM 的三个函数完成「取下行 Key → 查身份 →
|
|
||||||
查配额」。若 llm 与 apix 平级,就是 plugin-apix → plugin-llm 的依赖,破坏「插件平级」。
|
|
||||||
|
|
||||||
**判据**:`ukey:` 鉴权与 `rl:` 配额,是「**去掉 llm 还要(apix 要)、去掉 apix 还要(llm 要)、
|
|
||||||
两个都去掉才不要**」——典型的**共用 ⇒ 放内核**。
|
|
||||||
|
|
||||||
**修法:新建 `crates/ipass-core/src/auth.rs`**,下沉三件套:
|
|
||||||
|
|
||||||
```rust
|
|
||||||
pub fn downstream_key(r: *mut ngx_http_request_t) -> Option<String>; // 原 llm::downstream_key
|
|
||||||
pub fn identity(key: &str) -> Option<(String, Vec<String>, i64, i64)>; // 原 llm::identity,读 ukey:
|
|
||||||
pub fn check_quota(r: *mut ngx_http_request_t, user: &str, rpm: i64, daily: i64)
|
|
||||||
-> Option<Status>; // 原 llm::check_quota,读 rl:
|
|
||||||
```
|
|
||||||
|
|
||||||
同时把 `rl:` 前缀从 `config.rs` 的 LLM 段移到 core 段。
|
|
||||||
|
|
||||||
> sso 的参考实现把 `rl:` 划给 plugin-llm,是因为 sso **没有 apix 这条链路**。
|
|
||||||
> iPass 有两条共用配额的下行链路,所以这里必须与 sso 不同——这是本方案对参考实现的
|
|
||||||
> 第一处有意偏离。
|
|
||||||
|
|
||||||
### ③ `stats.rs` 585 行:记账原语 vs 业务解读
|
|
||||||
|
|
||||||
整块搬进 plugin-llm 会让 core 的 `users` 钩子无处落(见①),整块留 core 又会让内核长出
|
|
||||||
LLM 语义(`token` / `模型` / `趋势` 这些词不该出现在内核里)。
|
|
||||||
|
|
||||||
**修法:按「回答什么问题」切开。**
|
|
||||||
|
|
||||||
| 部分 | 目标 | 回答的问题 |
|
|
||||||
| --- | --- | --- |
|
|
||||||
| `record` / `add_tokens` / `forget` / 前缀扫描薄封装 | `core/usage.rs` | 「给这个键 +1」「这个键还有什么」——**纯键值操作,不含业务语义** |
|
|
||||||
| `trend()` / `overview()` / `user_models()` / `tokens_user()` / `all_users()`、日桶聚合 | `plugin-llm/stats.rs` | 「这些数字代表什么」——**业务解读** |
|
|
||||||
|
|
||||||
`core/usage.rs` 只认「前缀 + 名字 + 计数」,不认识 `ust:` 与 `ums:` 的区别;日桶
|
|
||||||
(`ud:`/`udu:`/`uds:`)的 TTL 与保留策略由 plugin-llm 传入。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 5. 契约层(内核与插件之间唯一的接口)
|
|
||||||
|
|
||||||
### 5.1 `Plugin` trait
|
|
||||||
|
|
||||||
沿用 sso 的形态,**签名保持一致**(P5 若与 sso 合流,trait 不用再改):
|
|
||||||
|
|
||||||
```rust
|
|
||||||
// crates/ipass-core/src/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
|
|
||||||
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 的 `ngx_module_t.commands` 是 null 结尾的**连续**数组,
|
|
||||||
不同 crate 的 `static` 数组无法拼接。配置指令由 gateway 集中声明,插件通过 `loc::Switch`
|
|
||||||
查询自己所在 location 是否开启——**指令解析归壳、行为归插件**。
|
|
||||||
|
|
||||||
`dispatch_api` 的语义是「不认领就返回 `None`,让下一个插件试」,**绝不自行 404**
|
|
||||||
(否则后注册的插件永远收不到请求)。404 由 gateway 在全部插件都返回 `None` 后统一发出。
|
|
||||||
|
|
||||||
### 5.2 `loc::Switch`:取并集
|
|
||||||
|
|
||||||
```rust
|
|
||||||
pub enum Switch {
|
|
||||||
Api, // 该 location 暴露管理 API + 身份端点
|
|
||||||
Iap, // 预留(iPass 无用,sso 用;合流时不用改 core)
|
|
||||||
Domain, // 预留(同上)
|
|
||||||
Proxy, // 该 location 走「子域名 → 后端」转发 ← iPass 用
|
|
||||||
Llm, // 该 location 走 LLM 代理 ← iPass 用
|
|
||||||
Apix, // 该 location 走 API 代理 ← iPass 用
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
`Switch` 是内核与插件之间**唯一的契约点**,宁可多留两个变体,也不要在 P5 合流时做破坏性改动。
|
|
||||||
gateway 注入查询实现(`set_switch_fn`),**未实现的变体一律保守返回 `false`**
|
|
||||||
(sso 已踩过这个坑:`Switch::Llm => false`,绝不能误开)。
|
|
||||||
|
|
||||||
### 5.3 gateway 的 5 处装配(少任一处 = 「代码全对但功能不生效」)
|
|
||||||
|
|
||||||
```rust
|
|
||||||
// gateway/src/lib.rs
|
|
||||||
use plugin_apix::ApixPlugin; // ①
|
|
||||||
use plugin_domain::DomainPlugin;
|
|
||||||
use plugin_llm::LlmPlugin;
|
|
||||||
|
|
||||||
static PLUGINS: &[&dyn Plugin] = &[
|
|
||||||
&ipass_core::api::CorePlugin, // 身份端点必须先认领
|
|
||||||
&DomainPlugin, &LlmPlugin, &ApixPlugin,
|
|
||||||
]; // ② 顺序 = 装配顺序
|
|
||||||
|
|
||||||
struct ModuleConfig { api: bool, proxy: bool, llm: bool, apix: bool } // ③
|
|
||||||
// Merge::merge 里补 4 个 if;指令数组长度不变(7 + empty = 8)+ set_flag_* 4 个
|
|
||||||
|
|
||||||
fn loc_switch(r: &mut Request, s: Switch) -> bool { // ④
|
|
||||||
match s {
|
|
||||||
Switch::Api => c.api, Switch::Proxy => c.proxy,
|
|
||||||
Switch::Llm => c.llm, Switch::Apix => c.apix,
|
|
||||||
Switch::Iap | Switch::Domain => false, // 未实现:保守 false
|
|
||||||
}
|
|
||||||
}
|
|
||||||
// ⑤ preconfiguration 里只留 loc::set_switch_fn(loc_switch),其余全部下放插件
|
|
||||||
```
|
|
||||||
|
|
||||||
### 5.4 指令名与 conf:**一个字都不用改**
|
|
||||||
|
|
||||||
iPass 现有 7 条指令 `ipass_state` / `ipass_data_dir` / `ipass_audit_dir` / `ipass_proxy` /
|
|
||||||
`ipass_api` / `ipass_llm` / `ipass_apix`,**与插件划分恰好 1:1**,全部保持原名,
|
|
||||||
数组长度仍是 8。模块名仍是 `ngx_http_ipass_module`,`.so` 仍是 `libipass_gateway.so`。
|
|
||||||
|
|
||||||
> 这是 iPass 相对 sso 参考实现的**结构性优势**:sso 的指令都叫 `sso_*`(`sso_api` /
|
|
||||||
> `sso_iap` / `sso_domain`),搬到 iPass 要全部改名并同步 conf;iPass 侧零改动。
|
|
||||||
> 连带收益:`conf/nginx.conf`、`tests/gateway/nginx.conf.in`、`tests/llm/nginx.conf.in`
|
|
||||||
> **全部不动**,回归基线直接可比。
|
|
||||||
|
|
||||||
### 5.5 变量注册下放
|
|
||||||
|
|
||||||
| 变量 | 现位置 | 目标 |
|
|
||||||
| --- | --- | --- |
|
|
||||||
| `$proxy_backend_addr` | `lib.rs:660-676` | plugin-domain `preconfig` |
|
|
||||||
| `$llm_target` `$llm_host` `$llm_auth` | `lib.rs:680-691` | plugin-llm `preconfig` |
|
|
||||||
| `$apix_target` `$apix_host` `$apix_key` `$apix_body` `$apix_probe_target` `$apix_probe_body` | `lib.rs:694-711` | plugin-apix `preconfig` |
|
|
||||||
|
|
||||||
> 下放后天然更安全:三组变量分属三个 crate,不会像 sso 那样两个 `.so` 注册同名
|
|
||||||
> `$auth_*` 再互相劫持 get_handler。
|
|
||||||
|
|
||||||
**`$upstream_status` 的索引预取**(`lib.rs:739-747`,依赖 `upstream` 内建模块已注册该变量)
|
|
||||||
→ plugin-llm 的 `postconfig`。插件 `postconfig` 在 gateway 自己的 `postconfig` 之前执行,
|
|
||||||
而内建模块的 `preconfiguration` 早已跑完,时序安全。
|
|
||||||
|
|
||||||
### 5.6 phase handler 下放
|
|
||||||
|
|
||||||
| handler | 阶段 | 目标 |
|
|
||||||
| --- | --- | --- |
|
|
||||||
| `ResolveHandler` | access | plugin-domain `postconfig` |
|
|
||||||
| `LlmHandler` | access | plugin-llm `postconfig` |
|
|
||||||
| `ApiProxyHandler` | access | plugin-apix `postconfig` |
|
|
||||||
| `LlmHealthHandler` | log | plugin-llm `postconfig` |
|
|
||||||
| `AuditHandler` | log | plugin-llm `postconfig`(同处调 `usage_filter::install()`) |
|
|
||||||
| `ApiHandler` | content | **留 gateway**——统一收口后按 `PLUGINS` 顺序分发 |
|
|
||||||
|
|
||||||
### 5.7 shm 装载
|
|
||||||
|
|
||||||
```rust
|
|
||||||
extern "C" fn state_zone_init(zone, _data) -> ngx_int_t {
|
|
||||||
state::init_zone(zone)?;
|
|
||||||
users::reload_shm(); // ① 内核自有的 ukey: 索引(不是插件能力)
|
|
||||||
for p in PLUGINS { p.zone_load(); } // ② 各插件装自己的表
|
|
||||||
plugin_llm::install_hooks(); // ③ 注册 on_delete 钩子(§4①)
|
|
||||||
NGX_OK
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
> `users::reload_shm()`(`users.rs:93`)装的是 `ukey:` Key → 身份索引,**属内核**,
|
|
||||||
> 不能靠某个插件的 `zone_load` 顺带完成——否则「核心索引是否装载」会依赖插件是否装配。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 6. 与 sso 参考实现的差异(有意偏离)
|
|
||||||
|
|
||||||
| # | sso 做法 | iPass 做法 | 原因 |
|
|
||||||
| --- | --- | --- | --- |
|
|
||||||
| 1 | `rl:` 配额归 plugin-llm | 归 **core** `auth.rs` | iPass 有 LLM + apix **两条**共用配额的链路(§4②) |
|
|
||||||
| 2 | `stats` 整体在插件 | **拆**:原语进 core `usage.rs`,解读进 plugin-llm | 内核删账号要摘用量索引(§4①③) |
|
|
||||||
| 3 | 身份端点全在 plugin-sso | 身份端点在 **core**(`CorePlugin`) | 已拍板;iPass 无 SSO 插件(§0) |
|
|
||||||
| 4 | 指令 `sso_*`,迁移需改名 | 保持 `ipass_*` | 指令与插件 1:1,conf 零改动(§5.4) |
|
|
||||||
| 5 | `Switch { Api, Iap, Domain, Llm }` | 取**并集** `{Api, Iap, Domain, Proxy, Llm, Apix}` | 契约点一次到位,避免 P5 破坏性改动 |
|
|
||||||
| 6 | 无 | 新增 `users::on_delete` 钩子 | 内核不认识插件的键空间(§4①) |
|
|
||||||
| 7 | 无 `plugin-llm`(明确不迁入) | **要** plugin-llm | iPass 的本体就是域名 + LLM + apix |
|
|
||||||
| 8 | `libsso_gateway.dylib` | 仍是 `libipass_gateway.so` | Dockerfile 产物路径不变 |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 7. 落地路径(每阶段独立可回滚)
|
|
||||||
|
|
||||||
### P0 · 建 workspace,内核落地(**行为零变化**)
|
|
||||||
|
|
||||||
1. `rust/Cargo.toml` → 变 workspace 根:`members = ["crates/ipass-core", "gateway"]`,
|
|
||||||
`exclude = ["vendor/ngx-rust"]`,依赖全部上移到 `[workspace.dependencies]`。
|
|
||||||
2. 建 `crates/ipass-core`,迁入 `config`(共性裁剪)/ `models`(仅 `User`)/ `state` /
|
|
||||||
`store` / `session` / `util` / `http` / `users`。
|
|
||||||
3. 建 `gateway`,`lib.rs` 整体搬过去——**此时所有业务模块仍留在 gateway**,
|
|
||||||
先证明「产物名、路径、行为全部不变」。
|
|
||||||
|
|
||||||
**验收**:`target/release/libipass_gateway.so` 同名同路径;
|
|
||||||
`bash deploy/... ` 容器可起;`bash tests/run.sh all` **262 项全绿**。
|
|
||||||
|
|
||||||
> ⚠️ 最容易漏的一处:`[profile.release]`(`opt-level`/`lto`/`codegen-units`/`panic="abort"`/
|
|
||||||
> `strip`)**必须在 workspace 根**——member 里写会被 cargo 忽略。`panic="abort"` 丢了
|
|
||||||
> 就意味着 panic 可能跨 FFI 边界展开。
|
|
||||||
|
|
||||||
### P1 · 契约层
|
|
||||||
|
|
||||||
新增 `core/plugin.rs`(`Plugin` trait)与 `core/loc.rs`(`Switch` + `set_switch_fn`/`enabled`);
|
|
||||||
gateway 实现 `loc_switch`、把 `PLUGINS` 数组与分发循环接上(此时 `PLUGINS` 只有 `CorePlugin`)。
|
|
||||||
|
|
||||||
**验收**:编译通过、262 全绿(契约层不改变行为)。
|
|
||||||
|
|
||||||
### P2 · 拆 plugin-domain(最小、最独立,用来验证流程)
|
|
||||||
|
|
||||||
迁 `domains.rs` + `DomainEntry` + `sub:` 前缀 + 域名类端点 + `ResolveHandler` +
|
|
||||||
`$proxy_backend_addr` 注册 + `TEMP_DOMAIN_TTL`/`SUBDOMAIN_*`/`RESERVED_SUBDOMAINS`。
|
|
||||||
|
|
||||||
**验收**:`tests/gateway` 102 项全绿(含域名审批 / 写穿生效 / 通配符转发)。
|
|
||||||
|
|
||||||
### P3 · 拆 plugin-llm(最大,前置换算在下沉 core)
|
|
||||||
|
|
||||||
前置三件事:**`auth.rs` 下沉**(§4②)、**`usage.rs` 拆分**(§4③)、**`on_delete` 钩子**(§4①)。
|
|
||||||
然后迁 `llm` / `upstreams` / `llm_usage` / `llm_audit` / `stats`(解读部分)+ LLM 类端点 +
|
|
||||||
三个 handler + `up:`…`uh:` 全部前缀 + `llm_*` 三变量。
|
|
||||||
|
|
||||||
**验收**:`tests/llm` 160 项全绿(含流式、模型发现、配额、用量趋势、审计落盘)。
|
|
||||||
|
|
||||||
### P4 · 拆 plugin-apix
|
|
||||||
|
|
||||||
迁 `apix.rs` + `ax:` 前缀 + apix 类端点 + `ApiProxyHandler` + `apix_*` 六变量。
|
|
||||||
|
|
||||||
**验收**:apix 用例全绿(现混在 `tests/llm` 内);手工确认两点——
|
|
||||||
`/apix/<slug>` 用 **lm host**、`/_apix_probe/` 在 **mdm server**(`mdm` 上打 `/apix/` 应是 nginx 404)。
|
|
||||||
|
|
||||||
### P5 · 收尾 + 文档 + 技能;**(可选)**与 ssw/sso 的关系
|
|
||||||
|
|
||||||
- 文档:`CLAUDE.md`(crate 清单 + 目录地图 + 回归套数)、`readme.md` §6 目录结构、
|
|
||||||
本文件转正为 `docs/plugin/PLUGIN_ARCHITECTURE.md`(P2 的论证部分直接引用 sso 的
|
|
||||||
`plugin-architecture-analysis.md`,不重复写)。
|
|
||||||
- 技能:把 sso 的 `.workbuddy/skills/ipass-core-add-plugin/SKILL.md` 改造为 iPass 版
|
|
||||||
(改 crate 名、指令名、e2e 路径;保留「5 处装配缺一不可」「症状 → 根因」两张表)。
|
|
||||||
- **待定**:是否把 `sww/sso` 的 `plugin-sso` 并入 iPass(届时 `CorePlugin` 的身份端点
|
|
||||||
移交 plugin-sso,或 plugin-sso 直接实现同一批路由)。P0–P4 的设计已为此留好口子
|
|
||||||
(`Switch` 并集、`Plugin` trait 签名与 sso 一致)。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 8. 周边影响面
|
|
||||||
|
|
||||||
| 文件 | 是否要改 | 说明 |
|
|
||||||
| --- | --- | --- |
|
|
||||||
| `Dockerfile` | **不改** | `COPY rust/ ./` + 在 workspace 根 `cargo build --release`,产物仍是 `target/release/libipass_gateway.so` |
|
|
||||||
| `conf/nginx.conf` | **不改** | 指令名与 `.so` 名不变(§5.4) |
|
|
||||||
| `compose.yml` | **不改** | |
|
|
||||||
| `deploy/release.sh` `deploy/agent.sh` `deploy/ipass-agent.py` | **不改** | 镜像 tag / 产物路径 / 端口不变 |
|
|
||||||
| `tests/run.sh` + `tests/*/nginx.conf.in` | **不改** | 套数与端口不变 |
|
|
||||||
| `tests/*/fixtures/*.json` | **不改** | 持久化格式零变化(§9⑤) |
|
|
||||||
| `.gitignore` `.dockerignore` | **不改** | `vendor/` 仍在 `rust/vendor/` |
|
|
||||||
| `www/` 管理台 | **不改** | API 路径全部保持原样 |
|
|
||||||
| 迭代命令 | **变** | 单 crate 快速迭代:`cargo build -p plugin-llm`(几十秒 vs 全量 ~1.5 分钟) |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 9. 风险与纪律
|
|
||||||
|
|
||||||
1. **P3 是主战场**。边界切错会让内核长出 LLM 语义(难事后拆),或形成 core↔plugin 循环
|
|
||||||
(cargo 直接报错,不会静默——这点比运行时问题好排查)。开工前先按 §4 三条把
|
|
||||||
`auth.rs` / `usage.rs` / `on_delete` 建好,再动搬移。
|
|
||||||
2. **`[profile.release]` 只能在 workspace 根**。`panic="abort"`(防 panic 跨 FFI)、
|
|
||||||
`lto`、`codegen-units=1`、`strip` 一项丢了都是线上隐患。
|
|
||||||
3. **`[features] export-modules` + `ngx::ngx_modules!` 宏属于 gateway**。`[lib] crate-type`
|
|
||||||
的 `"cdylib"` 也只给 gateway;插件一律 `["rlib"]`(不要为了「顺便能测」给插件加 cdylib)。
|
|
||||||
4. **`loc::Switch` 未实现的变体必须保守 `false`**。返回 `true` 会让未装配的能力意外开门。
|
|
||||||
5. **`data/*.json` 零格式变化**:已核对 `User`/`Upstream`/`ApiProxy`/`ApiProxyStore`/
|
|
||||||
`DomainEntry` 的字段全部带 `#[serde(default)]`(含 `default_llm_rpm` / `default_llm_daily` /
|
|
||||||
`default_true` 三个函数缺省),存量文件可直接被新 `.so` 接管。**但要在 P0 单独做一次
|
|
||||||
「新旧解析对拍」**(同一份 `data/` 跑改造前/后的构建,比对内存装载条数与账号数),
|
|
||||||
这是唯一可能出现「账号全部消失」类事故的地方。
|
|
||||||
6. **热路径永不回源**:插件的每请求决策只能读共享内存;任何写操作必须**先落文件、
|
|
||||||
再写穿 shm**,且写 shm 失败必须 `log_err`。迁移时逐插件核对 `sync_shm` 调用点,
|
|
||||||
漏一处 = 「刚配好却 404」。
|
|
||||||
7. **`ngx` 依赖必须走 `vendor/ngx-rust` 的 path 依赖**:crates.io 的 `ngx = "0.5"` 没有请求阶段
|
|
||||||
API(`add_phase_handler`/`HttpPhase` 未发版);git 依赖会去克隆 submodule 而卡死。
|
|
||||||
workspace 化后统一放 `[workspace.dependencies]`,各 crate 用 `.workspace = true`。
|
|
||||||
8. **别在 P2 顺手把 plugin-llm 建一半**:`members` 里列了但目录缺 `Cargo.toml`/`lib.rs`
|
|
||||||
会让整个 workspace 编不过。要么做完,要么从 `members` 摘掉并把目录移到 `/tmp` 备份。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 10. 已拍板 / 待拍板
|
|
||||||
|
|
||||||
**已拍板(2026-09-13)**
|
|
||||||
|
|
||||||
- [x] 只做 iPass 自身插件化;`ssw/sso` 的仓库归属留到 P5
|
|
||||||
- [x] 身份端点(登录 / 会话 / 账号管理 / `me`)由 `ipass-core` 直接收口,经 `CorePlugin` 装配
|
|
||||||
- [x] 单 `.so` + crate 级插件(不做运行时多 `.so`)
|
|
||||||
- [x] `ukey:` 鉴权与 `rl:` 配额下沉 core(两条下行链路共用)
|
|
||||||
- [x] `stats` 按「记账原语 / 业务解读」切开,原语进 core
|
|
||||||
- [x] 指令名与 `.so` 名保持不变(conf 与测试零改动)
|
|
||||||
|
|
||||||
**待拍板**
|
|
||||||
|
|
||||||
- [ ] P5:是否把 `plugin-sso` 并入 iPass(并入后身份端点移交,`CorePlugin` 退化为纯库)
|
|
||||||
- [ ] 是否同步把 `ssw/sso` 的 core 与本项目的 `ipass-core` 收敛为同一份(
|
|
||||||
需先确认两边 `Switch` 并集与 `Plugin` trait 已对齐——本方案已按对齐设计)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 附:查证位置
|
|
||||||
|
|
||||||
| 论断 | 位置 |
|
|
||||||
| --- | --- |
|
|
||||||
| 17 模块 / 7035 行 | `rust/src/*.rs`(`wc -l`) |
|
|
||||||
| 模块依赖图 | 各文件 `use crate::` 汇总(§1 表) |
|
|
||||||
| 7 条指令 + 长度 8 | `rust/src/lib.rs:752-810` |
|
|
||||||
| `ModuleConfig` 四开关 + `Merge` | `rust/src/lib.rs:563-594` |
|
|
||||||
| 6 个 phase handler 注册点 | `rust/src/lib.rs:716-749` |
|
|
||||||
| 10 个变量注册 | `rust/src/lib.rs:655-711` |
|
|
||||||
| `$upstream_status` 索引预取 | `rust/src/lib.rs:739-747` |
|
|
||||||
| `state_zone_init` 三表装载 | `rust/src/lib.rs:956-975` |
|
|
||||||
| `ApiProxyHandler` 调 llm 三件套 | `rust/src/lib.rs:344` `:352` `:383` |
|
|
||||||
| `users::delete` → `stats::forget` | `rust/src/users.rs:372` |
|
|
||||||
| `users::reload_shm` 装 `ukey:` | `rust/src/users.rs:93-113` |
|
|
||||||
| `llm_usage::install()` 无参 | `rust/src/llm_usage.rs:59-64` |
|
|
||||||
| 键前缀全景 | `rust/src/config.rs:78-166` |
|
|
||||||
| 持久化结构全部 `serde(default)` | `rust/src/models.rs`(`User` 23-48、`Upstream` 82-93、`ApiProxy` 135-161、`DomainEntry` 179-187) |
|
|
||||||
| 为什么不拆多 `.so` | `ssw/sso` → `docs/plugin-architecture-analysis.md` |
|
|
||||||
| 加插件的 5 处装配 / 排错表 | `ssw/sso` → `.workbuddy/skills/ipass-core-add-plugin/SKILL.md` |
|
|
||||||
@@ -0,0 +1,216 @@
|
|||||||
|
# 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(组合根)
|
||||||
@@ -128,7 +128,7 @@ DNS:*.yourdomain.com ──(泛解析,只配一次,永不修改)──▶
|
|||||||
> `^(.+dm)\.mayishangshu\.cn$`,捕获组**必须以 `dm` 结尾**;不以 `dm` 结尾的子域名
|
> `^(.+dm)\.mayishangshu\.cn$`,捕获组**必须以 `dm` 结尾**;不以 `dm` 结尾的子域名
|
||||||
> 建出来也匹配不上转发 server(等于建了个打不开的域名)。这是硬约束,不是命名偏好。
|
> 建出来也匹配不上转发 server(等于建了个打不开的域名)。这是硬约束,不是命名偏好。
|
||||||
|
|
||||||
规则真源在 **`rust/src/config.rs`**(`ENTERPRISE_ZONE` / `SUBDOMAIN_PREFIX` /
|
规则真源在 **`rust/crates/plugin-domain/src/config.rs`**(`ENTERPRISE_ZONE` / `SUBDOMAIN_PREFIX` /
|
||||||
`SUBDOMAIN_SUFFIX` / `SUBDOMAIN_RAND_DIGITS`),由 `GET /api/admin/domains` 的
|
`SUBDOMAIN_SUFFIX` / `SUBDOMAIN_RAND_DIGITS`),由 `GET /api/admin/domains` 的
|
||||||
`subdomain_rule` 下发给面板——改后端常量,面板自动跟随;**改 zone 必须同步改
|
`subdomain_rule` 下发给面板——改后端常量,面板自动跟随;**改 zone 必须同步改
|
||||||
`conf/nginx.conf` 那条正则**(两处耦合,注释里已互相标注)。
|
`conf/nginx.conf` 那条正则**(两处耦合,注释里已互相标注)。
|
||||||
@@ -192,24 +192,17 @@ subdomain/
|
|||||||
├── .gitignore
|
├── .gitignore
|
||||||
├── conf/
|
├── conf/
|
||||||
│ └── nginx.conf # 四个 server(转发 / LLM / 管理 / 默认拒绝)、路由、共享内存声明、subdomain_* 系列指令(main 级 `ipass_state` / `ipass_data_dir` + location 级 `ipass_proxy` / `ipass_api` / `ipass_llm`)
|
│ └── nginx.conf # 四个 server(转发 / LLM / 管理 / 默认拒绝)、路由、共享内存声明、subdomain_* 系列指令(main 级 `ipass_state` / `ipass_data_dir` + location 级 `ipass_proxy` / `ipass_api` / `ipass_llm`)
|
||||||
├── rust/ # ★ Rust 动态模块(业务全部在这里)
|
├── rust/ # ★ Rust 动态模块(业务全部在这里;2026-09-13 起 workspace 化)
|
||||||
│ ├── Cargo.toml # ngx / nginx-sys 走 path 依赖(vendor)
|
│ ├── Cargo.toml # workspace 根:members + 统一依赖 + [profile.release]
|
||||||
│ ├── build.rs # macOS 需要 -undefined dynamic_lookup
|
│ ├── build.rs # gateway 的 macOS -undefined dynamic_lookup
|
||||||
│ ├── vendor/ngx-rust/ # vendored 的 ngx-rust(不可换成 crates.io / git)
|
│ ├── vendor/ngx-rust/ # vendored 的 ngx-rust(不可换成 crates.io / git)
|
||||||
│ └── src/
|
│ ├── crates/
|
||||||
│ ├── lib.rs # 模块入口:指令、共享内存装载、变量注册、三个阶段处理器
|
│ │ ├── ipass-core/ # 内核:状态/账号/会话/下行鉴权(auth)/记账原语(usage)/契约(plugin,loc)/身份端点(api)
|
||||||
│ ├── api.rs # API 统一分发器(路由表 + 鉴权分流)
|
│ │ ├── plugin-domain/ # 域名插件:申请/审批/ResolveHandler(sub: 键空间)
|
||||||
│ ├── users.rs # 账号:创建/改密/重置 Key/授予与撤销临时授权
|
│ │ ├── plugin-llm/ # LLM 插件:llm/upstreams/usage_filter/llm_audit/stats/handlers
|
||||||
│ ├── domains.rs # 域名:申请/审核/过期判定/写穿共享内存/清理
|
│ │ └── plugin-apix/ # API 代理插件:apix/handlers/api(ax: 键空间)
|
||||||
│ ├── upstreams.rs # LLM 上游(含真实密钥)
|
│ └── gateway/ # 唯一 cdylib:模块壳(指令/开关)+ PLUGINS 注册表 + trend 组合端点
|
||||||
│ ├── session.rs # 管理员登录会话
|
│ # 插件化架构详见 docs/plugin/PLUGIN_ARCHITECTURE.md
|
||||||
│ ├── state.rs # 共享内存(SlabPool + RbTreeMap + RwLock)
|
|
||||||
│ ├── store.rs # JSON 原子读写 + 跨 worker 文件锁
|
|
||||||
│ ├── http.rs # 参数合并、两段式请求体读取、JSON 响应
|
|
||||||
│ ├── util.rs # 随机数/摘要/口令哈希/常量时间比较/日志
|
|
||||||
│ ├── models.rs # User / DomainEntry 结构
|
|
||||||
│ ├── llm.rs # LLM 转发热路径
|
|
||||||
│ └── config.rs # 全部策略常量(TTL、保留名、长度上限)
|
|
||||||
├── www/ # 管理台(多页,纯静态 + fetch)
|
├── www/ # 管理台(多页,纯静态 + fetch)
|
||||||
│ ├── login.html # 登录页
|
│ ├── login.html # 登录页
|
||||||
│ ├── overview.html # 数据总览(卡片 + 趋势图 + Top 排名)
|
│ ├── overview.html # 数据总览(卡片 + 趋势图 + Top 排名)
|
||||||
@@ -218,16 +211,18 @@ subdomain/
|
|||||||
│ ├── users.html # 账号管理
|
│ ├── users.html # 账号管理
|
||||||
│ ├── upstreams.html # LLM 上游(API 组)
|
│ ├── upstreams.html # LLM 上游(API 组)
|
||||||
│ ├── usage.html # 用量统计(趋势 · 按人 · 按 API 组 · token)
|
│ ├── usage.html # 用量统计(趋势 · 按人 · 按 API 组 · token)
|
||||||
|
│ ├── apix.html # API 代理(列表 + 弹出卡片编辑 + 免费预估测试)
|
||||||
│ └── assets/ # admin.css + core.js + chart.js + 各页 JS
|
│ └── assets/ # admin.css + core.js + chart.js + 各页 JS
|
||||||
├── tests/ # ★ 本机回归夹具(bash tests/run.sh [gateway|llm|all])
|
├── tests/ # ★ 本机回归夹具(bash tests/run.sh [gateway|llm|all],262 项)
|
||||||
│ ├── run.sh # 统一入口:编译 + 渲染配置 + 起停 nginx + 跑断言
|
│ ├── run.sh # 统一入口:编译 + 渲染配置 + 起停 nginx + 跑断言
|
||||||
│ ├── gateway/ # 域名网关:nginx.conf.in + e2e.sh(90 条断言)+ 转发靶机
|
│ ├── gateway/ # 域名网关:nginx.conf.in + e2e.sh(102 条断言)+ 转发靶机
|
||||||
│ └── llm/ # LLM 代理:nginx.conf.in + e2e.sh(111 条)+ 假上游 + 合成夹具
|
│ └── llm/ # LLM 代理:nginx.conf.in + e2e.sh(160 条)+ 假上游 + 合成夹具
|
||||||
│ # (.run/ 是运行目录,已 gitignore)
|
│ # (.run/ 是运行目录,已 gitignore)
|
||||||
├── data/ # ★ 状态目录(需可写;运行期真源在共享内存)
|
├── data/ # ★ 状态目录(需可写;运行期真源在共享内存)
|
||||||
│ ├── users.json # 账号表(含口令哈希与 API Key)
|
│ ├── users.json # 账号表(含口令哈希与 API Key)
|
||||||
│ ├── domains.json # 子域名映射表 + 申请记录
|
│ ├── domains.json # 子域名映射表 + 申请记录
|
||||||
│ └── llm-upstreams.json # LLM 上游表(含厂商真 Key)
|
│ ├── llm-upstreams.json # LLM 上游表(含厂商真 Key)
|
||||||
|
│ └── api-proxies.json # API 代理表(含供应商真 Key)
|
||||||
├── logs/ # 日志(容器内软链到 stdout/stderr)
|
├── logs/ # 日志(容器内软链到 stdout/stderr)
|
||||||
└── archive/
|
└── archive/
|
||||||
└── openresty-lua-20260910/ # 旧 OpenResty+Lua 版归档(只读参考)
|
└── openresty-lua-20260910/ # 旧 OpenResty+Lua 版归档(只读参考)
|
||||||
@@ -412,7 +407,7 @@ curl -s -H "X-API-Key: $KEY" "$API/api/v1/domains"
|
|||||||
| GET | `/api/admin/usage` | - | LLM 用量总览:全局合计 + 按账号 + 按上游(每个含今日 / 累计 / 最近调用 / token 合计) |
|
| GET | `/api/admin/usage` | - | LLM 用量总览:全局合计 + 按账号 + 按上游(每个含今日 / 累计 / 最近调用 / token 合计) |
|
||||||
| GET | `/api/admin/trend` | `days`(可选,默认 14、上限 90) | LLM 用量趋势(图表数据源):按**本地自然日**分桶,返回 `{days, labels, total, users, slots}`,后三者各含 `requests` / `in` / `out` 三条与 `labels` 等长的数组 |
|
| GET | `/api/admin/trend` | `days`(可选,默认 14、上限 90) | LLM 用量趋势(图表数据源):按**本地自然日**分桶,返回 `{days, labels, total, users, slots}`,后三者各含 `requests` / `in` / `out` 三条与 `labels` 等长的数组 |
|
||||||
|
|
||||||
> 完整路由表以 `rust/src/api.rs` 的 `route()` 为准(精确匹配,新增接口三步见 CLAUDE.md「硬约定」)。LLM 相关接口(`users/models` / `users/limits` / `users/display` / `upstreams*` / `usage`)详见第 15 节。
|
> 完整路由表以各插件 `api.rs` 的 `route()` 为准(ipass-core / plugin-domain / plugin-llm / plugin-apix 各管一段,精确匹配,新增接口三步见 CLAUDE.md「硬约定」)。LLM 相关接口(`users/models` / `users/limits` / `users/display` / `upstreams*` / `usage`)详见第 15 节。
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -452,7 +447,7 @@ LLM 代理读 `Authorization: Bearer`。重置 Key 会同时影响两个入口
|
|||||||
|
|
||||||
`llm_rpm` / `llm_daily` 是该账号的 LLM 限流:每分钟请求数 / 每日请求数,
|
`llm_rpm` / `llm_daily` 是该账号的 LLM 限流:每分钟请求数 / 每日请求数,
|
||||||
`0` 表示**不限**;老数据缺省时取全局默认(`LLM_RPM_DEFAULT=60` / `LLM_DAILY_DEFAULT=0`,
|
`0` 表示**不限**;老数据缺省时取全局默认(`LLM_RPM_DEFAULT=60` / `LLM_DAILY_DEFAULT=0`,
|
||||||
定义在 `rust/src/config.rs`,改策略只改那里)。详见「LLM API 代理 → 限流与配额」。
|
定义在 `rust/crates/ipass-core/src/config.rs`,改策略只改那里)。详见「LLM API 代理 → 限流与配额」。
|
||||||
|
|
||||||
### `data/domains.json`
|
### `data/domains.json`
|
||||||
|
|
||||||
|
|||||||
Reference in new issue
Block a user