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:
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 禁用回归)。
|
||||
Reference in new issue
Block a user