公众号阅读器Liuli：内容归档、正文提取与离线阅读设计

1. 先想清楚：这类阅读器到底在解决什么问题

我做内容归档这件事有几年了，最初的想法很朴素：每天在手机上刷到的长文，看的时候觉得有用，过两周想回头找某个观点，翻聊天记录、翻收藏夹、翻搜索历史，全都翻不到。平台内的收藏功能只解决"存"，不解决"找"和"读"，尤其是当一个作者持续产出几十上百篇的时候，你根本没有办法像翻一本书那样去翻他。

公众号阅读器 Liuli 这个项目，本质上就是把这件事拆成了三段：把公开内容取回来、把正文从页面里抠干净、把抠出来的东西变成一个可检索可离线阅读的本地库。听起来像三件事，但真正动手做过的都清楚，这三段的难度是倒着来的——采集反而是最简单的，正文抽取是最容易翻车的，阅读端体验是最容易被忽略但最决定你还会不会用第二天的。

这篇东西我想按源码剖析的路子走一遍，把每一层的设计意图、关键参数、以及我踩过的坑都摊开。适合两类人看：一类是想自己搭一个内容归档工具、有点 Python 或 Go 基础但没做过完整链路的；另一类是已经写过爬虫但只写过"抓下来存文件"这种初级形态，想搞清楚怎么把它做成一个能长期跑、能天天用的东西。代码我会贴关键片段，但重点不在抄代码，而在为什么这么写。

有一点先说明白：下文所有采集行为都限定在公开可访问内容的个人归档范围内，只讨论调度、解析、存储这些工程问题，不涉及任何访问控制相关的手段。这条线必须先划清楚，否则后面所有技术讨论都是空中楼阁。

2. 架构拆解：三个解耦决定了整个项目的上限

2.1 采集与阅读解耦：为什么不能边抓边看

新手最容易犯的错，是把采集和展示写在一个循环里：抓一篇文章，立刻渲染到界面。这样写起来快，二十行代码就能跑，但它有三个致命问题。

第一个是阻塞。网络请求的耗时是不可控的，慢的时候三五秒，长的时候三十秒超时。如果渲染逻辑挂在请求的同一根线上，用户点开列表就得看着转圈，体验直接崩掉。第二个是状态污染，采集过程中的临时数据、重试计数、异常堆栈会混到展示层的状态里，出问题的时候你根本分不清是抓取失败还是渲染失败。第三个是不可回放，采集一旦失败，前端什么都拿不到，你也没法单独重跑那一次抓取。

Liuli 的做法是彻底切断这两端：采集端只管往库里写，阅读端只管从库里读，两边通过数据库这个"中间态"通信。这个设计的直接好处是，采集可以放在后台定时跑，阅读端永远只查本地，响应时间从"网络延迟"降到"磁盘 IO"级别。实测在一个十几万篇文章量级的库上，列表页首次查询大概几十毫秒，翻页基本无感。

更隐蔽的好处是可回放。因为原始响应和解析结果可以分开存，当你的正文提取规则升级了（这种事一定会发生），你可以把历史原始数据重新跑一遍解析，不用重新抓。这一点在长期维护里价值极高，我后面第 5 章会专门讲这个设计怎么落到表结构上。

2.2 内容与呈现解耦：正文抽取才是真正的核心

很多人以为这个项目的技术含量在"怎么抓到"，实际上抓取是这个链条里最标准化的一环——请求、拿 HTML、存下来，没了。真正吃功夫的是从一坨混着导航、广告、推荐位、评论区、样式脚本的 HTML 里，把正文那一块准确抠出来。

为什么难？因为页面结构不是为你准备的。你面对的是一个为了在浏览器里好看而生成的文档树，正文只是其中一部分，而且不同账号、不同排版模板、不同文章类型（图文、纯文字、带大量代码块、带表格）的结构差异巨大。写死 XPath 的方案，换一个模板就全废。

Liuli 采用的是基于文本密度和标点密度的启发式评分，而不是选择器硬匹配。这个选择的理由很实在：选择器方案的上限是"你能枚举多少种模板"，而启发式方案的上限是"你的评分函数有多贴合人类对'正文'的直觉"。前者是线性增长，后者可以泛化。代价是启发式方案永远做不到 100% 准确，所以必须配一套人工兜底和规则兜底的机制，这个我在第 4 章展开。

2.3 本地优先：为什么存储选了 SQLite 而不是别的

选型这块我纠结过挺久，最后落到 SQLite，理由有三条，都挺功利的。

第一，部署成本为零。这个工具的使用者大概率是"自己电脑上跑一个服务"，不是团队协作。上 PostgreSQL 或者 MySQL 意味着用户要先装数据库、配账号、开端口，一多半人会在这一步放弃。SQLite 是一个文件，复制粘贴就能迁移，备份就是cp。

第二，单机读性能足够。这个场景的并发量是"一个人，可能加一个手机"，读写比大概是 100:1。SQLite 在 WAL 模式下，读是完全并发的，写虽然串行但写入量很小（定时批量插入），完全构不成瓶颈。我压过一轮，单表百万行、带索引的列表查询在普通 SSD 上是个位数毫秒。

第三，全文搜索能内建。SQLite 自带 FTS5 扩展，中文虽然需要自己做分词，但方案成熟（后面细讲）。如果换成别的存储，你大概率要再引入一个搜索引擎，那是另一个量级的运维负担。

注意：SQLite 不适合的场景也要说清楚——如果你打算做成多人共享的在线服务，或者要做跨设备的实时同步，那它的写锁会成为瓶颈，那时候该换就换，别硬扛。

3. 采集层：调度、限速、增量，三件事决定它能不能长期跑

3.1 订阅清单是唯一的真相源

整个系统的入口是一份订阅清单，里面记录了你关注哪些来源、每个来源的标识、最近一次成功抓取的时间、连续失败次数。这份清单必须是唯一真相源，所有调度都从它派生，不要在别处再存一份副本，否则状态一定会不一致。

我在早期版本里犯过一个错：把"待抓列表"缓存在内存里，进程重启就丢了，导致重启后要全量重扫一遍。后来改成从清单表里按next_run_at排序取任务，重启后状态完全恢复，代价只是多一次索引查询。

调度这块，Liuli 用的是最简单的单进程 + 定时轮询，没有上 Celery 或者消息队列。理由是这个场景的任务量级是"几十到几百个来源，每几个小时跑一轮"，用重量级方案属于杀鸡用牛刀，还会引入一堆依赖问题。单进程的顺序执行反而更好调试，出问题看日志一目了然。

任务优先级的计算大概是这么个逻辑：

# 优先级 = 基础权重 + 逾期程度 - 失败惩罚 def task_priority(source, now): overdue = (now - source.next_run_at).total_seconds() / 60.0 base = 100.0 if source.is_starred else 50.0 penalty = min(source.fail_count * 20.0, 120.0) # 连续失败最多扣 120 return base + min(overdue, 240.0) - penalty

这个公式里几个常数的来历值得说一下。overdue封顶 240 分钟，是为了防止一个很久没跑的老来源永远霸占队头，把新来源饿死。失败惩罚每次 20、封顶 120，意思是连续失败 6 次之后就不再继续加罚，让它保持一个"低优先级但不被彻底放弃"的状态——因为很多失败是临时的，彻底拉黑反而会让你漏掉恢复后的内容。

3.2 频率控制：算清楚你的配额，别凭感觉

限速这块，我的建议是先算，再写代码。假设你订阅了 80 个来源，希望每 6 小时更新一轮，每个来源平均每次产出 3 篇新文章，每篇文章需要 1 次列表请求 + 1 次详情请求。

那么单轮请求量 = 80 × (1 + 3) = 320 次。6 小时 = 21600 秒。平均下来每秒 0.015 次请求，也就是大约68 秒一次。这个数字说明什么？说明你的请求频率可以放得非常非常慢，慢到几乎不可能给对方造成压力，同时也意味着你完全没必要做并发——串行跑，加上随机抖动，是最稳的方案。

import time, random class RateLimiter: def __init__(self, base_interval=60.0, jitter=15.0): self.base = base_interval self.jitter = jitter self._last = 0.0 def wait(self): target = self.base + random.uniform(0, self.jitter) elapsed = time.time() - self._last if elapsed < target: time.sleep(target - elapsed) self._last = time.time()

jitter这个参数不是凑数的。固定间隔的请求在服务端看来是一条完美的等距直线，很容易被识别成非人类行为；加上 0 到 15 秒的随机抖动之后，请求间隔变成一个区间分布，更接近正常使用形态。这不是什么"绕过"技巧，就是基本的礼貌——就像你不会每隔整 60 秒准时敲一次邻居的门。

重试策略我用的是指数退避 + 次数上限：第 1 次失败等 30 秒，第 2 次等 2 分钟，第 3 次等 10 分钟，最多 3 次，然后标记该来源本轮失败，等下一个调度周期再试。这个曲线是照着"大部分临时故障在几分钟内会恢复"这个经验来的。不要用线性重试，那会在对方真的出问题时形成密集轰炸。

3.3 增量判断：唯一键设计错了，后面全是坑

增量抓取的核心是怎么判断一篇文章是不是新的。这里有个反直觉的结论：不要用发布时间做判断依据。

原因是发布时间不可靠。有的文章会重新编辑推送，时间变了但内容没变；有的文章时间字段是"相对时间"（比如"3天前"），每次抓都不一样；还有的模板干脆不输出时间。拿它当唯一键，你会得到大量重复和漏抓。

Liuli 用的是来源标识 + 文章标识的复合唯一键，加一个内容哈希做二次去重。文章标识从详情页里稳定提取（链接里的那段固定 ID 是最可靠的），内容哈希用正文纯文本算，用来兜住"同一篇文章被重新推送、ID 变了但内容一样"的情况。

CREATE UNIQUE INDEX idx_article_uniq ON articles(source_id, article_key); CREATE INDEX idx_article_hash ON articles(content_hash);

入库的时候用INSERT OR IGNORE，重复的直接被数据库挡掉，不用在应用层先查后插——那样有并发窗口，虽然单进程场景下问题不大，但没必要留这个隐患。

提示：内容哈希要在正文提取之后算，不要在原始 HTML 上算。原始 HTML 里通常带时间戳、阅读数、推荐位这些每次都变的东西，哈希值永远对不上。

4. 正文提取：这个项目的技术重心全在这

4.1 三条路线的取舍，我用表格说清楚

Liuli 选的是第二条，理由前面说过——泛化。但要说清楚它的边界：启发式评分在"结构清晰的文章页"上表现很好，在"正文和评论混排、正文被大量图片打断、正文极短（比如只有一句话的公告）"这三类页面上会翻车。所以工程上一定要配兜底：评分失败时回退到"取页面里最大的一段连续文本块"，再失败就存原始 HTML 并在界面上标注"解析异常"，让人工介入。

4.2 文本密度评分：评分函数怎么设计

核心思路很朴素：正文的特征是文字多、链接少、标点密、段落长。把这几个维度量化成一个分数，从根节点往下递归，取分数最高的子树。

import re PUNCT = re.compile(r'[，。！？；：、""''（）《》]') def block_score(node): text = node.get_text(" ", strip=True) if len(text) < 30: return 0.0 # 文字长度分（对数压缩，避免超长块碾压一切） length_score = min(len(text) / 500.0, 3.0) # 标点密度分：正文标点多，导航栏几乎没有 punct_ratio = len(PUNCT.findall(text)) / max(len(text), 1) punct_score = min(punct_ratio * 10.0, 2.0) # 链接密度惩罚：链接文字占比越高越不像正文 link_len = sum(len(a.get_text(strip=True)) for a in node.find_all("a")) link_ratio = link_len / max(len(text), 1) link_penalty = link_ratio * 5.0 # 段落结构分：有多个 <p> 的块更像正文 p_count = len(node.find_all("p", recursive=False)) struct_score = min(p_count / 5.0, 1.0) return length_score + punct_score + struct_score - link_penalty

几个常数不是拍脑袋定的，是调出来的。length_score用对数压缩是因为，一篇长文可能一万字，一个导航块可能两百字，如果线性算，长文的分数会高到让所有阈值失去意义。link_penalty的系数 5.0 给得比较重，是因为导航块和推荐位几乎全是链接，这一项能把它们直接打到负分。

递归的时候要注意不要只看叶子节点。很多模板里正文被拆成十几个并列的<div>，单独看每一块分数都不高，但合起来是最优解。所以策略是：自底向上计算每个节点的分数，如果一个节点的分数不如它的子节点之和，就用子节点的组合。这个逻辑实现起来大概二十行，但它是准确率从 70% 提到 90% 的关键。

4.3 图片本地化：不做这件事，你的归档三年后就是一堆裂图

这一点我要重点说，因为它是最容易偷懒、后果最严重的地方。如果你在文章里直接引用原始图片链接，短期看没问题，长期看必然失效——外链会过期、会做防盗链、会限制来源。你的归档库会在半年后变成一堆"图片加载失败"的占位符，那这个库就废了一半。

正确做法是下载图片、改成本地路径、同时保留原链接作为备份。实现上注意几个点：

def rewrite_images(doc, article_id, save_dir): for i, img in enumerate(doc.find_all("img")): src = img.get("data-src") or img.get("src") if not src or src.startswith("data:"): continue try: data, ext = download_with_limit(src, max_bytes=5 * 1024 * 1024) fname = f"{article_id}_{i}{ext}" (save_dir / fname).write_bytes(data) img["data-original-src"] = src # 保留原始地址 img["src"] = f"/static/img/{fname}" # 替换为本地路径 img.attrs.pop("srcset", None) # 清掉多分辨率属性 except Exception: img["src"] = "" # 失败就留空，不阻断整篇 img["data-original-src"] = src

三个细节：>-- 来源表 CREATE TABLE sources ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, source_key TEXT NOT NULL UNIQUE, -- 来源的稳定标识 last_run_at TEXT, next_run_at TEXT, fail_count INTEGER DEFAULT 0, is_starred INTEGER DEFAULT 0, created_at TEXT NOT NULL ); -- 文章表 CREATE TABLE articles ( id INTEGER PRIMARY KEY AUTOINCREMENT, source_id INTEGER NOT NULL REFERENCES sources(id), article_key TEXT NOT NULL, title TEXT NOT NULL, author TEXT, published_at TEXT, content_html TEXT, -- 清洗后的正文 HTML content_text TEXT, -- 纯文本，用于搜索和哈希 content_hash TEXT, raw_html TEXT, -- 原始响应，用于重解析 status TEXT DEFAULT 'ok', -- ok / parse_failed / fetched_failed fetched_at TEXT NOT NULL ); -- 原始响应层（单独一张表，和 articles 分离） CREATE TABLE raw_pages ( id INTEGER PRIMARY KEY AUTOINCREMENT, article_id INTEGER REFERENCES articles(id), url TEXT, body BLOB, fetched_at TEXT NOT NULL );

raw_html和raw_pages看起来冗余，但这是有意为之：articles.raw_html存的是解析时用的那一版，raw_pages存的是每次抓取的完整历史。前者用于快速重解析，后者用于排查"为什么这次抓回来的东西和上次不一样"。两张表分离的好处是，raw_pages可以定期清理（比如只保留最近三个月），而articles.raw_html永久保留。

5.2 中文全文搜索：FTS5 加自定义分词

SQLite 的 FTS5 默认分词对中文是按字符切的，效果很差——搜"内容归档"会匹配到任何包含"内""容""归""档"任一字的文章。解法是给 FTS5 配一个自定义分词器，把中文按二元组切分。

# 建表时指定分词器，这里用 trigram 方案做粗粒度全文索引 # FTS5 自带 trigram tokenizer，中文场景实测可用，无需额外扩展 CREATE_FTS = """ CREATE VIRTUAL TABLE articles_fts USING fts5( title, content_text, content='articles', content_rowid='id', tokenize='trigram' ); """ # 触发器保持同步 TRIGGERS = """ CREATE TRIGGER articles_ai AFTER INSERT ON articles BEGIN INSERT INTO articles_fts(rowid, title, content_text) VALUES (new.id, new.title, new.content_text); END; CREATE TRIGGER articles_ad AFTER DELETE ON articles BEGIN INSERT INTO articles_fts(articles_fts, rowid, title, content_text) VALUES('delete', old.id, old.title, old.content_text); END; """

trigram分词器的好处是不依赖外部分词库，三个字符起步的查询都能命中，代价是索引体积会大一些（大概是原文的 2 到 3 倍）。如果你的库不大（十万篇以内），这个代价完全可以接受。库再大的话，就要考虑只对标题和摘要建索引，正文搜索走别的路径。

触发器同步这个设计要特别注意：批量插入的时候触发器会逐行触发，速度会慢。如果一次性导入上千篇，建议先关触发器、批量插完、再手动重建索引，能快一个数量级。

5.3 备份：别等到硬盘坏了才想起来

SQLite 的备份不能简单cp，因为在 WAL 模式下，数据分散在.db、.db-wal、.db-shm三个文件里，直接复制可能拿到一个不一致的快照。正确做法是用 SQLite 自带的备份 API：

sqlite3 data.db ".backup 'backup/data-$(date +%Y%m%d).db'"

或者用VACUUM INTO：

VACUUM INTO 'backup/data-snapshot.db';

VACUUM INTO会生成一个整理过的单文件副本，体积更小，可以直接拷走。我现在的做法是每天凌晨跑一次，保留最近 14 天，加上每月一个归档，总共占用不到几百兆。

6. 阅读端：决定你会不会用第二天的地方

6.1 列表与详情的信息密度

列表页最容易犯的错是塞太多信息。标题、来源、时间、摘要、缩略图、已读状态、标签，全放上去，一眼看过去全是字，反而不知道该点哪个。我的经验是列表页只有三样东西是有用的：标题、来源、时间，其余全部挪到详情页或者悬停态。

已读状态要做得足够轻——一个左侧的细竖条就够了，不要用变色整行这种重手法，因为大部分文章你其实是扫过去的，"已读"这个状态本身价值不高，重要的是"未读"的视觉锚点。

详情页的核心是排版还原。这里有个坑：公众号文章的原始 HTML 里带大量内联样式（style="..."），直接用会和你自己的主题冲突。Liuli 的处理是保留内联结构样式（font-weight、text-align、line-height），剥掉颜色相关的属性（color、background），统一用自己的主题色。这样既保留了作者的行文节奏（比如空行、加粗、引用块），又保证了深色模式下的可读性。

6.2 图片懒加载和离线缓存

既然图片已经本地化了，理论上不需要懒加载。但实际上一篇文章带几十张图、每张几百 KB，一次性全部加载会让首屏卡顿明显。用的是原生的loading="lazy"，加上decoding="async"，就这两行属性，改造成本极低，效果立竿见影。

离线这块，如果你的阅读端是 Web 页面，用 Service Worker 缓存静态资源 + 页面骨架，正文数据走接口请求，配合 Cache API 做一层"最近读过的二十篇"的缓存。实测下来，在地铁这种断网环境下，最近读过的内容基本都能正常打开。

6.3 移动端适配的两个具体坑

第一个坑是长表格横向溢出。公众号文章里经常有宽表格，在手机上会把整个页面撑开，导致左右滑动的时候页面跟着晃。解法是给所有表格包一层overflow-x: auto的容器，让表格自身滚动，页面不跟着滚。

第二个坑是代码块不换行。技术类文章里的长代码行在窄屏上会溢出，或者被强制折断导致缩进全乱。正确做法是overflow-x: auto+white-space: pre，让代码块内部横向滚动，保住格式。同时字号要降到13px左右，不然一行代码只能看四个字符。

7. 常见问题与排查实录

7.1 抓回来的正文是空的

这是最高频的问题，排查顺序建议按这个走：

"打印每个候选块的分数"这一步非常关键。我一开始是靠猜的，改了半天没效果，后来把前十个候选块的分数和文本前五十个字全打出来，一眼就看到问题所在——某个推荐位模块因为文字特别长，分数排到了第二。

7.2 图片批量 403

本地化的时候如果大量图片返回 403，八成是 Referer 校验。处理方式是在下载请求里带上和页面同源的 Referer，同时补一个常见的 User-Agent。这两条能解决绝大多数情况。

如果还不行，检查是不是图片地址本身有过期签名（URL 里带一长串参数），这种就只能抓取时即时下载，不能延后。这就是为什么图片下载要放在解析流程里同步做，而不是异步排队——异步排队可能几分钟后才执行，签名早过期了。

7.3 同一篇文章入库两次

去重失效一般有两个原因。一是article_key提取不稳定，比如从 URL 里截取的时候用了带查询参数的完整地址。二是标题被重新编辑过，内容哈希对不上。

排查方法很简单，把那两条记录的article_key、content_hash、published_at打出来对比。如果 key 不同但 hash 相同，说明是 URL 变了，要把 key 的提取规则收紧到只用路径里那段固定 ID。如果 hash 也不同，那可能是真的两篇不同文章（作者改了内容重发），这时候不该去重，反而要保留两个版本。

7.4 跑久了内存涨

这多半是解析阶段的 DOM 树没释放。如果用的是 lxml 或者 BeautifulSoup，每解析完一篇要显式把引用置空，别指望 GC 自动回收——Python 的循环引用回收是有延迟的。批量跑几千篇的时候，这个延迟会累积成明显的内存增长。

我的做法是每处理 200 篇，把解析器实例重建一次，简单粗暴但有效。另外raw_pages里的body字段如果存了完整的二进制响应，读完就关连接，别在内存里留副本。

提示：长期跑的服务一定要加一个"看门狗"——记录进程的常驻内存，超过阈值（比如 800MB）就优雅重启。别迷信自己能找到所有内存泄漏，兜底比完美更重要。

8. 一点实际使用的体会

这个项目我前后迭代了大概一年多，最大的感受是：工程上真正难的从来不是那个听起来最唬人的部分。采集、解析这些技术点，网上资料一大把，写出来能跑也就一两天的事。真正拖时间的是那些不起眼的地方——图片三年后还在不在、搜索能不能搜到三个月前看过的一句话、深色模式下代码块看不看得清、手机上一篇长文滑到一半会不会卡。

如果让我给准备动手的人一句建议，我会说：先把"读"这一端做出来，用假数据都能跑通的那种，然后再回去补采集。因为阅读体验决定了你还会不会继续投入，而采集的那些坑，你只有在天天用的时候才会真正意识到哪些值得填。

另外一个我自己踩过的坑，是早期太执着于"全自动"。总想着规则写得足够好，就永远不用人工干预。事实证明不可能，页面会改，模板会变，总有一些文章解析得不对。后来我加了一个"解析异常"的标记，把评分低的文章单独列出来，人工看一眼，顺手把新的脏模式加进黑名单。承认不完美，反而让这个工具真正能用下去。

后面如果想继续扩展，我列了几个方向：一是把归档内容导出成标准格式，方便接别的阅读器；二是加一个简单的全文高亮，搜索命中的词在详情页里标出来；三是把同一作者的文章聚合成一个"合订本"视图，按时间线读。这几个都是小改动，但对使用体验提升挺明显的。