diff --git a/TECHNICAL-NOTES.md b/TECHNICAL-NOTES.md index 686277cda0..ed0e1e17bf 100644 --- a/TECHNICAL-NOTES.md +++ b/TECHNICAL-NOTES.md @@ -30,6 +30,45 @@ The hook probes each candidate's `/__bili/health` before attaching: armed → at Attach discovery is lane-aware across **all** live instances (#1232): the launcher probes every live entry in the instance registry, not just the single instance file (last-writer-wins — under concurrent multi-client use it can point at another client's proxy), and applies the gate above to every candidate. Among compatible candidates the newest instance with the launcher's own declared lane wins; an instance without a lane (a user-zone daemon) is wildcard-compatible on the lane axis and gate-exempt by default (#1660). The `another bili instance is running` warning (#394) is lane-aware too: it fires for same-lane or lane-less coexistence, but stays silent between two *different* declared lanes, whose session files are disjoint. +## Shared state dir and multi-instance security boundary (#394, #1724) + +Every bili instance on a host reads and writes the **same** per-host +storage: the XDG data dir (`~/.local/share/billion-context/` — session +records, CCR content-store, prefix-affinity) plus the state dir +(`~/.local/state/billion-context/` — log, instance registry). The control +plane is lane-aware (#1232: +attach discovery and the #394 coexistence warning both respect declared +lanes), but the **data plane is not partitioned** — there is no per-session +owner and no per-lane isolation on disk. Two consequences follow: + +- **Cross-instance session visibility.** Each instance's Web UI + (`__bili/sessions` list / detail / logs) re-scans the whole shared store, so + any instance reachable over loopback can enumerate and read *any* session — + raw messages, content-store payloads, compressed blocks — created by any + other instance/lane on that host. +- **Restart drain race.** On a restart the new process hydrates the store + before the old one finishes flushing, so last-writer-wins can drop the old + process's final writes: lost tail updates and a provider prefix-cache bust + (the outbound body diverges from what the provider had cached). The #1724 + mitigations: the #405 snapshot-counter guard (rejects stale session writes), + the prefix-affinity union-on-write guard (#1737: one instance's flush never + clobbers a sibling chain), and the self-restart ordering fix (#1742: durable + state is flushed to disk before the replacement spawns). Host-driven restarts + (dsh et al., #991) still rely on these data-layer guards, since their + kill/spawn order is not bili-controlled. + +**Security posture:** the shared-state surface is protected *only* by the admin +endpoint's loopback gate (non-loopback source addresses are refused) plus +filesystem permissions on the user's home tree (both dirs live under $HOME) — +there is no per-session authorization. For a **single-user host** that is +sufficient. On a **multi-user host** it is not: any local account able to reach +the proxy's loopback port can read every session of every user. Such hosts must +partition their per-host storage (per-user/per-lane subdirectories) — the root +fix named in #1724 +(direction #1), still open as an architecture decision; Web UI scoping +(#1724 direction #4) reduces cross-instance browsing but does not change this +boundary. + ## Runtime-info protocol (#955) A native plugin lives inside the client process, so it can read the model diff --git a/TECHNICAL-NOTES.zh-CN.md b/TECHNICAL-NOTES.zh-CN.md index 2d6c4bce94..638bca92d5 100644 --- a/TECHNICAL-NOTES.zh-CN.md +++ b/TECHNICAL-NOTES.zh-CN.md @@ -21,6 +21,15 @@ hook 附着前先探测候选者的 `/__bili/health`:armed → 附着并注册 w 附着发现在**所有**存活实例间是 lane 感知的(#1232):启动器探测实例注册表里的每一条存活记录,而不只是单个实例文件(last-writer-wins —— 并发多客户端下它可能指向别的客户端的代理),并对每个候选应用上面的门禁。兼容候选中,lane 与启动器自身声明一致的最新实例胜出;未声明 lane 的实例(用户主权区守护进程)在 lane 轴上通配,且门禁默认豁免(#1660)。`another bili instance is running` 告警(#394)也是 lane 感知的:同 lane 或无 lane 共存时触发,两个*不同声明* lane 之间保持沉默(它们的会话文件互不相交)。 +## 共享 state 目录与多实例安全边界(#394、#1724) + +同一台 host 上的每个 bili 实例读写的是**同一组** per-host 存储:XDG data 目录(`~/.local/share/billion-context/` —— 会话记录、CCR content-store、prefix-affinity)加 state 目录(`~/.local/state/billion-context/` —— 日志、实例注册表)。控制面是 lane 感知的(#1232:附着发现与 #394 共存告警都尊重已声明 lane),但**数据面没有分区** —— 既无按会话的属主,也无按 lane 的磁盘隔离。由此带来两个后果: + +- **跨实例会话可见。** 每个实例的 Web UI(`__bili/sessions` list / detail / logs)都会重新扫描整个共享存储,因此任何经回环可达的实例都能枚举并读取*任意*会话 —— 原始报文、content-store 载荷、压缩块 —— 无论它由该 host 上哪个其他实例/lane 创建。 +- **重启 drain 竞态。** 重启时新进程在旧进程完成 flush 之前就 hydrate 了存储,last-writer-wins 可能丢掉旧进程的最终写入:tail 更新丢失,以及 provider 前缀缓存击穿(出站 body 与 provider 已缓存的前缀分叉)。#1724 的缓解措施:#405 快照计数器守卫(拒绝陈旧会话写入)、prefix-affinity union-on-write 守卫(#1737:一个实例的 flush 永不覆盖兄弟 chain)、自重启顺序修复(#1742:durable state 在替换进程 spawn 之前落盘)。host 驱动的重启(dsh 等,#991)仍依赖这些数据层守卫,因为其 kill/spawn 顺序不受 bili 控制。 + +**安全边界:** 共享 state 面目前**仅**由管理端点的回环门禁(非回环源地址被拒绝)+ 用户 home 树下这些目录的文件系统权限保护(两个目录都在 $HOME 下)—— 没有按会话的鉴权。对**单用户 host** 这已足够。对**多用户 host** 则不够:任何能触达代理回环端口的本地账户都能读取所有用户的所有会话。这类 host 必须给这组 per-host 存储分区(按用户/按 lane 子目录)—— 即 #1724 指出的根因修复(direction #1),目前仍作为架构决策开放;Web UI scoping(#1724 direction #4)能减少跨实例浏览,但不改变这一边界。 + ## Runtime-info 协议(#955) 原生插件就在客户端进程里,因此能读到客户端自己将要使用的模型配置。它通过两个通道把真相推给代理,代理在上下文窗口解析链里优先采用它而不是 models.dev 注册表/内置表: