Files
sso/docs/superpowers/plans/2026-10-12-user-sync.md
adminandClaude Code 163cd91a41 fix(plan): Task 4 补 env 白名单 + 清掉全部陈旧 attribution trailer
**功能级缺陷**:Task 4 原来只加 location,没加 env 指令。sync.rs 全部配置走
std::env::var,执行位置在 nginx worker 内,而 nginx 默认清空 worker 环境变量、
只保留 main 上下文 env NAME; 显式声明的。两个仓的 nginx.conf 都已有白名单块,
都不含 IPASS_SYNC_*。

漏了不报错、只静默失效:token 恒空 → push 恒 401;side 恒空 → export 恒 400、
notify_peer 直接 return 一次都不推、pull 恒报错。fail-closed 不泄密,
但功能整个是死的,且只有 Task 7 e2e 才暴露成难以定位的 401。

顺带把计划里 5 处陈旧的 Claude Opus 4.8 trailer 全部更正。

Co-Authored-By: Claude Code <[email protected]>
2026-10-12 12:36:48 +08:00

62 KiB
Raw Permalink Blame History

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 依赖)

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<RemoteUser>, pub deleted: Vec<String> }(含 Serialize, Deserialize, Clone, Debug, Default)
    • pub struct RemoteUser { ... }(含 Serialize, Deserialize, Clone, Debug)
    • pub struct MergeReport { pub created: Vec<String>, pub updated: Vec<String>, pub deleted: Vec<String>, 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 创建文件,内容(含类型定义 + 测试,先不写实现):

//! 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<String>,
    pub salt: Option<String>,
    pub pwd_hash: Option<String>,
    pub email: Option<String>,
    pub department: Option<String>,
    pub groups: Option<String>,
    pub wx_avatar: Option<String>,
    pub wx_source: Option<String>,
    pub wx_userid: Option<String>,
    pub created_via: Option<String>,

    // ---- Authority::All 权威 ----
    pub api_key: Option<String>,
    pub allowed_models: Option<Vec<String>>,
    pub llm_rpm: Option<i64>,
    pub llm_daily: Option<i64>,
    pub role: Option<String>,
}

/// 一次同步的完整载荷:全量快照 + 删除名单。
#[derive(Serialize, Deserialize, Clone, Debug, Default)]
pub struct SyncPayload {
    pub users: Vec<RemoteUser>,
    /// 对端删掉的账号名。**只在 `from == Authority::Sso` 时被应用**——
    /// all 侧删除不外推,避免误删 IdP 账号;而 sso 删了 all 必须跟着删,
    /// 否则 all 上残留一个仍可调用 LLM 的幽灵账号。
    pub deleted: Vec<String>,
}

/// merge 结果,供接口回显与审计。
#[derive(Default, Debug, PartialEq)]
pub struct MergeReport {
    pub created: Vec<String>,
    pub updated: Vec<String>,
    pub deleted: Vec<String>,
    /// 被丢弃的越权字段数量(安全事件指标,正常应为 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<String> {
    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` 的字段数(安全指标,不阻断)。
///
/// ⚠️ 两个分支必须**对称地列全**对端权威字段。少列一个,该字段被塞进
/// payload 时就不会计入 `ignored_fields`——功能上仍安全(`merge_fields`
/// 根本不读它),但这个计数器是我们唯一的越权推送信号,漏计等于把
/// 审计指标做废。
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_avatar.is_some())
                + n(ru.wx_source.is_some())
                + n(ru.wx_userid.is_some())
                + n(ru.created_via.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", "[email protected]".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("[email protected]"));
    }

    #[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; 那一行附近,加:

pub mod sync;
  • Step 2: 运行测试,确认失败
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: 核对既有测试未被破坏
cargo test -p ipass-core --lib 2>&1 | tail -20

Expected: test result: ok. 14 passed; 0 failed(原 5 个 + 新 9 个)

  • Step 4: 提交
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 Code <[email protected]>"

Task 2: 写盘漏斗拆出 notify 参数

Files:

  • Modify: ipass-core/rust/crates/ipass-core/src/store.rs:123

Interfaces:

  • Consumes: crate::sync
  • Produces:
    • pub fn update_users<T, F>(f: F) -> Result<T, String>(行为不变,等价 notify=true)
    • pub fn update_users_with_notify<T, F>(f: F, notify: bool) -> Result<T, String>
    • pub fn update_users_quiet<T, F>(f: F) -> Result<T, String>

⚠️ 本任务无法单元测试: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):

/// 加锁「读-改-写」账号表,并在写盘后通知对端同步。
///
/// 闭包返回 `Ok(T)` 表示提交,`Err(msg)` 表示放弃(不写盘)。
pub fn update_users<T, F>(f: F) -> Result<T, String>
where
    F: FnOnce(&mut UserTable) -> Result<T, String>,
{
    update_users_with_notify(f, true)
}

/// 同 `update_users`,但 `notify = false` 时**不通知对端**。
///
/// merge 走这条路。merge 只写**对端权威**字段,本侧权威字段一个字节都没动,
/// 所以本侧本就无需重推——不需要抑制标志、不需要时间戳、也不会误伤并发请求。
pub fn update_users_quiet<T, F>(f: F) -> Result<T, String>
where
    F: FnOnce(&mut UserTable) -> Result<T, String>,
{
    update_users_with_notify(f, false)
}

/// `update_users` 的真正实现。
///
/// `notify` 为真且写盘成功后,把**写后的表**交给同步层推送(不重读文件)。
/// 推送失败绝不影响本次写盘的返回值:同步是尽力而为,不能让建号/改密
/// 因为对端不可达而失败。
pub fn update_users_with_notify<T, F>(f: F, notify: bool) -> Result<T, String>
where
    F: FnOnce(&mut UserTable) -> Result<T, String>,
{
    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)] 之前):

// ===========================================================================
// 传输与通知
// ===========================================================================

use std::io::{Read, Write};
use std::net::{TcpStream, ToSocketAddrs};

/// 本部署扮演的角色。env 未配置 = 同步关闭(fail-closed)。
pub fn local_authority() -> Option<Authority> {
    match std::env::var("IPASS_SYNC_SIDE").ok()?.trim() {
        "sso" => Some(Authority::Sso),
        "all" => Some(Authority::All),
        _ => None,
    }
}

fn sync_token() -> Option<String> {
    let t = std::env::var("IPASS_SYNC_TOKEN").ok()?;
    if t.is_empty() { None } else { Some(t) }
}

fn peer_url() -> Option<String> {
    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<MergeReport, String> {
    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<String, String> {
    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::<u16>().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。
///
/// ⚠️ 必须用 `connect_timeout(&SocketAddr, dur)`,**不能**先
/// `TcpStream::connect()` 再 `set_connect_timeout()`——后者在 connect
/// 返回之后才调用,完全约束不了连接耗时:DNS 解析 + SYN 重试会一直
/// 挂到 OS 默认 TCP 超时(约 2 分钟),代码注释承诺的「300ms 连接」
/// 就是假的。故先解析出 SocketAddr 再带超时逐个尝试。
fn connect(url: &str) -> Result<TcpStream, String> {
    let (host, port, _) = split_url(url)?;
    let addrs: Vec<std::net::SocketAddr> = (host.as_str(), port)
        .to_socket_addrs()
        .map_err(|e| format!("解析 {host} 失败:{e}"))?
        .collect();
    if addrs.is_empty() {
        return Err(format!("{host} 未解析到任何地址"));
    }
    let mut last = String::from("无可用地址");
    for addr in &addrs {
        match TcpStream::connect_timeout(addr, std::time::Duration::from_millis(300)) {
            Ok(s) => {
                s.set_read_timeout(Some(std::time::Duration::from_millis(800))).ok();
                s.set_write_timeout(Some(std::time::Duration::from_millis(800))).ok();
                return Ok(s);
            }
            Err(e) => last = e.to_string(),
        }
    }
    Err(format!("连接 {host}:{port} 失败:{last}"))
}

/// 读完整响应。有 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::<u16>().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::<usize>().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: 编译检查
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: 确认既有测试仍通过
cargo test -p ipass-core --lib 2>&1 | tail -12

Expected: 14 passed; 0 failed

  • Step 5: 提交
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 Code <[email protected]>"

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 7 e2e 验证。 鉴权逻辑(token 比对)刻意做成可单测的纯函数 sync::token_matches,见 Step 1。

  • Step 1: 加 token 比对与 authority 投影

在 sync.rs 的 sync_token() 之后插入:

/// 常量时间比对 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 里追加:

    #[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 } 改为:

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) { ... } 之后)加一支:

        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), 之后加:

        ("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 末尾追加:

// ===========================================================================
// 集群内同步(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)。
///
/// ⚠️ **必须发裸 `SyncPayload`,不能用 `http::ok`**。`http::ok` 会包成
/// `{code,data,msg}` 信封,而对端 `sync::pull_from_peer` 是
/// `serde_json::from_str::<SyncPayload>` 直接解顶层 `users`/`deleted`——
/// serde 忽略未知的 `code`/`data`/`msg`,随后因缺 `users` 字段报错,
/// **pull 每次都必然失败**(且只在 Task 7 端到端才暴露)。
/// 同步链路是机器对机器、自带 token 鉴权,不该耦合管理台信封格式;
/// 信封形状是会变的(壳现在读 `data.plugins`)。
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);
    match serde_json::to_string(&payload) {
        Ok(body) => http::send(r, HTTPStatus::OK, &body),
        Err(e) => http::fail(r, HTTPStatus::INTERNAL_SERVER_ERROR, &format!("序列化同步载荷失败:{e}")),
    }
}

/// 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,
                }),
                "拉取合并完成",
            )
        }
        // pull 失败统一报 500 而非 502:失败原因不止「对端转发失败」,还包含
        // 载荷解析失败、本侧写盘失败等,502 会把后两者误述成网关问题。
        Err(e) => http::fail(r, HTTPStatus::INTERNAL_SERVER_ERROR, &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。只需补两条:

use crate::store;
use crate::sync;

加在现有的 use crate::state; / use crate::users; 那组里(保持字母序)。

  • Step 6: 编译 + 测试
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: 提交
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 Code <[email protected]>"

Task 4: nginx 来源限制(两个仓)

Files:

  • Modify: ipass-sso/deploy/nginx.conf
  • Modify: ipass-all/deploy/nginx.conf

Interfaces:

  • Consumes: IPASS_SYNC_SIDE / IPASS_SYNC_PEER / IPASS_SYNC_TOKEN(Task 5 写进 Deployment env)
  • Produces: /api/admin/sync/ 只接受集群内来源,且三个 env 在 worker 里可见

⚠️ ipass-all 复用的是同一条仓内路径依赖,无需额外处理。

  • Step 1: 给两个仓的 nginx.conf 加 env 白名单(漏了则整个功能静默失效)

⚠️ 本步最容易被漏,且漏了不会报错、只会静默失效。

sync.rs 全部配置读的是 std::env::var(...),执行位置在 nginx worker 进程内。 nginx 默认把 worker 的环境变量清空,只有在 main 上下文用 env NAME; 显式声明的 才会保留。两个仓的 nginx.conf 都已有 env 白名单块(ipass-sso 第 24-38 行、 ipass-all 第 27-35 行),注释里就写着「漏一条 = worker 里恒空」。

不补这三条的后果(全部 fail-closed,不会泄密,但功能整个是死的): IPASS_SYNC_TOKEN 为空 → token_matches("", got) 恒 false → 每次 push 都 401; IPASS_SYNC_SIDE 为空 → local_authority() 返回 None → export 恒 400、 notify_peer 直接 return,一次都不会推;pull 恒报错。

在 ipass-sso 的 env 白名单末尾追加(env WXWORK_REDIRECT; 之后):

# 集群内账号同步(ipass-all ↔ ipass-sso)—— 不声明则 worker 里恒空,
# 表现为 push 恒 401 / export 恒 400 / 从不推送,且没有任何报错
env IPASS_SYNC_SIDE;
env IPASS_SYNC_PEER;
env IPASS_SYNC_TOKEN;

在 ipass-all 的 env 白名单末尾追加(env PASSWORD_RESET_TTL; 之后)——内容完全相同:

# 集群内账号同步(ipass-all ↔ ipass-sso)—— 不声明则 worker 里恒空,
# 表现为 push 恒 401 / export 恒 400 / 从不推送,且没有任何报错
env IPASS_SYNC_SIDE;
env IPASS_SYNC_PEER;
env IPASS_SYNC_TOKEN;

校验:

cd /Users/xs/Documents/ipass/ipass-sso && grep -c 'env IPASS_SYNC' deploy/nginx.conf   # 期望 3
cd /Users/xs/Documents/ipass/ipass-all && grep -c 'env IPASS_SYNC' deploy/nginx.conf   # 期望 3

⚠️ 三条必须在 main 上下文(与既有 env 同级,缩进 0)。写进 http {} 或 server {} 里 nginx 启动即报 unknown directive。

  • Step 2: 查清 ipass-sso 的 nginx.conf 结构
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 3: 在 ipass-sso 加 location

在 location /api/ 块之前插入(更长的前缀优先于 /api/ 的普通前缀匹配):

        # ---- 集群内账号同步(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 4: 在 ipass-all 加同样一块
cd /Users/xs/Documents/ipass/ipass-all
grep -n "location /api/\|ipass_api on" deploy/nginx.conf | head

在 location /api/ 块之前插入完全相同的内容(缩进对齐该文件既有 server 块的层级)。

  • Step 5: 校验语法

nginx 不在本机,只能靠人工核对缩进与 deny all; 是否有分号。

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 6: 提交(两个仓分别提交)
cd /Users/xs/Documents/ipass/ipass-sso
git add deploy/nginx.conf
git commit -m "feat(sync): 同步端点限定集群内来源 + 放行三个 env

push 的请求体带全量 salt + pwd_hash + api_key,不该出集群。nginx 层
allow/deny 与 SyncToken 头是两道独立的门,任一道漏了另一道还在。

同时补 env 白名单:sync.rs 在 worker 里读 std::env::var,nginx 默认清空
worker 环境变量,不声明这三条则 token/side/peer 恒空——push 恒 401、
export 恒 400、从不推送,且不报任何错。

Co-Authored-By: Claude Code <[email protected]>"
cd /Users/xs/Documents/ipass/ipass-all
git add deploy/nginx.conf
git commit -m "feat(sync): 同步端点限定集群内来源 + 放行三个 env

push 的请求体带全量 salt + pwd_hash + api_key,不该出集群。nginx 层
allow/deny 与 SyncToken 头是两道独立的门,任一道漏了另一道还在。

同时补 env 白名单:sync.rs 在 worker 里读 std::env::var,nginx 默认清空
worker 环境变量,不声明这三条则 token/side/peer 恒空——push 恒 401、
export 恒 400、从不推送,且不报任何错。

Co-Authored-By: Claude Code <[email protected]>"

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

python3 -c "import secrets; print(secrets.token_hex(32))"

把输出记为 <TOKEN>。它会出现在后面的 manifest 与本次终端历史里—— 若在意,改用 xop run --secret 注入,或事后统一轮换。

  • Step 2: 找准 env 插入点
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 空格):

            # ---- 集群内账号同步(对端 = 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: "<TOKEN>"
  • Step 4: 给 ipass-all 加三个 env
            # ---- 集群内账号同步(对端 = 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: "<TOKEN>"
  • Step 5: 校验 YAML 能解析
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 <file>。

  • Step 6: 提交(两个仓分别提交)
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 Code <[email protected]>"
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 Code <[email protected]>"

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 树完好
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:

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 镜像
cd /Users/xs/Documents/ipass/ipass-all
TAG=ipass-all-v0.6.0 bash deploy/build.sh

当前线上是 ipass-all-v0.5.2。

  • Step 4: 确认两个镜像都已推送成功
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
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 变更
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 Code <[email protected]>"
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 Code <[email protected]>"

Task 7: 部署与端到端验证

Files: 无代码改动

Interfaces:

  • Consumes: Task 6 的镜像

  • Produces: 集群内可用的同步链路 + 验证结论

  • Step 1: 先备份两边的 users.json

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
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 起来了且端点存在
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
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
TOKEN='<Task 5 生成的 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: 先做一次手动全量对齐(必须)
# 在 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: 验证收敛
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 管理台改一个测试账号的密码,然后:

kubectl exec -n wuguirong $A -- grep -o "wuguirong" /usr/local/nginx/data/users.json | head -1

Expected: 有输出。改密码后不需要重启、不需要手动 reload——密码走磁盘读路径。

  • Step 9: 验证 reload 端点
curl -s -X POST -b "admin_cookie=<cookie>" http://$A_IP:18097/api/admin/reload; echo

Expected: {"keys": 22, ...},且所有会话仍然有效(这是它相对 /api/admin/restart 的核心优势)。

  • Step 10: 验证删除传播(用测试账号,别用真人)

在 ipass-sso 删掉那个测试账号,等几秒后:

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 关闭。
    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 的备份):
    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 只在启动跑):
    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。