weread-omni 本地内容库原理:SQLite + 内容寻址存储如何构建零重复阅读缓存
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 号柜」,而是「按包裹指纹算出的编号」。两个内容完全相同的包裹,会算出同一个编号,自然放进同一格——零重复就是这么来的。
这套机制带来三个好处:
- 跨章节去重:同一本书里若出现相同片段,只占一份磁盘。
- 跨账号去重:多个账号读到同一章,字节仍是同一份。
- 内容即地址:文件名就是内容的指纹,读到哪都能反查校验,天然防「张冠李戴」。
去重不是巧合,而是构造出来的:两个并发写入者存的是逐字节相同的内容,谁先到谁成功,后到者直接复用,见 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 体检,这套缓存在追求「快」的同时,也把「可靠」和「可度量」做到了位——这正是它敢把阅读内容长期留存在本地的底气所在。