From 8079982ba8f44d7e3085bb80fc44bd38662d5701 Mon Sep 17 00:00:00 2001 From: ssw Date: Sun, 13 Sep 2026 10:23:25 +0800 Subject: [PATCH] =?UTF-8?q?chore:=20=E6=94=BE=E8=A1=8C=20.workbuddy/skills?= =?UTF-8?q?/=20=E5=B9=B6=E6=96=B0=E5=A2=9E=E9=A1=B9=E7=9B=AE=E7=BA=A7?= =?UTF-8?q?=E6=8A=80=E8=83=BD=20ipass-core-add-plugin?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit .workbuddy/ 原为整体忽略(本地记忆与临时产物),但项目级技能需要随仓库 共享给团队,故改为忽略其全部内容、仅放行 .workbuddy/skills/。 注意写法:不能用 `.workbuddy/` + `!.workbuddy/skills/` —— 父目录被整体 排除后 git 不会再向下遍历,否定规则不生效;必须写 `.workbuddy/*`。 新增技能 ipass-core-add-plugin:在「内核 + 编译期插件」式 nginx Rust 工作区 (ipass-core / plugin-* / gateway 单 cdylib)里新增或从 refs/ 移植一个能力插件 的完整流程 —— 量内核边界、crate 骨架、文件分工、gateway 5 处装配、配置、 e2e 注册,附「症状 → 根因」排错表。 --- .gitignore | 7 +- .../skills/ipass-core-add-plugin/SKILL.md | 219 ++++++++++++++++++ 2 files changed, 225 insertions(+), 1 deletion(-) create mode 100644 .workbuddy/skills/ipass-core-add-plugin/SKILL.md diff --git a/.gitignore b/.gitignore index 4d7ca27..61f264f 100644 --- a/.gitignore +++ b/.gitignore @@ -23,7 +23,12 @@ # --------------------------------------------------------------------------- # 工具与临时文件 # --------------------------------------------------------------------------- -.workbuddy/ +# .workbuddy 为本地工作目录(记忆、临时产物)——整体忽略; +# 但「项目级技能」要随仓库共享给团队,故单独放行 .workbuddy/skills/ +# (注意:不能写成 `.workbuddy/` + `!.workbuddy/skills/`—— +# 父目录被整体排除后,git 不会再往下看,否定规则无效) +.workbuddy/* +!.workbuddy/skills/ .DS_Store *.log *.pid diff --git a/.workbuddy/skills/ipass-core-add-plugin/SKILL.md b/.workbuddy/skills/ipass-core-add-plugin/SKILL.md new file mode 100644 index 0000000..43be525 --- /dev/null +++ b/.workbuddy/skills/ipass-core-add-plugin/SKILL.md @@ -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-/src +``` + +`Cargo.toml`(照 `plugin-domain` 抄): + +```toml +[package] +name = "plugin-" +version.workspace = true +edition.workspace = true +publish.workspace = true +description = "……" + +[lib] +name = "plugin_" # 下划线!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-", ...] +[workspace.dependencies] +plugin- = { path = "crates/plugin-" } +``` + +> 依赖必须用 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`) | +| `.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::(cf).is_ok() + } + // 管理 API 分发:不认领就返回 None(让下一个插件试),**不要**自作主张 404 + fn dispatch_api(&self, r: *mut ngx_http_request_t) -> Option { + 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_::Plugin; // ① +static PLUGINS: &[&dyn Plugin] = &[&SsoPlugin, &Plugin]; // ② 顺序即装配顺序 +struct ModuleConfig { api: bool, iap: bool, : bool } // ③ location 开关字段 +// Merge::merge 里补 if prev. { self. = true; } +fn loc_switch(...) -> bool { match s { + Switch::Api => c.api, Switch::Iap => c.iap, Switch:: => c., + Switch::Other => false, // ④ 未实现的插件保守 false +}} +// ⑤ 指令数组:长度 +1,新增 sso_ 项 + 对应的 set_flag_ +static mut NGX_HTTP_SSO_COMMANDS: [ngx_command_t; N+1] = [...]; +``` + +`gateway/Cargo.toml` 也要加 `plugin-.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- +# 产物: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_ on;`。 + 本机没有 PCRE,**`server_name ~regex` 会被渲染脚本降级成 `server_name _`**, + 所以判 Host 的逻辑要放在插件里(按后缀 `strip_suffix`),不要依赖 `server_name` 捕获。 +- `source/conf/nginx.conf`:生产模板可用正则 `server_name ~^(?.+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/-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::` 报 **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>` 取业务值那一次) | 尾表达式里的 `RefMut` 临时值在局部变量**之后**才释放 → 借用比 `Rc` 活得久 | 先 `let placed = cap.borrow_mut().take();` 再 `placed.ok_or_else(...)` 作为最后一行 | +| 插件里 `domain`/`Switch` 之类找不到 | 忘了在内核 `loc.rs` 的 `Switch` 枚举加变体 | 加变体(`Switch` 是内核与插件之间的唯一契约点) | +| e2e 里新接口全部 401 | location 没开 `sso_ on;`,或鉴权走错通道(Admin 用 Cookie / User 用 `X-API-Key`) | 先手工 curl 确认 `sso_` 生效,再核对凭据类型 | +| 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` 才算绿。