7 个任务 43 步,TDD:merge 纯函数与 token 比对可单测(无 nginx shm 也能 跑),I/O 壳靠 e2e。规划期对 spec 的三处修正写进 Global Constraints: payload 是嵌套 JSON 不能用 http::params;push 走分离线程短超时避免 阻塞单线程 worker;pull 需要额外的 export 出口端点。 Co-Authored-By: Claude Opus <[email protected]>
57 KiB
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) -> Authoritypub 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) -> SyncPayloadpub 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` 的字段数(安全指标,不阻断)。
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", "[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 Opus 4.8 (1M context) <[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;
/// 本部署扮演的角色。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。
fn connect(url: &str) -> Result<TcpStream, String> {
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::<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 Opus 4.8 (1M context) <[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 8 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)。
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。只需补两条:
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 Opus 4.8 (1M context) <[email protected]>"
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 结构
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/ 的普通前缀匹配):
# ---- 集群内账号同步(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 加同样一块
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; 是否有分号。
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: 提交(两个仓分别提交)
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) <[email protected]>"
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) <[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 Opus 4.8 (1M context) <[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 Opus 4.8 (1M context) <[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 Opus 4.8 (1M context) <[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 Opus 4.8 (1M context) <[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 侧跟随删除,没有残留幽灵账号。
回滚
任一步出问题,按此顺序回滚,不要跳步:
- 停同步(不需重新构建):把两个 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 - 恢复数据(Task 7 Step 1 的备份):
改完必须重启 Pod 才装载(
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' # 同理 ssozone_load/reload_shm只在启动跑):kubectl rollout restart deploy/ipass-all -n wuguirong - 回退镜像:把两个 manifest 的 image tag 改回
ipass-sso-v0.7.22/ipass-all-v0.5.2后 apply。
已知缺口(实施时不要试图"顺手修掉")
- 删除名单不从本地推导。
authority_view的deleted恒为空——本地删除后已无痕迹, 无法反推谁被删了。后果:通过管理台删除的账号不会同步,只有走apply的删除才生效。 彻底解决需要给账号加软删墓碑字段,属独立改动,不在本计划范围。 - Task 2 / Task 3 无单元测试。nginx shm 与
ngx_http_request_t在cargo test里不存在。 已把可测的部分(merge 纯函数、token 比对)单独拆出并覆盖;I/O 壳靠 e2e。 - 推送无重试。失败只记 warn,靠手动 pull 补偿。
- ipass-waf 未一并重建。它跑的是旧 core 编译的旧 .so,运行自洽; 下次升级 ipass-waf 时会顺带带上新 core。