docs(skill): ipass-core-add-plugin 补 P1/P2 协议端点族经验并去重

- 新增「协议扩展端点族」章节:兄弟模块 route() 兜底分发、零新增 crate(手写 BER / TcpStream)

- 三条实测坑:新模块 env 白名单、302 空 body→NGX_ERROR、重置类 e2e 勿动 admin 种子口令(锁定级联)

- 步骤 6 补 env 白名单铁律;排错表 +3 行;套数更新为七套;删除重复的「基准约定」段
This commit is contained in:
ssw committed 2026-09-14 19:00:15 +08:00
1 parent 4a780a4ce7
commit 7718c9cf5a
1 file changed
+43 -18
@@ -184,6 +184,8 @@ CARGO_NET_OFFLINE=true cargo build --release
- `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"; }`。
- **新模块若读环境变量(`std::env::var`),必须在 conf 的 main 上下文加 `env XXX;` 白名单**,
否则 worker 里恒读空(**`nginx.conf` 与 `nginx.test.conf` 两处都要加**)。
### 7. 写 e2e 并注册进回归
@@ -198,23 +200,6 @@ CARGO_NET_OFFLINE=true cargo build --release
### 0. 基准约定(2026-09-13 起生效,先读这条)
**内核(ipass-core)以上游 refs/ipass 为基准,本地零业务补丁**:
- 内核源码与 `refs/ipass/rust/crates/ipass-core/src` 逐字节一致;需要内核改的
先提建议(`docs/upstream-core-changes.md` 模式:A 档请上游改 / B 档插件自解),
上游采纳后 `git -C refs/ipass pull` 再同步 `src/*.rs`。
- 插件个性代码一律放**插件 crate 本地模块**(参照 plugin-sso 的 accounts.rs/
storex.rs/utilx.rs/audit.rs 四件套),身份扩展字段存 `User.extra`(flatten
透传),经 `UserExt` 强类型读写;账号操作走 `store::update_users` + `users::sync_shm`。
- 插件文件用 `store::path_in_data`(上游唯一口径);`iter_prefix_ex`/`update_extra`
等上游已提供,不要再造。
- gateway 装配要点:`[SsoPlugin, CorePlugin, DomainPlugin]`(sso 先认领身份端点)、
`CoreExt::reclaim_on_delete`(删账号回收域名)、dispatch 兜底 JSON 信封、
指令 `ipass_state/ipass_data_dir/ipass_api/ipass_proxy` + `sso_iap`(sso 特有)。
- Cargo.toml 元数据(crate 名 sso-gateway 等)保留我方:产物名 libsso_gateway.dylib
是 nginx conf / 部署脚本依赖,勿改。
## 0. 基准约定(2026-09-13 起生效,先读这条)
**内核(ipass-core)以上游 refs/ipass 为基准,本地零业务补丁**:
- 内核源码与 `refs/ipass/rust/crates/ipass-core/src` 逐字节一致;需要内核改的
先提建议(`docs/upstream-core-changes.md` 模式:A 档请上游改 / B 档插件自解),
@@ -271,6 +256,43 @@ cd refs/ipass && git fetch origin && git merge --ff-only origin/main
(`email`/`groups`/`failed_count`/`locked_until` …),**由上游改写会抹掉它们**。
两侧不要互写同一份 `users.json`;同理,`gen_id` 形状不同 ⇒ 两侧记录 id 不能互相校验。
## 协议扩展端点族(SCIM / CAS / 同步 / 密码重置 / 归属地)
把「一类协议端点」做成 plugin-sso 内的**独立模块**(`scim.rs` / `cas.rs` / `sync.rs` / `reset.rs` / `geo.rs`),
而不是往主路由表里逐条塞路径。分发靠 `api.rs` 的 `route()` **兜底段**:
```rust
_ => {
if let Some(e) = crate::scim::route(method, uri) { return Some(e); }
if let Some(e) = crate::cas::route(method, uri) { return Some(e); }
if let Some(e) = crate::reset::route(method, uri) { return Some(e); }
if let Some(e) = crate::sync::route(method, uri) { return Some(e); }
None
}
```
各模块自持 `route(method, uri) -> Option<(Guard, Handler)>`(前缀/精确匹配自定、鉴权级别自定),
`Guard`/`Handler` 用 `pub(crate)` 暴露。新增同类能力**照此扩展**,不要往主表里逐条塞。
**零新增 crate 是硬约束**(禁 crates.io/git 依赖):LDAP 不能用 `ldap3`(async/tokio 冲突)——
改为**手工 BER/ASN.1** 编码做 Simple Bind(`ldap.rs`);HTTP 拉取用标准库 `TcpStream`(`sync.rs`)。
三个必踩点(本仓 2026-09-14 实测):
1. **新模块读 env 必须进白名单**。nginx 默认剥离全部 env,worker 里 `std::env::var` 恒空。
用了 `SYNC_*` / `PASSWORD_RESET_*` / `LDAP_*` 的模块,必须在 `nginx.conf` **和** `nginx.test.conf`
的 main 上下文显式 `env XXX;`(未设置时按缺省兜底,不报错)。
2. **302 的 body 不能为空**。`http::redirect` 若用空串,`pool.create_buffer_from_str("")` 返回 `None`
→ `send_with` 返回 `NGX_ERROR` → 302 根本不发出(curl 拿不到 `Location`,CAS `?ticket=` 全空)。
给一个单空格 body 即可。
3. **重置/改密类 e2e 不得动 admin 种子口令**。种子口令(如 `123456`)过不了插件 8 位策略,
重置接口无法还原它 → 一旦改成强口令,后续套件用旧口令登录会反复失败 → 触发账号锁定(**423,600s**),
整轮回归崩掉。正确做法:**一次性账号**闭环(admin 会话 `users/create` → forgot → reset → 新口令登录 →
`users/delete`),并在 `trap ... EXIT` 里兜底清理;admin 全程不动。已锁时用
`bash scripts/seed-data.sh --force` 复原 users.json(同时清掉账号锁)。
---
## 高价值排错(症状 → 根因)
| 症状 | 根因 | 修法 |
@@ -285,10 +307,13 @@ cd refs/ipass && git fetch origin && git merge --ff-only origin/main
| 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 脚本** |
| 新模块读不到 `SYNC_*` / `PASSWORD_RESET_*` 等 env | nginx 剥离全部 env;未在 main 上下文 `env XXX;` | `nginx.conf` 与 `nginx.test.conf` 都加 `env XXX;` |
| CAS `/cas/login` 302 无 `Location` / 无 `?ticket=` | `http::redirect` 传了**空 body** → 零长 buffer 分配失败 → `NGX_ERROR` | redirect 的 body 给单空格 |
| e2e 跑到一半后续套件全 401、日志见 `423 账号已锁定` | 重置类用例改了 admin 种子口令且无法还原,反复登录失败触发账号锁 | 改一次性账号闭环;已锁时 `seed-data.sh --force` 复原 |
## 交付物约定
- 插件新增后,同步更新三处文档:`CLAUDE.md`(crate 清单 + 目录地图 + e2e 套数)、
`README.md`(结构树 + 端口范围)、`docs/roadmap.md`(把「待迁入」改成已完成)。
- 「不做」的决定也要写进文档(例如明确不迁入某插件、以及理由),否则下一个人会再问一遍。
- 收尾跑全量回归并给出 `rc`:`bash scripts/run-local-e2e.sh`,五套/六套全 `rc=0` 才算绿。
- 收尾跑全量回归并给出 `rc`:`bash scripts/run-local-e2e.sh`,七套全 `rc=0` 才算绿(第 7 套 `tests/maxkey-p1p2-e2e.sh`:SCIM/CAS/密码重置/同步/LDAP 禁用回归)。