discrawl 架构解析:一个 SQLite 文件背后的 5 大表设计、FTS 索引与持久化机制

原创2026-10-25 09:55:071,690 阅读

discrawl 架构解析:一个 SQLite 文件背后的 5 大表设计、FTS 索引与持久化机制

discrawl 是一个基于本地 SQLite 文件的 Discord 历史归档 CLI 工具:它把服务器消息、成员、附件元数据全部存进单个本地数据库,并通过 SQLite FTS5 全文索引提供免网络、免外部服务的离线搜索。本文带你快速看懂这个单文件架构:核心表怎么设计、FTS5 索引如何与消息表保持同步、以及 WAL + FULL 同步如何保证断电级持久化。

discrawl 项目横幅:Mirror Discord into SQLite 并本地搜索

一、核心思路:所有数据都在一个本地 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 天老化,不进入分享快照

两个值得新手注意的设计:

  1. 双份内容:messages 同时保存 content(原始内容)与 normalized_content(规范化内容),后者才是进入 FTS 索引的文本;
  2. 元数据与二进制分离:附件只存文件名、SHA-256、缓存路径等元数据,媒体本体放在 cache_dir/media 目录,SQLite 保持轻量。

索引也按高频查询模式设计,例如 idx_messages_channel_created_id 覆盖「按频道取最近消息」,idx_messages_channel_updated_id 覆盖「按频道找被修改过的消息」,全部在 store.go 的基线迁移中批量创建。

三、FTS5 全文索引:message_fts 虚拟表的同步机制

discrawl 官方社交卡片:本地 sqlite archive 中 312k 条消息、FTS5 ready

默认搜索模式 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),映射结果确定且幂等。由此带来三条不变式:

  1. 同事务写入:消息 upsert 时,在同一事务内先 delete from message_fts where rowid = ? 再插入新行(见 write.go),索引与数据不会漂移;
  2. 删除即清理:消息删除时连同 FTS 行、向量、嵌入任务一起清除;
  3. 重建兜底: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/ 下的完整文档。

登录后查看全文
discrawl