diff --git a/docs/superpowers/specs/2026-10-12-user-sync-design.md b/docs/superpowers/specs/2026-10-12-user-sync-design.md new file mode 100644 index 0000000..3de447f --- /dev/null +++ b/docs/superpowers/specs/2026-10-12-user-sync-design.md @@ -0,0 +1,220 @@ +# ipass-all ↔ ipass-sso 用户同步 + 接口触发热更新 + +日期:2026-10-12 +状态:设计已定,待实施 + +## 1. 背景与问题 + +`ipass-all`(网关)与 `ipass-sso`(IdP)各自持有一份独立的 `users.json`, +挂在同一个 PVC `nginx-data` 的不同 subPath 下(`ipass-all` / `sso`),内容不相交: + +| | ipass-all | ipass-sso | +|---|---|---| +| 角色 | 网关:LLM 代理 / apix / cache / 动态域名 | 唯一 IdP:OIDC + IAP + 企微登录 | +| 用户数 | 22 个真实员工账号 | 3 个(admin / alice / wx_Rong) | +| `sso` 插件 | **关闭(有意)** | 开启 | + +后果:22 个员工在 IdP 里一个都没有,无法用统一身份登录。 + +### 1.1 为什么不能共享同一个文件 + +曾经评估过「软链接同一份 `users.json`」,**不成立**: + +1. **致命**:`store::write_json` 是 `write(tmp)` + `rename(tmp → users.json)`, + 而 `path_of` 只做 `PathBuf::join`,**不解析符号链接**。rename 到已存在的 + symlink 路径 = 替换该目录项本身。任何一侧的第一次写入就会把链接换成普通 + 文件,之后两边静默分叉——比不同步更糟。硬链接同理。 +2. subPath 挂载下容器看不到兄弟目录,软链接目标在容器内根本不存在。 +3. `state::file_lock()` 是 **shm 里的 RwLock(进程内)**,两个 Pod 两块 shm + = **零互斥**,共享同一文件必然 read-modify-write 竞态丢更新。 + +同理,共享目录 + 改写并发(CAS)虽是终局形态,但要动内核核心写路径, +失败模式是「静默丢账号」,风险高于收益。本设计走**互推 + reload**。 + +### 1.2 为什么不需要「先重启再同步」 + +`ShmRoot`(含 `RwLock`)建在 shm zone 里,所有 nginx worker 共享同一块内存。 +因此新增一个 `POST /api/admin/reload` 直接调 `users::reload_shm()`, +worker 内执行即对全部 worker 生效——**不重启 Pod、不丢会话**。 + +另外实测确认:**ipass-sso 根本不建 `ukey:` 索引**(其 `state_zone_init` 只跑 +插件 `zone_load()`),全磁盘读;而 `users.rs` 所有写路径都会 `sync_shm` 写穿。 +故 `/api/admin/reload` 定位为**兜底工具**(外部改文件 / shm 漂移), +不是同步链路的必需环节。 + +## 2. 目标 + +- 两侧账号自动收敛,身份字段以 ipass-sso 为准,配额字段以 ipass-all 为准。 +- 同步无需重启、无需人工搬运明文密码(搬 `salt` + `pwd_hash`)。 +- 新增端点全部为**新增代码**,不改变现有写路径的语义,出问题可摘钩回退。 + +## 3. 非目标 + +- 不共享文件、不引入外部数据库、不引入后台常驻进程。 +- 不做 delta 同步(只推全量快照,见 §6.1)。 +- 不做自动重试队列(补偿靠手动 pull + cron)。 +- **不打开 ipass-all 的 sso 插件**(有意关闭,保持现状)。 + +## 4. 架构 + +五个新增组件,全部落在 `ipass-core` 与部署配置: + +| 组件 | 位置 | 作用 | +|---|---|---| +| `POST /api/admin/sync/push` | `ipass-core/.../api.rs` | 收对端推来的字段更新,按权威模型 merge 进本地 `users.json` | +| `POST /api/admin/sync/pull` | 同上 | 从 `IPASS_SYNC_PEER` 拉全量并 merge(补偿手段) | +| `POST /api/admin/reload` | 同上 | 调 `users::reload_shm()`,兜底 | +| 写后 ping | `ipass-core/.../store.rs` | `update_users` 成功后 fire-and-forget 通知对端 | +| nginx location + env | 两边 `deploy/nginx.conf` / Deployment | 限制来源 + 配置 peer/token | + +### 4.1 为什么必须放 ipass-core 而非 plugin-sso + +`dispatch_api` 会跳过被禁插件。ipass-all 的 `sso` 插件**有意关闭**, +端点若挂在 plugin-sso 上,ipass-all 根本不认领,同步无从成立。 + +副作用:ipass-waf 等其他使用 ipass-core 的发行版也会带上这些端点。 +默认 **fail-closed**——env 未配 `IPASS_SYNC_PEER` 则不发 ping, +未配 `IPASS_SYNC_TOKEN` 则拒绝 push。 + +## 5. 字段契约 + +| 字段 | 权威方 | 方向 | +|---|---|---| +| `pwd_hash` `salt` | ipass-sso | sso → all | +| `email` `department` `groups` | ipass-sso | sso → all | +| `wx_avatar` `wx_source` `wx_userid` `created_via` `no_password` | ipass-sso | sso → all | +| `display_name` | ipass-sso | sso → all | +| `api_key` `allowed_models` `llm_rpm` `llm_daily` | ipass-all | all → sso | +| `role` | ipass-all | all → sso | +| `created_at` | 首次创建方 | **不覆盖** | +| `failed_count` `locked_until` | 各自本地 | **不同步**(本地安全状态) | + +合并规则:接收端**只写对端权威的列**,本地权威列一律不碰。 +推来的 payload 若含越权字段,必须被忽略(见 §10 测试 1)。 + +**处理顺序:先 upsert 全量,再应用 delete 名单。** 顺序反了会导致 +「sso 已删的用户被 upsert 复活」——自动创建逻辑(§8)会把它重新建出来。 + +### 5.1 删除传播(单向) + +**删除只从 ipass-sso 传播到 ipass-all。** sso 删除账号后 all 必须跟随, +否则 all 上残留一个**仍可调用 LLM 的幽灵账号**——这是安全问题。 +all 侧删除不外推,避免误删 IdP 账号。 + +## 6. 数据流 + +### 6.1 推全量快照,不做 delta + +每次写盘后推送**全量**账号快照(约 22 条,几 KB),接收端按权威字段幂等覆盖。 + +- 好处:无 diff 逻辑,不会漏字段,收端幂等即可 +- 代价:每次登录失败也会推一次(`failed_count` 不在权威字段列表, + 压根不会进 payload,但推送动作本身仍会触发) +- 取舍:先接受;若 push 频率成为问题再引入 delta。 + +**payload 只含推送方权威字段**,接收方的本地权威字段既不在 payload 里, +收端也不会写它。 + +### 6.2 链路示例 + +``` +sso 改密码 + → store::update_users(notify=true) 写盘 + → ping all: POST http://ipass-all...:18097/api/admin/sync/push + payload = sso 权威字段全量快照 + delete 名单 + → all: Guard::SyncToken 通过 + → update_users_quiet(notify=false) merge + → sync_shm 写穿(api_key 索引自动保持正确) + → all 不再 ping sso(notify=false) +``` + +### 6.3 配置 + +```yaml +# ipass-sso +- name: IPASS_SYNC_PEER value: "http://ipass-all.wuguirong.svc.cluster.local:18097" +- name: IPASS_SYNC_TOKEN value: "<共享随机串>" +# ipass-all(反向) +- name: IPASS_SYNC_PEER value: "http://ipass-sso.wuguirong.svc.cluster.local:18098" +- name: IPASS_SYNC_TOKEN value: "<同一个共享随机串>" +``` + +18097 / 18098 均为**明文 HTTP**,ClusterIP 同 ns 直连,不经 NodePort、不依赖外部入口。 +凭证明文写 env:本租户 SA 无 `create secret` 权限(见 k8s skill §2.6)。 + +## 7. 防回环 + +ping 挂在 `update_users` 写盘后**无条件**触发会导致无限震荡:写盘与 +「改了哪些字段」无关,merge 也会写盘。 + +正解——把通知做成参数,而非抑制标志: + +```rust +pub fn update_users(f: F) -> Result // notify=true ← 所有现有调用点,行为不变 +pub fn update_users_quiet(f: F) -> Result // notify=false ← 仅 merge 用 +``` + +逻辑上自洽:merge 只写**对端权威**字段。sso merge 时写入的是 +`api_key` / 配额(all 的权威,all 自己会推),sso 自己的身份字段 +一个字节都没动,故 sso 无需重推。不需要抑制标志、不需要时间戳、 +不会误伤并发请求。 + +## 8. 安全 + +- **鉴权**:新增 `Guard::SyncToken`,比对 `X-Sync-Token` 与 env + `IPASS_SYNC_TOKEN`,用现成的 `util::ct_eq`(防时序侧信道)。 +- **网络层**:nginx 叠一层来源限制,pod CIDR + Service CIDR 双保险: + ```nginx + location /api/admin/sync/ { + allow 10.244.0.0/16; # pod CIDR + allow 10.96.0.0/12; # Service CIDR(实测 ClusterIP 10.96–10.110) + deny all; + ipass_api on; + } + ``` +- **理由**:payload 含全量 `salt` + `pwd_hash` + `api_key`,绝不能出集群。 +- 非法 token → 401 且不泄漏原因;payload 畸形 → 400。 +- 本地不存在该账号 → **自动创建**:用推来的身份字段 + 本地新生成的 + `api_key` 与配额默认值。 + +## 9. 错误处理 + +| 情况 | 行为 | +|---|---| +| ping 失败 / 对端不可达 | **绝不阻塞业务**。fire-and-forget + `util::log_warn`。建号/改密不因同步失败而失败 | +| 同步丢失 | 手动或 cron 调 `POST /api/admin/sync/pull` 补齐(对端全量拉取并 merge) | +| 本地无该账号 | 自动创建(见 §8) | +| 非法 token / 畸形 payload | 401 / 400 | + +不做自动重试队列——YAGNI,运维手段足够。 + +## 10. 测试 + +`cargo test`,不需要起集群: + +1. **权威过滤(最关键的安全断言)**:从 sso 推来含 `api_key` 的 payload, + 断言 merge **忽略**它——越权字段打不开 LLM 门禁。 +2. **幂等**:同一 payload 连推两次,结果字节一致。 +3. **回环**:merge 走 quiet,断言不发 ping。 +4. **删除传播**:sso 的 delete 在 all 侧删账号;反向不删。 +5. **往返**:sso 权威字段经 all 中转后仍等于原始值。 + +e2e:起两个 Pod,用 curl 打真实端点验端到端。 + +## 11. 落地影响面 + +| 仓库 | 改动 | +|---|---| +| `ipass-core`(上游共享) | `api.rs` 加 3 条 route + `Guard::SyncToken`;`store.rs` 加 `update_users_quiet` + ping;`users.rs` 加 merge 函数 | +| `ipass-sso` | `deploy/nginx.conf` 加 location;`deploy/k8s/ipass-sso.yaml` 加 env;重建镜像 | +| `ipass-all` | 同上(`deploy/nginx.conf` / `deploy/k8s/ipass-all.yaml`);重建镜像 | + +⚠️ 改 ipass-core 是**上游仓**,ipass-all / ipass-sso / ipass-waf 均依赖它, +需一并重建受影响镜像。节点 `imagePullPolicy: IfNotPresent`,**必须换新 tag**。 + +## 12. 运维要点 + +- 首次上线前需**手工做一次全量对齐**(调一次 `/api/admin/sync/pull`), + 因为存量 22 vs 3 的差异不会靠增量自动补齐。 +- ping 与 pull 均应在审计日志中留痕。 +- 改 token 需同时更新两个 Deployment 的 env 并重启。 \ No newline at end of file