跳到正文
曾亮懿 ZengLiangYi Blog

从 sql.js 迁移到 node:sqlite:WAL 与多源后台同步

在 Node.js 24 与 Electron 中用内置 node:sqlite WAL 替换 sql.js 全库导出:详解零重写兼容层、Gzip 懒加载缓存与 Worker 解析池,打通 Claude Code、Cursor、Codex 等 32 源本地会话同步。

阅读约 10 分钟
目录 展开 收起

在 Node.js 与 Electron 本地优先(Local-First)应用中,sql.js 凭借纯 WASM 零原生编译的优势非常适合早期快速交付;但当本地 AI 编程数据源从 5 个扩展到 32 个(涵盖 Claude Code、Cursor、Codex、OpenCode、Cline 等客户端及 Windows WSL 目录)时,“主线程逐个解析 + sql.js 整库 db.export() 重写落盘”同时撞上了首屏白屏、事件循环阻塞与磁盘写放大三道墙。ChatCrystal 在 v0.7(对照提交 842e44a)将持久化与同步链路拆解为四层架构:Node.js 24 内置 node:sqlite WAL 持久化、Index-First 索引优先懒加载、带解析器版本指纹的 Gzip 快照缓存,以及单飞后台同步引擎与 worker_threads 解析池。

此前在sql.js WASM 数据库持久化边界与海量对话批量导入性能优化方案中,我们定位过全量内存导出和单线程导入的瓶颈。本文复盘如何把这些诊断落地为可复用的工程实现,并诚实记录审视代码时新发现的三处并发与交互边界。

为什么 sql.js 全库导出在多源高并发同步下会成为瓶颈

sql.js 将整个 SQLite 数据库驻留在 WASM 线性内存中,本身不直接映射宿主机磁盘页;一旦消息表增长到数十万行,且接入 32 个包含上百 MB 外部状态库(如 opencode.db)、多帧拼接 .jsonl.zst 日志与数万插件文件的目录时,原有导入链路会在三个位置同时退化:

  1. 存储层整库重写写放大:每次调用 saveDatabase() 与 30 秒定时保存都必须执行 db.export(),在内存中分配完整的 Uint8Array 副本并从头覆写 chatcrystal.db,保存动作本身演变为周期性内存尖峰与同步 I/O 阻塞。
  2. 首屏可见性与最慢解析器强绑定:importAll() 必须等前序会话全文解析入库后,前端列表才能看到记录。遇到大体积外部 SQLite 或慢速 \\wsl.localhost 路径时,主线程上的同步 JSON 解析与正则清洗还会直接阻塞 Fastify HTTP 响应。
  3. 手动按钮与文件监听器各自为政:前端依赖一次性“导入”按钮,而 chokidar 只维护局部防抖布尔锁,既无法与启动期导入共享进度,又容易在启动全盘建树时与首轮导入争抢磁盘队列。
架构维度 v0.6 旧实现 v0.7 重构后实现 直接工程收益
主库持久化 sql.js 内存库 + db.export() 全量写盘 Node 24 node:sqlite(DatabaseSync + WAL) 事务即时落盘,saveDatabase() 降为轻量 WAL checkpoint
外部客户端 DB 读取 sql.js 只读快照 继续保留 sql.js(配 20 秒空闲句柄缓存) 不触碰宿主 IDE 活跃锁与外部 -wal/-shm
列表可见时机 全文解析入库后才可见 scan() 后立写 pending 索引行,正文按需懒物化 首屏列表耗时仅取决于目录 fs.stat 扫描
重复解析开销 仅靠 DB 行 size + mtime 跳过 叠加 <dataDir>/transcript-cache/*.json.gz 缓存 删库重建、中途取消续跑与懒加载均免重复解析
同步调度与监听 手动按钮 + Watcher 局部防抖锁 全局单飞 SyncEngine + 首轮同步后挂载定向 Watcher 消除启动 I/O 踩踏,变更按最长前缀只扫归属源

从 sql.js 平滑迁移到 Node.js 24 node:sqlite(WAL 模式)

将主数据库从 sql.js 切换到 Node.js 24 内置 node:sqlite 模块(Electron 44 内置 Node 24 运行时同样原生提供 DatabaseSync),能够在不引入 better-sqlite3 原生 C++ 编译链(node-gyp 与 Electron ABI 重编译)的前提下,直接获得真实磁盘文件连接与 SQLite WAL(Write-Ahead Logging)模式。

为了让既有路由、Schema 迁移与测试套件零重写切换,server/src/db/sqlite-compat.ts 用不到 400 行代码实现了 SqliteCompatDatabase 兼容层,精确对齐 sql.js 的调用语义:

  • 连接初始化开启 WAL 与外键约束:构造阶段立即执行 PRAGMA journal_mode = WAL、PRAGMA synchronous = NORMAL 与 PRAGMA foreign_keys = ON。每次事务提交即落入磁盘 WAL,原本昂贵的 saveDatabase() 直接简化为非阻塞的 PRAGMA wal_checkpoint(TRUNCATE)。
  • 词法级多语句切分与 CREATE TRIGGER 保护:sql.js 的 exec() 和 run() 支持一次传入分号分隔的多条 SQL,而 DatabaseSync.prepare() 每次仅接受单条语句。splitSqlStatements() 逐字符跳过单双引号转义、-- 与 /* */ 注释,并专门识别 CREATE TRIGGER … BEGIN …; END; 块,防止触发器体内的分号被误切分。
  • 命名参数前缀与空结果集对齐:sql.js 允许参数对象键带 :、$、@ 前缀(如 { ':id': 'abc' })且在 0 行结果时返回空数组 [];兼容层在 toNamedParams() 与 execPrepared() 中抹平了这两处差异,并借助 DatabaseSync.serialize() 保留了备份测试所需的字节导出能力。
export class SqliteCompatDatabase {
  private readonly handle: DatabaseSync;

  constructor(filePath: string) {
    this.handle = new DatabaseSync(filePath);
    this.handle.exec('PRAGMA journal_mode = WAL');
    this.handle.exec('PRAGMA synchronous = NORMAL');
    this.handle.exec('PRAGMA foreign_keys = ON');
  }

  checkpoint(): void {
    try {
      this.handle.exec('PRAGMA wal_checkpoint(TRUNCATE)');
    } catch {
      // 存在活跃读取或未提交事务时保留当前 WAL,留待下次检查点或 close() 刷盘
    }
  }
}

同样关键的是读写分治策略:ChatCrystal 自身持有的 chatcrystal.db 走 node:sqlite WAL,但解析 Cursor(state.vscdb)、OpenCode(opencode.db)、Goose、Hermes、Alma 等第三方本地数据库时,适配器仍然使用 sql.js 将文件快照读入 WASM 内存。因为宿主 IDE 往往正持有这些数据库的写锁,直接挂载外部活跃 SQLite 连接极易触发 SQLITE_BUSY 或污染宿主的 -wal/-shm 文件,内存快照则是天然无锁的只读隔离层。

大体积 JSONL 与 SQLite 会话懒加载:Index-First 与 Gzip 版本化缓存

面对上千条历史会话,决定用户体感速度的不是最后一条文件何时解析完,而是列表第一屏何时可交互。server/src/services/import.ts 通过 Index-First(索引优先) 两阶段流水线将目录发现与正文解析彻底拆开。

第一阶段:扫描即建 pending 索引行,详情页按需懒物化

各源适配器的 scan() 仅执行目录遍历与 fs.stat。每扫完一个源,importAll() 立刻在单事务内调用 ensureIndexedConversation() 插入 transcript_status = 'pending' 的索引行(若已知文件的 file_size 或 file_mtime 变化,则保留原行并重置回 'pending')。

即使后台队列仍有上千个文件待解析,前端列表也能立即展示全部会话。当用户直接点开某条 pending 会话(或触发摘要生成)时,server/src/routes/conversations.ts 会即时调用 materializeConversationById() 插队补齐该篇正文:

if (
  loaded.conversation.transcript_status &&
  loaded.conversation.transcript_status !== 'materialized'
) {
  const materialized = await materializeConversationById(id);
  if (materialized === 'error') {
    reply.status(500);
    return { success: false, error: 'Failed to load the conversation transcript' };
  }
  loaded = loadConversation();
}

物化阶段同步处理了两类一致性边界:若解析器读完正文后重写了规范 ID(parsed.id !== meta.id),会先清理扫描期插入的临时占位行;若解析后有效消息少于两条(parsed.messages.length < 2),则删除该 indexOnly 占位行,确保懒加载与全量导入的数据过滤规则严格等价。

第二阶段:带 parserVersion 指纹的原子 Gzip 快照缓存

为避免删库重导、中途取消续跑或按需物化重复解析大文件,server/src/services/transcript-cache.ts 将归一化后的 ParsedConversation 压缩保存在 <dataDir>/transcript-cache/<source>/<sha1>.json.gz。

缓存键将所有会影响解析结果的输入拼成 \0 分隔的七元组计算 SHA-1(延伸自 SourceAdapter 内容哈希与幂等导入设计):

function cacheKey(meta: TranscriptCacheMeta, parserVersion: string): string {
  const parts = [
    meta.source,
    meta.id,
    parserVersion,
    meta.filePath,
    String(meta.fileSize),
    meta.fileMtime,
    meta.rootDir ?? '',
  ];
  return createHash('sha1').update(parts.join('\0')).digest('hex');
}

纳入 parserVersion(如修复 Codex 0.160+ 事件格式后的 codex@4、双表去重的 opencode@2)与 rootDir(区分宿主机与 WSL 根目录)后,任何解析逻辑升级只需递增版本号即可自动淘汰旧缓存。写入采用 <sha1>.json.gz.<pid>.<uuid>.tmp 同目录临时文件加 rename 原子替换,并按每 20 次写入定期清理超过 512 MB 或 30 天 的冷数据;任何损坏归档或 Windows 文件锁异常均静默回退为重新解析。

Node.js worker_threads 解析池(tsx 兼容)与 chokidar v4 静态目录监听

要彻底告别手动导入按钮且不拖慢开发机,后台调度必须同时管住并发冲突、CPU 隔离与文件系统监听风暴:

  1. 单飞状态机 SyncEngine(server/src/services/sync.ts):启动后 2.5 秒自动首扫、POST /api/sync/start 手动触发与文件变更事件全部汇入同一状态机。同一时刻最多运行一轮同步;运行期间的新触发按源合并进 pendingSources,待当前轮次收尾后自动续跑;cancel() 则清空挂起队列并通过 AbortSignal 在文件边界安全停机。
  2. 兼容 tsx 与打包降级的 ParserPool(server/src/services/parse-pool.ts):默认按 min(4, max(1, availableParallelism() - 1)) 懒启动 worker_threads。针对开发态 tsx 运行 .ts 源码时子线程不自动继承 ESM Loader 的常见坑,池子根据 import.meta.url 自动注入 execArgv: ['--import', 'tsx'];若受限打包环境下首个 Worker 在 10 秒内未能就绪,则告警一次并平滑退化为主线程内联解析(degraded = true)。
  3. 首轮同步完成后才挂载的 chokidar v4 定向监听(server/src/watcher/index.ts):部分客户端(如 WorkBuddy)主目录下有约 7 万个插件市场文件,启动时若让 chokidar 建树与首轮导入并发执行,双倍 readdir/stat 会直接打满磁盘 I/O。因此 createServer 严格等 syncManager 完成首轮同步后才启动监听器;同时适配 chokidar v4 移除 glob 字符串的变更,由 normalizeWatchTarget() 截取首个通配符前的静态父目录,忽略 node_modules/.git/.cache,并在 1.8 秒防抖后按最长路径前缀反查变更所属的单一 source 触发增量同步。

解析 32 个 AI 编程客户端记录:共享基板、多帧 zstd 与 WSL 边界

从早期的五种主流客户端对话存储格式扩展到 32 个会话源(涵盖 Claude Code、Cursor、Codex、Gemini CLI、OpenCode、Goose、Cline、Roo Code、Kilo Code、Continue、Claude Desktop、Copilot / Copilot CLI、Trae、Factory Droid、Antigravity、Hermes、Kimi、Qwen、MiniMax、DeepSeek Harness、Pi、omp、Raft、Cindy、ZCode、Alma、CodeBuddy、WorkBuddy、Qoder / Qoder CN、Grok Build),v0.7 没有编写 32 套孤立脚本,而是提炼出三类家族基板:Cline 家族 VS Code 任务基板(adapters/vscode-tasks.ts,参数化兼容 history_item.json 与 taskHistory.json)、Pi 会话流基板(adapters/pi-sessions.ts,复用于 Pi / omp / Raft / Cindy)以及 OpenCode 跨代双 Schema 基板(adapters/opencode.ts,合并 1.x 三表与 2.x session_v2 并复用于 ZCode)。

在异构协议落地上,有两个极易踩坑的系统级边界值得单独拆解:

修复 Node.js zlib.zstdDecompressSync 多帧 .jsonl.zst 截断

DeepSeek Harness 与新版 Codex 的 .jsonl.zst 会话在每次写入刷盘时,都会向文件末尾直接拼接(concatenate)一帧独立的 zstd 数据。Node.js 内置的 zlib.zstdDecompressSync() 面对多帧拼接缓冲区时只解压第一帧便提前结束,导致首轮之后的所有对话静默丢失;但若简单用 buf.indexOf 搜索 4 字节魔数(0xFD2FB528)切分,一旦压缩负载内巧合出现相同字节序列就会截断报错。

server/src/parser/zstd.ts 严格依据 RFC 8878 §3.1.1 帧格式规范解析 Frame_Header_Descriptor、窗口描述符、字典 ID 与变长 Frame_Content_Size,再循环读取 3 字节小端块头(Last_Block + Block_Type + 21 位 Block_Size)与可选 4 字节校验和,精确步进定位每一帧边界;仅当末尾帧正处于半写入状态导致步进返回 null 时,才回退到最多 3 次魔数边界探测,完整抢救已落盘的前序对话。

Windows 读取 \\wsl.localhost:UTF-16LE 解码与禁止唤醒休眠 WSL

Windows 虽可通过 \\wsl.localhost\<distro>\home\<user> 读取 WSL 内的 Claude Code 或 Codex 会话,但存在两个隐蔽副作用:一是 wsl.exe 标准输出在管道重定向时默认编码为 UTF-16LE 而非 UTF-8;二是对已停止(Stopped)的发行版执行 fs.stat 或挂载 chokidar,会触发系统在后台强行冷启动整个 Linux 虚拟机。

parser/wsl.ts 通过支持 UTF-16LE BOM 与零字节特征检测的解码器执行 wsl.exe -l --running -q,严格只扫描当前处于 Running 状态的发行版(目录解析结果缓存 5 分钟),并配合 watcher/index.ts 中的 isWslUncPath() 守卫,彻底禁止对 \\wsl.localhost 和 \\wsl$ 建立文件监听。

工程复盘:三个已识别的并发吞吐与交互边界

全链路审视 v0.7 代码后,存储持久化与多源隔离已经非常扎实,但也清晰暴露了三个可在下一版本继续打磨的边界:

  1. 事件循环解耦已完成,但批处理尚未喂饱多核 Worker 槽位:ParserPool 默认开启最多 4 个工作线程,但 importAll() 主循环仍采用串行 await importConversationItem(...),意味着批量同步期间池内同时只有 1 个 Worker 处于忙碌状态。下一步可将“读缓存 + Worker 解析”改为有界滑动窗口预取(主线程保持串行 SQLite 事务落盘),并对缓存了 20 秒 sql.js 实例的大体积外部库按 source 做固定 Worker 亲和路由,避免 4 个线程重复加载同一份百兆 opencode.db。
  2. scanning 阶段列表渐进刷新签名还可更灵敏:前端 useSyncStatus 当前仅根据 ${imported}:${replaced}:${skipped}:${errors} 变化触发列表重拉;在 32 个源依次 scan() 插入 pending 行阶段,四个计数恒为 0:0:0:0,需等到首条会话解析完成才触发首次刷新。将 progress.total 纳入签名即可实现每扫完一个源立刻上屏。
  3. 不足 2 条消息的 pending 占位行被抢先点击时的空态过渡:scan() 不读正文,单行中断会话会短暂生成 pending 行;若用户在后台清理前点入详情,materializeConversationById() 判定有效消息不足 2 条会删除占位行并返回 'skipped',使详情接口二次查询返回 404。为 'skipped' 分支补充显式前端提示并退回列表即可闭合该边界。

从早期全内存 sql.js 演进到 node:sqlite WAL、索引优先与异构解析池,最核心的工程经验只有一条:本地优先工具的流畅度,取决于何时避免全量写盘、何时推迟正文解析,以及何时绝对不碰邻居进程的文件锁与虚拟机电源状态。完整模块关系可进一步参考 ChatCrystal 项目架构导览与源码中的 sqlite-compat.ts 及 transcript-cache.ts。

分享:

相关文章

大文件批量导入的 Node.js 内存管理与分批流式处理

测量与治理 Node.js 大体积会话批量导入的内存峰值:拆解 JSONL 解析、sql.js WASM 线性内存、全库导出与异步队列开销,用可复现基准决定分批策略。

曾亮懿 曾亮懿
阅读约 6 分钟
#ChatCrystal #Node.js #数据解析 #性能优化

从文章到代码

到我的 GitHub 看看 ChatCrystal、KeelDesk、n8n 工作流和日常学习记录,欢迎交流实现细节。