- 上游 P0-P5 已同源插件化,Plugin trait 三回调与我方同构,trait 层零适配可合流 - 域名插件第一轮结论全部维持:8 路由 7 条一致、DomainEntry 逐字相同、domains.json 可互换 - 真分歧收敛为两类:内核边界属定位分歧(身份在内核 vs 身份即插件),建议项维持 (update_plugin 三泛型、dispatch 兜底改 JSON 信封,上游实现可直抄) - 技能第 8 节前提更新:先探明上游形态再选对照口径
15 KiB
与上游 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,建议仍以统一为准)。 DomainEntry10 字段逐字相同 →domains.json双向可互换 ✓;users.json单向兼容结论不变(第 4 节)。- 文件分工差异:上游把常量拆
config.rs、文件写拆store.rs(update_domains<T,F>三泛型), 我方对应折进keys.rs/domains.rs。内容等价。
6.4 对第 5 节两条建议的复核
update_plugin改三泛型:上游update_domains<T, F> -> Result<T, String>(闭包返回业务值) 证实了该方向,照上游签名改即可,可消掉 plugin-domain 全部 6 处Rc<RefCell>舞蹈。维持建议。- 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 行,过滤后只剩机械改写)。