chore: 放行 .workbuddy/skills/ 并新增项目级技能 ipass-core-add-plugin

.workbuddy/ 原为整体忽略(本地记忆与临时产物),但项目级技能需要随仓库
共享给团队,故改为忽略其全部内容、仅放行 .workbuddy/skills/。

注意写法:不能用 `.workbuddy/` + `!.workbuddy/skills/` —— 父目录被整体
排除后 git 不会再向下遍历,否定规则不生效;必须写 `.workbuddy/*`。

新增技能 ipass-core-add-plugin:在「内核 + 编译期插件」式 nginx Rust 工作区
(ipass-core / plugin-* / gateway 单 cdylib)里新增或从 refs/ 移植一个能力插件
的完整流程 —— 量内核边界、crate 骨架、文件分工、gateway 5 处装配、配置、
e2e 注册,附「症状 → 根因」排错表。
This commit is contained in:
ssw committed 2026-09-13 10:23:25 +08:00
1 parent 3a908071ff
commit 8079982ba8
2 files changed
+225 -1

No files matched your search

+6 -1
View File
@@ -23,7 +23,12 @@
# ---------------------------------------------------------------------------
# 工具与临时文件
# ---------------------------------------------------------------------------
.workbuddy/
# .workbuddy 为本地工作目录(记忆、临时产物)——整体忽略;
# 但「项目级技能」要随仓库共享给团队,故单独放行 .workbuddy/skills/
# (注意:不能写成 `.workbuddy/` + `!.workbuddy/skills/`——
# 父目录被整体排除后,git 不会再往下看,否定规则无效)
.workbuddy/*
!.workbuddy/skills/
.DS_Store
*.log
*.pid
@@ -0,0 +1,219 @@
---
name: ipass-core-add-plugin
description: 在「内核 + 编译期插件」式 nginx Rust 工作区(ipass-core / ssw-sso 一类:crates/ipass-core + crates/plugin-* + gateway,产出单个 cdylib)里新增一个能力插件。适用于「把某个功能做成插件」「加一个新插件 crate」「从 refs/ 里移植一个插件过来」「给网关加 XXX 能力」这类请求;也用于排查这些症状:插件写完了但 gateway 里没生效、cargo build 报 plugin-xxx 目录不存在 / 未在 members 里、插件里调 ipass_core::xxx 找不到符号、新插件的 location 开关不生效、e2e 里子命令全部 401、Edit 工具报成功但 cargo 仍报旧错误。关键词:ipass-core、plugin-sso、plugin-domain、plugin-llm、Plugin trait、PLUGINS 数组、zone_load、preconfig、postconfig、dispatch_api、loc::Switch、sso_domain、单 .so 装配、libsso_gateway.dylib。
agent_created: true
---
# 给「内核 + 插件」式 nginx 模块加一个能力插件
## 何时用
用户要在这种工作区里新增/移植一个插件。典型形态(本文以 `ssw/sso` 为参照):
```text
source/rust/
├── crates/ipass-core/ 内核:state(共享内存) / store(JSON 原子写) / users(账号唯一写入口)
│ / models(共性字段 + extra 透传) / config(共性常量) / plugin(契约) / loc(开关)
├── crates/plugin-sso/ 身份插件
├── crates/plugin-domain/ 能力插件(本流程的产出物形态)
└── gateway/ **唯一**产出 cdylib:module 壳 + PLUGINS 数组
```
**先确认范围**:用户说「只做 A 插件当示例」时,不要顺手把 B 插件也建一半。半成品 crate 会让整个
workspace 编不过(成员在 `members` 里但目录缺 `Cargo.toml`/`lib.rs` → cargo 直接报错),
要么做完,要么从 `members` 里摘掉并把目录移走(别直接 rm,移到 `/tmp` 备份)。
## 铁律(违反必出问题)
1. **仓库里只有一个 cdylib**(`gateway`)。插件是 `crate-type = ["rlib"]`,被 gateway 静态链进去。
不要试图让插件各自产出 `.so`:nginx 动态模块无稳定 ABI,跨 `.so` 传 `String` 即双重 free;
且共享内存 zone tag / 同名变量都会冲突。
2. **装配顺序 = `gateway` 里 `PLUGINS` 数组的顺序**,显式可控,别用注册宏之类隐式机制。
3. **`users.json` 由内核独占读写**。插件只读(`users::get` / `find_by_key`),
要给账号加插件字段走 `users::update_extra(username, |extra| ...)`。
4. **配置指令必须在 gateway 声明**。`ngx_module_t.commands` 是 null 结尾的连续数组,
不同 crate 的 static 数组无法拼接 —— 插件不持有指令,只通过 `loc::Switch` 查询开关。
5. **热路径永不回源**。插件的每请求决策读共享内存;任何写操作必须**同时**更新共享内存与文件
(先落文件、再写穿 shm),否则表现是「改完不生效,重启才好」。
## 步骤
### 1. 先量内核的真实边界(最容易翻车的一步)
移植过来的插件通常假设内核里有它熟悉的 API,而**收窄过的内核很多已经不提供**。
不要凭 refs 的旧代码猜,逐条 grep 确认:
```bash
cd source/rust
# 内核到底导出了什么
sed -n '1,200p' crates/ipass-core/src/lib.rs
# 逐个核实你要用的符号
grep -n "pub fn " crates/ipass-core/src/state.rs # get/get_live/put/remove/clear_prefix/iter_prefix*
grep -n "pub fn " crates/ipass-core/src/store.rs # read_plugin/write_plugin/update_plugin/update_extra
grep -n "pub fn " crates/ipass-core/src/users.rs
grep -n "pub fn \|pub enum" crates/ipass-core/src/loc.rs
grep -n "pub fn " crates/ipass-core/src/http.rs
```
常见缺口(实测踩过):内核**没有** `bump_window` / `put_ukey` / `put_upstream` / `get_upstream` /
`remove_upstream` / `reload_shm` / `set_allowed_models` —— 这些是原单体项目的,插件要**自己在插件内重建**
(用内核的泛型原语 `state::{get,get_live,put,remove,clear_prefix,iter_prefix}` 封装)。
按前缀分域是既有惯例:插件在自家 `keys.rs` 里定义自己的键前缀常量(如 `sub:` / `up:` / `rl:` / `uh:`),
**不要**往内核 `config.rs` 里加。
### 2. 建 crate 骨架
```bash
mkdir -p source/rust/crates/plugin-<name>/src
```
`Cargo.toml`(照 `plugin-domain` 抄):
```toml
[package]
name = "plugin-<name>"
version.workspace = true
edition.workspace = true
publish.workspace = true
description = "……"
[lib]
name = "plugin_<name>" # 下划线!crate 名带横线,lib name 必须转下划线
crate-type = ["rlib"] # 绝不 cdylib
[dependencies]
ngx.workspace = true # 依赖一律 .workspace = true(vendor 的 ngx,不能走 crates.io)
nginx-sys.workspace = true
ipass-core.workspace = true
serde.workspace = true
serde_json.workspace = true
```
同时在 workspace 根 `Cargo.toml` 补两处:
```toml
members = [..., "crates/plugin-<name>", ...]
[workspace.dependencies]
plugin-<name> = { path = "crates/plugin-<name>" }
```
> 依赖必须用 workspace 里 vendor 好的 `ngx`:crates.io 的 `ngx = "0.5"` 只有配置阶段接口,
> 请求阶段(`add_phase_handler`/`HttpPhase`/`HttpRequestHandler`)尚未发版;git 依赖会去拉
> nginx 完整仓库的 submodule 而卡死。详见 `nginx-rs-module-local-verify` 技能。
### 3. 写插件源码(文件分工照 plugin-domain)
| 文件 | 内容 |
| --- | --- |
| `keys.rs` | 本插件共享内存前缀 + 业务常量 + `put/get/remove/clear` 薄封装 |
| `models.rs` | 插件自有数据模型(`serde`,集合用 `type XxxTable = Vec<Xxx>`) |
| `<feature>.rs` | 业务逻辑:校验、增删改、`sync_shm`(写穿) / `reload_shm`(全量装载) |
| `resolve.rs` | 每请求热路径:阶段处理器 + 注入 nginx 变量 + `register_vars` |
| `api.rs` | 管理/账号态 API:`route` / `matches` / `dispatch` 三件套 + 各 handler |
| `lib.rs` | `XxxPlugin` 实现 `Plugin`,把上面拼起来 |
`Plugin` trait(全部方法有默认实现,按需覆盖):
```rust
impl Plugin for DomainPlugin {
fn name(&self) -> &'static str { "domain" }
// 配置解析前:注册 nginx 变量(否则 proxy_set_header $var 解析失败)
fn preconfig(&self, cf: *mut ngx_conf_t) -> bool { unsafe { resolve::register_vars(cf) } }
// 配置解析后:注册自己的阶段处理器
fn postconfig(&self, cf: *mut ngx_conf_t) -> bool {
let cf = unsafe { &mut *cf };
ngx::http::add_phase_handler::<resolve::ResolveHandler>(cf).is_ok()
}
// 管理 API 分发:不认领就返回 None(让下一个插件试),**不要**自作主张 404
fn dispatch_api(&self, r: *mut ngx_http_request_t) -> Option<Status> {
let (m, u) = (ipass_core::http::method_str(r), ipass_core::http::uri(r));
if api::matches(&m, &u) { Some(api::dispatch(r)) } else { None }
}
// 共享内存初始化(nginx fork 前调用一次):全量装载,返回条数
fn zone_load(&self) -> usize { domains::reload_shm() }
}
```
**API 层的鉴权沿用三件套**:Admin 走登录会话 Cookie → `session::authenticate` → `users::get` →
`u.is_admin()`;User 走 `X-API-Key` → `users::find_by_key`。失败 `http::fail(r, UNAUTHORIZED/FORBIDDEN, msg)`。
### 4. 装配 gateway
改 `gateway/src/lib.rs`(**这 5 处缺一不可**,少任一处就是「代码全对但功能不生效」):
```rust
use plugin_<name>::<Name>Plugin; // ①
static PLUGINS: &[&dyn Plugin] = &[&SsoPlugin, &<Name>Plugin]; // ② 顺序即装配顺序
struct ModuleConfig { api: bool, iap: bool, <name>: bool } // ③ location 开关字段
// Merge::merge 里补 if prev.<name> { self.<name> = true; }
fn loc_switch(...) -> bool { match s {
Switch::Api => c.api, Switch::Iap => c.iap, Switch::<Name> => c.<name>,
Switch::Other => false, // ④ 未实现的插件保守 false
}}
// ⑤ 指令数组:长度 +1,新增 sso_<name> 项 + 对应的 set_flag_<name>
static mut NGX_HTTP_SSO_COMMANDS: [ngx_command_t; N+1] = [...];
```
`gateway/Cargo.toml` 也要加 `plugin-<name>.workspace = true`。
### 5. 编译
```bash
cd source/rust
NGINX_SOURCE_DIR=/tmp/sso-build/src/nginx-1.30.4 \
NGINX_BUILD_DIR=/tmp/sso-build/src/nginx-1.30.4/objs \
CARGO_NET_OFFLINE=true cargo build --release
# 先单 crate 快速迭代(几十秒 vs 全量 ~1.5 分钟):
# ... cargo build -p plugin-<name>
# 产物:target/release/libsso_gateway.dylib
```
输出里 vendor 的 `ngx`/`nginx-sys` 会刷几百行 warning,**只 grep 错误**,别被淹:
```bash
... cargo build --release 2>&1 | grep -E "^error" -A 12
```
### 6. nginx 配置(测试 + 生产)
- `source/conf/nginx.test.conf`:给新能力加 listen 端口 + `sso_<name> on;`。
本机没有 PCRE,**`server_name ~regex` 会被渲染脚本降级成 `server_name _`**,
所以判 Host 的逻辑要放在插件里(按后缀 `strip_suffix`),不要依赖 `server_name` 捕获。
- `source/conf/nginx.conf`:生产模板可用正则 `server_name ~^(?<sub>.+dm)\.zone$;`。
- `proxy_pass http://$module_var;` 在变量为空时会报 500 `no host in upstream`。
**不要用 `if ($var = "")` 兜底** —— `if` 在 rewrite 阶段求值,而变量是 access 阶段才写的,
合法请求会被一起误判。用 `error_page 500 502 503 = @fallback;` + `location @fallback { return 404 "MARKER"; }`。
### 7. 写 e2e 并注册进回归
新增 `tests/<name>-e2e.sh`(照 `tests/admin-users-batch-e2e.sh` 的结构:`jget` / `areq` / `ok` / `bad`
计数器),然后改 `scripts/run-local-e2e.sh`:加端口常量、加 `[N/M]` 段、加 `RCN=$?`、汇总行补一项。
口令/密钥**不进脚本**:脚本开头 `source scripts/load-env.sh`,账号态 API Key 从
`$DATA_DIR/users.json` 运行时读(`json.load(...)['alice']['api_key']`)。
用例开头必须先**清理上一轮残留**(列表 → 逐条删除),否则第二次跑就不是从零开始,
「初始状态」类断言会假失败。
## 高价值排错(症状 → 根因)
| 症状 | 根因 | 修法 |
| --- | --- | --- |
| `cargo build` 报找不到 `crates/plugin-x` | 目录建了半成品(缺 `Cargo.toml`/`lib.rs`),或在 `members` 里但目录不存在 | 要么补齐,要么从 `members` + `[workspace.dependencies]` 摘掉并把目录移走 |
| `unresolved import ipass_core::xxx` | 内核收窄后不提供该符号(移植代码的常见假设) | grep 内核真实导出,缺的原语用 `state::*` 泛型在插件内重建 |
| 插件代码全对,但线上/测试完全没反应 | gateway 的 5 处装配漏了某处(最常见:`PLUGINS` 没加 / `loc_switch` 没加分支 / 指令数组长度没 +1) | 按步骤 4 的清单逐条核对 |
| `add_phase_handler::<resolve::Handler>` 报 **private struct** | 阶段处理器定义在子模块里但没有 `pub` | `pub struct XxxHandler;` |
| 闭包返回 `Err(&str)` 报 `expected String, found &str` | `update_plugin` 的闭包错误类型是 `String`;带 `?` 的位置会自动 `From`,**尾表达式不会** | 尾表达式用 `.ok_or_else(\|\| "…".to_owned())` |
| `X does not live long enough`(`Rc<RefCell<..>>` 取业务值那一次) | 尾表达式里的 `RefMut` 临时值在局部变量**之后**才释放 → 借用比 `Rc` 活得久 | 先 `let placed = cap.borrow_mut().take();` 再 `placed.ok_or_else(...)` 作为最后一行 |
| 插件里 `domain`/`Switch` 之类找不到 | 忘了在内核 `loc.rs` 的 `Switch` 枚举加变体 | 加变体(`Switch` 是内核与插件之间的唯一契约点) |
| e2e 里新接口全部 401 | location 没开 `sso_<name> on;`,或鉴权走错通道(Admin 用 Cookie / User 用 `X-API-Key`) | 先手工 curl 确认 `sso_<name>` 生效,再核对凭据类型 |
| shell 报 `X:: unbound variable` | `$VAR` 后紧跟全角字符(`$SUB)`)被吞进变量名 | 写 `${SUB})`(本项目高频坑,e2e 里成片出现) |
| Edit 工具报成功,但 cargo 仍报同一错误 | 该工具在部分机器上「报告成功但磁盘未落盘」 | 改完 `bash grep` 复核真实磁盘;确定性整段替换**优先用 python 脚本** |
## 交付物约定
- 插件新增后,同步更新三处文档:`CLAUDE.md`(crate 清单 + 目录地图 + e2e 套数)、
`README.md`(结构树 + 端口范围)、`docs/roadmap.md`(把「待迁入」改成已完成)。
- 「不做」的决定也要写进文档(例如明确不迁入某插件、以及理由),否则下一个人会再问一遍。
- 收尾跑全量回归并给出 `rc`:`bash scripts/run-local-e2e.sh`,五套/六套全 `rc=0` 才算绿。