Colibri 是法语里蜂鸟的意思。在我这边，它也是最近折腾的一个小工具的名字——一个只做一件事的本地书签管理器：把浏览器里攒了多年的几千条链接全部导入进来，然后让我在任何时候都能用一两秒时间把它们搜出来。之所以叫这个名字，是因为我对它的期待和蜂鸟一样：小、快、不占地方。
这篇文章我会把这个项目的来龙去脉讲一遍，从为什么不想用现成方案，到选型、实现、压测，再到实际用了三个月踩过的坑，尽量把每一步的取舍都说清楚。如果你也是那种收藏了几千条、却几乎从没再打开过的书签囤积症患者，这个项目多少能给你一点启发。
1. 书签越存越多却越难找到：Colibri 想解决的恰恰是这个
1.1 浏览器自带书签为什么"够用但难用"
先别急着做新工具，得先把痛点想明白。浏览器自带书签最大的问题是：它能存，但不好找。
- 搜索基本只匹配标题和 URL，不匹配正文内容。你当时收藏那篇文章是因为里面有个关键观点，可标题早就忘光了，搜不出来就是搜不出来。
- 文件夹分类需要手动维护，时间一长全是"未命名文件夹 7""待读 28"。分类本身就是一种认知负担，越攒越乱。
- 跨设备同步依赖厂商账号，浏览器一换，数据迁移麻烦得想摔键盘。
- 书签栏变成扩展图标停车场，真正有用的东西被挤得看不见。
这些问题不是"忍一忍"就能过去的。收藏得越多，检索成本越高，直到某天你发现收藏夹已经变成了一个只能进、不好出的仓库。
1.2 从"收藏家"到"捡垃圾"：我自己的体验
我属于重度收藏用户：写方案找参考链接、读技术文章顺手存一篇、看到好工具马上丢进书签，每个月至少有百来条新增。几年下来估算一下，累计超过一万条。
真正的问题出现在一次写周报前。我明明记得几个月前看到过一篇关于性能优化的文章，里面有个结论对我当时的工作很关键，但标题是什么、哪个网站发的、大概什么日期，全忘了。浏览器自带搜索按"性能优化"试了几轮，翻出几百条不相关的东西，最后只能放弃。
那一刻我意识到，工具不该是这样的。收藏的初衷是"以后用得上"，如果以后根本找不到，收藏这个行为就失去了意义。我需要的不是更庞大的资料库，而是一只能精准悬停的蜂鸟：小、快、准。
1.3 "蜂鸟原则"：小巧轻盈，但反应极快
蜂鸟的体型在所有鸟类里算是极小的一档，体重通常只有几克，翅膀每秒能扇动几十下，可以在空中定点悬停去吸花蜜。这个特点映射到工具上特别有意思：
- 体型小：不搞虚拟化、不搞容器编排，一个可执行文件就是全部。
- 反应快：启动毫秒级，搜索毫秒级，不给用户等待的借口。
- 定位准：没有几十个菜单，没有复杂的设置项，打开就能搜、搜到就能跳。
Colibri 这个名字就是这么来的。下面每一步设计，我都在用这套标准问自己：这个功能值不值得增加体积？这个依赖会不会拖累启动速度？这个东西在真实场景下真的能帮到人吗？
2. 选型不是赶时髦，而是做减法：Go + SQLite + FTS5 的组合逻辑
2.1 为什么不是浏览器插件、在线服务或重型自托管
动手之前我认真把市面上现有的方案捋了一遍，做成对比就能看得很清楚。
| 方案方向 | 代表 | 优势 | 我认为不可接受的地方 |
|---|---|---|---|
| 浏览器插件 | 各类 Bookmark Manager 扩展 | 安装简单、数据在本地 | 绑定特定浏览器；侧边栏/弹窗使用不够顺手；搜不了正文内容 |
| 在线服务 | Pocket、Raindrop 等 | 多端同步、界面漂亮 | 数据在别人服务器上；免费版功能受限；哪天服务停服，数据可能拿不回来 |
| 重型自托管 | Wallabag、Shiori 等 | 功能完整、开源可自控 | 需要维护数据库和服务端，有的还依赖 PHP/Node 环境；对"只想快速检索书签"来说太重 |
| Colibri 的方向 | 我自己的方案 | 单文件、本地存储、毫秒级搜索 | 功能上只做"导入 + 存储 + 搜索 + 跳转" |
选型的本质是取舍。我要解决的核心场景很单一：快速导入、快速搜索、快速打开。所有与这三个目标无关的功能都砍掉。
2.2 单二进制和 SQLite 到底赢在哪一步
决定用 Go 编译成单个可执行文件，核心原因是部署和迁移太省心了。没有运行时依赖，没有环境变量配置，没有 YAML 配置文件迷宫。把二进制丢到服务器、NAS、或者自己的笔记本里，双击就能跑。数据全部存在同目录下一个.db文件里，备份就是拷贝文件，迁移就是拷贝到另一台机器再打开一次。
数据库选 SQLite 而不是 MySQL、PostgreSQL，理由也很直接：这是单用户、本地优先的场景。SQLite 是嵌入式数据库，不需要独立进程，不会占用几百兆内存，查询性能对于几万条数据完全足够。换句话说，这是一个"杀鸡不要用牛刀"的标准案例。如果你愿意花半小时去搭一个 PostgreSQL 来做个人书签检索，当然也可以，但你要多维护的东西会直接违背"蜂鸟原则"。
2.3 搜索方案直接选 FTS5：数据规模决定技术选型
作为写过一段时间搜索相关代码的人，我承认第一反应也想过上 Elasticsearch 或者 Meilisearch。但冷静下来算了一笔账：我的数据量是几万条书签，不是几亿条文档。为这个数据量去维护一个独立搜索引擎，属于典型的用牛刀杀鸡，而且会多出两三个常驻服务。
SQLite 从 3.x 版本开始自带 FTS5 全文搜索扩展，支持 BM25 排序、前缀查询、短语查询，还能自定义分词器。更关键的是，它在我的 Go 程序里只是一个嵌入式库，不需要额外启动任何进程。用 FTS5 还有一个好处：书签主数据表和全文索引表可以放在同一个数据库文件里，用触发器保持同步，事务一致性天然有保证。
注意：决定技术栈之前，先算清楚自己的数据量级。数据在百万级以下，嵌入式方案通常比独立服务更合适，少一个需要运维的东西，就少一个半夜被电话叫醒的理由。
3. 落地实现：书签存取、中文搜索与 HTML 导入的关键代码
真正写代码之前，我先明确了三个目标：导入要快、搜索要准、前端要轻。整个项目其实只包含两个部分：一个 Go 写成的后端服务，加上一个几乎没有框架依赖的静态页面。
3.1 建表：书签主表与 FTS 索引怎么配合
书签主表用来存数据，FTS 虚拟表用来做快速检索。主表结构尽量简单，不要过早设计一堆字段。我实际用的建表语句如下：
CREATE TABLE IF NOT EXISTS bookmarks ( id INTEGER PRIMARY KEY AUTOINCREMENT, url TEXT NOT NULL UNIQUE, title TEXT NOT NULL DEFAULT '', description TEXT NOT NULL DEFAULT '', created_at DATETIME NOT NULL DEFAULT (datetime('now')), updated_at DATETIME NOT NULL DEFAULT (datetime('now')) ); CREATE VIRTUAL TABLE IF NOT EXISTS bookmarks_fts USING fts5(title, description, url, content='bookmarks', content_rowid='id');这里有个很多人忽略的点：content='bookmarks'，这代表 FTS5 使用外部内容表模式。索引表本身不冗余存储原始文本，内容来自主表，这样能避免两份数据占双倍磁盘空间。当主表数据更新时，通过触发器告诉 FTS 索引哪些行的内容变了。
URL 字段加了UNIQUE约束，这个设计在导入重复书签时非常重要，后面专门讲。
3.2 触发器设计：让全文索引保持和主表同步
外部内容表模式下，必须用触发器维护 FTS 索引，否则主表插入新数据后却搜不到。三个触发器分别处理增、删、改：
CREATE TRIGGER IF NOT EXISTS bookmarks_ai AFTER INSERT ON bookmarks BEGIN INSERT INTO bookmarks_fts(rowid, title, description, url) VALUES (new.id, new.title, new.description, new.url); END; CREATE TRIGGER IF NOT EXISTS bookmarks_ad AFTER DELETE ON bookmarks BEGIN INSERT INTO bookmarks_fts(bookmarks_fts, rowid, title, description, url) VALUES ('delete', old.id, old.title, old.description, old.url); END; CREATE TRIGGER IF NOT EXISTS bookmarks_au AFTER UPDATE ON bookmarks BEGIN INSERT INTO bookmarks_fts(bookmarks_fts, rowid, title, description, url) VALUES ('delete', old.id, old.title, old.description, old.url); INSERT INTO bookmarks_fts(rowid, title, description, url) VALUES (new.id, new.title, new.description, new.url); END;删除触发器和更新触发器里的'delete'是 FTS5 的特殊指令，用于从索引中移除某一行的数据。这个套路如果你去搜 FTS5 的文档，能够看到官方推荐写法，照着抄就行，没必要自己发明。
3.3 中文搜索：trigram 与查询词转义
搜索引擎最麻烦的就是中文分词。英文有天然空格，FTS5 默认的 unicode61 分词器就能胜任。中文没有空格，按字切分或者按词切分都有取舍。
FTS5 从比较新的版本开始内置了trigram分词器，它按三个连续字符滑动窗口来建立索引。对中文来说，好处是不需要额外引入分词库，搜索"搜索引擎优化"时可以匹配包含其中任意三字连续片段的内容。代价是：两字以内的查询词无法匹配，需要特殊处理。
建表时指定分词器：
CREATE VIRTUAL TABLE IF NOT EXISTS bookmarks_fts USING fts5(title, description, url, tokenize = "trigram", content='bookmarks', content_rowid='id');还有一个非常容易踩的坑：FTS5 的MATCH语法支持AND、OR、NOT、引号和括号。用户输入的原始文本直接拼进MATCH就会导致语法错误，比如你搜一个带双引号的短语、或者含有连字符的 URL。所以任何用户输入进入查询前都要做一遍转义：
func escapeFTSQuery(s string) string { s = strings.TrimSpace(s) s = strings.ReplaceAll(s, "\"", "\"\"") // 处理 OR / AND / NOT 等由用户输入的查询关键字 s = "\"" + s + "\"" return s }这样处理后，用户搜"如何 优化"会变成""如何 优化""作为一个整体短语，不会再触发语法错误。代价是用户无法使用高级语法，但对个人书签搜索来说，精确短语匹配远比"能写复杂查询表达式"更重要。
3.4 解析浏览器导出的书签 HTML
Chrome、Firefox、Edge 导出的书签文件都是 Netscape Bookmark File Format，结构是一堆嵌套的<DL><DT>节点。直接用golang.org/x/net/html解析，抓到所有<a>标签就能拿到 URL 和标题：
func parseNetscapeHTML(r io.Reader) ([]Bookmark, error) { doc, err := html.Parse(r) if err != nil { return nil, err } var result []Bookmark var walk func(*html.Node) walk = func(n *html.Node) { if n.Type == html.ElementNode && n.Data == "a" { var href string for _, attr := range n.Attr { if attr.Key == "href" { href = attr.Val } } title := strings.TrimSpace(nodeText(n)) if strings.HasPrefix(href, "http://") || strings.HasPrefix(href, "https://") { result = append(result, Bookmark{URL: href, Title: title}) } } for child := n.FirstChild; child != nil; child = child.NextSibling { walk(child) } } walk(doc) return result, nil }这里过滤了javascript:、chrome://、about:这类伪协议。导入的时候我用INSERT OR IGNORE，遇到重复 URL 就直接跳过，等于天然去重。标题为空的那条用 URL 兜底，避免搜索结果里出现一个光秃秃的链接。
3.5 用 go:embed 把前端塞进二进制，实现单文件部署
如果前端文件在二进制外面，那"单文件部署"就是空话。Go 的embed包可以把静态文件直接打进二进制里：
import "embed" //go:embed static/* var staticFS embed.FSHTTP 服务建议直接用标准库，不引入 Gin 之类的框架。整个项目就两个路由：一个/提供静态页面，一个/api/search处理搜索请求。Go 标准库自带的net/http在高并发和路由匹配上对我的场景绰绰有余。
前端页面同样走极简路线：一个搜索框、一个结果列表、一份原生 JavaScript，不引 npm 包。这样编译出来的二进制只有十几兆，静态资源和后端都在里面，拷到哪都能跑。
4. 压了一万条书签进去之后的真实数据
4.1 测试环境与数据准备
理论说得再好，也要看实际跑起来怎么样。我的测试环境是一台老掉牙的笔记本：Intel i5-8250U，8GB 内存，普通 SATA SSD。系统是 Ubuntu 22.04，Go 版本 1.21，使用的 SQLite 驱动是 modernc.org/sqlite（纯 Go 实现，便于交叉编译）。
测试数据来源是我自己的真实书签导出，加上从 Common Crawl 随便拉了部分 URL 补足数量，最终导入 12000 条书签。这个数据量对于个人用户来算偏大，能看出真实性能上限。
4.2 导入耗时、文件体积、内存占用与查询延迟
我把实测数据整理成一张表，数字都是取三次测试的平均值，仅供参考：
| 指标 | 实测结果 | 备注 |
|---|---|---|
| 导入 12000 条书签 | 约 1.8 秒 | 包含 HTML 解析、URL 规范化、批量插入 |
| 数据库文件体积 | 3.4 MB 主库 + 2.1 MB FTS 索引 | trigram 索引比主库还大，正常现象 |
| 二进制体积 | 约 16 MB | modernc.org/sqlite 是纯 Go，体积稍大 |
| 空闲内存占用 | 约 28 MB | RSS 实测 |
| 三字以上中文搜索 | 平均 6 ms | 12000 条数据下，毫秒级 |
| 两字词搜索（LIKE 兜底） | 平均 45 ms | 全表扫描，但数据量小所以也可接受 |
启动速度我没单独测，因为体感就是"命令敲完就起来了"，一个不加载任何远程依赖、没有握手过程、没有动态依赖库的静态二进制，启动不会超过 50 毫秒。
4.3 和浏览器自带搜索的一次正面比较
我特意找了一批测试书签，包含标题、URL、description 三种来源的关键词，分别用 Chrome 书签搜索和 Colibri 搜索同样的词"react performance optimization"。
Chrome 的搜索结果全部来自标题和 URL，匹配到 3 条，其中 2 条还是无关的。Colibri 的 FTS5 搜索因为把 description 也加了进来，匹配到 11 条，并且按 BM25 相关性排序，明显更接近我记忆中的那篇文章。
这个结果其实不意外。浏览器书签本身没有全文索引，也没有给书签正文做相关性排序。区别的根本原因在于：我设计了 FTS 索引，而浏览器没有。只要数据量不太夸张，FTS5 在这种场景下就是降维打击。
5. 使用三个月后踩过的坑，以及每一步的补救方法
5.1 用户输入里的引号和连接符随时让 MATCH 崩溃
第一个坑是搜索框里输入C++或者"xxx"的时候，前端直接报错。原因就是 FTS5 把+、-、引号、括号都当作语法符号解析。我在 3.3 里已经写了escapeFTSQuery，但第一次实现的时候没有处理，结果同事随手搜了个C++ 教程，接口直接返回 500。
排查过程很简单：把用户输入原样打到 SQLite 控制台里跑一遍，报错信息是fts5: syntax error near "+"，问题立刻定位。修复方案就是把整个查询短语当作一个整体用双引号包起来，再替换内部双引号。
提示：任何让用户直接触碰搜索语法的功能，都必须做同样的输入防护。这不是安全问题，是语法正确性问题。FTS5 的 MATCH 语法是给开发者用的，不是给普通用户用的。
5.2 两字以内中文词查不到，得用 LIKE 兜底
trigram分词器有个硬性限制：查询词必须至少 3 个字符。用户输入"并发""性能"这种两字词，MATCH 查询会直接报错，或者返回空集。
第一次遇到这个问题时我先把报错补丁打了，然后加了一个分支：查询字符串去掉引号后长度小于 3，就退化成LIKE '%关键词%'在 title、description、url 三列上做全表模糊匹配。对一万多条数据而言，这个 LIKE 查询耗时 40 到 80 毫秒，完全能接受。
这也是"蜂鸟原则"的一个体现：不为 1% 的场景去引入一个重型分词库，选一个 80% 场景都足够快的方案，剩下 20% 用更朴素的兜底。
5.3 database is locked：写完才遇到的并发问题
前端搜索接口用了防抖，通常在 150ms 内只发一次请求，所以查询冲突很少。真正的database is locked出现在导入大文件时：导入过程动辄上万条的写事务，如果此时用户正在搜索，读写并发就会上来。
解决方案有两个，建议两个同时做：
- 在打开数据库连接时设置 busy timeout，让 SQLite 等待锁而不是立即报错。
- 打开 WAL（Write-Ahead Logging）模式，读写可以并发，写和写之间互斥：
db, err := sql.Open("sqlite", "colibri.db?_pragma=busy_timeout(5000)&_pragma=journal_mode(WAL)")开启 WAL 之后，导入时搜索基本不会再碰到锁问题。另外补充一个备份坑：WAL 模式会产生-wal和-shm文件，备份数据库时不能只复制.db文件，要么先执行PRAGMA wal_checkpoint(TRUNCATE);把 WAL 内容合并回主文件，要么把三个文件一起备份。这个细节很容易被忽略，等到数据丢了才想起来就晚了。
5.4 重复书签和 URL 规范化
导入几千条书签后我发现数据库里有不少"长得一样但又不完全一样"的 URL。比如http://example.com/page和https://example.com/page、带不带www、带不带结尾斜杠、链接里带#section锚点这种。从用户角度看它们大多是同一篇文章。
我的处理是导入前先做一层 URL 规范化：协议和域名全部转小写、去掉#锚点、去掉默认端口。配合数据库层的UNIQUE约束，做到真正确认重复就跳过。
规范化规则不能做太激进。比如去掉utm_追踪参数这种操作，不同站点参数名千奇百怪，处理不好反而把不同链接误判成同一个。我的建议是只做确定安全的那几步：转小写、去锚点、去默认端口，其余不要动。
5.5 使用习惯上的调整：少分类，多搜索
工具做好之后，我还改了自己原来的收藏习惯。以前总是纠结"这条放前端还是放工具类"，现在完全不分类，导入后统一靠搜索。搜索框只有一个，输入关键词、回车、点开链接。文件夹结构彻底消失之后，收藏的心理负担小了很多，收藏频率反而上来了。
这个转变恰恰是 Colibri 的价值所在：工具替你想"怎么找"，你就只需要想"存什么"。
6. 如果也准备做一个属于自己的"蜂鸟级工具"的三条建议
6.1 这个项目还能怎么扩展
我现在对 Colibri 的下一步计划很克制，考虑过几个方向：
- 为书签自动抓取网页标题和描述，这样导入时不用依赖浏览器导出的信息。
- 给搜索结果做简单的去重和分组，比如同一个域名的结果折叠到一起。
- 增加导出功能，一键导出成 Markdown 格式的书单，方便在别的地方二次使用。
- 做一个 15MB 以内的 ARM 版本，部署到树莓派或软路由上，作为家庭局域网里的共享书签服务。
这些功能都会小步迭代，每次只加一个，加完用一段时间确认没有违背"小快准"的初衷再决定是否继续。如果某个功能需要引入一个大框架，我会直接放弃。
6.2 三条建议：克制、真实测试、留好门
第一，定义清楚你的"蜂鸟原则"。做一个工具之前，先写清楚三个关键词：小到什么程度算小？快到什么程度算快？准到什么程度算准？没有标准，后面功能越加越多，迟早变成一个四不像。
第二，用真实规模的数据测试。不要只用 10 条测试数据跑一遍就上线。从第一天起就把自己真实的一万条书签导进去，索引体积、搜索延迟、内存占用全部在真实数据下才有意义。我最初就是拿少量数据测的，觉得一切飞快，等到压入全部书签才发现 trigram 索引体积比预期大不少。
第三，给数据留一条后路。本地优先的工具有个隐患：一旦这个工具不维护了，你的数据怎么办？所以从一开始就要保证数据库是标准 SQLite 格式、有导出接口，这样未来就算换工具也能把数据迁移出去。宁可现在多做一步，不要让数据被困在一个闭源格式里。
6.3 一点使用体会
这个项目做下来，我最大的收获不是会用了 FTS5，也不是学会了 go:embed，而是亲身体会到"少即是多"在软件世界里有多成立。市面上不缺功能庞杂的书签管理器，缺的是一个让人没有心理负担、打开就想用、用完就能找到东西的小工具。
蜂鸟为了在空中悬停，每秒要用翅膀扇动几十次，看起来一点都不"省力"，但它从不让自己变得臃肿。我的 Colibri 也是这样：它可能永远不会成为一个大而全的笔记系统，但在我需要的那一瞬间，它永远足够快、足够准。如果你手上也有一个"攒了几千条但找不到"的数字仓库，不妨也试试用这种思路，给自己做一只蜂鸟。
