weread-omni 本地内容库原理:SQLite + 内容寻址存储如何构建零重复阅读缓存

原创2026-11-02 22:12:561,884 阅读

weread-omni 本地内容库原理:SQLite + 内容寻址存储如何构建零重复阅读缓存

weread-omni 是微信读书(WeRead)的增强工具包,它的本地内容库用 SQLite + 内容寻址存储搭出了一套零重复阅读缓存:相同内容只落盘一次,再次读取直接命中本地副本,无需重复下载。这篇指南带你弄懂这套缓存背后的原理、目录布局和日常管理命令。


💡 先说结论:它为什么快、为什么不重复

本地内容库把「查什么」和「存内容」拆成了两套系统,各司其职:

组件 存什么 为什么用它
SQLite 索引库 图书信息、目录、章节与文章的「指针」 需要按 bookId、chapterUid 快速索引
内容寻址存储(blob) 章节正文、样式、文章全文等「字节」 大、可流式读写,且天然去重

两者一结合,就实现了文章标题里那三件事:SQLite 负责「定位」,内容寻址负责「去重」,合起来就是零重复缓存。

核心思路来自源码 src/library/store.ts 的设计注释:

记录与索引进 SQLite,字节进内容寻址存储。分离是刻意为之——身份查找要索引,载荷要可流式、可去重。


🗂 本地内容库的目录布局:一库两仓

默认存放在 ~/.local/share/weread/library(若设置了 XDG_DATA_HOME 则为 $XDG_DATA_HOME/weread/library,也可用 WEREAD_LIBRARY_DIR 改写),见 src/library/paths.ts。整个目录长这样:

~/.local/share/weread/library/
├── library.db          # SQLite 索引库(含 -wal / -shm 边车文件)
├── blobs/sha256/        # 内容寻址字节仓库
│   ├── 1a/1a2b3c…      # 按哈希前 2 位分片
│   └── fe/fe99…        # 每个文件 = 一段完整正文
└── tmp/                # 写入暂存区(staging)

目录权限为 0700、文件为 0600,正文是明文但不含登录信息,仍应按敏感数据对待。

两个关键细节让「两仓」更稳:

  • 分片:字节文件不堆在一个目录,而是按哈希前 2 位分散到 blobs/sha256/<前2位>/ 子目录,避免单目录文件爆炸,见 src/library/paths.ts。
  • 暂存区:写入先落到 tmp/,最后才「转正」到正式路径,避免写一半的文件污染缓存。

🧬 内容寻址:用 SHA-256 实现零重复

「内容寻址(content-addressed)」的意思是——文件的名字不是人起的,而是由内容本身算出来的。weread-omni 用 SHA-256 摘要作为每个字节文件的文件名(见 src/library/blobs.ts):

相同正文  →  相同 SHA-256  →  相同文件名  →  只存一份

打个比方:这像一排快递柜,柜子编号不是「1 号柜」「2 号柜」,而是「按包裹指纹算出的编号」。两个内容完全相同的包裹,会算出同一个编号,自然放进同一格——零重复就是这么来的。

这套机制带来三个好处:

  1. 跨章节去重:同一本书里若出现相同片段,只占一份磁盘。
  2. 跨账号去重:多个账号读到同一章,字节仍是同一份。
  3. 内容即地址:文件名就是内容的指纹,读到哪都能反查校验,天然防「张冠李戴」。

去重不是巧合,而是构造出来的:两个并发写入者存的是逐字节相同的内容,谁先到谁成功,后到者直接复用,见 src/library/blobs.ts。


📊 SQLite 索引库:8 张表与 WAL 模式

library.db 里的表定义在 src/library/schema.ts。对新手来说,最该知道这几张:

表 作用
account 账号身份,内容按账号建立索引
blob 每个字节文件的元信息(哈希、字节数、媒体类型)
chapter 章节 → 正文/样式/纯文本的指针
book_toc 书籍目录(含章节列表 JSON)
book_meta 图书基础信息
article 公众号文章指针(原文 / Markdown / HTML)
content_version 追加式记录「被替换掉的旧版本」

注意 chapter 表里并没有正文,只有一串 sha256 指针,真正内容在 blobs/ 里,见 src/library/schema.ts。

数据库层(src/library/database.ts)还做了两件「让缓存可靠」的事:

  • WAL 模式(journal_mode = WAL):支持多进程并发读写。若文件系统不支持(如某些网络盘),CLI 会警告并自动退化为不用缓存,而不是悄悄出错。
  • synchronous = FULL:每次提交都落盘,掉电也不会留下「指针在、内容丢」的半截状态。

需要 Node.js >= 22.13.0,因为用的是内置的 node:sqlite 模块。


🎯 零重复缓存的三种生效方式

缓存不是「存了就算」,而是通过不同读取模式决定命中与否,见 src/library/cached-client.ts:

模式 行为 触发
prefer(默认) 先读本地,命中即返回,不联网 正常读取
refresh 重新下载并替换本地副本 加 --refresh
off 完全跳过缓存读写 加 --no-library

读公众号文章时,JSON 会明确标注来源:fromCache 表示是否命中本地副本;命中时返回 cachedAt(缓存时间)、fetchedAt 为 null,不伪装成刚抓取的。

关键原则:读取失败会降级为「未命中」而非报错。也就是说本地副本即使损坏,也只是回退成「重新联网抓取」,绝不会把坏内容当好的给你。


🧯 旧内容为什么「不自动清理」

content_version 表是只追加的:每当你 --refresh 更新某章,旧版本的指针不会被删,而是记一笔「被谁在何时替换」(见 src/library/schema.ts)。

这不是漏写清理逻辑,而是刻意的取舍:

一次重新抓取如果返回的是验证页或截断内容,绝不能让它把原本的好正文「擦掉」。保留旧版本,才让用户能安全重试。

代价是缓存会持续长大。library status 会专门报告 supersededVersions(被替换但保留的旧版本数量),让你能度量增长,而不是当成内存泄漏。


🩺 verify:给缓存做一次健康体检

weread-omni library verify 会对缓存做一轮全面体检,实现见 src/library/store.ts:

  • PRAGMA integrity_check:校验 SQLite 页面结构是否完好;
  • PRAGMA foreign_key_check:找出「指向不存在字节的悬空指针」;
  • 逐条重读每个 blob 并复核 SHA-256:任何被篡改、截断的文件都会当场暴露。

它还能识别一个隐蔽陷阱:只拷了 library.db、漏拷了 -wal 边车文件的备份,会在打开时被判为「无 schema」并如实报告,而不是给你一本读不出来的空书。


🧰 如何查看和管理本地内容库

三条命令即可掌控缓存(完整说明见 README.md 的「本地内容库」一节):

weread-omni library path --json     # 打印缓存存放路径
weread-omni library status --json   # 统计章节/文章/blob 数量与占用
weread-omni library verify --json   # 检查数据库与已存文件是否健康

配合两条全局开关即可灵活控制:

  • --refresh:忽略已有副本,重新下载并更新本地内容;
  • --no-library:本次命令不读写本地内容库。

内容库里的正文是明文、不含令牌,但备份时请连同 library.db 的 -wal/-shm 边车文件一起拷,避免上面提到的「空书」问题。


✅ 小结

weread-omni 的本地内容库把「索引」和「内容」解耦成 SQLite + 内容寻址存储:SQLite 负责按 ID 快速定位,SHA-256 命名让相同字节只存一份,从而实现跨章节、跨账号的零重复缓存。配合 WAL 并发、FULL 落盘、只追加的版本保留与 verify 体检,这套缓存在追求「快」的同时,也把「可靠」和「可度量」做到了位——这正是它敢把阅读内容长期留存在本地的底气所在。

登录后查看全文
weread-omni