Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 39 additions & 0 deletions TECHNICAL-NOTES.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
9 changes: 9 additions & 0 deletions TECHNICAL-NOTES.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 注册表/内置表:
Expand Down
Loading