Files
sso/docs/upstream-sync-2026-09-13.md
T
ssw 912c21a442 docs: 上游 ipass 插件化落地(ddd4172)第二轮一致性核对
- 上游 P0-P5 已同源插件化,Plugin trait 三回调与我方同构,trait 层零适配可合流
- 域名插件第一轮结论全部维持:8 路由 7 条一致、DomainEntry 逐字相同、domains.json 可互换
- 真分歧收敛为两类:内核边界属定位分歧(身份在内核 vs 身份即插件),建议项维持
  (update_plugin 三泛型、dispatch 兜底改 JSON 信封,上游实现可直抄)
- 技能第 8 节前提更新:先探明上游形态再选对照口径
2026-09-13 16:34:54 +08:00

15 KiB
Raw Blame History

与上游 ipass 的一致性核对(2026-09-13)

上游仓库:http://192.168.1.18:13300/ssw/ipass → 拉到本地 refs/ipass。 本次核对分两轮:

  • 第一轮:1f548ac → 1fb83e4(2 个新提交,当时上游仍为单体,见第 0–6 节)。
  • 第二轮:上游随后推送 P0–P5 插件化落地(ddd4172),逐文件对照见第 6 节(第 0 节「上游仍是单体」的前提已过时,仅保留作第一轮记录)。

0. 先澄清一个前提

「插件化」只发生在本仓库(ssw/sso)。 refs/ipass 到 1fb83e4 仍是单体结构:

refs/ipass/rust/src/*.rs        # 单体,17 个模块
(无 crates/、无 gateway/、Cargo.toml 无 members)

且上游完全没有 SSO/OAuth 代码(grep "/oauth/token"、"sso_sid"、"fn h_login" 均无命中)—— 两边的分工是「ipass = 流量网关(admin + llm + apix + domains)/ssw-sso = 身份层」。

所以「一致性」的正确问法是:插件化之后,我方语义是否仍与上游等价? 结论:等价。下面把「上游这两笔新改动」与「我方移植范围的逐模块差异」分开说。


1. 上游这两笔新改动:对我们零影响

commit 内容
dbee9ff fix(admin): 登录页因会话探测 401 被通用兜底重定向,导致自刷新死循环
1fb83e4 feat(admin/apix): 编辑改弹出卡片 + API 代理去「市场」概念 + 修示例地址拼接

落点全部是 apix(API 代理)与管理台前端:

  • config.rs:只改 KEY_AX_PREFIX / APIX_* 相关注释与常量说明。
  • models.rs:只改 ApiProxyStore / ApiProxy——由「一个市场 + 全局 base/key」改为 「每条记录自带 base + key + supplier + asset_id」,删掉 price_* 快照字段。
  • api.rs:删掉两条路由 POST /api/admin/apix/platform、POST /api/admin/apix/price 及其处理器;h_admin_apix 不再回 platform。
  • store.rs / conf/nginx.conf / www/* / tests/llm/*:apix 域的描述与前端。

我方移植的范围内(内核 / 域名插件 / SSO)没有被碰过任何一行。


2. 域名插件 plugin-domain:一致,3 处边界分歧

核对方式:把两侧模块路径归一(crate::config:: ≡ keys::、ipass_core::state:: ≡ crate::state:: …), 再对函数体做逐函数 diff。

项目 结果
常量 完全一致:ENTERPRISE_ZONE / sub: / i / dm / 8 位 / SUBDOMAIN_MAX_LEN=62 / 保留名 4 个 / TEMP_DOMAIN_TTL=6h / REJECTED_PURGE_TTL=7d / 尝试次数 5
domains.rs 函数清单 1:1 对应,共 21 个
函数体 差异全是机械改写:收窄内核的 update_plugin 闭包要求返回整表,我方用 Rc<RefCell<Option<..>>> 捕获业务值 + list.clone()
DomainEntry + effective_status / is_forwardable 逐字一致
8 个 API 处理器 仅 actor.admin_name() → 内联 match;Actor::User(User) → Actor::User(String)(只需 username)
鉴权 dispatch 一致:Admin 走会话 Cookie(非管理员 403 / 无会话 401);User 走 X-API-Key(401)
临时授权判定 user.has_temp_permission(now) ≡ extra_i64("temp_grant_until") > now(缺省 0 → false)✓

分歧 1:purge 路径不同 | 建议对齐

路径
上游 POST /api/admin/purge
我方 POST /api/admin/domains/purge

来历:该路径在我方仓库首次出现于 P2 移植提交 a988cc3(git log -S 可证),不是历史遗留。 上游前端不调用它,只有 refs/ipass/tests/gateway/e2e.sh 用;我方只有 tests/domain-e2e.sh 用。 → 影响面小,但「两侧路由表对不上」会让后续照文档写脚本的人踩空,建议统一。

分歧 2:热路径的子域名提取方式(我方有意加固,非漂移)

做法 非本 zone 的 Host
上游 subdomain_of:取 Host 第一段标签(split('.').next()),不校验 zone 当子域名查表 → 未命中 404
我方 strip_suffix(".mayishangshu.cn"),取剩余部分 DECLINED 放行,交给别的 location

生产用正则 server_name ~^(?<subdomain>.+dm)\.mayishangshu\.cn$ 时两者等价。 我方更严格,且更适合「一台机器挂多个域(SSO 面 + 域名面)」的部署——这是为本机无 PCRE(渲染脚本把 server_name ~regex 降级成 _)做的有意加固。保留我方实现。

分歧 3:变量兜底 get_handler(我方少一层保险)

$proxy_backend_addr 的 get_handler
上游 backend_get:在 proxy_pass 求值时重算子域名与后端——即使 access 阶段没赋值也能转发;no_cacheable(1)
我方 backend_var_get:直接返回 NGX_DECLINED;no_cacheable(0)

实践等价(开了 sso_domain on 的 location 一定会走 access),但上游那层兜底在我方缺席。 若哪天出现「配置里引用了变量、但 access 因某原因没跑」的组合,我方会退化成 500 no host in upstream。低风险,可按需补齐。


3. 内核 ipass-core:一致,差异均为形状/展示

模块 结论
config.rs / session.rs 共有函数零差异
http.rs 仅 host_port 不同:我方多处理 IPv6 [] 括号。header() 两侧都大小写不敏感,故上游写 "Host"、我方写 "host" 无碍 ✓
state.rs split_value 我方用 rposition(末个分隔符),上游用 position(首个)。值布局 payload ‖ 0x1f ‖ 十进制过期时刻——我方更稳(payload 内含 0x1f 时上游会解析错)。其余为抽取子函数
store.rs write_json 我方 to_string_pretty,上游 compact —— 仅文件观感。domains.json 两侧都是裸 JSON 数组,可互换解析 ✓
util.rs 见下

util.rs 的形状差异(不参与协议,但要知道):

函数 上游 我方
day_id libc localtime_r(跟服务器时区) (ts + 8*3600)/86400(固定 UTC+8)
fmt_left h 小时 m 分 / m 分 s 秒 / 已过期 支持「天」:1天2小时3分钟 / <1分钟 / 空串
gen_id d_<12 位 hex> <hex(now)><8 位 hex>
rand_digits <250 掩码 + %10(去模偏) b % 10(有轻微模偏,10^8 空间下无碍)

⚠️ gen_id 形状不同 ⇒ 两侧生成的记录 id 不能互相校验。真要做数据迁移时须注意。

刻意不移植(与上游保持一致的分工)

bump_window / put_ukey / get_upstream / put_upstream / remove_upstream / window_count, 以及 upstreams.rs / stats.rs / llm.rs / llm_audit.rs / llm_usage.rs / apix.rs—— LLM 上游代理与按量计费、API 代理属流量层,与本服务的「身份层」定位分界不变。 插件要用的前缀与封装一律在自家 keys.rs 里定义,不往内核 config.rs 加。


4. 账号数据:users.json 只能单向兼容

上游 User 我方 User(ipass-core)
共有 username / display_name / role / salt / pwd_hash / api_key / created_at 同
LLM 字段 顶层 allowed_models / llm_rpm / llm_daily / temp_grant_until 落在 extra 透传(#[serde(flatten)] BTreeMap)
身份字段 无 email / department / groups / failed_count / locked_until
unknown 字段策略 未声明 deny_unknown_fields 未声明

由此:

  • 上游 users.json → 我方:可以原样读 ✓ —— 上游那些顶层 LLM 字段会被 extra 自动认领。
  • 我方 users.json → 上游:能读,但写回会丢字段 ✗ —— 上游不认识 email/groups/failed_count/ locked_until,一旦由上游改写该文件,这些字段被抹掉。

结论:两侧 users.json 不要互写。 各自独立 data 目录最安全;若要共用,只允许「上游读、我方写」这一个方向。


5. 两处可改进(非缺陷,属设计代价)

5.1 store::update_plugin 的闭包签名

// 我方现在
pub fn update_plugin<T, F>(name: &str, f: F) -> Result<T, String>
where F: FnOnce(&mut T) -> Result<T, String>   // ← 返回整表

// 上游(更好用)
pub fn update_domains<T, F>(f: F) -> Result<T, String>
where F: FnOnce(&mut Vec<DomainEntry>) -> Result<T, String>  // ← 返回业务值

我方签名要求闭包把整张表交回来,导致每个写操作都得写 Rc<RefCell<Option<..>>> 捕获 + list.clone():既啰嗦,又每次写都克隆整张表(O(n) 分配)。

建议:改成三个泛型

pub fn update_plugin<T, R, F>(name: &str, f: F) -> Result<R, String>
where T: DeserializeOwned + Serialize + Default,
      F: FnOnce(&mut T) -> Result<R, String>

可一次性消掉 plugin-domain 里 6 处 Rc<RefCell> 舞蹈。

5.2 网关未命中路由的 404 形状

未知 /api/... 的响应
上游 http::fail(404, "接口不存在:{method} {uri}") → JSON 信封 {code,msg,data}
我方 gateway::api_body_ready 默认 HTTPStatus::NOT_FOUND → nginx 默认 HTML 404

插件化后「无人认领」由装配层兜底,但兜底形状与其余 API 不一致。 建议在 api_body_ready 的默认分支改调 ipass_core::http::fail(r, NOT_FOUND, &format!("接口不存在:{method} {uri}"))。


6. 第二轮核对(ddd4172:上游 P0–P5 已插件化)

上游经 0d8e1c9(P3 拆 plugin-llm)→ 85ea0a1(P4 拆 plugin-apix)→ ddd4172(P5 方案转正), 完成了与本文档前 5 节所描述的同源插件化,最终形态:

refs/ipass/rust/crates/
├── ipass-core        # 内核 14 文件 2737 行(新增 api.rs 鉴权框架 465 行 + auth.rs 身份端点 + usage.rs)
├── plugin-domain     # 域名 7 文件 1050 行(config.rs / store.rs 独立成文件)
├── plugin-llm        # LLM 代理 / 配额 / 计量 / 审计
├── plugin-apix       # API 代理
└── gateway           # 装配根(唯一动态模块)
docs/plugin/PLUGIN_ARCHITECTURE.md    # P5 方案转正文档

ipass-core/src/plugin.rs 注释原文:「沿用 ssw/sso 的形态……若将来与 sso 合流 trait 不用再改」。 两侧 Plugin trait(preconfig / postconfig / dispatch_api 三回调)已实质同构——trait 层零适配即可合流。

6.1 装配层逐项对照

维度 我方(ssw/sso) 上游(ddd4172) 结论
Plugin trait preconfig / postconfig / dispatch_api 同 一致
PLUGINS 顺序即装配 ✓ &[&SsoPlugin, &DomainPlugin] ✓ &[&CorePlugin, &DomainPlugin, &LlmPlugin, &ApixPlugin, &GatewayRoutes] 一致(成员不同属定位差异)
loc::Switch 内核契约 ✓(Api/Iap/Domain/Llm) ✓(并集:Api/Proxy/Llm/Apix/Iap/Domain,Domain 注释「为 sso 预留」) 一致;上游把两侧开关都收进枚举
变量/阶段注册 preconfig 注册变量、postconfig 注册 handler,均按插件循环 同 一致
ctx_index 注入内核 ✓ ✓(plugin::set_ctx_index) 一致
指令命名 sso_state / sso_api / sso_iap / sso_domain …(6 条) ipass_state / ipass_api / ipass_proxy / ipass_llm / ipass_apix …(8 条) 仅前缀差异,机制相同
模块路径改写 移植时直接改 ipass_core::… gateway 里 pub use ipass_core::{config, http, …} re-export 桥(业务文件不改路径,P2–P4 迁完逐个撤) 等价手段,上游过渡成本更低
dispatch 未命中兜底 finalize 原生 404(nginx 默认 HTML 页) http::fail(404, "接口不存在:{method} {uri}") → JSON 信封 分歧,见 6.4
admin 播种 seed-data.sh + .env 口令 init_process 里 users::seed_admin() 幂等播种 定位差异(我方口令不入库文件)

6.2 内核边界:真正的定位分歧

我方 上游
内核路由数 0(内核零业务端点) 身份端点(登录/会话/账号 CRUD)+ CorePlugin 排 PLUGINS 第一
鉴权框架 在 plugin-sso 内 ipass-core/api.rs 465 行:Actor / Guard / run_guarded,路由表声明式写 ("POST", path) => (Guard::Admin, h_xxx)
反向扩展 无此需求 CoreExt 装饰回调(decorate_admin_users / decorate_me / reclaim_on_delete / validate_slots)+ gateway 自认领 /api/admin/trend 组合端点

上游把「身份」放内核、我方把「身份」做成第一个插件——这是分工定位分歧(上游是统一流量网关自带账号体系; 我方是纯身份层,身份即插件)。不构成缺陷,也不建议互改;但合流时须二选一,CoreExt 这层反向注册 是上游为「内核不认识插件」付出的代价,我方没有这层所以更干净。

6.3 域名插件:第一轮结论全部维持

  • 路由 8 条 7 条一致(含鉴权等级);purge 路径分歧依旧:上游 POST /api/admin/purge (api.rs 路由表 L30),我方 POST /api/admin/domains/purge(第 3 节分歧 1,建议仍以统一为准)。
  • DomainEntry 10 字段逐字相同 → domains.json 双向可互换 ✓;users.json 单向兼容结论不变(第 4 节)。
  • 文件分工差异:上游把常量拆 config.rs、文件写拆 store.rs(update_domains<T,F> 三泛型), 我方对应折进 keys.rs / domains.rs。内容等价。

6.4 对第 5 节两条建议的复核

  1. update_plugin 改三泛型:上游 update_domains<T, F> -> Result<T, String>(闭包返回业务值) 证实了该方向,照上游签名改即可,可消掉 plugin-domain 全部 6 处 Rc<RefCell> 舞蹈。维持建议。
  2. dispatch 兜底改 JSON 信封:上游实现可直接抄—— http::fail(r, HTTPStatus::NOT_FOUND, &format!("接口不存在:{method} {uri}"))。维持建议。

7. 复现方式

# 拉上游最新
cd refs/ipass && git fetch origin && git merge --ff-only origin/main   # 第二轮拉到 ddd4172

# 归一模块路径后逐函数比对(脚本见下)
python3 - <<'PY'
# 把所有 crate::X:: / ipass_core::X:: 归一成同一占位符,再剔掉注释与 use 行,
# 然后用 difflib 对函数体逐一对齐 —— 噪声消失后剩下的才是真差异。
PY

判定口径:先归一模块路径与导入,再剔注释,否则会被「crate::config:: vs keys::」这类 等价改写淹没(域名 domains.rs 原始 diff 有 317 行,过滤后只剩机械改写)。