diff --git a/docs/superpowers/plans/2026-10-12-user-sync.md b/docs/superpowers/plans/2026-10-12-user-sync.md new file mode 100644 index 0000000..c5b7b3a --- /dev/null +++ b/docs/superpowers/plans/2026-10-12-user-sync.md @@ -0,0 +1,1521 @@ +# ipass-all ↔ ipass-sso 用户同步 Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** 让 ipass-all 与 ipass-sso 的账号自动收敛,身份字段以 ipass-sso 为准、配额字段以 ipass-all 为准,同步不需重启、不需人工搬运明文密码。 + +**Architecture:** 新增 `ipass-core/src/sync.rs`,内含**纯函数**的字段权威模型(可在无 nginx 环境单测)。写盘漏斗 `store::update_users` 拆出 `notify` 参数:普通写触发 fire-and-forget 推送,对端 merge 走 `update_users_quiet`(notify=false)从而天然无回环。新增 4 个端点 + `Guard::SyncToken`,落 ipass-core(ipass-all 的 sso 插件有意关闭,端点挂 plugin-sso 不会被认领)。 + +**Tech Stack:** Rust(`no_std` 无关,用 std)、nginx 动态模块(ngx-rust vendored)、serde_json、K8s wuguirong 租户。 + +**Spec:** `docs/superpowers/specs/2026-10-12-user-sync-design.md` + +## Global Constraints + +- **组件必须落 `ipass-core`**(`rust/crates/ipass-core/src/`),不能落 `ipass-plugin-sso`:`dispatch_api` 跳过被禁插件,ipass-all 的 `sso` 插件关闭,端点挂插件上不会被认领。 +- **端到端不得重载会话**:新增 `POST /api/admin/reload` 调 `users::reload_shm()`,不用 `POST /api/admin/restart`。 +- **payload 只含推送方权威字段**;接收端只写**对端权威**列,本地权威列一律不碰。 +- **删除单向**:`from == Authority::Sso` 时才应用 delete 名单;`Authority::All` 的删除一律忽略。 +- **处理顺序固定**:先 upsert 全量,再应用 delete 名单。反了会把已删账号复活。 +- **push 必须在分离线程执行**,绝不在 nginx worker 内同步阻塞。超时:连接 300ms / 读 800ms。 +- **同步请求体是嵌套 JSON**:不能用 `http::params`(它丢弃嵌套结构),必须 `http::collect_body` + serde_json。 +- **fail-closed 默认**:env 未配 `IPASS_SYNC_SIDE` / `IPASS_SYNC_PEER` / `IPASS_SYNC_TOKEN` 时,所有同步行为关闭。 +- **凭证明文写 env**:本租户 SA 无 `create secret` 权限。`ipass-sso-secrets`(含 + `oauth-signing-secret`)是管理员预建的、已存在,本计划不碰它;但新增的 + `IPASS_SYNC_TOKEN` 两边都没有对应 Secret 可挂,只能明文写 env。 +- **必须换新镜像 tag**:节点 `imagePullPolicy: IfNotPresent`,复用旧 tag 不刷新。 +- 代码注释与错误文案用中文,风格对齐既有文件(见 `store.rs` / `users.rs`)。 + +### 本机构建前置(TDD 依赖) + +```bash +export LIBCLANG_PATH=/Library/Developer/CommandLineTools/usr/lib +export NGINX_SOURCE_DIR=$HOME/Documents/ipass/ngxbuild/nginx-1.30.4 +export NGINX_BUILD_DIR=$NGINX_SOURCE_DIR/objs +``` + +nginx 构建树被挪过位置,`objs/Makefile` 里烤死了 `~/Desktop/workspace/ipass/ngxbuild/pcre-8.45` +的绝对路径。**已用符号链接接回**(`~/Desktop/workspace/ipass` → `~/Documents/ipass`)。 +若该链接丢失,`cargo test` 会在 nginx-sys 构建阶段报 `'pcre.h' file not found`。 +重建方式:`ln -s /Users/xs/Documents/ipass /Users/xs/Desktop/workspace/ipass` + +--- + +## File Structure + +| 文件 | 职责 | +|---|---| +| `ipass-core/rust/crates/ipass-core/src/sync.rs` | **新建**。权威模型 + 纯函数 merge + HTTP 传输。分三段:纯函数段(可单测)、传输段(碰 TCP)、通知段(碰线程) | +| `ipass-core/rust/crates/ipass-core/src/lib.rs` | 加 `pub mod sync;` | +| `ipass-core/rust/crates/ipass-core/src/store.rs` | 改:`update_users` 拆出 notify 参数 | +| `ipass-core/rust/crates/ipass-core/src/api.rs` | 改:`Guard::SyncToken` + 4 条路由 + 4 个 handler | +| `ipass-sso/deploy/nginx.conf` | 改:加 `/api/admin/sync/` location + 来源限制 | +| `ipass-sso/deploy/k8s/ipass-sso.yaml` | 改:加 3 个 env | +| `ipass-all/deploy/nginx.conf` | 改:同上 | +| `ipass-all/deploy/k8s/ipass-all.yaml` | 改:同上 | + +**模块边界**:`sync.rs` 的纯函数段只依赖 `models::UserTable` / `models::User` / `util`,**不 import `ngx`**——这样 `cargo test` 在无 nginx 环境下也能跑。传输段与通知段 import `std::net::TcpStream` / `std::thread`。 + +--- + +## Task 1: 权威模型与纯函数 merge + +**Files:** +- Create: `ipass-core/rust/crates/ipass-core/src/sync.rs` +- Modify: `ipass-core/rust/crates/ipass-core/src/lib.rs` +- Test: 内联 `#[cfg(test)] mod tests`(同文件,沿用 `plugin_registry.rs` 的既有风格) + +**Interfaces:** +- Consumes: `ipass_core::models::{User, UserTable}`、`ipass_core::util::{gen_salt, gen_key, now}`、`ipass_core::config::{LLM_RPM_DEFAULT, LLM_DAILY_DEFAULT}` +- Produces: + - `pub enum Authority { Sso, All }`,方法 `peer(self) -> Authority` + - `pub struct SyncPayload { pub users: Vec, pub deleted: Vec }`(含 `Serialize, Deserialize, Clone, Debug, Default`) + - `pub struct RemoteUser { ... }`(含 `Serialize, Deserialize, Clone, Debug`) + - `pub struct MergeReport { pub created: Vec, pub updated: Vec, pub deleted: Vec, pub ignored_fields: usize }` + - `pub fn authority_view(table: &UserTable, side: Authority) -> SyncPayload` + - `pub fn apply(local: &mut UserTable, payload: &SyncPayload, from: Authority) -> MergeReport` + +**注意**:`User` 的 `extra` 是 `#[serde(flatten)]`,`email`/`department`/`groups`/`wx_*`/`no_password` 等 +sso 专有字段都落在 `extra` 里,不在 `User` 结构体上。 + +- [ ] **Step 1: 写失败的测试** + +在 `sync.rs` 创建文件,内容(含类型定义 + 测试,先不写实现): + +```rust +//! ipass-all ↔ ipass-sso 的账号同步:字段权威模型 + 纯函数 merge。 +//! +//! **为什么要有这一层**:两个部署各自持有 `users.json`,但字段职责不同—— +//! 身份(密码 / 企微绑定)只有 ipass-sso 说得准,配额(Key / 模型 / 限额) +//! 只有 ipass-all 说得准。本模块把这个划分写死成代码,收发两端共用。 +//! +//! **为什么 merge 必须是纯函数**:nginx 的共享内存 zone 在单元测试里不存在, +//! 任何碰 `state::` 的代码都无法在 `cargo test` 中运行。把「算」与「写」 +//! 拆开,merge 部分就能被真正测到——**越权字段打不开 LLM 门禁**这条安全 +//! 断言必须能跑,否则整个方案的核心保障形同虚设。 + +use std::collections::BTreeMap; + +use serde::{Deserialize, Serialize}; + +use crate::config::{LLM_DAILY_DEFAULT, LLM_RPM_DEFAULT}; +use crate::models::{User, UserTable}; +use crate::util; + +/// 本部署扮演的角色。决定哪些字段由本侧说了算。 +#[derive(Clone, Copy, PartialEq, Eq, Debug)] +pub enum Authority { + /// ipass-sso:IdP。权威字段是身份。 + Sso, + /// ipass-all:网关。权威字段是配额。 + All, +} + +impl Authority { + /// 对端角色。 + pub fn peer(self) -> Authority { + match self { + Authority::Sso => Authority::All, + Authority::All => Authority::Sso, + } + } +} + +/// 一个账号在**对端权威范围内**的字段集合。 +/// +/// 全部字段都是 `Option`:`None` = 对端没有这个值,merge 时不动本地。 +/// 这是权威过滤的实现方式——收端只读 `from` 那一半,其余字段即使被 +/// 塞进 payload 也永远不会被读取。 +#[derive(Serialize, Deserialize, Clone, Debug, Default)] +pub struct RemoteUser { + pub username: String, + + // ---- Authority::Sso 权威 ---- + pub display_name: Option, + pub salt: Option, + pub pwd_hash: Option, + pub email: Option, + pub department: Option, + pub groups: Option, + pub wx_avatar: Option, + pub wx_source: Option, + pub wx_userid: Option, + pub created_via: Option, + + // ---- Authority::All 权威 ---- + pub api_key: Option, + pub allowed_models: Option>, + pub llm_rpm: Option, + pub llm_daily: Option, + pub role: Option, +} + +/// 一次同步的完整载荷:全量快照 + 删除名单。 +#[derive(Serialize, Deserialize, Clone, Debug, Default)] +pub struct SyncPayload { + pub users: Vec, + /// 对端删掉的账号名。**只在 `from == Authority::Sso` 时被应用**—— + /// all 侧删除不外推,避免误删 IdP 账号;而 sso 删了 all 必须跟着删, + /// 否则 all 上残留一个仍可调用 LLM 的幽灵账号。 + pub deleted: Vec, +} + +/// merge 结果,供接口回显与审计。 +#[derive(Default, Debug, PartialEq)] +pub struct MergeReport { + pub created: Vec, + pub updated: Vec, + pub deleted: Vec, + /// 被丢弃的越权字段数量(安全事件指标,正常应为 0)。 + pub ignored_fields: usize, +} + +// =========================================================================== +// 出站:抽出本侧权威字段 +// =========================================================================== + +/// 从本地账号表抽出 `side` 侧权威的字段,形成可推送的载荷。 +pub fn authority_view(table: &UserTable, side: Authority) -> SyncPayload { + let users = table + .values() + .map(|u| match side { + Authority::Sso => sso_side(u), + Authority::All => all_side(u), + }) + .collect(); + // 删除名单不从本地推导:sso 删账号时本地已无痕迹,无法反推。 + // 由调用方(`deleted_since`)在有删除事件时补齐。 + SyncPayload { users, deleted: Vec::new() } +} + +fn sso_side(u: &User) -> RemoteUser { + RemoteUser { + username: u.username.clone(), + display_name: Some(u.display_name.clone()), + salt: Some(u.salt.clone()), + pwd_hash: Some(u.pwd_hash.clone()), + email: extra_str(u, "email"), + department: extra_str(u, "department"), + groups: extra_str(u, "groups"), + wx_avatar: extra_str(u, "wx_avatar"), + wx_source: extra_str(u, "wx_source"), + wx_userid: extra_str(u, "wx_userid"), + created_via: extra_str(u, "created_via"), + ..Default::default() + } +} + +fn all_side(u: &User) -> RemoteUser { + RemoteUser { + username: u.username.clone(), + api_key: Some(u.api_key.clone()), + allowed_models: Some(u.allowed_models.clone()), + llm_rpm: Some(u.llm_rpm), + llm_daily: Some(u.llm_daily), + role: Some(u.role.clone()), + ..Default::default() + } +} + +fn extra_str(u: &User, k: &str) -> Option { + match u.extra.get(k) { + Some(serde_json::Value::String(s)) => Some(s.clone()), + // 布尔/数字型 extra(no_password)不参与本函数 + _ => None, + } +} + +// =========================================================================== +// 入站:merge(纯函数,不碰文件) +// =========================================================================== + +/// 把 `payload` 中 `from` 权威的字段 merge 进 `local`,就地修改。 +/// +/// **处理顺序:先 upsert,再删。** 反序会让「已被 sso 删除的账号」被 +/// upsert 分支的自动创建重新建出来——静默复活已注销账号。 +pub fn apply(local: &mut UserTable, payload: &SyncPayload, from: Authority) -> MergeReport { + let mut rep = MergeReport::default(); + + for ru in &payload.users { + match local.get_mut(&ru.username) { + Some(u) => { + if merge_fields(u, ru, from, &mut rep) { + rep.updated.push(ru.username.clone()); + } + } + None => { + let mut u = blank_user(&ru.username); + merge_fields(&mut u, ru, from, &mut rep); + if from == Authority::All { + // 对端是网关:它不知道 sso 的登录方式。标成免密, + // 让账号仍可走 IAP / OIDC 登录,而不是卡在无法登录。 + u.extra + .insert("no_password".to_owned(), serde_json::Value::Bool(true)); + } + local.insert(ru.username.clone(), u); + rep.created.push(ru.username.clone()); + } + } + } + + if from == Authority::Sso { + for name in &payload.deleted { + if local.remove(name).is_some() { + rep.deleted.push(name.clone()); + } + } + } else { + rep.ignored_fields += payload.deleted.len(); + } + + rep +} + +/// 只写 `from` 权威的那一半字段。返回是否真的改了东西。 +fn merge_fields( + u: &mut User, + ru: &RemoteUser, + from: Authority, + rep: &mut MergeReport, +) -> bool { + let before = u.clone(); + match from { + Authority::Sso => { + if let Some(v) = &ru.display_name { + u.display_name = v.clone(); + } + if let Some(v) = &ru.salt { + u.salt = v.clone(); + } + if let Some(v) = &ru.pwd_hash { + u.pwd_hash = v.clone(); + } + if let Some(v) = &ru.email { + put_extra(u, "email", v.clone()); + } + if let Some(v) = &ru.department { + put_extra(u, "department", v.clone()); + } + if let Some(v) = &ru.groups { + put_extra(u, "groups", v.clone()); + } + if let Some(v) = &ru.wx_avatar { + put_extra(u, "wx_avatar", v.clone()); + } + if let Some(v) = &ru.wx_source { + put_extra(u, "wx_source", v.clone()); + } + if let Some(v) = &ru.wx_userid { + put_extra(u, "wx_userid", v.clone()); + } + if let Some(v) = &ru.created_via { + put_extra(u, "created_via", v.clone()); + } + } + Authority::All => { + if let Some(v) = &ru.api_key { + u.api_key = v.clone(); + } + if let Some(v) = &ru.allowed_models { + u.allowed_models = v.clone(); + } + if let Some(v) = ru.llm_rpm { + u.llm_rpm = v; + } + if let Some(v) = ru.llm_daily { + u.llm_daily = v; + } + if let Some(v) = &ru.role { + u.role = v.clone(); + } + } + } + // 越权字段计数:payload 里带了不属于 from 的字段 = 可疑载荷。 + rep.ignored_fields += count_foreign(ru, from); + before != *u +} + +/// 统计 payload 中不属于 `from` 的字段数(安全指标,不阻断)。 +fn count_foreign(ru: &RemoteUser, from: Authority) -> usize { + let n = |present: bool| usize::from(present); + match from { + Authority::Sso => { + n(ru.api_key.is_some()) + + n(ru.allowed_models.is_some()) + + n(ru.llm_rpm.is_some()) + + n(ru.llm_daily.is_some()) + + n(ru.role.is_some()) + } + Authority::All => { + n(ru.pwd_hash.is_some()) + + n(ru.salt.is_some()) + + n(ru.display_name.is_some()) + + n(ru.email.is_some()) + + n(ru.department.is_some()) + + n(ru.groups.is_some()) + + n(ru.wx_userid.is_some()) + } + } +} + +fn put_extra(u: &mut User, k: &str, v: String) { + u.extra.insert(k.to_owned(), serde_json::Value::String(v)); +} + +/// 新账号的本地默认。非权威字段由本侧生成,对端到了也会被覆盖。 +fn blank_user(username: &str) -> User { + User { + username: username.to_owned(), + display_name: String::new(), + role: "user".to_owned(), + salt: util::gen_salt(), + pwd_hash: String::new(), + api_key: util::gen_key(), + allowed_models: Vec::new(), + llm_rpm: LLM_RPM_DEFAULT, + llm_daily: LLM_DAILY_DEFAULT, + temp_grant_until: 0, + created_at: util::now(), + extra: BTreeMap::new(), + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn mk_user(name: &str) -> User { + let mut u = blank_user(name); + u.display_name = "旧名".to_owned(); + u.salt = "salt-local".to_owned(); + u.pwd_hash = "hash-local".to_owned(); + u.api_key = "sk_local".to_owned(); + u.role = "user".to_owned(); + u + } + + fn table_of(names: &[&str]) -> UserTable { + let mut t = UserTable::new(); + for n in names { + t.insert((*n).to_owned(), mk_user(n)); + } + t + } + + #[test] + fn merge_from_sso_does_not_touch_api_key() { + // 安全断言:sso 推来的 payload 即使塞了 api_key,也打不开 LLM 门禁。 + let mut local = table_of(&["alice"]); + let payload = SyncPayload { + users: vec![RemoteUser { + username: "alice".to_owned(), + pwd_hash: Some("hash-from-sso".to_owned()), + api_key: Some("sk_injected".to_owned()), + ..Default::default() + }], + deleted: vec![], + }; + let rep = apply(&mut local, &payload, Authority::Sso); + let alice = &local["alice"]; + assert_eq!(alice.pwd_hash, "hash-from-sso", "sso 权威字段应被写入"); + assert_eq!(alice.api_key, "sk_local", "api_key 属 all 权威,必须原样保留"); + assert_eq!(rep.ignored_fields, 1, "越权字段应被计入 ignored_fields"); + } + + #[test] + fn merge_from_all_does_not_touch_password() { + let mut local = table_of(&["alice"]); + let payload = SyncPayload { + users: vec![RemoteUser { + username: "alice".to_owned(), + api_key: Some("sk_from_all".to_owned()), + pwd_hash: Some("injected".to_owned()), + salt: Some("injected".to_owned()), + ..Default::default() + }], + deleted: vec![], + }; + let rep = apply(&mut local, &payload, Authority::All); + let alice = &local["alice"]; + assert_eq!(alice.api_key, "sk_from_all"); + assert_eq!(alice.pwd_hash, "hash-local", "密码属 sso 权威,必须原样保留"); + assert_eq!(alice.salt, "salt-local"); + assert_eq!(rep.ignored_fields, 2); + } + + #[test] + fn apply_is_idempotent() { + let mut a = table_of(&["alice", "bob"]); + let payload = SyncPayload { + users: vec![ + RemoteUser { username: "alice".to_owned(), pwd_hash: Some("h".to_owned()), ..Default::default() }, + RemoteUser { username: "bob".to_owned(), pwd_hash: Some("h2".to_owned()), ..Default::default() }, + ], + deleted: vec![], + }; + apply(&mut a, &payload, Authority::Sso); + let once = serde_json::to_string(&a).unwrap(); + apply(&mut a, &payload, Authority::Sso); + assert_eq!(once, serde_json::to_string(&a).unwrap(), "同一 payload 推两次结果必须一致"); + } + + #[test] + fn delete_after_upsert_does_not_resurrect() { + // 顺序回归:bob 已在 sso 侧删除,但全量快照里若仍带着他, + // 也不能被 upsert 分支重新建出来。 + let mut local = table_of(&["alice"]); + let payload = SyncPayload { + users: vec![RemoteUser { username: "bob".to_owned(), pwd_hash: Some("h".to_owned()), ..Default::default() }], + deleted: vec!["bob".to_owned()], + }; + apply(&mut local, &payload, Authority::Sso); + assert!(!local.contains_key("bob"), "先 upsert 后 delete,bob 最终必须不存在"); + } + + #[test] + fn delete_from_all_is_ignored() { + let mut local = table_of(&["alice", "bob"]); + let payload = SyncPayload { + users: vec![], + deleted: vec!["bob".to_owned()], + }; + apply(&mut local, &payload, Authority::All); + assert!(local.contains_key("bob"), "all 的删除不得外推删掉 IdP 账号"); + } + + #[test] + fn apply_creates_missing_user_from_all_is_passwordless() { + let mut local = table_of(&["alice"]); + let payload = SyncPayload { + users: vec![RemoteUser { + username: "carol".to_owned(), + api_key: Some("sk_carol".to_owned()), + ..Default::default() + }], + deleted: vec![], + }; + let rep = apply(&mut local, &payload, Authority::All); + let carol = local.get("carol").expect("carol 应被自动创建"); + assert_eq!(carol.api_key, "sk_carol"); + assert_eq!( + carol.extra.get("no_password"), + Some(&serde_json::Value::Bool(true)), + "由 all 创建的账号必须免密,否则在 sso 上无法登录" + ); + assert_eq!(rep.created, vec!["carol".to_owned()]); + } + + #[test] + fn round_trip_preserves_sso_fields() { + let mut origin = table_of(&["alice"]); + origin.get_mut("alice").unwrap().display_name = "爱丽丝".to_owned(); + put_extra(origin.get_mut("alice").unwrap(), "email", "a@x.cn".to_owned()); + + // alice 经 all 中转到 sso + let sso_out = authority_view(&origin, Authority::Sso); + let mut via_all = table_of(&["alice"]); + apply(&mut via_all, &sso_out, Authority::Sso); + let all_out = authority_view(&via_all, Authority::All); + let mut back = table_of(&["alice"]); + apply(&mut back, &all_out, Authority::All); + + let a = &back["alice"]; + assert_eq!(a.pwd_hash, origin["alice"].pwd_hash); + assert_eq!(a.salt, origin["alice"].salt); + assert_eq!(a.display_name, "爱丽丝"); + assert_eq!(extra_str(a, "email").as_deref(), Some("a@x.cn")); + } + + #[test] + fn authority_view_only_emits_own_fields() { + let t = table_of(&["alice"]); + let sso_out = authority_view(&t, Authority::Sso); + let r = &sso_out.users[0]; + assert!(r.api_key.is_none(), "sso 出站不得携带 api_key"); + assert!(r.llm_rpm.is_none(), "sso 出站不得携带限额"); + + let all_out = authority_view(&t, Authority::All); + let r = &all_out.users[0]; + assert!(r.api_key.is_some()); + assert!(r.pwd_hash.is_none(), "all 出站不得携带密码哈希"); + } + + #[test] + fn merge_does_not_alter_local_authoritative_fields() { + // 防回环的数据级断言(spec §10.3)。all 侧收到 sso 的推送后, + // 它的**权威字段**(api_key / 配额 / role)必须一个字节都没变—— + // 没有新东西可推,于是不会重推,回环在数据层就终止了。 + // + // 这比「断言不发 ping」更根本:ping 是 I/O 行为,改 transport 就会失效; + // 而「本地权威字段没被 merge 动过」是 merge 的固有性质,改不动。 + let mut local = table_of(&["alice"]); + let before = authority_view(&local, Authority::All); + + let payload = SyncPayload { + users: vec![RemoteUser { + username: "alice".to_owned(), + pwd_hash: Some("new-hash".to_owned()), + display_name: Some("新名".to_owned()), + salt: Some("new-salt".to_owned()), + ..Default::default() + }], + deleted: vec![], + }; + apply(&mut local, &payload, Authority::Sso); + + let after = authority_view(&local, Authority::All); + assert_eq!( + before.users[0].api_key, after.users[0].api_key, + "merge 不该动本地权威字段 api_key" + ); + assert_eq!(before.users[0].llm_rpm, after.users[0].llm_rpm); + assert_eq!(before.users[0].llm_daily, after.users[0].llm_daily); + assert_eq!(before.users[0].role, after.users[0].role); + // 顺带确认 sso 权威字段确实落了(否则上面的相等可能是"什么都没改") + assert_eq!(local["alice"].pwd_hash, "new-hash"); + } +} +``` + +同时在 `lib.rs` 加模块声明。找到 `pub mod store;` 那一行附近,加: + +```rust +pub mod sync; +``` + +- [ ] **Step 2: 运行测试,确认失败** + +```bash +cd /Users/xs/Documents/ipass/ipass-core/rust +export LIBCLANG_PATH=/Library/Developer/CommandLineTools/usr/lib +export NGINX_SOURCE_DIR=$HOME/Documents/ipass/ngxbuild/nginx-1.30.4 +export NGINX_BUILD_DIR=$NGINX_SOURCE_DIR/objs +cargo test -p ipass-core --lib sync:: 2>&1 | tail -20 +``` + +Expected: 9 个测试全部 ok(实现与测试同文件写入,故本步实际是验证通过)。 +若报 `'pcre.h' file not found`,说明符号链接丢失,重建之。 + +- [ ] **Step 3: 核对既有测试未被破坏** + +```bash +cargo test -p ipass-core --lib 2>&1 | tail -20 +``` + +Expected: `test result: ok. 14 passed; 0 failed`(原 5 个 + 新 9 个) + +- [ ] **Step 4: 提交** + +```bash +cd /Users/xs/Documents/ipass/ipass-core +git add rust/crates/ipass-core/src/sync.rs rust/crates/ipass-core/src/lib.rs +git commit -m "feat(sync): 字段权威模型与纯函数 merge + +ipass-all 与 ipass-sso 各持一份 users.json,字段职责不同:身份只有 +ipass-sso 说得准,配额只有 ipass-all 说得准。本模块把划分写死成代码。 + +merge 做成不碰 state::/ngx 的纯函数,这样「越权字段打不开 LLM 门禁」 +这条安全断言能在 cargo test 里真正跑起来——nginx 的共享内存 zone +在单元测试里不存在,任何碰它的代码都测不了。 + +Co-Authored-By: Claude Opus 4.8 (1M context) " +``` + +--- + +## Task 2: 写盘漏斗拆出 notify 参数 + +**Files:** +- Modify: `ipass-core/rust/crates/ipass-core/src/store.rs:123` + +**Interfaces:** +- Consumes: `crate::sync` +- Produces: + - `pub fn update_users(f: F) -> Result`(行为不变,等价 notify=true) + - `pub fn update_users_with_notify(f: F, notify: bool) -> Result` + - `pub fn update_users_quiet(f: F) -> Result` + +**⚠️ 本任务无法单元测试**:`update_users` 依赖 `state::file_lock()`,而它读的是 nginx shm zone +里的 `RwLock`,在 `cargo test` 中 `root()` 返回 `None`。只能靠 `cargo check` + Task 8 的 e2e 验证。 +这是已知且接受的缺口——不要为了"能测"而把锁抽象掉,那会动到内核的并发正确性。 + +- [ ] **Step 1: 改 store.rs** + +把 `update_users` 整个替换为下面三段(原函数在 `store.rs:123`): + +```rust +/// 加锁「读-改-写」账号表,并在写盘后通知对端同步。 +/// +/// 闭包返回 `Ok(T)` 表示提交,`Err(msg)` 表示放弃(不写盘)。 +pub fn update_users(f: F) -> Result +where + F: FnOnce(&mut UserTable) -> Result, +{ + update_users_with_notify(f, true) +} + +/// 同 `update_users`,但 `notify = false` 时**不通知对端**。 +/// +/// merge 走这条路。merge 只写**对端权威**字段,本侧权威字段一个字节都没动, +/// 所以本侧本就无需重推——不需要抑制标志、不需要时间戳、也不会误伤并发请求。 +pub fn update_users_quiet(f: F) -> Result +where + F: FnOnce(&mut UserTable) -> Result, +{ + update_users_with_notify(f, false) +} + +/// `update_users` 的真正实现。 +/// +/// `notify` 为真且写盘成功后,把**写后的表**交给同步层推送(不重读文件)。 +/// 推送失败绝不影响本次写盘的返回值:同步是尽力而为,不能让建号/改密 +/// 因为对端不可达而失败。 +pub fn update_users_with_notify(f: F, notify: bool) -> Result +where + F: FnOnce(&mut UserTable) -> Result, +{ + let _guard = state::file_lock().ok_or("内部错误:状态锁不可用")?; + let mut data = read_users(); + let out = f(&mut data)?; + write_users(&data)?; + drop(_guard); + if notify { + crate::sync::notify_peer(&data); + } + Ok(out) +} +``` + +- [ ] **Step 2: 加同步层的传输与通知段** + +追加到 `sync.rs` 末尾(**在 `#[cfg(test)]` 之前**): + +```rust +// =========================================================================== +// 传输与通知 +// =========================================================================== + +use std::io::{Read, Write}; +use std::net::TcpStream; + +/// 本部署扮演的角色。env 未配置 = 同步关闭(fail-closed)。 +pub fn local_authority() -> Option { + match std::env::var("IPASS_SYNC_SIDE").ok()?.trim() { + "sso" => Some(Authority::Sso), + "all" => Some(Authority::All), + _ => None, + } +} + +fn sync_token() -> Option { + let t = std::env::var("IPASS_SYNC_TOKEN").ok()?; + if t.is_empty() { None } else { Some(t) } +} + +fn peer_url() -> Option { + let u = std::env::var("IPASS_SYNC_PEER").ok()?; + if u.is_empty() { None } else { Some(u.trim_end_matches('/').to_owned()) } +} + +/// 写盘后触发推送。**绝不阻塞调用方**。 +/// +/// nginx worker 是单线程的,一次失败的同步会把整个 worker 卡住 700ms, +/// 而 `users.json` 在登录失败(记 `failed_count`)时也会写盘——那会让真实 +/// 登录被拖慢。故分离线程 + 短超时,worker 只付「clone 一份表」的代价。 +pub fn notify_peer(table: &UserTable) { + let (Some(side), Some(peer), Some(token)) = (local_authority(), peer_url(), sync_token()) else { + return; // 未配置 = 同步关闭 + }; + let payload = authority_view(table, side); + let body = match serde_json::to_string(&payload) { + Ok(b) => b, + Err(e) => { + util::log_warn(&format!("[sync] 序列化同步载荷失败:{e}")); + return; + } + }; + let url = format!("{peer}/api/admin/sync/push"); + std::thread::spawn(move || { + if let Err(e) = post_json(&url, &body, &token) { + util::log_warn(&format!("[sync] 推送对端失败(不影响本次写盘):{e}")); + } + }); +} + +/// 从对端拉全量并 merge 到本地(补偿手段,供手动 / cron 调用)。 +pub fn pull_from_peer() -> Result { + let (Some(side), Some(peer), Some(token)) = (local_authority(), peer_url(), sync_token()) else { + return Err("未配置 IPASS_SYNC_SIDE / IPASS_SYNC_PEER / IPASS_SYNC_TOKEN".to_owned()); + }; + let url = format!("{peer}/api/admin/sync/export"); + let body = get_with_token(&url, &token)?; + let payload: SyncPayload = + serde_json::from_str(&body).map_err(|e| format!("解析对端载荷失败:{e}"))?; + let from = side.peer(); + let mut report = MergeReport::default(); + crate::store::update_users_quiet(|local| { + report = apply(local, &payload, from); + Ok(()) + })?; + Ok(report) +} + +/// 极简 HTTP POST(明文 HTTP,集群内 ClusterIP 直连)。 +/// 只发同步载荷这么小的请求体,不引第三方 HTTP 客户端(零外部依赖硬约束)。 +fn post_json(url: &str, body: &str, token: &str) -> Result<(u16, String), String> { + let mut s = connect(url)?; + let req = format!( + "POST {path} HTTP/1.1\r\nHost: {host}\r\nConnection: close\r\n\ + Content-Type: application/json\r\nContent-Length: {len}\r\n\ + X-Sync-Token: {token}\r\n\r\n{body}", + path = path_of(url), + host = host_of(url), + len = body.len(), + ); + s.write_all(req.as_bytes()).map_err(|e| e.to_string())?; + read_response(&mut s) +} + +/// 极简 HTTP GET,带 token 头。 +fn get_with_token(url: &str, token: &str) -> Result { + let mut s = connect(url)?; + let req = format!( + "GET {path} HTTP/1.1\r\nHost: {host}\r\nConnection: close\r\n\ + X-Sync-Token: {token}\r\n\r\n", + path = path_of(url), + host = host_of(url), + ); + s.write_all(req.as_bytes()).map_err(|e| e.to_string())?; + let (_, body) = read_response(&mut s)?; + Ok(body) +} + +/// 拆 `http://host:port/path`。仅支持明文 HTTP——同步只走集群内 ClusterIP, +/// 出集群的路径不走这里。 +fn split_url(url: &str) -> Result<(String, u16, String), String> { + let rest = url + .strip_prefix("http://") + .ok_or_else(|| format!("同步地址必须是 http://(集群内 ClusterIP):{url}"))?; + let (hostport, path) = match rest.split_once('/') { + Some((h, p)) => (h, format!("/{p}")), + None => (rest, "/".to_owned()), + }; + let (host, port) = match hostport.rsplit_once(':') { + Some((h, p)) => (h.to_owned(), p.parse::().map_err(|_| format!("端口非法:{p}"))?), + None => (hostport.to_owned(), 80), + }; + Ok((host, port, path)) +} + +fn host_of(url: &str) -> String { + split_url(url).map(|(h, _, _)| h).unwrap_or_default() +} + +fn path_of(url: &str) -> String { + split_url(url).map(|(_, _, p)| p).unwrap_or_else(|_| "/".to_owned()) +} + +/// 连接 + 设置超时。**超时必须短**:这是 worker 之外的后台线程, +/// 但线程数会随写盘次数增长,连接悬挂会拖垮 pod。 +fn connect(url: &str) -> Result { + let (host, port, _) = split_url(url)?; + let stream = TcpStream::connect((host.as_str(), port)).map_err(|e| e.to_string())?; + stream.set_connect_timeout(Some(std::time::Duration::from_millis(300))).ok(); + stream.set_read_timeout(Some(std::time::Duration::from_millis(800))).ok(); + stream.set_write_timeout(Some(std::time::Duration::from_millis(800))).ok(); + Ok(stream) +} + +/// 读完整响应。有 Content-Length 就精确截取,否则用 Connection: close 读到 EOF。 +fn read_response(s: &mut TcpStream) -> Result<(u16, String), String> { + let mut buf = Vec::new(); + s.read_to_end(&mut buf).map_err(|e| e.to_string())?; + let text = String::from_utf8_lossy(&buf).into_owned(); + let (head, body) = text + .split_once("\r\n\r\n") + .ok_or_else(|| "响应格式异常".to_owned())?; + let status = head + .lines() + .next() + .and_then(|l| l.split_whitespace().nth(1)) + .and_then(|c| c.parse::().ok()) + .unwrap_or(0); + let cl = head.lines().find_map(|l| { + if l.len() >= 15 && l[..15].eq_ignore_ascii_case("content-length:") { + l[15..].trim().parse::().ok() + } else { + None + } + }); + let body = match cl { + Some(n) if body.len() >= n => body[..n].to_owned(), + _ => body.to_owned(), + }; + Ok((status, body)) +} +``` + +- [ ] **Step 3: 编译检查** + +```bash +cd /Users/xs/Documents/ipass/ipass-core/rust +export LIBCLANG_PATH=/Library/Developer/CommandLineTools/usr/lib +export NGINX_SOURCE_DIR=$HOME/Documents/ipass/ngxbuild/nginx-1.30.4 +export NGINX_BUILD_DIR=$NGINX_SOURCE_DIR/objs +cargo check -p ipass-core 2>&1 | tail -20 +``` + +Expected: 无 error。若报 unused import 等 warning,可忽略(仓库已有既有 warning)。 + +- [ ] **Step 4: 确认既有测试仍通过** + +```bash +cargo test -p ipass-core --lib 2>&1 | tail -12 +``` + +Expected: `14 passed; 0 failed` + +- [ ] **Step 5: 提交** + +```bash +cd /Users/xs/Documents/ipass/ipass-core +git add rust/crates/ipass-core/src/store.rs rust/crates/ipass-core/src/sync.rs +git commit -m "feat(sync): 写盘漏斗拆出 notify 参数 + 推送传输 + +update_users 保持原签名与行为(notify=true),新增 update_users_quiet +供 merge 使用。推送走分离线程 + 300ms/800ms 短超时——nginx worker 单 +线程,内联阻塞会在对端不可达时把真实登录拖慢 700ms。 + +推送失败绝不影响写盘返回值:同步尽力而为,不让建号/改密因对端挂掉而失败。 + +Co-Authored-By: Claude Opus 4.8 (1M context) " +``` + +--- + +## Task 3: Guard::SyncToken 与四个端点 + +**Files:** +- Modify: `ipass-core/rust/crates/ipass-core/src/api.rs` + +**Interfaces:** +- Consumes: `crate::sync::{apply, authority_view, pull_from_peer, local_authority, Authority, SyncPayload}`、`crate::users::reload_shm`、`crate::util::ct_eq`、`crate::http::collect_body` +- Produces: + - `Guard::SyncToken` 变体 + - `("POST", "/api/admin/sync/push")` → `Guard::SyncToken` + - `("GET", "/api/admin/sync/export")` → `Guard::SyncToken` + - `("POST", "/api/admin/sync/pull")` → `Guard::Admin` + - `("POST", "/api/admin/reload")` → `Guard::Admin` + +**⚠️ 本任务无法单元测试**:handler 依赖 `*mut ngx_http_request_t`。靠 `cargo check` + Task 8 e2e 验证。 +鉴权逻辑(token 比对)刻意做成可单测的纯函数 `sync::token_matches`,见 Step 1。 + +- [ ] **Step 1: 加 token 比对与 authority 投影** + +在 `sync.rs` 的 `sync_token()` 之后插入: + +```rust +/// 常量时间比对 token。抽成纯函数以便单测——鉴权是这套机制唯一的门。 +pub fn token_matches(expected: &str, got: &str) -> bool { + if expected.is_empty() || got.is_empty() { + return false; + } + util::ct_eq(expected, got) +} +``` + +在 `sync.rs` 的 `#[cfg(test)] mod tests` 里追加: + +```rust + #[test] + fn token_matches_rejects_empty_and_mismatch() { + assert!(token_matches("abc", "abc")); + assert!(!token_matches("abc", "abd")); + assert!(!token_matches("", ""), "未配置 token 必须 fail-closed"); + assert!(!token_matches("abc", ""), "缺失 token 必须拒绝"); + } +``` + +- [ ] **Step 2: 扩展 Guard 枚举** + +`api.rs` 中 `pub enum Guard { Public, User, Admin }` 改为: + +```rust +pub enum Guard { + Public, + User, + Admin, + /// 集群内同步专用:比对 `X-Sync-Token` 与 `IPASS_SYNC_TOKEN`。 + /// 与 Admin 严格分开——sync/push 会写入账号表并携带全量密码哈希, + /// 不该被任何管理员会话拿到。 + SyncToken, +} +``` + +- [ ] **Step 3: 在 run_guarded 里处理新变体** + +`run_guarded` 的 `match guard {` 末尾(`Guard::Admin => match authenticate_admin(r) { ... }` 之后)加一支: + +```rust + Guard::SyncToken => { + let expected = std::env::var("IPASS_SYNC_TOKEN").unwrap_or_default(); + let got = http::header(r, "x-sync-token").unwrap_or_default(); + if !crate::sync::token_matches(&expected, &got) { + // 不说"token 错"还是"没带"——避免探测 + return http::fail(r, HTTPStatus::UNAUTHORIZED, "同步鉴权失败"); + } + Actor::None + } +``` + +- [ ] **Step 4: 加四条路由** + +在 `route()` 的 `("GET", "/api/v1/me") => (Guard::User, h_me),` 之后加: + +```rust + ("POST", "/api/admin/sync/push") => (Guard::SyncToken, h_sync_push), + ("GET", "/api/admin/sync/export") => (Guard::SyncToken, h_sync_export), + ("POST", "/api/admin/sync/pull") => (Guard::Admin, h_sync_pull), + ("POST", "/api/admin/reload") => (Guard::Admin, h_admin_reload), +``` + +- [ ] **Step 5: 加四个 handler** + +在 `api.rs` 末尾追加: + +```rust +// =========================================================================== +// 集群内同步(ipass-all ↔ ipass-sso) +// =========================================================================== + +/// POST /api/admin/sync/push —— 收对端推来的账号字段。 +/// +/// 请求体是**嵌套 JSON**,不能用 `http::params`——它把嵌套对象与数组直接 +/// 丢弃(`_ => continue`),推来的账号列表会变成空。这里走 collect_body +/// 自己解析。 +fn h_sync_push(r: *mut ngx_http_request_t, _actor: Actor) -> Status { + let Some(side) = sync::local_authority() else { + return http::fail(r, HTTPStatus::BAD_REQUEST, "本部署未配置 IPASS_SYNC_SIDE"); + }; + let body = unsafe { http::collect_body(r) }; + let payload: sync::SyncPayload = match serde_json::from_slice(&body) { + Ok(p) => p, + Err(e) => return http::fail(r, HTTPStatus::BAD_REQUEST, &format!("载荷不是合法 JSON:{e}")), + }; + let from = side.peer(); + + let mut report = sync::MergeReport::default(); + let res = store::update_users_quiet(|local| { + report = sync::apply(local, &payload, from); + Ok(()) + }); + if let Err(e) = res { + return http::fail(r, HTTPStatus::INTERNAL_SERVER_ERROR, &format!("合并失败:{e}")); + } + + util::log_notice(&format!( + "[sync] push 来自 {}:新增 {} / 更新 {} / 删除 {} / 丢弃越权字段 {}", + match from { sync::Authority::Sso => "sso", sync::Authority::All => "all" }, + report.created.len(), + report.updated.len(), + report.deleted.len(), + report.ignored_fields + )); + if report.ignored_fields > 0 { + util::log_warn(&format!( + "[sync] 载荷含 {} 个不属于对端权威的字段,已丢弃(疑似越权推送)", + report.ignored_fields + )); + } + + http::ok( + r, + json!({ + "created": report.created, + "updated": report.updated, + "deleted": report.deleted, + "ignored_fields": report.ignored_fields, + }), + "同步已合并", + ) +} + +/// GET /api/admin/sync/export —— 导出本侧权威字段(供对端 pull)。 +fn h_sync_export(r: *mut ngx_http_request_t, _actor: Actor) -> Status { + let Some(side) = sync::local_authority() else { + return http::fail(r, HTTPStatus::BAD_REQUEST, "本部署未配置 IPASS_SYNC_SIDE"); + }; + let payload = sync::authority_view(&store::read_users(), side); + http::ok(r, json!({ + "users": payload.users, + "deleted": payload.deleted, + }), "导出本侧权威字段") +} + +/// POST /api/admin/sync/pull —— 主动从对端拉全量并合并(补偿手段)。 +fn h_sync_pull(r: *mut ngx_http_request_t, _actor: Actor) -> Status { + match sync::pull_from_peer() { + Ok(rep) => { + util::log_notice(&format!( + "[sync] pull 完成:新增 {} / 更新 {} / 删除 {}", + rep.created.len(), + rep.updated.len(), + rep.deleted.len() + )); + http::ok( + r, + json!({ + "created": rep.created, + "updated": rep.updated, + "deleted": rep.deleted, + "ignored_fields": rep.ignored_fields, + }), + "拉取合并完成", + ) + } + Err(e) => http::fail(r, HTTPStatus::BAD_GATEWAY, &e), + } +} + +/// POST /api/admin/reload —— 重建 Key 索引共享内存。 +/// +/// **为什么不是 `/api/admin/restart`**:restart 走 SIGTERM → K8s Recreate, +/// shm 里所有会话作废、全员重新登录、服务中断。`ShmRoot` 在共享内存 zone 里、 +/// 所有 worker 共享同一块,故 worker 内直接 `reload_shm()` 即刻对全部 worker +/// 生效——不重启、不掉会话。 +fn h_admin_reload(r: *mut ngx_http_request_t, _actor: Actor) -> Status { + let n = users::reload_shm(); + util::log_notice(&format!("[api] 已重建 {n} 个账号的 Key 索引")); + http::ok(r, json!({ "keys": n }), &format!("已重建 {n} 个账号 Key 索引")) +} +``` + +补 import。`api.rs` 顶部**已有**这些,不用重复加:`ngx::core::Status`、 +`ngx::ffi::ngx_http_request_t`、`ngx::http::HTTPStatus`、`serde_json::{Value, json}`、 +`crate::http`、`crate::users`、`crate::util`。**只需补两条**: + +```rust +use crate::store; +use crate::sync; +``` + +加在现有的 `use crate::state;` / `use crate::users;` 那组里(保持字母序)。 + +- [ ] **Step 6: 编译 + 测试** + +```bash +cd /Users/xs/Documents/ipass/ipass-core/rust +export LIBCLANG_PATH=/Library/Developer/CommandLineTools/usr/lib +export NGINX_SOURCE_DIR=$HOME/Documents/ipass/ngxbuild/nginx-1.30.4 +export NGINX_BUILD_DIR=$NGINX_SOURCE_DIR/objs +cargo test -p ipass-core --lib 2>&1 | tail -15 +``` + +Expected: `15 passed; 0 failed`(14 + token_matches) + +- [ ] **Step 7: 提交** + +```bash +cd /Users/xs/Documents/ipass/ipass-core +git add rust/crates/ipass-core/src/api.rs rust/crates/ipass-core/src/sync.rs +git commit -m "feat(sync): Guard::SyncToken + push/export/pull/reload 四端点 + +push 会写入账号表并携带全量密码哈希,用独立的 SyncToken 门而非管理员 +会话,且比对走常量时间。payload 是嵌套 JSON——http::params 会把嵌套 +结构丢弃,必须自己解析。 + +reload 调 reload_shm() 而非 restart:shm 在共享内存 zone 里、worker +共享,秒级生效且不掉会话;restart 会 SIGTERM 重建并让全员重新登录。 + +Co-Authored-By: Claude Opus 4.8 (1M context) " +``` + +--- + +## Task 4: nginx 来源限制(两个仓) + +**Files:** +- Modify: `ipass-sso/deploy/nginx.conf` +- Modify: `ipass-all/deploy/nginx.conf` + +**Interfaces:** +- Consumes: 无(纯配置) +- Produces: `/api/admin/sync/` 只接受集群内来源 + +**⚠️ ipass-all 复用的是同一条仓内路径依赖,无需额外处理。** + +- [ ] **Step 1: 查清 ipass-sso 的 nginx.conf 结构** + +```bash +cd /Users/xs/Documents/ipass/ipass-sso +grep -n "location /api/\|ipass_api on" deploy/nginx.conf | head +``` + +Expected: 能看到 `location /api/ { ipass_api on; }` 之类的既有块。 + +- [ ] **Step 2: 在 ipass-sso 加 location** + +在 `location /api/` 块**之前**插入(更长的前缀优先于 `/api/` 的普通前缀匹配): + +```nginx + # ---- 集群内账号同步(ipass-all ↔ ipass-sso)---- + # 只接受集群内来源:pod CIDR + Service CIDR 双保险。 + # 理由——sync/push 的请求体带全量 salt + pwd_hash + api_key, + # 绝不能出集群。nginx 层与 SyncToken 头是两道独立的门。 + 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; + } +``` + +- [ ] **Step 3: 在 ipass-all 加同样一块** + +```bash +cd /Users/xs/Documents/ipass/ipass-all +grep -n "location /api/\|ipass_api on" deploy/nginx.conf | head +``` + +在 `location /api/` 块之前插入**完全相同**的内容(缩进对齐该文件既有 server 块的层级)。 + +- [ ] **Step 4: 校验语法** + +nginx 不在本机,只能靠人工核对缩进与 `deny all;` 是否有分号。 + +```bash +cd /Users/xs/Documents/ipass/ipass-sso && grep -n -A 9 "集群内账号同步" deploy/nginx.conf +cd /Users/xs/Documents/ipass/ipass-all && grep -n -A 9 "集群内账号同步" deploy/nginx.conf +``` + +Expected: 两个文件都能打印出完整的 9 行块。 + +- [ ] **Step 5: 提交(两个仓分别提交)** + +```bash +cd /Users/xs/Documents/ipass/ipass-sso +git add deploy/nginx.conf +git commit -m "feat(sync): /api/admin/sync/ 限定集群内来源 + +push 的请求体带全量 salt + pwd_hash + api_key,不该出集群。nginx 层 +allow/deny 与 SyncToken 头是两道独立的门,任一道漏了另一道还在。 + +Co-Authored-By: Claude Opus 4.8 (1M context) " +``` + +```bash +cd /Users/xs/Documents/ipass/ipass-all +git add deploy/nginx.conf +git commit -m "feat(sync): /api/admin/sync/ 限定集群内来源 + +push 的请求体带全量 salt + pwd_hash + api_key,不该出集群。nginx 层 +allow/deny 与 SyncToken 头是两道独立的门,任一道漏了另一道还在。 + +Co-Authored-By: Claude Opus 4.8 (1M context) " +``` + +--- + +## Task 5: K8s env(两个仓) + +**Files:** +- Modify: `ipass-sso/deploy/k8s/ipass-sso.yaml` +- Modify: `ipass-all/deploy/k8s/ipass-all.yaml` + +**Interfaces:** +- Consumes: `IPASS_SYNC_SIDE` / `IPASS_SYNC_PEER` / `IPASS_SYNC_TOKEN` +- Produces: 两个部署互相可达的同步配置 + +- [ ] **Step 1: 生成共享 token** + +```bash +python3 -c "import secrets; print(secrets.token_hex(32))" +``` + +把输出记为 ``。**它会出现在后面的 manifest 与本次终端历史里**—— +若在意,改用 `xop run --secret` 注入,或事后统一轮换。 + +- [ ] **Step 2: 找准 env 插入点** + +```bash +cd /Users/xs/Documents/ipass/ipass-sso +grep -n "OAUTH_ISSUER" -A 2 -B 2 deploy/k8s/ipass-sso.yaml | head -12 +cd /Users/xs/Documents/ipass/ipass-all +grep -n "env:" -A 6 deploy/k8s/ipass-all.yaml | head -20 +``` + +- [ ] **Step 3: 给 ipass-sso 加三个 env** + +在 ipass-sso 的 `env:` 块里加(**实测既有条目是 12 空格缩进**,`env:` 本身在 10 空格): + +```yaml + # ---- 集群内账号同步(对端 = ipass-all)---- + - name: IPASS_SYNC_SIDE + value: "sso" + - name: IPASS_SYNC_PEER + value: "http://ipass-all.wuguirong.svc.cluster.local:18097" + - name: IPASS_SYNC_TOKEN + value: "" +``` + +- [ ] **Step 4: 给 ipass-all 加三个 env** + +```yaml + # ---- 集群内账号同步(对端 = ipass-sso)---- + - name: IPASS_SYNC_SIDE + value: "all" + - name: IPASS_SYNC_PEER + value: "http://ipass-sso.wuguirong.svc.cluster.local:18098" + - name: IPASS_SYNC_TOKEN + value: "" +``` + +- [ ] **Step 5: 校验 YAML 能解析** + +```bash +python3 -c "import yaml,sys; d=yaml.safe_load(open('/Users/xs/Documents/ipass/ipass-sso/deploy/k8s/ipass-sso.yaml')); print('ipass-sso OK')" +python3 -c "import yaml,sys; d=yaml.safe_load(open('/Users/xs/Documents/ipass/ipass-all/deploy/k8s/ipass-all.yaml')); print('ipass-all OK')" +``` + +Expected: 两个 OK。若 `yaml` 模块缺失,改用 `kubectl apply --dry-run=client -f `。 + +- [ ] **Step 6: 提交(两个仓分别提交)** + +```bash +cd /Users/xs/Documents/ipass/ipass-sso +git add deploy/k8s/ipass-sso.yaml +git commit -m "feat(sync): 部署同步 env(side/peer/token) + +Co-Authored-By: Claude Opus 4.8 (1M context) " +``` + +```bash +cd /Users/xs/Documents/ipass/ipass-all +git add deploy/k8s/ipass-all.yaml +git commit -m "feat(sync): 部署同步 env(side/peer/token) + +Co-Authored-By: Claude Opus 4.8 (1M context) " +``` + +--- + +## Task 6: 构建并推送镜像 + +**Files:** 无代码改动 + +**Interfaces:** +- Consumes: Task 1–5 的全部改动 +- Produces: 阿里云 CR 上三个新 tag + +**⚠️ ipass-core 是上游共享仓,ipass-all / ipass-sso / ipass-waf 三个发行版都依赖它。** +只重建前两个会让 ipass-waf 的 `.so` 与新的 core 不一致——但 waf 没有触发 +sync 的代码路径(env 未配 = fail-closed),且它不重建就仍是旧 core 编译的旧 .so, +**运行上自洽**。因此本次只重建 ipass-all 与 ipass-sso,ipass-waf 留待下次一并升级。 + +- [ ] **Step 1: 确认 nginx 树完好** + +```bash +ls -d $HOME/Documents/ipass/ngxbuild/nginx-1.30.4 && ls -d $HOME/Desktop/workspace/ipass +``` + +Expected: 两个路径都存在。 + +- [ ] **Step 2: 构建 + 推送 ipass-sso 镜像** + +两个仓都有现成的 `deploy/build.sh`(内置 dist 收集 + BuildKit `--build-context` +注入兄弟仓 + push),用 `TAG=` 覆盖 tag: + +```bash +cd /Users/xs/Documents/ipass/ipass-sso +TAG=ipass-sso-v0.8.0 bash deploy/build.sh +``` + +tag 必须是**新的**(`IfNotPresent` 不刷新旧 tag)。当前线上是 `ipass-sso-v0.7.22`。 +ipass-core 的改动经 `--build-context ipass-core=$IPASS_DIR/ipass-core` 自动带进去。 + +- [ ] **Step 3: 构建 + 推送 ipass-all 镜像** + +```bash +cd /Users/xs/Documents/ipass/ipass-all +TAG=ipass-all-v0.6.0 bash deploy/build.sh +``` + +当前线上是 `ipass-all-v0.5.2`。 + +- [ ] **Step 4: 确认两个镜像都已推送成功** + +```bash +grep -n "^IMAGE=\|^TAG=" /Users/xs/Documents/ipass/ipass-sso/deploy/build.sh +docker images --format '{{.Repository}}:{{.Tag}}' | grep ssw188/nginx | grep -E 'v0.8.0|v0.6.0' +``` + +Expected: 两个新 tag 都在本地(build.sh 走的是 `docker build` 非 buildx, +成功后本地可见,且 push 已执行)。仓库固定 +`crpi-yscq976uwza88qap.cn-shenzhen.personal.cr.aliyuncs.com/ssw188/nginx`。 + +- [ ] **Step 5: 更新两个 manifest 的 image tag** + +```bash +cd /Users/xs/Documents/ipass/ipass-sso +sed -i '' 's|ipass-sso-v0\.7\.22|ipass-sso-v0.8.0|' deploy/k8s/ipass-sso.yaml +grep -n "image:" deploy/k8s/ipass-sso.yaml + +cd /Users/xs/Documents/ipass/ipass-all +sed -i '' 's|ipass-all-v0\.5\.2|ipass-all-v0.6.0|' deploy/k8s/ipass-all.yaml +grep -n "image:" deploy/k8s/ipass-all.yaml +``` + +- [ ] **Step 6: 提交 tag 变更** + +```bash +cd /Users/xs/Documents/ipass/ipass-sso && git add deploy/k8s/ipass-sso.yaml && git commit -m "chore: 镜像 tag 升 v0.7.22 → v0.8.0(含账号同步) + +Co-Authored-By: Claude Opus 4.8 (1M context) " +cd /Users/xs/Documents/ipass/ipass-all && git add deploy/k8s/ipass-all.yaml && git commit -m "chore: 镜像 tag 升 v0.5.2 → v0.6.0(含账号同步) + +Co-Authored-By: Claude Opus 4.8 (1M context) " +``` + +--- + +## Task 7: 部署与端到端验证 + +**Files:** 无代码改动 + +**Interfaces:** +- Consumes: Task 6 的镜像 +- Produces: 集群内可用的同步链路 + 验证结论 + +- [ ] **Step 1: 先备份两边的 users.json** + +```bash +export KUBECONFIG=/Users/xs/.kube/kubeconfig-wuguirong +A=$(kubectl get pod -n wuguirong -l app=ipass-all -o jsonpath='{.items[0].metadata.name}') +S=$(kubectl get pod -n wuguirong -l app=ipass-sso -o jsonpath='{.items[0].metadata.name}') +mkdir -p ~/ipass-sync-backup-20261012 +kubectl exec -n wuguirong $A -- cat /usr/local/nginx/data/users.json > ~/ipass-sync-backup-20261012/all-users.json +kubectl exec -n wuguirong $S -- cat /usr/local/nginx/data/users.json > ~/ipass-sync-backup-20261012/sso-users.json +wc -l ~/ipass-sync-backup-20261012/*.json +``` + +Expected: 两个文件都非空。**这一步不能跳**——merge 会自动创建缺失账号,操作写错无法回滚。 + +- [ ] **Step 2: 部署 ipass-sso** + +```bash +kubectl apply -f /Users/xs/Documents/ipass/ipass-sso/deploy/k8s/ipass-sso.yaml +kubectl rollout status deploy/ipass-sso -n wuguirong --timeout=120s +``` + +- [ ] **Step 3: 验证 ipass-sso 起来了且端点存在** + +```bash +S_IP=$(kubectl get pod -n wuguirong -l app=ipass-sso -o jsonpath='{.items[0].status.podIP}') +curl -s -o /dev/null -w "export(无token): %{http_code}\n" http://$S_IP:18098/api/admin/sync/export +``` + +Expected: **401**(端点存在,鉴权拦住)。404 说明镜像没更新成功。 + +- [ ] **Step 4: 部署 ipass-all** + +```bash +kubectl apply -f /Users/xs/Documents/ipass/ipass-all/deploy/k8s/ipass-all.yaml +kubectl rollout status deploy/ipass-all -n wuguirong --timeout=120s +``` + +- [ ] **Step 5: 验证带正确 token 能拉到 export** + +```bash +TOKEN='' +A_IP=$(kubectl get pod -n wuguirong -l app=ipass-all -o jsonpath='{.items[0].status.podIP}') +curl -s -H "X-Sync-Token: $TOKEN" http://$A_IP:18097/api/admin/sync/export | head -c 300; echo +``` + +Expected: 返回 `{"code":0,"data":{"users":[...]}}`,且**看不到任何 `pwd_hash` / `salt`** +(all 是非权威侧,出站只带配额字段)。若看到密码哈希,说明权威过滤写反了,**停下排查**。 + +- [ ] **Step 6: 先做一次手动全量对齐(必须)** + +```bash +# 在 ipass-sso 上登录管理台拿 cookie,再调 pull +curl -s -X POST -b "admin_cookie=<从登录拿到的>" \ + http://$S_IP:18098/api/admin/sync/pull | head -c 500; echo +``` + +Expected: `created` 里有 ipass-all 上的账号。**存量 22 vs 3 的差异靠增量补不齐,必须手工拉一次。** + +- [ ] **Step 7: 验证收敛** + +```bash +kubectl exec -n wuguirong $S -- sh -c 'python3 -c "import json;d=json.load(open(\"/usr/local/nginx/data/users.json\"));print(len(d), sorted(d)[:5])"' 2>/dev/null \ + || kubectl exec -n wuguirong $S -- sh -c 'grep -o "\"username\"" /usr/local/nginx/data/users.json | wc -l' +``` + +Expected: 账号数 ≥ 22(原 3 + 新增)。 + +- [ ] **Step 8: 验证双向闭环(改密码 → 自动同步)** + +在 ipass-sso 管理台改一个测试账号的密码,然后: + +```bash +kubectl exec -n wuguirong $A -- grep -o "wuguirong" /usr/local/nginx/data/users.json | head -1 +``` + +Expected: 有输出。**改密码后不需要重启、不需要手动 reload**——密码走磁盘读路径。 + +- [ ] **Step 9: 验证 reload 端点** + +```bash +curl -s -X POST -b "admin_cookie=" http://$A_IP:18097/api/admin/reload; echo +``` + +Expected: `{"keys": 22, ...}`,且**所有会话仍然有效**(这是它相对 `/api/admin/restart` 的核心优势)。 + +- [ ] **Step 10: 验证删除传播(用测试账号,别用真人)** + +在 ipass-sso 删掉那个测试账号,等几秒后: + +```bash +kubectl exec -n wuguirong $A -- grep -c "wuguirong" /usr/local/nginx/data/users.json || echo "已删除(符合预期)" +``` + +Expected: `已删除` —— all 侧跟随删除,没有残留幽灵账号。 + +--- + +## 回滚 + +任一步出问题,按此顺序回滚,**不要跳步**: + +1. **停同步(不需重新构建)**:把两个 Deployment 的 `IPASS_SYNC_SIDE` 置空 → 重建 Pod。 + `local_authority()` 返回 `None` → 所有同步路径 fail-closed 关闭。 + ```bash + kubectl set env deploy/ipass-sso -n wuguirong IPASS_SYNC_SIDE= --overwrite + kubectl set env deploy/ipass-all -n wuguirong IPASS_SYNC_SIDE= --overwrite + kubectl rollout status deploy/ipass-sso -n wuguirong --timeout=120s + kubectl rollout status deploy/ipass-all -n wuguirong --timeout=120s + ``` +2. **恢复数据**(Task 7 Step 1 的备份): + ```bash + kubectl cp ~/ipass-sync-backup-20261012/all-users.json wuguirong/$A:/tmp/all-users.json + kubectl exec -n wuguirong $A -- sh -c 'cp /tmp/all-users.json /usr/local/nginx/data/users.json' + # 同理 sso + ``` + 改完**必须重启 Pod 才装载**(`zone_load` / `reload_shm` 只在启动跑): + ```bash + kubectl rollout restart deploy/ipass-all -n wuguirong + ``` +3. **回退镜像**:把两个 manifest 的 image tag 改回 `ipass-sso-v0.7.22` / `ipass-all-v0.5.2` 后 apply。 + +--- + +## 已知缺口(实施时不要试图"顺手修掉") + +1. **删除名单不从本地推导**。`authority_view` 的 `deleted` 恒为空——本地删除后已无痕迹, + 无法反推谁被删了。后果:**通过管理台删除的账号不会同步**,只有走 `apply` 的删除才生效。 + 彻底解决需要给账号加软删墓碑字段,属独立改动,不在本计划范围。 +2. **Task 2 / Task 3 无单元测试**。nginx shm 与 `ngx_http_request_t` 在 `cargo test` 里不存在。 + 已把可测的部分(merge 纯函数、token 比对)单独拆出并覆盖;I/O 壳靠 e2e。 +3. **推送无重试**。失败只记 warn,靠手动 pull 补偿。 +4. **ipass-waf 未一并重建**。它跑的是旧 core 编译的旧 .so,运行自洽; + 下次升级 ipass-waf 时会顺带带上新 core。 \ No newline at end of file