From 81c8346ad6949d7090ec13ccffc252fde66c15a6 Mon Sep 17 00:00:00 2001 From: ssw Date: Sun, 13 Sep 2026 17:18:16 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=87=B4=E4=B8=8A=E6=B8=B8=20ipass=20?= =?UTF-8?q?=E5=86=85=E6=A0=B8=E4=BF=AE=E6=94=B9=E5=BB=BA=E8=AE=AE=EF=BC=88?= =?UTF-8?q?A=20=E6=A1=A3=206=20=E9=A1=B9=20+=20B=20=E6=A1=A3=E8=87=AA?= =?UTF-8?q?=E8=A7=A3=E6=B8=85=E5=8D=95=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - A1 User 加 extra flatten 透传通道(插件字段通用解,替代逐字段硬编码) - A2 split_value position→rposition(内嵌分隔符截断 bug) - A3 iter_prefix_ex 带 exp 枚举原语 - A4 账号操作支持路径确认(插件经 store::update_users + sync_shm 自实现) - A5 插件文件读写口径二选一 - A6 PASSWORD_MIN_LEN 6→8、COOKIE_NAME 由插件声明 - B 档全部本地自解,不阻塞内核原样收敛 --- docs/upstream-core-changes.md | 126 ++++++++++++++++++++++++++++++++++ 1 file changed, 126 insertions(+) create mode 100644 docs/upstream-core-changes.md diff --git a/docs/upstream-core-changes.md b/docs/upstream-core-changes.md new file mode 100644 index 0000000..55f46bb --- /dev/null +++ b/docs/upstream-core-changes.md @@ -0,0 +1,126 @@ +# 致 ipass 上游:内核修改建议(基于 ddd4172 对照) + +> 背景:ssw/sso 正按「上游 ipass-core 为内核基准」收敛——内核原样复制,域名插件以上游为准, +> sso 作为纯插件并入。收敛过程中发现以下内核问题,**按影响分两档**: +> **A 档 = 请求上游修改**(不改则两侧合流后有实际损失); +> **B 档 = 供参考**(我方可自行解决,但上游统一改掉对两家都更干净)。 +> 我方在等待期间一律先用本地标记补丁(`// PATCH(sso): 待上游采纳后撤销`)推进,不阻塞。 + +--- + +## A 档:请求上游修改 + +### A1. `models.rs` User 增加 `extra` 透传通道(最重要) + +上游 User 目前硬编码了 LLM 配额字段(`slots` / `allowed_models` / `llm_rpm` / `llm_daily` / +`temp_grant_until`)。这些是 **plugin-llm 的语义**,放在内核模型里意味着:下一个插件要存 +TOTP 密钥、邮箱、用户组、锁定状态……每个都得再来内核加一轮字段——插件用户不可能提供 +覆盖所有场景的字段。 + +建议加一个内核「持有但不解释」的透传字段(我方已有生产实现,可直接抄): + +```rust +/// 插件字段:内核持有、透传,不解释。 +/// 读文件时未被上面字段认领的 key 自动进 `extra`;写回时展开回顶层。 +/// 存量 users.json(含任何插件写入的字段)可原样接管,不会因内核不认识而丢数据。 +#[serde(flatten)] +pub extra: BTreeMap, +``` + +两点说明: +- `flatten` 对上游现有字段**零影响**(已认领的字段优先),老 users.json 反序列化后原样写回。 +- 若上游采纳,现有 LLM 字段可继续保留 typed(无冲突);也可顺势迁入 `extra` 让模型瘦身, + 由上游定。 + +### A2. `state.rs` `split_value` 用 `position` 会截断内嵌分隔符的值(疑似 bug) + +```rust +// 上游 ddd4172:取第一个分隔符 +let sep = bytes.iter().position(|&b| b == VAL_SEP)?; +``` + +共享内存值格式为 `payloadexp`。当 payload 自身含 `VAL_SEP`(OAuth 授权码会话、 +带逗号串的注入头 payload 都会),`position` 取到 payload 内部的分隔符,payload 被截断、 +exp 解析失败。应改为 `rposition`(取最后一个——exp 里不可能再有分隔符): + +```rust +let sep = bytes.iter().rposition(|&b| b == VAL_SEP)?; +``` + +我方生产已按 `rposition` 运行(这正是当初踩坑后改的)。 + +### A3. `state.rs` 缺带过期时间的枚举原语 `iter_prefix_ex` + +上游只有 `iter_prefix`(丢掉 exp)。会话管理类插件(登录会话、OAuth 会话的 kick/清理/列表) +需要 `(key, payload, exp)` 三元组才能判断条目是否已过期。建议: + +```rust +pub fn iter_prefix_ex(prefix: &[u8]) -> Vec<(String, String, i64)>; +``` + +(`iter_prefix` 可保留为兼容包装。) + +### A4. `users.rs` 请确认「插件自实现账号操作」的支持路径 + +上游 `users` 模块有 `create/delete/set_display_name/set_password/grant_temp/...`,但身份类 +插件还需要:`set_profile`(部门/用户组)、`set_role`、`batch_update`、`unlock`、 +`record_login_failure`(登录失败计数与锁定)、`update_extra`。 + +我看到 `store::update_users` 与 `users::sync_shm` 都是 `pub`,理论上插件可以自实现 +这些函数并在写回后调 `sync_shm`——**若这是上游支持的路徑,确认即可,我们不再请求内核加函数**。 +若上游认为这些属于通用账号能力,欢迎收进内核,签名可参照: + +```rust +pub fn set_profile(username: &str, display_name: Option<&str>, department: Option<&str>, + add_groups: &[String], remove_groups: &[String]) -> Result; +pub fn set_role(username: &str, role: &str) -> Result; +pub fn batch_update(usernames: &[String], add_groups: &[String], remove_groups: &[String], + department: Option<&str>, role: Option<&str>, unlock: bool) -> Result, String>; +pub fn unlock(username: &str) -> Result; +pub fn record_login_failure(key: &str, now: i64) -> Result<(i64, i64), String>; // (失败次数, 锁定截止) +pub fn update_extra(username: &str, f: F) -> Result; // 配合 A1 的 extra 通道 +``` + +### A5. `store.rs` 插件文件读写口径 + +上游公开的只有 `path_in_data(name)`。我方插件普遍使用「插件命名空间」口径 +`plugin_path(name)`(`data/plugins/.json`)+ `read_plugin/write_plugin/update_plugin` +泛型封装(含 `update_plugin` 返回业务值)。建议上游二选一: +1. 收编 `plugin_path` 系(多插件并存时文件不易互相踩); +2. 或确认 `path_in_data` 是唯一口径、由插件自行拼子目录(我方按此自解)。 + +### A6. `config.rs` 两处小项 + +- `PASSWORD_MIN_LEN = 6`:建议提到 8(弱口令门槛;上游若有兼容顾虑可维持,我方在插件层 + 自行加校验)。 +- `COOKIE_NAME = "ipass_admin_session"` 硬编码在内核:换内核/改内核会使存量会话全部失效。 + 建议会话 cookie 名改由插件声明(内核提供默认值即可)。 + +--- + +## B 档:我方本地自解(仅供上游参考,不改不阻塞) + +| 项 | 我方处理 | +| --- | --- | +| `audit.rs`(审计日志,仅 sso 使用) | 移入 plugin-sso,内核保持上游原样 | +| 锁定/部门/用户组/临时授权等常量(`ACCOUNT_LOCK_*`、`DEPARTMENT_MAX_LEN`、`GROUPS_*`、`TEMP_GRANT_TTL`、`PASSWORD_MIN_LEN=8`) | 移入 plugin-sso 自己的常量模块 | +| `split_value` rposition(= A2) | 本地补丁,标记待上游采纳后撤销 | +| `iter_prefix_ex`(= A3) | 本地补丁,标记待上游采纳后撤销 | +| User `extra` flatten(= A1) | 本地补丁,标记待上游采纳后撤销 | +| `zone_ready` | 无使用者,直接删除 | +| `users::set_profile/batch_update/...`(= A4) | plugin-sso 内基于 `store::update_users` + `sync_shm` 自实现 | + +--- + +## 已确认无需上游改动的部分 + +- `http.rs host_port`:上游 `rsplit_once` 实现比我方更简洁,语义等价,直接采纳。 +- `store.rs` `write_json` 用紧凑 JSON(我方是 pretty):等价,采纳上游。 +- `Plugin` trait(preconfig/postconfig/dispatch_api/zone_load/log_handler)、PLUGINS 装配、 + `loc::Switch` 契约、`ctx_index` 注入:两侧已同构,**trait 层零适配可合流**。 + +## 对照基线 + +- 上游:`ssw/ipass` `ddd4172`(P0–P5 插件化收尾) +- 我方:`ssw/sso` `912c21a` +- 详细逐文件对照见 `docs/upstream-sync-2026-09-13.md` 第 6 节