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
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,9 @@ Versions follow the merge of a `*_release-v*` branch; CI publishes to npm on tag

## [Unreleased]

### 存储

- **SQLite 引擎自举按运行时分级钉死产物(#3894,作者 @zypNB123)**:Node ≥ 22 且 N-API ≥ 10 继续用单个 v13 tarball;Node 20 与 22.0–22.12(只有 N-API 9)改用 better-sqlite3 v12.9.0(纯 JS tarball + ABI 匹配的 prebuild,经 npmmirror 二进制镜像获取、sha512 校验、nativeBinding 注入)——低版本 Node 留在统一存储车道而不是降级 legacy。任何钉死产物都不支持的运行时在**加载之前**拒绝(`unsupported-node`,不下载、不注册缓存副本),因为在那里 dlopen 该 binding 会直接崩溃进程(win32 上 1485 次连续 0xC0000005 崩溃环的根因);同版本多 ABI 缓存共存,切换 Node 大版本不重下。
### 存储后端热路径接线(#3388 第三步 / #3931)

- `storage.backend="mysql"` 接进代理热路径:保存经异步影子 facade 进串行后端队列(水位 delta、#3841 收割台账、digest 采样、三振自禁用,与 sqlite 路径逐条 lockstep);sqlite 保持零 await 同步快车道,行为逐字节不变。
Expand Down
4 changes: 3 additions & 1 deletion CONFIGURATION.md

Large diffs are not rendered by default.

4 changes: 3 additions & 1 deletion CONFIGURATION.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -175,6 +175,8 @@
| `persist.epermAlertRepeatMs` | number | 0 (no repeats) | BILI_PERSIST_EPERM_ALERT_REPEAT_MS | EPERM 告警的重复间隔;0 只记录一次。 |
| `storage` | object | {} (all defaults) | — | 统一 SQLite 存储边车设置(#2671)。 |
| `storage.unified` | legacy\|shadow\|full | unset (full) | BILI_STORAGE_UNIFIED | 分层存储迁移开关(#2671):shadow = 统一 SQLite 双写干跑 + digest 对账;full = 平替读路径(unified-first 加载 + 有机导入 + legacy 兜底)。两处均未设置时默认 full(#3818 翻转 —— shadow 干跑自 #2815 起对账一直干净,索引因此成为默认加载路径;JSON 信封照写,legacy 仍是一行逃生口)。文件层只接受 legacy/shadow/full;环境变量层还接受 1/true(=shadow)与 unified(=full)并优先于文件。每个 lane 启动时解析一次 —— 热改动需重启生效。加密(BILI_ENCRYPTION_KEY)会硬阻断边车。 |
| `storage.backend` | sqlite\|mysql | unset (sqlite) | BILI_STORAGE_BACKEND | 存储后端选择,可插拔存储计划第一步(#3388 / #3931):统一存储消费操作级的异步 StorageBackend 契约,sqlite 为默认且是当前唯一真实现(现有 UnifiedStore 套一层 Promise 包装适配器 —— 零行为变化、零 schema 变化)。mysql 是已注册占位:该名字能通过校验(真实后端随第二步落地 —— mysql2 客户端,走可选依赖+自下载纪律 —— 期间配置不会在 unknown/unimplemented 之间来回弹),但选中它只会在 lane 启动时打一行提示并继续用 sqlite;直接开后端的路径(export)按文档化的错误失败。未知名字同样回退 sqlite 并提示。每个 lane 启动时解析一次。 |
| `storage.sqliteAutoDownload` | boolean | true | BILI_SQLITE_AUTO_DOWNLOAD | SQLite 引擎一次性自下载的闸门(#2833):进程内没有可用引擎(无内置 node:sqlite、宿主未装 better-sqlite3)且本平台希望启用统一边车时,bili 从 npm registry 一次性下载钉死的 better-sqlite3 预编译 tarball(约 11 MB,sha512 校验)到缓存目录,之后每次启动复用。引擎解析顺序:内置 node:sqlite(Node >= 22.5)-> 宿主机已装的 better-sqlite3 -> 缓存的自下载副本 -> 自下载(本开关控制)-> 无引擎(仅 legacy,即 #2825 降级契约)。开关只控制网络下载 —— 为 false 时缓存副本仍会使用;不支持的平台永不下载。 tarball 下载内置镜像列表兜底(#3338):先试配置的 registry(BILI_UPDATE_REGISTRY / update.registry),再试 https://registry.npmjs.org、https://registry.npmmirror.com —— 第一个通过 sha512 校验的镜像生效;Node < 22.5 且无引擎时,降级原因会给出明确的 Node 升级提示(#3385)。引擎产物按运行时特性分别钉死,因为 binding 无法在包自身声明的范围之外加载:Node >= 22 且 N-API >= 10 用 better-sqlite3 v13(单个 tarball 自带 prebuilds),而 Node 20 与 Node 22.0–22.12(满足 v13 的大版本下限但只带 N-API 9)用 v12.9.0(纯 JS tarball 加与之 ABI 匹配的 prebuild,从二进制镜像获取并经 nativeBinding 注入)—— 低版本 Node 因此留在统一存储车道上,而不是降级到 legacy。任何钉死产物都不支持的运行时(低于所有下限,或 ABI 无对应 prebuild)会在加载之前被拒绝,下载与缓存副本注册都不进行 —— 在那里加载该 binding 会让进程崩溃,而不是优雅失败(#3341、#3894)。下载失败会置一个 6 小时的重试冷却,以标记文件形式持久化在缓存目录下(billion-context/sqlite/.bootstrap-failed.json);storage 诊断块会显示该标记的绝对到期时间与路径 —— 删除该文件并重启 bili 即可强制立即重试,不必等完整个冷却窗口(#3788)。 |
| `storage.backend` | sqlite\|mysql | unset (sqlite) | BILI_STORAGE_BACKEND | 存储后端选择(#3388 / #3931):统一存储消费操作级的异步 StorageBackend 契约。sqlite 为默认(现有 UnifiedStore 套一层 Promise 包装适配器)。mysql 已完整接线(第二+三步):openBackend("mysql", dsn) 打开真正的 MysqlBackend,对接 MySQL 8.0 —— 完整契约面(带 CAS 引用计数的 ingest、读取、session_ext、收割台账、归档/恢复/GC、checkpoint、会话绑定),mysql2 作为常规依赖打包并按需懒加载(从不选 mysql 的启动永不加载它)。代理热路径经异步影子 facade 接线:保存进串行后端队列(水位 delta、孤儿/收割台账、digest 采样 —— sqlite 保持零 await 同步快车道不变),同步读走 JSON 信封(sidecar 经 ready() 异步挂载;viewFor/importRecord 同步面按设计 miss),replicas/ext/GC/export 走异步孪生。writerOff 仅 sqlite(信封就是 mysql 的同步读路径)。未知名字回退 sqlite 并提示。每个 lane 启动时解析一次。 |
| `storage.mysql.dsn` | string | unset | BILI_MYSQL_DSN | storage.backend="mysql" 的 MySQL DSN(#3388 第二步,#3931):mysql://user:pass@host:3306/db。由 StorageBackend 契约路径消费(含热路径 —— 异步影子队列)。环境变量 BILI_MYSQL_DSN 优先于文件键。空/未设置 = mysql 后端无法打开 —— 文档化错误会同时列出两个旋钮和可用的默认值。 |
| `storage.sqliteAutoDownload` | boolean | true | BILI_SQLITE_AUTO_DOWNLOAD | SQLite 引擎一次性自下载的闸门(#2833):进程内没有可用引擎(无内置 node:sqlite、宿主未装 better-sqlite3)且本平台希望启用统一边车时,bili 从 npm registry 一次性下载钉死的 better-sqlite3 预编译 tarball(约 11 MB,sha512 校验)到缓存目录,之后每次启动复用。引擎解析顺序:内置 node:sqlite(Node >= 22.5)-> 宿主机已装的 better-sqlite3 -> 缓存的自下载副本 -> 自下载(本开关控制)-> 无引擎(仅 legacy,即 #2825 降级契约)。开关只控制网络下载 —— 为 false 时缓存副本仍会使用;不支持的平台永不下载。 tarball 下载内置镜像列表兜底(#3338):先试配置的 registry(BILI_UPDATE_REGISTRY / update.registry),再试 https://registry.npmjs.org、https://registry.npmmirror.com —— 第一个通过 sha512 校验的镜像生效;Node < 22.5 且无引擎时,降级原因会给出明确的 Node 升级提示(#3385)。下载失败会置一个 6 小时的重试冷却,以标记文件形式持久化在缓存目录下(billion-context/sqlite/.bootstrap-failed.json);storage 诊断块会显示该标记的绝对到期时间与路径 —— 删除该文件并重启 bili 即可强制立即重试,不必等完整个冷却窗口(#3788)。 |
Expand Down Expand Up @@ -1892,7 +1894,7 @@ ACP 原生 agent(当前为 `pi` 扩展)会在每个进程内向代理上报
| `BILI_PERSIST_DEBOUNCE_MS` | 持久化写盘的防抖窗口(毫秒,默认 `500`)。 |
| `BILI_PERSIST_TAIL_TOKENS` | 持久化会话快照的 token 预算(#401)。盘上记录的是**折叠视图**(压缩范围以块摘要替代)并截断到该预算内的最新消息 —— 不再存全量原始历史。默认 `16384`;设 `0` 彻底不持久化消息(块摘要与压缩原件仍会持久化,`bili export` 退回块级渲染)。活会话内存不受影响 —— 活会话的 `bili export` 始终完整。 |
| `BILI_PERSIST_ZSTD` | 设为 `1`/`true` 启用会话文件的 zstd 压缩(#1080,owner 决定:**默认关闭**——纯 JSON 可恢复性最强:可用 jq/grep 调试,且无降级尾部风险)。启用后,每个确实能压缩变小的会话文件均以 `BILIZSTD1` 格式写入——即在 JSON 主体之上附加一个小头部(魔数 + 格式版本 + 模式字节),在 Node ≥ 22.15 上以 zstd 压缩存储,在旧版运行时上则原样存储;读取端兼容两种主体格式(优先使用原生 zstd,否则回退至内置的 WASM 实现),因此文件在不同运行时和版本间均可正常读取。压不小的小会话与无密钥的原始主体以裸 JSON 落盘。与 `BILI_ENCRYPTION_KEY` 相互独立——两者同时生效时,压缩方式会记录在 `BILIENC1` 内部的模式字节中。已有的纯 JSON 文件**永不在启动时改写**(降级安全——批量重编码会让回退到旧版 bili 时把自己的写入当成“损坏文件”);它们在其下一次保存时自然转换。注意:一旦会话已保存为 `BILIZSTD1`,旧版 bili(< 0.1.135)无法读取——该限制仅对显式启用的部署生效;未设置或其他值均保持纯 JSON。 |
| `BILI_STORAGE_UNIFIED` | 存储迁移分层开关(#2671)。配置文件层:`{"storage":{"unified":"legacy|shadow|full"}}` 选用相同模式(严格拼写),在环境变量未设时生效;`BILI_STORAGE_UNIFIED`(额外接受 `1`/`true`=shadow、`unified`=full)始终优先于文件。模式在每个 lane 启动时解析一次——文件热改动在下次重启生效。设 `1`/`true` 启用**统一 SQLite 存储干跑**(Phase 1):每次会话写入都会双写到 `<sessions-dir>/index.db`(引擎解析顺序自 #2833 起:运行时提供内置 `node:sqlite` 时优先(Node >= 22.5)-> 宿主已装的 `better-sqlite3` 原生模块 -> 先前自下载的缓存副本 -> 一次性自下载钉死的 `better-sqlite3` 预编译 tarball(约 11 MB,sha512 校验,受 `storage.sqliteAutoDownload` 控制,不支持的平台永不下载)-> 无引擎则按 #2825 降级契约保持仅 legacy;引擎获取永不依赖宿主安装期的构建脚本审批),并将统一层回放与旧格式加载视图做 digest 对账——不匹配时记录 `[storage] unified shadow DIGEST DRIFT …`,绝不阻塞或改写主写路径(旧格式文件仍是唯一事实源)。设 `full`/`unified` 启用**平替读路径**(Phase 1.5):`loadSync`/`boot`/`loadAll`/`loadStateForSearch` 改为 unified-first——首次打开旧文件会话时有机导入索引(`[storage] unified import on first open: …`),后续加载直接由 `index.db` 提供,任意统一层失败自动回退旧文件;旧格式文件照常双写,**回滚 = 去掉开关(环境变量与/或文件值)**。加密硬互斥:`BILI_ENCRYPTION_KEY` 激活时整个 sidecar 拒绝开启(index.db 明文存 ingest 载荷,记录 `unified sidecar DISABLED` 警告后保持 legacy-only)。枚举/GC 与 web 列表仍以文件为基底;`removeLegacyFile` 同步删除索引行并释放 CAS 引用计数。digest 把末次写入者版本戳 `biliVersion` 与墙钟时间戳视为环境(`__VER__`/`__TS__`),其余字节必须逐一致。连续 3 次内部失败后自动停用(full 模式下停用即回退 legacy 读)。**副本/检查点 REST(Phase 2)**:任意统一层 lane(shadow 或 full)上,`POST /__bili/replicas {sessionId, label?, pinned?}` 把会话持久化状态冻结为一条内容寻址的 checkpoint blob+行(先强制刷新驻留会话),`GET /__bili/replicas[?sessionId=]` 列出副本,`GET /__bili/replicas/<cpId>` 返回详情+字节数,`POST /__bili/replicas/<cpId>/restore {sessionId?}` 把检查点物化为全新的一等会话(走正常双写路径:JSON+统一层 ingest;`meta.restoredFrom`/`restoredCheckpoint` 记录来源),`DELETE /__bili/replicas/<cpId>` 删除。pinned 副本持有 CAS 引用计数,可在 `deleteSession` GC 中存活(本功能的意义:破坏性实验前抓的副本活得过实验本身);显式 DELETE 仍可删 pinned。legacy-only lane 返回 501 并附开关提示。路由与 `__bili` 其余部分一样仅限 loopback。未设置时默认 `full`(#3818)。 |
| `BILI_STORAGE_UNIFIED` | 存储迁移分层开关(#2671)。配置文件层:`{"storage":{"unified":"legacy|shadow|full"}}` 选用相同模式(严格拼写),在环境变量未设时生效;`BILI_STORAGE_UNIFIED`(额外接受 `1`/`true`=shadow、`unified`=full)始终优先于文件。模式在每个 lane 启动时解析一次——文件热改动在下次重启生效。设 `1`/`true` 启用**统一 SQLite 存储干跑**(Phase 1):每次会话写入都会双写到 `<sessions-dir>/index.db`(引擎解析顺序自 #2833 起:运行时提供内置 `node:sqlite` 时优先(Node >= 22.5)-> 宿主已装的 `better-sqlite3` 原生模块 -> 先前自下载的缓存副本 -> 一次性自下载钉死的 `better-sqlite3` 预编译 tarball(约 11 MB,sha512 校验,受 `storage.sqliteAutoDownload` 控制,不支持的平台永不下载;引擎产物按 Node 大版本分别钉死(Node >= 22 用 better-sqlite3 v13;Node 20 用 v12.9.0 及其 ABI 匹配的 prebuild),任何钉死产物都不支持的运行时会在加载之前被拒绝,下载与缓存副本注册都不进行,因为在那里加载该 binding 会让进程崩溃(#3341、#3894))-> 无引擎则按 #2825 降级契约保持仅 legacy;引擎获取永不依赖宿主安装期的构建脚本审批),并将统一层回放与旧格式加载视图做 digest 对账——不匹配时记录 `[storage] unified shadow DIGEST DRIFT …`,绝不阻塞或改写主写路径(旧格式文件仍是唯一事实源)。设 `full`/`unified` 启用**平替读路径**(Phase 1.5):`loadSync`/`boot`/`loadAll`/`loadStateForSearch` 改为 unified-first——首次打开旧文件会话时有机导入索引(`[storage] unified import on first open: …`),后续加载直接由 `index.db` 提供,任意统一层失败自动回退旧文件;旧格式文件照常双写,**回滚 = 去掉开关(环境变量与/或文件值)**。加密硬互斥:`BILI_ENCRYPTION_KEY` 激活时整个 sidecar 拒绝开启(index.db 明文存 ingest 载荷,记录 `unified sidecar DISABLED` 警告后保持 legacy-only)。枚举/GC 与 web 列表仍以文件为基底;`removeLegacyFile` 同步删除索引行并释放 CAS 引用计数。digest 把末次写入者版本戳 `biliVersion` 与墙钟时间戳视为环境(`__VER__`/`__TS__`),其余字节必须逐一致。连续 3 次内部失败后自动停用(full 模式下停用即回退 legacy 读)。**副本/检查点 REST(Phase 2)**:任意统一层 lane(shadow 或 full)上,`POST /__bili/replicas {sessionId, label?, pinned?}` 把会话持久化状态冻结为一条内容寻址的 checkpoint blob+行(先强制刷新驻留会话),`GET /__bili/replicas[?sessionId=]` 列出副本,`GET /__bili/replicas/<cpId>` 返回详情+字节数,`POST /__bili/replicas/<cpId>/restore {sessionId?}` 把检查点物化为全新的一等会话(走正常双写路径:JSON+统一层 ingest;`meta.restoredFrom`/`restoredCheckpoint` 记录来源),`DELETE /__bili/replicas/<cpId>` 删除。pinned 副本持有 CAS 引用计数,可在 `deleteSession` GC 中存活(本功能的意义:破坏性实验前抓的副本活得过实验本身);显式 DELETE 仍可删 pinned。legacy-only lane 返回 501 并附开关提示。路由与 `__bili` 其余部分一样仅限 loopback。未设置时默认 `full`(#3818)。 |
| `BILI_PERSIST_EPERM_ALERT_THRESHOLD` | 同一会话连续 N 次持久化写失败(`EPERM`/`EBUSY`/`EACCES`)后触发一次性「把该目录加入杀软排除项」告警的阈值(默认 `5`)。仅 Windows。见下文「Windows:把会话目录加入杀软排除项」章节。 |
| `BILI_PERSIST_EPERM_ALERT_REPEAT_MS` | persist EPERM 告警的重复窗口(毫秒)。`0`(默认)= 只告警一次后静默;`>0` = 失败持续期间最多每这么久重复告警一次。 |
| `BILI_MAX_SESSIONS` | 内存中最多保留的会话数(默认 `256`;LRU 淘汰 —— 磁盘是事实源)。 |
Expand Down
Loading
Loading