discrawl 架构解析:一个 SQLite 文件背后的 5 大表设计、FTS 索引与持久化机制
discrawl 架构解析:一个 SQLite 文件背后的 5 大表设计、FTS 索引与持久化机制
discrawl 是一个基于本地 SQLite 文件的 Discord 历史归档 CLI 工具:它把服务器消息、成员、附件元数据全部存进单个本地数据库,并通过 SQLite FTS5 全文索引提供免网络、免外部服务的离线搜索。本文带你快速看懂这个单文件架构:核心表怎么设计、FTS5 索引如何与消息表保持同步、以及 WAL + FULL 同步如何保证断电级持久化。
一、核心思路:所有数据都在一个本地 SQLite 文件里
discrawl 的整个后端只有一个文件 discrawl.db,没有服务进程、没有外部搜索引擎:
- Linux:
${XDG_DATA_HOME:-~/.local/share}/discrawl/discrawl.db - macOS:
~/Library/Application Support/discrawl/discrawl.db
这意味着归档可以整体拷贝、随 Git 快照分享、也可被 discrawl sql 以只读 SQL 直接分析。官方数据布局说明见 data-storage.md。
二、表设计:10 张核心表如何组织数据
完整建表语句见 schema.sql。各表职责如下:
| 表名 | 主键 | 职责 |
|---|---|---|
guilds |
id |
服务器元数据 + 原始 JSON |
channels |
id |
频道与线程(Discord 中线程就是频道) |
members |
(guild_id, user_id) |
当前成员快照,含角色列表 |
messages |
id |
规范化消息行,全文搜索的数据源 |
message_events |
event_id |
追加式事件记录(编辑、删除等) |
message_attachments |
attachment_id |
附件元数据、提取文本与缓存状态 |
sync_state |
scope |
同步游标 + 索引版本标记(多用途 KV 表) |
embedding_jobs / message_embeddings |
message_id |
可选语义搜索的任务队列与向量存储 |
failure_ledger |
failure_id |
本地故障账本,90 天老化,不进入分享快照 |
两个值得新手注意的设计:
- 双份内容:
messages同时保存content(原始内容)与normalized_content(规范化内容),后者才是进入 FTS 索引的文本; - 元数据与二进制分离:附件只存文件名、SHA-256、缓存路径等元数据,媒体本体放在
cache_dir/media目录,SQLite 保持轻量。
索引也按高频查询模式设计,例如 idx_messages_channel_created_id 覆盖「按频道取最近消息」,idx_messages_channel_updated_id 覆盖「按频道找被修改过的消息」,全部在 store.go 的基线迁移中批量创建。
三、FTS5 全文索引:message_fts 虚拟表的同步机制
默认搜索模式 fts 完全跑在本地 SQLite FTS5 上,无需任何外部服务。虚拟表定义在 store.go:
author_name、channel_name、content三列参与分词检索(默认unicode61分词器);message_id、guild_id、channel_id、author_id标记为unindexed,只用于过滤回表,不占倒排索引空间。
rowid 映射是同步的关键。 FTS 行与 messages 表通过 rowid 绑定:消息 ID 是数字时直接用作 rowid,否则用 FNV-1a 哈希生成(见 store.go),映射结果确定且幂等。由此带来三条不变式:
- 同事务写入:消息 upsert 时,在同一事务内先
delete from message_fts where rowid = ?再插入新行(见 write.go),索引与数据不会漂移; - 删除即清理:消息删除时连同 FTS 行、向量、嵌入任务一起清除;
- 重建兜底:
rebuildFTS会整体 drop + 重建虚拟表,并在重建前设置pgsz=32768、automerge=0等批量加载参数、结束后执行optimize,大幅加速大档案重建(见 store.go)。
版本守卫也很巧妙:FTS 重建后会把 schema:message_fts_rowid_version 写进 sync_state 表,下次打开发现版本不符就自动重建(见 store.go)。此外,若运行环境缺少 FTS5 模块,search 会自动降级到回退查询而不是直接报错(见 query.go)。
💡 进阶:配置 <a href="https://link.gitcode.com/i/01214056bb84020dee59911161a1ffa9" target="_blank">search.lexical] 后可为韩、日、中、阿拉伯语各建独立 FTS 表(如 message_fts_ko),用各语言分词器分别建索引,再以互逆排名融合(RRF)合并结果,源码见 [lexical.go,用法见 search-modes.md。
四、持久化机制:WAL + synchronous=FULL + 批量提交
作为「档案级」工具,discrawl 对写入连接强制最严格的持久化策略(详见 sqlite-durability.md):
- WAL 模式 +
synchronous=FULL:每次提交都完整刷盘,macOS 上还请求fullfsync=1; - 启动自检:写入连接启动时校验实际生效参数,不一致直接失败,读连接不受影响;
- 批量提交:正因为每次提交代价高昂,目录级数据按批提交而非逐行提交——一个 Gateway
GUILD_CREATE事件的所有频道/线程在同一事务中落地,失败则整批回滚; - 私有文件:数据库以
0600权限创建,避免聊天历史被同机其他用户读取。
discrawl diagnostics 可一键查看 SQLite 完整性、WAL 状态、写入锁与数据新鲜度;discrawl failures 则读取 failure_ledger 查看同步失败的明细与重试次数。
五、Schema 迁移与版本控制
- 全局版本号由
PRAGMA user_version维护,启动时若本地库版本高于程序支持版本会快速失败(意味着你用了过旧的 binary 打开了新库); - 基线表结构用
create table if not exists幂等落地,索引维护在可写打开时补建,只读打开不做任何 schema 工作; - 备份注意:存在未 checkpoint 的 WAL 数据时,只拷贝主库文件是不一致的,官方文档建议整目录备份并验证恢复(见 data-storage.md)。
六、动手验证:三条命令看懂你的档案
discrawl diagnostics # SQLite 完整性 / WAL / 锁状态
discrawl sql 'select count(*) as messages from messages' # 只读 SQL 直查
discrawl search "release" # 走 FTS5 索引的默认搜索
如果你想改词法语言配置后重新建索引,运行 discrawl lexical rebuild 即可,它会持有写锁、不访问 Discord。
总结
discrawl 的架构可以概括为「一张主表 + 一个 FTS 索引 + 一套版本化迁移」:messages 表保存规范化文本,message_fts 通过 rowid 映射在同事务中同步,sync_state 承担游标与索引版本双重角色,而 WAL + FULL 同步加批量提交则把单文件 SQLite 的持久化做足了。对新手来说,这套设计也给出了一个很好的参照——如何用最简单的存储组件,构建出可分享、可审计、可离线检索的本地数据档案。
更多细节可参考 internal/store/ 源码与 docs/ 下的完整文档。

