docs(sync): ipass-all ↔ ipass-sso 用户同步设计(互推 + 热重载)
两侧各持一份不相交的 users.json(22 员工 vs 3 demo 账号),导致员工无法 用统一身份登录 IdP。 评估并否决「软链接同一份文件」:write_json 是 rename 语义且 path_of 不解析 符号链接,首次写入即摧毁链接;且 file_lock 是进程内 shm 锁,跨 Pod 零互斥。 采用互推 + 接口触发热更新: - 组件落 ipass-core(ipass-all 的 sso 插件有意关闭,端点挂 plugin-sso 不会被认领) - 分字段权威:身份字段以 sso 为准,配额字段以 all 为准,天然无回环 - ping 做成 update_users 的 notify 参数,merge 走 quiet,不靠抑制标志 - 新增 /api/admin/reload 兜底:shm 是 worker 共享的,无需重启、不丢会话 - 删除单向 sso → all,避免 all 残留可调 LLM 的幽灵账号 Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
This commit is contained in:
1 parent
ddc396c992
commit
d483c6af35
1 file changed
+220
@@ -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: F) -> Result<T, String> // notify=true ← 所有现有调用点,行为不变
|
||||
pub fn update_users_quiet<F>(f: F) -> Result<T, String> // 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 并重启。
|
||||
Reference in new issue
Block a user