Skip to content

[bug] index.db-wal 在长驻进程内永不 checkpoint —— STORAGE_PRAGMAS 无 journal_size_limit、master 无 wal_checkpoint 调用,WAL 单调增长到 55 MiB 不回收 #3250

Closed

Description

@xiaweiliang060035

症状

长驻的 bili 进程(lane 模式,非每次请求新建)持续 ingest 会话状态后,
<state>/sessions/index.db-wal 只增不减,从不回落:

时刻 index.db-wal
2026-10-14 10:33 起 58,145,592 B(单调增长到 55.5 MiB 后长期停住)
2026-10-14 全时段复采(10 次间隔采样) 58,145,592 B(无变化)
2026-10-15 03:03 58,145,592 B(index.db 同期 63.8 MB)

同时 index.db-shm 只有 32 KiB、index.db 63–77 MB —— 说明不是有活跃写事务卡住,
只是没有任何一方触发 checkpoint。

从外部进程(独立 sqlite 连接)执行一次 checkpoint,帧立刻全部落盘:

// 外部探针,bili 进程仍在运行
db.prepare("PRAGMA wal_checkpoint(PASSIVE)").get()
// => { busy: 0, log: 2720, checkpointed: 2720 }

busy:0 + 全部 2720 帧可 checkpoint = WAL 里全是已经可以安全回收的帧,
却没有任何代码路径去回收它们。于是它同时吃到两点代价:

  1. 磁盘常驻占用:本例 55.5 MiB 永不释放,且随运行时长继续涨;
  2. 崩溃恢复时间:进程被强杀/掉电后,下一次 open 必须重放整个 WAL。

环境

  • bili 版本:0.1.197(npm latest,commit 3aeddc16)—— 该现象在 0.1.196 与 0.1.197 上都观察到
  • 模式:Launcher(DSH Desktop 宿主 DeepSeek Harness.exe 直接 spawn node dist/index.js start --host 127.0.0.1 --port 18795)
  • 客户端:dsh(DeepSeek Harness Desktop),lane dsh
  • 操作系统:Windows 11,NTFS
  • 上游/模型:本机回环 relay(http://127.0.0.1:8791)· deepseek-v4.1-flash / glm-5.3-flash
  • storage 配置:默认 unified: "shadow"(未显式设过 legacy)
  • node:v26.7.0(内置 node:sqlite,storage.engine = {name:"node:sqlite", source:"builtin"})
  • 会话负载量级参考:单会话 3368 requests / 559M input tokens;本机共 83 个会话信封

根因(master 代码事实)

STORAGE_PRAGMAS = [
  "PRAGMA journal_mode = WAL",
  "PRAGMA synchronous = NORMAL",
  "PRAGMA busy_timeout = 5000",
  "PRAGMA foreign_keys = ON",
]
  • 没有 PRAGMA journal_size_limit —— WAL 文件本身没有任何大小上限;
  • 没有 PRAGMA wal_autocheckpoint 干预,也没有显式的 wal_checkpoint(...) 调用。

在 master 上做 code search 交叉验证(已认证,scopes 含 repo):

搜索词 命中
wal_checkpoint 仅 1 处,tests/launcher-sqlite-overlay.test.ts(测试文件,不在运行路径)
journal_size_limit 0
wal_autocheckpoint 0

对上游 0.1.197 的原始 dist/index.js(未打任何本地补丁的副本)逐字节复核:
wal_checkpoint 0 命中、journal_size_limit 0 命中、synchronous = NORMAL 2 命中。

也就是说:sqlite 自带的 autocheckpoint(默认 1000 页 ≈ 4 MiB)在持续快速 ingest
的场景下会被反复推迟——每一次写入都会推进 WAL 头,checkpoint 只能在「没有读者、
且写事务之间」的窗口里跑,而 bili 的 ingest 节奏让这个窗口很少出现;
叠加 synchronous=NORMAL 语义(不保证每次提交落盘),内核也没有任何补位机制。
结果是 WAL 在一个长驻进程里单调增长,只有进程重启或外力介入才会回落。

注:#3163 的 fsync 修复(b31d193d)只覆盖 tmp+rename 的状态信封写路径,
不触及 sqlite 的 WAL 生命周期 —— 这两件事是独立的。

本机修复验证(供参考的最小实现)

三条改动,互不冲突,全部用 try/catch 包住(checkpoint 失败绝不该影响 ingest 路径):

// 1) 给 WAL 一个上限
STORAGE_PRAGMAS = [
  "PRAGMA journal_mode = WAL",
  "PRAGMA synchronous = NORMAL",
  "PRAGMA busy_timeout = 5000",
  "PRAGMA foreign_keys = ON",
  "PRAGMA journal_size_limit = 8388608",   // 8 MiB
];

// 2) open 后 / close 前各一次 TRUNCATE,收敛残留并保证干净退出
for (const pragma of STORAGE_PRAGMAS) db.exec(pragma);
migrateSchema(db);
db.prepare("PRAGMA wal_checkpoint(TRUNCATE)").get();        // open

close() {
  db.prepare("PRAGMA wal_checkpoint(TRUNCATE)").get();      // close
  this.db.close();
}

// 3) ingest 计数每 N 次走一次 PASSIVE,避免长任务里永远轮不到回收
this.store.ingestSession(plan);
this.stats.ingests++;
if (this.stats.ingests % 20 === 0) {
  this.store.db.prepare("PRAGMA wal_checkpoint(PASSIVE)").get();
}

同样负载下打补丁后的实测(同一台机器、同一会话目录):

补丁前 补丁后
index.db-wal 行为 单调增长,停在 58,145,592 B 在 ≈12.5 MB 振荡(13,245,832 / 12,557,792 / 11,915,072 …)
5 次间隔采样 无变化 出现 −181,280 / −642,720 的回收

关联

复现与量化(可直接跑)

# WAL 大小随时间曲线(bili 运行中,间隔 30s 采 20 次)
$s = "$env:USERPROFILE\.local\share\billion-context\sessions"
1..20 | % { (Get-Item "$s\index.db-wal").Length; Start-Sleep 30 }

# 外部 checkpoint 对照:能落盘但没人触发 = 就是本条 bug
node -e "const {DatabaseSync}=require('node:sqlite');const d=new DatabaseSync(process.argv[1]);console.log(d.prepare('PRAGMA wal_checkpoint(PASSIVE)').get())" "$s\index.db"

Activity

  1. ranxianglei commented on Oct 15, 2026

    @ranxianglei
    Owner

    🤖 Powered by ework · qwen3.8-27b

    (ai: vllm-qwen/qwen3.8-27b)

    查重: 不重复。 open+closed issue/PR 全量检索(WAL / checkpoint / journal_size_limit / index.db-wal),只有本 issue 命中「单进程 WAL 无回收触发点」这一主题。与你引用的三个相邻项逐一比对:

    Triage 三步已对 master(effd544)验证,事实全部成立:

    1. 复现/查证:src/storage/schema.ts:68-73 的 STORAGE_PRAGMAS 确为 journal_mode/synchronous/busy_timeout/foreign_keys 四条,无 journal_size_limit;全仓运行时路径无 wal_checkpoint 调用(仅 tests/launcher-sqlite-overlay.test.ts 出现);UnifiedStore.open(src/storage/store.ts:229)无任何 checkpoint,close()(:247)裸 db.close()。长驻 lane 进程的 sidecar 只在 SIGTERM/SIGINT 的 flushAll/closeQuietly(src/persist.ts:1491/1501)才 close——SIGKILL/断电永远到不了 close,与你描述的触发条件一致。

    2. 层次判断:补一句机制细节,你的分析方向完全正确——sqlite 内置 autocheckpoint(默认 1000 页)即使正常触发,做的也是 PASSIVE checkpoint:只把帧搬进主库、把写偏移归零,从不调用 ftruncate 缩 WAL 文件。所以「文件涨到峰值后卡死不动」与 autocheckpoint 是否在工作无关,缺的就是文件级回收(TRUNCATE checkpoint / journal_size_limit)。你外部探针看到的 {log:2720, checkpointed:2720} 正是「帧可回收但无人执行回收」的形态。这是根因层的问题,不是表面现象。

    3. 方案评估:你本地验证过的三层补丁方向正确且最小,我按同一思路收进存储层实现(而不是 shadow 层):

      • ① STORAGE_PRAGMAS 加 PRAGMA journal_size_limit = 8388608(8 MiB)——让每次 auto/manual checkpoint 之后把 WAL 截回上限,治「单调增长」;
      • ② UnifiedStore.open 迁移完成后一次 TRUNCATE(收敛上次异常退出残留、缩短下次崩溃恢复回放)+ close() 前一次 TRUNCATE(干净退出即收敛);
      • ③ 每 20 次成功 ingest 一次 PASSIVE(连续灌入期兜底,永不阻塞)。

      所有 checkpoint 调用独立 try/catch:失败只记日志,绝不影响 ingest/写入路径;多进程共享目录拓扑(Storage layer: four concrete defects (filename coupling, multi-writer heuristic, non-atomic content-store write, immortal compressed sessions) #2671)下 TRUNCATE 遇外部落读者会返回 busy 行而非抛错,自然跳过,无损坏面。不加新 config/env(常量内部定死,符合配置面纪律)。

    交付计划:回归测试先行(重写下 WAL 有界、重启后收敛到 0、close 后收敛到 0、ingest 正确性不受影响;先在未修复代码上确认测试红),然后一个 PR 收掉本 issue,PR 里按规矩披露行为变更(WAL 由无界增长 → ≤8 MiB+余量;boot/shutdown 各多一次一次性 checkpoint IO)。开干。

  2. ranxianglei commented on Oct 15, 2026

    @ranxianglei
    Owner

    🤖 Powered by ework · qwen3.8-27b

    (ai: vllm-qwen/qwen3.8-27b)

    修完了,PR 已开:**#3255 #3250)。

    结构化八问

    1. 是什么问题:长驻进程里 sessions 索引的 sqlite WAL 文件(index.db-wal)随运行时长单调增长、永不回收(现场 55 MiB 平直),永久占盘;非正常退出后下次启动还要把整个 WAL 重放一遍。
    2. 什么原因导致的:两个机制叠加。① STORAGE_PRAGMAS 没设 journal_size_limit,而 sqlite 的 passive/auto checkpoint 只把帧搬进主 db、重置写偏移,从不缩小文件本身——文件永远停在历史高水位;② 运行时路径没有任何显式 checkpoint 调用,且(本地实测钉死)连接在仍是最后写者期间无法回收自己刚写的帧——commit 后立刻 same-conn PASSIVE 一帧都收不回来——所以没有「后续写入 + 一次完成的 checkpoint」这个循环做外部触发,文件就永远不会被推回去。SIGKILL/断电到不了 close(),连收敛点都没有。
    3. 影响范围与严重程度:所有用 unified 存储 sidecar 的长驻 lane 进程(dsh/opencode 等各 lane);严重度 = 持续磁盘占用(随运行时长增长)+ 崩溃恢复重放时间变长;不影响数据正确性与可用性,属「特定条件下有问题」(长驻 + 有写入量)。
    4. 怎么修复的:三层回收——① STORAGE_PRAGMAS 加 journal_size_limit = 8 MiB(每次完成的 checkpoint 把文件截回上限);② open 后一次性 TRUNCATE(收敛非正常退出残留,缩短下次恢复)+ close 前一次性 TRUNCATE(干净退出零残留);③ 每 20 次成功 ingest 一次 PASSIVE(连续 ingest 下保证回收,尤其外部读快照 pin 住帧时)。所有 checkpoint 调用独立 try/catch:失败只记日志,绝不影响 ingest/open/close 契约;多进程共享目录(Storage layer: four concrete defects (filename coupling, multi-writer heuristic, non-atomic content-store write, immortal compressed sessions) #2671 拓扑)下 busy 返回行而非抛错,自然跳过不损坏。
    5. 是否有回归问题:逐项审过既有行为——ingest 事务语义不变(checkpoint 在 commit 返回之后跑;delta 回退失败不计数);open() 失败契约不变(损坏文件仍走 close+rethrow 降级,checkpoint 失败被隔离、不参与该判定);close() 仍是 best-effort(shadow.close 本来就吞异常,内部只是多一个隔离 try/catch);持久化语义不变(synchronous = NORMAL 未动,Storage Subsystem Wrap-up Checklist (#3130 Review): Dropping the last tick upon self-disable; BILI_PERSIST=0 falsely triggering a "Storage Degraded" banner; storageMode stamp mismatched with the actual enabled mode; and 3 more (6 items total) | 存储子系统收尾清单… #3135 的掉电丢提交 INFO 是另一机制,不在本 PR);schema version 保持 5,无 wire/persistence 格式变更。本地验证:新增 4 个回归测试修复前全红(断言以具体字节数失败)、修复后全绿;storage 区 20 个测试文件 151 pass / 0 fail / 1 skip(既有 skip);typecheck 干净;全量回归等 CI。
    6. 是否破坏缓存:不涉及——未触碰前缀缓存/重试/去重键/增量游标;journal_size_limit 是 per-connection 设置,不影响其他进程的连接。
    7. 是否改了设计方向:不涉及——仍是 unified sidecar + legacy 回退架构,只在存储模块内部加了回收层。
    8. 是否引入了新的配置:无——8 MiB 与 20-ingest 周期是内部常量(导出仅为测试钉死),不是用户拨盘;日后要调参再走 owner-gated 流程进配置面。

    行为变更披露(old → new):index.db-wal 从「无界增长」变为「完成的 checkpoint 之后有界 ≈8 MiB」(两次回收之间可暂时超出,下个 tick/close/open 收敛);启动多一次 ms 级 TRUNCATE(并发 busy 自动跳过);干净退出把 WAL 截到零,下次启动无需重放。详见 PR 描述。

    判定:可合并——纯 fix、单模块范围、回归测试复现原缺陷(先红后绿已证明),§7.4 auto-merge 各条满足(kernel/config/wire/persistence 均未触碰);等 CI 绿 + 你合并。

  3. ranxianglei commented on Oct 15, 2026

    @ranxianglei
    Owner

    8M是不是太小了 任意一个会话都8M 10M甚至100M 同时支持十几个会话

  4. ranxianglei commented on Oct 15, 2026

    @ranxianglei
    Owner

    直接搞一个参数吧 storage下面?

  5. ranxianglei commented on Oct 15, 2026

    @ranxianglei
    Owner

    🤖 Powered by ework · qwen3.8-27b

    (ai: vllm-qwen/qwen3.8-27b)

    先澄清 8M 的语义,再说参数。

    8M 不是每个会话的存储配额。 WAL 只是 SQLite 的中转区:每次写入先进 WAL,checkpoint 立刻把它拷进 index.db 正身并清空 WAL——数据不留在 WAL 里,会话再大(100M)、并发再多(十几个),都是「填满→清掉→再填」在 cap 附近振荡,不会叠加。字段实测也印证:修复前是 55M 只涨不清(没有任何回收);修复后在 cap 附近振荡(大突发提交时短暂超过 cap,下一次完成的 checkpoint 就截回)。cap 调大 = 截断 IO 更稀疏但平时占盘更多、崩溃恢复要重放的尾巴更长,对正常负载没有收益。所以默认保持 8MiB。

    参数照你说的加,放 storage 下面,形态:

    项 值
    配置键 storage.walJournalSizeLimitBytes(整数字节)
    env BILI_STORAGE_WAL_JOURNAL_SIZE_LIMIT_BYTES(优先于文件值)
    默认 8388608(8 MiB)
    生效时机 lane 启动开库时(与 unified/jsonWriter 同生命周期,热改下次重启生效)
    非法值 落回文件值/默认,不崩

    你那种「单会话几十上百 M、十几会话并发」的场景如果实测发现突发太大、截断太频繁,把它调到 64/100 MiB 即可,不用改代码。checkpoint 节奏(每 20 次 ingest 一次 PASSIVE)先保持内部常量——没有用户可见的理由暴露它,需要再说。

    另外汇报 CI:上一版 head 的 39 条 lane 里只有 2 条红,都在 Windows 且与本 PR 无关的文件(wire-exit-matrix 一条 1.5s 定时的时序断言、web-routing 事件循环排空),正在查历史 flake 记录;本参数的新提交会触发全新一轮 CI,届时一并看结果。

  6. ranxianglei commented on Oct 15, 2026

    @ranxianglei
    Owner

    🤖 Powered by ework · qwen3.8-27b

    (ai: vllm-qwen/qwen3.8-27b)

    参数已加好,就在 storage 下面,PR #3255 已更新并 rebase 到当前 master。

    项 值
    配置键 storage.walJournalSizeLimitBytes(正整数字节,可选)
    env BILI_STORAGE_WAL_JOURNAL_SIZE_LIMIT_BYTES(优先于配置文件)
    默认 83888608 → 更正:8388608(8 MiB)= 原硬编码值,不配置行为不变
    生效时机 lane 启动(store open);热改需重启,与 storage.unified/jsonWriter 同生命周期
    非法值 env 非正整数静默落到配置文件层 → 默认,boot 不崩
    诊断 runtime-status 诊断块报两层取值;周期 checkpoint 的 debug 日志带 busy/log/checkpointed,调参时能直接看到 tick 是否真在收帧

    再确认一下默认值为什么留 8 MiB:这个 cap 不是每会话配额——WAL 只是两次回收之间的暂存区,数据 commit 时就进了 index.db,会话再多也只是让 WAL 在 cap 附近来回摆,不占额外磁盘。调大它的真实收益只有「truncate IO 更稀疏」,代价是崩溃恢复重放尾更长;如果你那台机器确实想放宽(比如 32 MiB),现在改一行配置就能生效,不用等发版。

    八问

    1. 是什么问题:上一版把回收上限写死在代码里,多会话宿主没法按自己的磁盘/恢复时间偏好调参——本轮是落实你的参数化要求,不是新缺陷。
    2. 什么原因导致的:原实现为最小修复面硬编码常量;你拍板后按 Config Surface 流程转正为配置项。
    3. 影响范围与严重程度:纯增量可选字段;所有现有配置不设它时行为与已推送版本完全一致,无外部可见变化。
    4. 怎么修复的:config 键 + env 走 knobs 三级解析(env > 文件 > 默认),在 UnifiedStore.open 注入 PRAGMA journal_size_limit;端到端有测试钉住(config → open → pragma 链路,自定义 1 MiB cap 实测截回 1 MiB 而非 8 MiB 默认)。
    5. 是否有回归问题:无——默认值 = 原硬编码值;storage 区 20 个测试文件 152 pass / 0 fail,typecheck + unused-export gate 干净。
    6. 是否破坏缓存:不涉及(SQLite pragma,连接级)。
    7. 是否改了设计方向:没有,仍在 storage 域内,与三个兄弟键同构。
    8. 是否引入了新的配置:是——即上表两项,零迁移。

    CI 在新 head(d97bf3e)上跑,绿了你合并即可:#3255

  7. ranxianglei commented on Oct 15, 2026

    @ranxianglei
    Owner

    🤖 Powered by ework · qwen3.8-27b

    (ai: vllm-qwen/qwen3.8-27b)

    笔误更正:上条表格里默认值应为 8388608(8 MiB),「83888608」是手误多打了一位。代码、CONFIGURATION.md/zh-CN、PR 描述里均为 8388608。

  8. ranxianglei commented on Oct 15, 2026

    @ranxianglei
    Owner

    🤖 Powered by ework · qwen3.8-27b

    (ai: vllm-qwen/qwen3.8-27b)

    CI 全绿,可以合并了:#3255 58e8689,40/40 通过)。

    过程中补了一个我漏掉的环节:CONFIGURATION.md 是 website/config-reference/*.yaml 的生成物(docs-sync/docs-coverage/config-surface-guard 三道门禁管这个),上一版直接手改了文档没加种子条目——已按规范补上 storage.walJournalSizeLimitBytes 种子并重新生成,本地三道门禁全过后推送。

    另外两个与本次改动无关的 CI 红,如实报备:① 上一 head 的两个 Windows 测试红(wire-exit-matrix 时序断言、web-routing 事件循环挂起)——前者正是刚合入 master 的 #3233 修的,rebase 后本轮通过;② hermetic registry e2e 在本 head 首次跑挂(ubuntu 一个 20s 安装窗口断言超时 + windows EBUSY 文件锁),同一代码在几分钟前的相邻 head 上刚跑绿过、且该 lane 今日在 ~20 个其他 PR 分支上全部成功,判定为偶发,已重跑失败 job,重跑通过。

  9. added a commit that references this issue on Oct 15, 2026
  10. added a commit that references this issue on Oct 24, 2026
  11. added a commit that references this issue on Oct 24, 2026
  12. added 4 commits that reference this issue on Oct 24, 2026
  13. added 4 commits that reference this issue on Oct 30, 2026
  14. added a commit that references this issue on Nov 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions