基于SQLite与FTS5构建本地全文检索知识库：告别数字坟墓

1. 收藏夹为什么会变成“数字坟墓”

1.1 一个几乎所有人都有的数字囤积症

先问一个问题：你的浏览器收藏夹里现在有多少条链接？三百？八百？还是早就过了四位数，连自己都不敢点开看？

我自己的情况是，攒了大概六年的收藏，横跨三台电脑、两个浏览器账号，最后同步到一起的时候，数字停在了一千七百多条。这个数字听起来挺唬人，但真实的使用状态是——我几乎从来不再打开它。偶尔需要找一篇以前看过的文章，我会下意识地去搜索引擎重新搜一遍，而不是去收藏夹里翻。因为翻收藏夹的成本太高了：文件夹层级混乱、命名随意、有些链接点开已经是404、有些标题党根本想不起来内容是什么。

这就是所谓的数字坟墓。你花了时间收藏，以为是在积累知识，实际上只是把信息从一个地方搬运到另一个地方，然后让它安静地烂掉。收藏这个动作本身给了你一种“我已经拥有了这条信息”的错觉，但拥有和能用之间，隔着一条巨大的鸿沟。

1.2 问题的本质不是收藏，而是检索

我认真复盘过这件事，发现核心矛盾其实不在“收藏”这个动作上。收藏本身没毛病，看到好东西先存下来是合理的信息处理策略。真正的问题在于检索。

一个知识库能不能用起来，取决于你能不能在需要它的那一刻，用最短的路径找到它。传统收藏夹的检索能力约等于零：你只能靠记忆去回忆“我当时把它放在哪个文件夹里了”，或者靠肉眼一条条扫标题。当条目超过两百条，这种方式就彻底失效了。

所以我的目标很明确：把这一千多条散落的收藏，变成一个可以全文搜索、可以按标签过滤、可以随时调用的本地知识库。不是云端服务，不是需要登录的在线工具，就是一个躺在我自己硬盘上、我完全掌控的数据库文件。

1.3 为什么选择 clawsqlite-knowledge 这条路线

市面上做知识管理的方案很多，笔记软件、在线书签、双链笔记、云盘同步，我都试过。但它们普遍有几个让我不舒服的地方：第一，数据不在我手里，服务商哪天关停我就全丢了；第二，导入导出格式封闭，想迁移成本极高；第三，搜索能力受限于它提供的功能，我想按自己的方式组合查询条件往往做不到。

clawsqlite-knowledge这个思路打动我的地方在于，它把知识库的底层直接建在SQLite上。SQLite 是一个单文件的嵌入式数据库，不需要服务器、不需要安装服务、一个.db文件拷走就能带走全部数据。而全文搜索这块，SQLite 自带的FTS5扩展就能搞定，中文分词虽然需要额外处理，但整体方案足够轻、足够稳、足够可控。

简单说，这套方案要解决的问题就是：把零散的收藏链接和正文内容，结构化地存进一个本地数据库，并建立全文索引，让你可以用 SQL 或者一个简单的搜索界面，秒级定位到任何一条历史收藏。

它适合谁？适合收藏夹已经失控、又不想把数据交给第三方、还愿意花一个周末折腾一下的技术爱好者。如果你完全不想碰命令行，那这套方案可能门槛偏高；但只要你用过一点点 Python 或者 SQL，后面会非常顺。

2. 整体方案设计与技术选型拆解

2.1 数据从哪来：收藏夹的导出与清洗

动手之前，第一件事是把数据弄出来。主流浏览器的收藏夹都支持导出为 HTML 文件，这个文件本质是一个嵌套的<DL>列表结构，每个书签是一个<A>标签，带href和ADD_DATE属性。导出的文件长这样：

<DT><A HREF="https://example.com/article" ADD_DATE="1609459200">某篇文章标题</A>

导出的原始数据有几个典型问题需要清洗。一是重复链接，同一个 URL 在不同时间被收藏了多次，标题可能还不一样；二是失效链接，很多老链接早就打不开了；三是标题噪音，有些标题带一堆网站后缀、广告词、特殊符号；四是文件夹信息丢失，导出后层级关系变成了一堆嵌套标签，需要自己解析出分类路径。

我的处理策略是：先全部导入，不做删除，把清洗和去重放在数据库层面做。因为原始数据一旦删了就找不回来了，而数据库里做去重和标记是可逆的。这一点很重要，永远不要在数据入口处做破坏性操作。

2.2 为什么底层选 SQLite 而不是别的

选 SQLite 做知识库底座，理由可以列一长串，但最核心的就三条。

第一是零运维。它就是一个文件，没有进程、没有端口、没有配置文件。你备份知识库就是复制一个文件，迁移就是拷贝一个文件，这种简单性在长期使用中是巨大的优势。我见过太多人用复杂的自建服务做笔记，结果服务挂了、依赖冲突了、升级把数据搞坏了，最后弃坑。

第二是全文搜索能力够用。FTS5 是 SQLite 内置的全文检索模块，支持布尔查询、短语查询、前缀查询，性能在几十万条记录级别完全没问题。对于个人知识库这种量级（几千到几万条），它绰绰有余。

第三是查询语言强大。知识库用久了，你一定会产生复杂的检索需求，比如“找出所有2022年收藏的、标签包含‘机器学习’、正文里提到‘注意力机制’、且最近半年没打开过的链接”。这种需求用 SQL 表达就是几行WHERE条件，用图形界面的书签工具根本做不到。

2.3 全文索引与中文分词的取舍

这里有个坑必须提前说清楚：SQLite 的 FTS5 默认分词器对中文几乎不可用。它默认按空格和标点切词，中文句子没有空格，会被当成一整个超长 token，搜索时基本匹配不上。

解决方案有两条路。一条是引入专门的中文分词器，比如基于结巴分词的扩展，效果最好但需要编译加载，跨平台部署麻烦。另一条是在入库前自己把中文正文预处理成空格分隔的词序列，也就是用 Python 的分词库先切好词，再存进 FTS 表。我选的是第二条，因为它不依赖 SQLite 的编译扩展，纯应用层解决，换台机器照样跑。

具体做法是：正文入库时，除了存原始文本，再存一份分词后的文本专门给 FTS 用。搜索时对查询词也做同样的分词处理。这样虽然多占一点存储，但换来的是零依赖和可移植性。

2.4 整体架构一图说清（文字版）

整个系统的数据流是这样的：

1. 浏览器导出 HTML 收藏夹文件
2. Python 脚本解析 HTML，提取 URL、标题、添加时间、文件夹路径
3. 对每条链接可选地抓取正文内容（这一步要控制频率，别把人家网站打挂）
4. 正文做中文分词，生成检索用文本
5. 写入 SQLite 主表，同时写入 FTS5 索引表
6. 通过命令行工具或简单的 Web 界面执行搜索

主表负责存结构化字段，FTS 表负责存检索文本，两者通过 rowid 关联。这种主表 + 索引表分离的设计是全文检索的标准做法，好处是索引重建不影响原始数据，字段扩展也灵活。

3. 核心细节解析与实操要点

3.1 数据库表结构怎么设计才不后悔

表结构设计是这套方案里最需要想清楚的部分，因为后期改表结构虽然可行，但迁移数据很烦。我最终的表结构大致是这样：

CREATE TABLE bookmarks ( id INTEGER PRIMARY KEY, url TEXT UNIQUE NOT NULL, title TEXT, folder_path TEXT, add_date INTEGER, fetch_status INTEGER DEFAULT 0, content TEXT, content_tokenized TEXT, created_at INTEGER, last_access INTEGER ); CREATE VIRTUAL TABLE bookmarks_fts USING fts5( title, content_tokenized, content='bookmarks', content_rowid='id' );

几个关键字段说明一下。url加了UNIQUE约束，这样重复收藏会自动被拦掉，配合INSERT OR IGNORE就能实现幂等导入。folder_path存的是文件夹的完整路径字符串，比如技术/数据库/SQLite，这样既能保留分类信息，又不用建复杂的多表关联。fetch_status用来标记正文抓取状态，0 表示未抓取，1 表示成功，2 表示失败，方便断点续抓。

content_tokenized这个字段是专门为 FTS 准备的，存的是分词后的文本。FTS 表用content='bookmarks'声明为外部内容表，意思是索引数据不重复存储，而是引用主表，这样能省不少空间。

注意：外部内容表的 FTS 需要手动维护同步，插入、更新、删除主表数据时，必须同步操作 FTS 表，否则索引和实际数据会不一致。这是新手最容易踩的坑。

3.2 中文分词的具体处理方式

分词这块我用的是 Python 的jieba库，成熟稳定，中文切词效果对知识库场景足够。处理逻辑很简单：

import jieba def tokenize(text): if not text: return "" # 精确模式切词，用空格连接 words = jieba.cut(text, cut_all=False) # 过滤掉单字和纯标点，减少索引噪音 tokens = [w for w in words if len(w.strip()) > 1] return " ".join(tokens)

这里有个细节值得说：为什么要过滤单字。中文里单个字的信息量太低，比如“的”“了”“是”这些高频字如果都进索引，会严重稀释检索质量，还会让索引体积膨胀。过滤掉长度小于等于1的 token，能显著提升搜索准确率。

另一个细节是标题和正文要分开索引。标题里的词权重天然比正文高，虽然 FTS5 的 BM25 排序算法本身会考虑词频和文档长度，但把标题单独作为一个列索引，搜索时可以用title:关键词的语法精确限定，灵活性更高。

3.3 正文抓取的边界与礼貌原则

抓取正文是让知识库真正“活”起来的关键一步，但也是最容易出问题的环节。我的原则是：只抓自己收藏的、公开可访问的页面，控制频率，尊重目标站点。

具体实现上，我用requests加BeautifulSoup，设置合理的超时和重试。频率控制上，每条请求之间 sleep 1 到 2 秒，遇到连续失败就暂停。正文提取用简单的启发式规则：优先取<article>标签，其次取<main>，再退回到密度最高的<div>。这套规则不完美，但对大部分文章页够用。

import time import requests from bs4 import BeautifulSoup def fetch_content(url): headers = {"User-Agent": "Mozilla/5.0 (compatible; PersonalKnowledgeBot/1.0)"} try: resp = requests.get(url, headers=headers, timeout=15) resp.raise_for_status() soup = BeautifulSoup(resp.text, "html.parser") for tag in soup(["script", "style", "nav", "footer"]): tag.decompose() article = soup.find("article") or soup.find("main") or soup.body return article.get_text(separator="\n", strip=True) if article else "" except Exception as e: return None

实操心得：抓取前先对 URL 做一轮过滤，把明显是视频页、登录页、PDF 直链的挑出来跳过。这些页面要么抓不到有效正文，要么会拖慢整体进度。我一开始没做过滤，结果卡在几个视频网站上浪费了大量时间。

3.4 索引同步的正确姿势

前面提到外部内容表需要手动同步，具体怎么做？SQLite 提供了专门的命令。插入数据后，要执行：

INSERT INTO bookmarks_fts(rowid, title, content_tokenized) VALUES (new.id, new.title, new.content_tokenized);

删除时执行：

INSERT INTO bookmarks_fts(bookmarks_fts, rowid, title, content_tokenized) VALUES ('delete', old.id, old.title, old.content_tokenized);

更新则是先删后插。这些操作最好封装成触发器，让数据库自动维护，避免应用层漏掉。用触发器虽然会稍微增加写入开销，但能保证索引永远和数据一致，这个可靠性值得。

CREATE TRIGGER bookmarks_ai AFTER INSERT ON bookmarks BEGIN INSERT INTO bookmarks_fts(rowid, title, content_tokenized) VALUES (new.id, new.title, new.content_tokenized); END;

4. 实操过程与核心环节实现

4.1 环境准备与依赖安装

整个项目跑起来需要的依赖不多，一个 Python 3.8 以上的环境就够。核心依赖是jieba、requests、beautifulsoup4，数据库直接用 Python 内置的sqlite3模块，不需要额外安装。

pip install jieba requests beautifulsoup4

验证 SQLite 是否支持 FTS5，可以跑一句：

import sqlite3 conn = sqlite3.connect(":memory:") try: conn.execute("CREATE VIRTUAL TABLE t USING fts5(x)") print("FTS5 可用") except sqlite3.OperationalError: print("FTS5 不可用，需要更换 Python 版本或重新编译 sqlite")

绝大多数现代 Python 发行版自带的 SQLite 都编译了 FTS5，如果这句报错，说明你的环境比较特殊，建议换个 Python 版本。

4.2 解析收藏夹 HTML 的完整脚本

解析 HTML 收藏夹的关键是理解它的嵌套结构。浏览器导出的格式里，文件夹是<DT><H3>文件夹名</H3>，书签是<DT><A>...</A>，它们都包在<DL>里。我用递归的方式遍历，维护一个当前路径栈。

from bs4 import BeautifulSoup import time def parse_bookmarks(html_path): with open(html_path, "r", encoding="utf-8") as f: soup = BeautifulSoup(f.read(), "html.parser") results = [] def walk(dl, path): for child in dl.find_all(["dt", "dl"], recursive=False): if child.name == "dl": walk(child, path) else: h3 = child.find("h3") a = child.find("a") if h3: new_path = path + [h3.get_text(strip=True)] next_dl = child.find_next_sibling("dl") if next_dl: walk(next_dl, new_path) elif a: results.append({ "url": a.get("href", ""), "title": a.get_text(strip=True), "folder_path": "/".join(path), "add_date": int(a.get("add_date", 0) or 0), }) root_dl = soup.find("dl") if root_dl: walk(root_dl, []) return results

这段代码跑完，你会得到一个字典列表，每条包含 URL、标题、文件夹路径和添加时间。实测一千多条数据解析耗时不到一秒。

4.3 批量入库与去重处理

入库用INSERT OR IGNORE配合url的唯一约束，天然实现去重。这里要注意事务的使用，一千多条数据如果一条条提交，速度会慢得离谱，包在一个事务里能快几十倍。

import sqlite3 def import_bookmarks(db_path, bookmarks): conn = sqlite3.connect(db_path) conn.execute("PRAGMA journal_mode=WAL") cur = conn.cursor() inserted = 0 with conn: for bm in bookmarks: cur.execute( """INSERT OR IGNORE INTO bookmarks (url, title, folder_path, add_date, created_at) VALUES (?, ?, ?, ?, ?)""", (bm["url"], bm["title"], bm["folder_path"], bm["add_date"], int(time.time())) ) inserted += cur.rowcount conn.close() return inserted

PRAGMA journal_mode=WAL这行值得单独说。WAL 是预写日志模式，开启后读写可以并发，批量写入性能也更好。对于知识库这种读多写少的场景，WAL 是标配。

4.4 正文抓取与分词入库的批处理

正文抓取我做成可断点续跑的批处理。每次从数据库里捞fetch_status=0的记录，抓一批、更新一批，中途断了下次接着跑。

def batch_fetch(db_path, batch_size=50, sleep_sec=1.5): conn = sqlite3.connect(db_path) cur = conn.cursor() while True: cur.execute( "SELECT id, url FROM bookmarks WHERE fetch_status=0 LIMIT ?", (batch_size,) ) rows = cur.fetchall() if not rows: break for bid, url in rows: content = fetch_content(url) if content: tokenized = tokenize(content) cur.execute( """UPDATE bookmarks SET content=?, content_tokenized=?, fetch_status=1 WHERE id=?""", (content, tokenized, bid) ) else: cur.execute( "UPDATE bookmarks SET fetch_status=2 WHERE id=?", (bid,) ) conn.commit() time.sleep(sleep_sec) conn.close()

注意：sleep_sec别设太小。我一开始设 0.3 秒，结果被某个站点限流，连续返回 429。后来改成 1.5 秒，虽然慢一点，但稳定跑完一千多条没再出问题。慢就是快，这话在抓取场景里特别对。

4.5 搜索功能的实现与查询语法

搜索这块，核心是把用户的查询词也做分词，然后拼成 FTS5 的 MATCH 语法。FTS5 支持AND、OR、NOT、短语查询"..."、前缀查询词*，组合起来非常灵活。

def search(db_path, query, limit=20): conn = sqlite3.connect(db_path) cur = conn.cursor() tokens = tokenize(query) if not tokens: return [] # 用 AND 连接，要求所有词都命中 match_expr = " AND ".join(tokens.split()) cur.execute( """SELECT b.id, b.title, b.url, b.folder_path, snippet(bookmarks_fts, 1, '[', ']', '...', 20) AS snip FROM bookmarks_fts f JOIN bookmarks b ON b.id = f.rowid WHERE bookmarks_fts MATCH ? ORDER BY rank LIMIT ?""", (match_expr, limit) ) return cur.fetchall()

snippet()函数是 FTS5 的亮点，它能直接返回命中关键词附近的文本片段，并用你指定的标记把关键词包起来。这样搜索结果里能直接看到上下文，不用点进去才知道是不是要找的东西。ORDER BY rank用的是 BM25 相关度排序，命中的词越重要、越集中，排得越靠前。

5. 常见问题与排查技巧实录

5.1 搜索搜不到中文怎么办

这是最高频的问题。现象是明明数据库里有这条记录，搜关键词就是搜不出来。九成九是分词环节出了问题。排查步骤：先确认content_tokenized字段里存的是不是空格分隔的词序列，如果存的是原始中文，那 FTS 根本没切词，自然搜不到。再确认搜索时查询词有没有做同样的分词处理，两边分词方式必须一致，一边切了一边没切，匹配必然失败。

还有一种情况是分词粒度不一致。比如“机器学习”这个词，入库时被切成“机器”和“学习”，搜索时你输入“机器学习”又被切成同样的两个词，那没问题；但如果某次分词库版本不同，切法变了，就会错位。解决办法是固定分词库版本，别随意升级。

5.2 索引和数据不一致怎么修

如果发现删掉的记录还能搜出来，或者新加的记录搜不到，那就是 FTS 索引和主表不同步了。最快的修复方式是重建索引：

INSERT INTO bookmarks_fts(bookmarks_fts) VALUES('rebuild');

这条命令会清空 FTS 索引，然后从主表重新读取全部数据重建。几千条数据重建也就一两秒。重建完再验证一下，如果还是不一致，那说明触发器没生效，检查触发器是不是被误删了。

5.3 数据库文件越来越大怎么办

知识库跑久了，.db文件会膨胀，尤其是频繁增删之后。这是因为 SQLite 删除数据后不会立即回收空间。解决办法是定期执行VACUUM：

VACUUM;

VACUUM会重建整个数据库文件，把碎片空间回收掉。注意它需要额外的磁盘空间（大约等于原文件大小），而且执行期间会锁库，所以别在搜索高峰期跑。我一般一个月跑一次，文件能瘦身三成左右。

5.4 常见问题速查表

问题现象	可能原因	排查方向	解决方式
中文搜不到	分词未生效	检查 tokenized 字段	统一分词流程
删除后仍可搜到	索引未同步	检查触发器	重建 FTS 索引
导入速度极慢	未用事务	检查提交方式	包在单事务内
抓取大量失败	被限流	看返回状态码	加大 sleep 间隔
文件异常膨胀	碎片未回收	看文件大小	定期 VACUUM
搜索结果排序差	排序未启用	检查 ORDER BY	用 rank 排序

5.5 几个我踩过的坑

第一个坑是URL 规范化。同一个页面，带不带末尾斜杠、带不带查询参数、http 还是 https，会被当成不同 URL 存进去，导致重复。后来我加了一步规范化：统一转小写、去掉末尾斜杠、去掉常见的追踪参数（如 utm 系列）。这一步能消掉大概一成的重复。

第二个坑是抓取时的编码问题。有些老站点不声明编码，requests猜错编码，抓回来的正文全是乱码。解决办法是优先用resp.apparent_encoding而不是resp.encoding，或者从 HTML 的 meta 标签里读 charset。

第三个坑是FTS 查询语法注入。用户输入的查询词里如果包含 FTS5 的特殊字符（比如"、*、(），直接拼进 MATCH 表达式会导致语法错误。稳妥做法是对查询词做转义，或者把每个词用双引号包起来当短语处理。

6. 让知识库真正用起来的几个习惯

6.1 定期增量导入而不是一次性大扫除

我现在的习惯是每周导出一次收藏夹，跑一次增量导入。因为INSERT OR IGNORE天然幂等，重复导入不会产生脏数据，所以完全不用手动挑哪些是新的。增量导入的好处是数据量小、抓取快、不容易触发限流，而且新收藏的内容新鲜度高，抓取成功率也高。

6.2 给搜索加上时间维度和文件夹维度

纯关键词搜索用久了会觉得不够，因为知识库的价值很大一部分在“什么时候收的”和“从哪个分类收的”。我在搜索函数里加了可选的时间范围和文件夹前缀过滤，SQL 层面就是多几个WHERE条件。比如“找出技术分类下、2023年之后收藏的、提到‘索引’的所有链接”，这种查询用图形工具根本做不了，但在这里就是一行 SQL 的事。

6.3 把常用查询固化成脚本

有些查询我会反复用，比如“最近一个月新增的收藏”“所有抓取失败的链接”“某个文件夹下的全部内容”。与其每次手敲 SQL，不如把它们写成小脚本或者 shell 别名。我现在终端里敲一个kb-recent就能列出最近新增，敲kb-failed就能看到所有抓取失败的链接，效率提升非常明显。

6.4 备份策略：单文件的好处

因为整个知识库就是一个.db文件，备份简单到极致。我设了一个定时任务，每天把数据库文件复制一份到另一个目录，保留最近三十天的版本。这种备份策略没有任何技术含量，但极其可靠。相比那些需要导出、打包、上传的复杂方案，单文件备份的优势在长期使用中会越来越明显。

6.5 后续可以扩展的方向

这套东西跑通之后，能扩展的地方其实很多。比如给搜索加一个简单的 Web 界面，用 Flask 或者 FastAPI 包一层，手机浏览器也能访问；比如接入本地的向量模型，做语义搜索，弥补关键词搜索的不足；比如把抓取到的正文做自动摘要和标签提取，让知识库从“能搜”进化到“能推荐”。

但我想说的是，别一上来就追求完美。我见过太多人一开始就想着做全功能的知识管理系统，结果架构设计了两周，代码一行没写，热情就耗光了。先用最小可行的方案把数据跑通，能搜到东西，然后再一点点加功能。这套 clawsqlite-knowledge 的方案，核心代码加起来也就两三百行，但它解决了我六年来一千多条收藏的检索问题，这个投入产出比已经非常划算了。

最后分享一个我自己的体会：知识库的价值不在于你存了多少，而在于你能不能在需要的时候把它调出来。一个能秒级检索的、只有五百条记录的库，远比一个存了一万条但搜不出来的库有用。工具是为人服务的，别让维护工具本身变成新的负担。