在实际项目里Syncthing 和 SQLite 是一对看起来很互补、实际很容易踩坑的组合。Syncthing 负责在手机、电脑、NAS 之间自动同步文件夹SQLite 负责在本地文件里保存结构化数据。很多开发者会把笔记数据、爬虫结果、内部小系统的业务库直接放进 Syncthing 同步目录期待两台设备上的数据始终一致。结果某天另一台设备打开数据库时SQLite 突然报出database disk image is malformed或者提示file is not a database。这个问题不是普通的同步冲突而是 Syncthing 的文件同步模型和 SQLite 的持久化模型之间天然不匹配造成的 gotcha。只有理解了“Syncthing 同步的是文件SQLite 依赖的是多个文件的原子配合”才能真正避免数据库被同步坏。读完这篇内容你会知道这个坑是怎么触发的、如何最小复现、损坏后怎么抢救以及生产环境里应该选择哪种同步策略。1. 为什么 Syncthing 同步文件不等于同步数据库1.1 Syncthing 的同步单位是文件不是事务Syncthing 是一个去中心化的文件同步工具。它的核心工作方式不是把数据写入同一个中心服务器而是让每台设备都保存文件的元数据并通过版本向量判断哪个文件是新版本。发现差异后Syncthing 会按块传输文件内容最终在另一端重组成完整文件。这种设计对普通文件非常合适。因为普通文件的语义是“整个文件作为一个整体”你改了文件里的几个字节Syncthing 只需要把改动过的块传过去接收端拼出来的仍然是一个完整的文件。问题在于Syncthing 不感知“两个文件之间存在事务关系”。它把两个文件当成两个独立对象来同步。如果事务 A 修改了文件 1事务 B 修改了文件 2Syncthing 可能先同步文件 1再同步文件 2也可能只同步了其中一个就发生了断开。对于互相之间有依赖关系的文件这个时间窗口就是隐患。1.2 SQLite 一个数据库由多个文件协同组成SQLite 常常被理解成“一个数据库就是一个 .db 文件”这个印象在绝大多数静态场景下是对的但数据库文件并不是独立存在的。在默认的 DELETE journal 模式下SQLite 执行写事务时会先创建主数据库文件对应的-journal回滚日志文件把原始页写入日志再修改主数据库文件。事务提交后日志文件被删除。如果数据库崩溃SQLite 打开数据库时会根据-journal是否存在来决定是否回滚事务。在 WALWrite-Ahead Logging模式下文件关系更复杂。SQLite 会把新写入的内容先追加到-wal文件主数据库文件可能暂时没有变化之后通过 checkpoint 机制把 WAL 中的页合并回主文件。另外还会创建-shm文件作为共享内存索引用于多进程并发访问。也就是说一个正在使用的 SQLite 数据库实际包含这些文件文件后缀在 DELETE 模式下在 WAL 模式下是否适合被同步.db主数据库文件主数据库文件单独同步有风险-journal事务回滚日志不使用不适合同步-wal不使用事务内容暂存区不适合同步-shm不使用共享内存索引完全不需要同步1.3 gotcha 的本质多文件原子性无法在两台设备之间保证SQLite 的一致性依赖一个关键前提主数据库文件和它的日志文件必须在同一时刻保持一致。这个保证在单机环境下由 SQLite 自己通过文件锁、页校验和、事务机制来实现但 Syncthing 无法提供这种跨文件的事务性。最典型的损坏过程是这样的设备 A 上的应用使用 WAL 模式写入 SQLite 数据库。写入后的主数据库文件是 v1WAL 文件是 v2其中 v2 包含了尚未合并进 v1 的新数据。Syncthing 扫描到两个文件都发生了变化分别开始同步。设备 B 先收到主数据库文件 v1后收到 WAL 文件 v2或者只收到其中一个。设备 B 上的 SQLite 打开数据库时发现主文件内容和 WAL 内容对不上于是报出数据库损坏。另一种常见情况是两端同时有应用进程在写同一个 SQLite 文件。设备 A 写入事务 A设备 B 写入事务 B两个事务各自产生独立的 WAL 状态。Syncthing 把 A、B 两个方向的改动合并到两端后任何一端都无法拼出一套自洽的“主文件 日志文件”组合。所以这个 gotcha 的本质不是“SQLite 文件损坏了”而是“Syncthing 成功同步了所有文件但同步后的文件组合是一个从未在单机数据库引擎里出现过的不一致状态”。2. 先复现一次数据库损坏亲眼看看报错2.1 环境准备为了验证这个 gotcha不需要准备物理上的两台设备。最简单的方式是准备两台虚拟机或者在 Linux 机器上通过两个目录模拟两端。下面这些组件需要提前确认组件用途建议版本Linux/macOS 主机运行 Syncthing 和 SQLite 实验不限Syncthing文件同步1.23 以上即可sqlite3 CLI操作和验证数据库3.37 以上Python 3可选做批量写入脚本3.8 以上在 Debian/Ubuntu 类系统上Syncthing 可以通过官方仓库或直接下载二进制安装。为了快速实验也可以下载官方 Linux 包后解压运行curl -s https://api.github.com/repos/syncthing/syncthing/releases/latest \ | grep linux-amd64 | cut -d -f 4 \ | wget -qi - tar -xzf syncthing-linux-amd64-*.tar.gz cd syncthing-linux-amd64-* ./syncthing serve --home/tmp/syncthing-a这里把 Syncthing 的配置目录放在/tmp/syncthing-a主要是为了隔离实验环境避免影响本机已有的 Syncthing 服务。两个目录需要先创建好mkdir -p /tmp/sync-a /tmp/sync-b2.2 构造双机同步场景Syncthing 最少需要两台设备才能同步。可以在一台主机上启动两个 Syncthing 实例分别使用不同的配置目录和监听端口然后互相添加设备 ID完成配对。这样可以完全模拟两台机器之间的文件传输。配对完成后在第一个实例中把/tmp/sync-a添加为共享文件夹第二个实例中也添加/tmp/sync-b然后确认两端目录都显示为已连接并且文件夹状态为“已同步”。这个实验的关键点是让 SQLite 的 WAL 文件持续存在并在同步尚未完成时制造中断。为了让 WAL 文件存在需要保持 SQLite 连接不关闭同时在事务中写入足够多的数据import sqlite3 conn sqlite3.connect(/tmp/sync-a/app.db) conn.execute(PRAGMA journal_modeWAL) conn.execute(CREATE TABLE IF NOT EXISTS t(id INTEGER PRIMARY KEY, payload TEXT)) # 写入多批数据让 WAL 文件持续增长 for i in range(200000): conn.execute( INSERT INTO t(payload) VALUES (?), (frow-{i}, ), ) conn.commit() input(连接保持中。此时 app.db-wal 应该存在按 Enter 结束进程并断开……) conn.close()运行脚本后在另一个终端观察/tmp/sync-a下的文件ls -lh /tmp/sync-a/ # 期望能看到 app.db、app.db-wal可能还有 app.db-shmWAL 文件越大主数据库文件和 WAL 文件之间的不一致窗口就越容易被 Syncthing 观察到。2.3 触发损坏并验证接下来有两种方式触发问题在同步传输过程中强制关掉其中一个 Syncthing 进程让主文件和 WAL 文件只同步过去一部分。在/tmp/sync-b还没收到完整的 WAL 文件时直接用 SQLite 打开app.db。最直接的验证方式是在写入脚本还保持连接时把/tmp/sync-b里已经收到的文件手动拷贝出来或者中途暂停另一个 Syncthing 进程然后执行sqlite3 /tmp/sync-b/app.db PRAGMA integrity_check;正常情况会输出ok如果文件组合不一致则可能看到*** in database main *** Page 123: ... database disk image is malformed或者干脆报file is not a database这里要注意这个实验不一定每次都能复现因为 Syncthing 在局域网内同步速度很快主文件和 WAL 文件可能几乎同时到达。但通过人为制造网络断开、进程停止、写入大量数据等方式可以显著提高复现概率。实际生产环境里恰好赶上同步窗口与数据库写入窗口重合是真实发生过的。注意不要在自己正在使用的真实数据库目录里做这个实验因为结果很可能是数据库损坏。实验结束后可以直接删除/tmp/sync-a和/tmp/sync-b。3. 用 sqlite3 和 DB Browser for SQLite 判断损坏程度3.1 先用命令行工具确认数据库状态收到“数据库损坏”的报错后第一件事不是急着修复而是判断损坏范围。SQLite 自带的命令行工具是最可靠的判断方式。先做一个只读完整性检查sqlite3 readonly /path/to/app.db PRAGMA integrity_check;readonly参数让 SQLite 以只读方式打开数据库避免检查过程本身引入新的写入。输出结果为ok时表示主文件内部页结构没有异常。此时如果应用可以正常读写说明问题可能只出现在某个历史 WAL 文件上实际数据并未完全损坏。如果检查结果出现了大量Page ... is malformed说明主数据库文件本身已经存在问题。此时需要进一步检查sqlite3 readonly /path/to/app.db PRAGMA foreign_key_check;foreign_key_check用于检查外键引用是否一致。它不会修复数据但能帮助确认有多少数据表存在关联完整性问题。3.2 用 DB Browser for SQLite 打开数据库DB Browser for SQLite简称 DB4S是一个图形化工具适合在不确定损坏原因时快速查看数据和导出表内容。用命令行工具判断损坏再用 DB4S 可视化确认是一个比较稳妥的流程。打开 DB4S 后把出现问题的.db文件拖入窗口。如果文件损坏程度较轻可以看到表结构并且在“浏览数据”页查看部分行数据。如果一个表完全无法打开通常说明该表的 B-tree 页已经损坏。如果数据库是使用 SQLCipher 加密过的普通版本 DB4S 无法直接打开需要使用支持 SQLCipher 的版本并在打开文件时正确配置加密算法和密码。不要在没有备份的情况下尝试使用强制修复功能图形化工具同样会写数据库文件。3.3 损坏数据的抢救流程损坏发生后一定要按顺序操作避免二次破坏立即停止 Syncthing 对这些目录的同步尤其要暂停另一端设备的自动恢复行为。停止所有正在访问该数据库的应用进程。把整个目录复制一份备份包括.db、-wal、-journal、-shm文件。使用.recover命令尝试导出可读数据sqlite3 /path/to/corrupt.db .recover /tmp/recovered.sql sqlite3 /path/to/recovered.db /tmp/recovered.sql.recover命令是 SQLite 提供的恢复工具会遍历数据库中的可访问页把能读取的表、索引、触发器等输出为 SQL 文件。它无法保证恢复全部数据但通常能救回大部分业务数据。恢复完成后立即对recovered.db执行PRAGMA integrity_check;确认恢复结果本身是健康的。把恢复出的数据导入到一个全新的数据库文件中通过应用的导入脚本完成数据迁移。常见错误是恢复成功后直接拿recovered.db覆盖原文件然后继续放在 Syncthing 同步目录里。这样做没有解决根本问题下次同步仍然可能损坏。4. 生产环境可行的四种方案4.1 方案一根因规避同步目录不直放数据库文件最稳妥的方案是把 SQLite 数据库文件从 Syncthing 同步目录里移出去。数据库文件放到应用数据目录、容器卷或者本地磁盘的专用目录Syncthing 只负责同步应用生成的非数据库产物例如导入文件、导出文件、日志、图片、文档。如果一个应用必须把数据库文件同步到其他设备可以考虑把“导出后的数据文件”作为同步对象而不是同步原始数据库文件。例如笔记应用每天定时导出一个 JSON 或 Markdown 压缩包Syncthing 只同步这个导出包。对端设备需要恢复时再通过导入流程重建 SQLite 数据库。这个方案牺牲了“实时多设备读取同一数据库”的体验但换来的是数据安全。对于绝大多数业务系统来说这个取舍是值得的。4.2 方案二降低风险关闭 WAL 并保证单写者如果确实无法避免同步数据库文件可以通过调整 SQLite 参数降低损坏概率但无法彻底消除。关闭 WAL 模式是最直接的一步PRAGMA journal_modeDELETE;把日志模式改为 DELETE 后SQLite 不再依赖-wal和-shm文件事务回滚信息只使用-journal文件。这样 Syncthing 需要关心的文件从三个减少到两个文件组合不一致的概率会下降。同时必须保证同一时间只有一个写者。如果设备 A 和设备 B 各自都有应用进程在写同一个 SQLite 文件即使关闭 WAL两台设备之间仍然可能因为各自的-journal状态不同而产生冲突。想让这种方案可用必须约定业务数据库只允许一台设备写入其他设备作为只读副本或下载端。可以设置一个busy_timeout让 SQLite 在遇到锁冲突时等待而不是立刻报错PRAGMA busy_timeout5000;不建议为了提升同步成功率把PRAGMA synchronousOFF。这个参数牺牲的是崩溃时的数据安全在数据库文件本身跨越两台设备时任何一致性缺陷都可能被放大。4.3 方案三用 .stignore 排除日志文件但别把它当银弹Syncthing 支持在每个共享文件夹下放置.stignore文件用于忽略指定模式的文件和目录。如果数据库开启了 WAL 模式可以尝试把日志类文件排除在同步之外*.db-wal *.db-shm *.db-journal这样做的好处是Syncthing 只会同步主.db文件避免三份文件由于到达顺序不同导致的不一致。但这个方案有非常明显的前提限制主数据库文件本身必须总是处于自洽状态。如果应用写了一半主文件还没完成 checkpoint那么单独同步主文件仍然可能把不完整状态传到另一端。对端设备如果在本地也打开同一个数据库SQLite 会认为-wal文件不存在可能根据主文件内容推断事务状态从而和数据实际状态不符。.stignore只影响新文件的同步已经同步到本地的-wal、-shm文件不会被自动清理需要手动处理。所以这个方案更适合“数据库只是定期备份到另一端不在另一端直接访问”的场景而不是“两台设备同时读写同一 SQLite 库”的场景。4.4 方案四定期生成一致性快照再交给 Syncthing如果要让 Syncthing 最终同步到的数据库在逻辑上完整最干净的手段是通过 SQLite 自身生成一致性快照再让 Syncthing 同步快照文件。SQLite 3.27 以上支持VACUUM INTO语法可以离线生成当前数据库的一个完整副本sqlite3 /var/lib/app/app.db VACUUM INTO /srv/syncthing/app-snapshot/app.db因为这个快照是 SQLite 引擎自己生成的新数据库文件它不包含 WAL 文件也不会把当前未提交的事务带入快照。Syncthing 同步的是快照目录而不是活跃数据库目录。可以把生成快照写成定时任务#!/usr/bin/env bash set -euo pipefail DB_PATH/var/lib/app/app.db SNAP_DIR/srv/syncthing/app-snapshot TMP_FILE${SNAP_DIR}/app.db.tmp sqlite3 ${DB_PATH} VACUUM INTO ${TMP_FILE} mv ${TMP_FILE} ${SNAP_DIR}/app.db执行完脚本后app-snapshot/app.db是一个独立的、逻辑完整的数据库文件Syncthing 同步它时不需要关心 WAL 或 journal 状态。对端设备拿到这个文件后可以原样使用。这个方案的缺点是快照不是实时的数据恢复最多恢复到最近一次快照的时间点。但它把“同步”和“数据库一致性”彻底解耦了是最稳妥的生产方案之一。方案实时性损坏风险适合场景同步目录不直放数据库低很低大部分业务系统关闭 WAL 单写者中中单写者、双机备份.stignore 排除日志文件中较高只备份、不在对端直接访问VACUUM INTO 快照低很低多端只读下载、定时备份5. NAS 上部署 Syncthing 时另一个常见的 gotcha5.1 威联通和 TrueNAS SCALE 的安装差异Syncthing 最常见的部署场景之一就是 NAS。很多人的规划是让 NAS 在后台挂机同步笔记本和手机只在需要时连接。威联通QNAP上常用 Container Station 安装 Syncthing 的 Docker 镜像TrueNAS SCALE 则通过应用商店安装官方或社区 Chart。这两个平台安装方式不同但有一个共同点应用安装本身出问题时排查入口都比较隐蔽。如果只是想在 NAS 上先跑通 Syncthing建议先关注三个基础条件存储池空间是否充足尤其是系统应用数据集的剩余空间。NAS 的时间是否准确NTP 时钟漂移会影响证书和设备认证。安装路径中是否包含特殊字符或中文目录某些容器模板对路径解析敏感。5.2 [EFAULT] Failed up action for syncthing app 的排查顺序在 TrueNAS SCALE 上安装 Syncthing 时有时任务会直接失败提示[EFAULT] Failed up action for syncthing app.这个报错非常笼统它只是说明应用在启动阶段没有成功进入运行状态并没有给出具体原因。建议按以下顺序排查查看任务日志和系统事件日志定位失败发生在下载镜像还是容器启动阶段。确认系统应用池是否有足够空间App 环境自身也需要存储空间。确认自定义数据集权限是否正确Syncthing 需要能够写入配置目录和数据目录。检查是否残留了上一次安装失败的 release 元数据如果有需要清理后重装。如果容器镜像来自外部仓库确认 NAS 能正常拉取镜像并检查是否因网络原因导致镜像下载超时。这类问题和 SQLite 文件同步损坏不是同一件事但都属于“Syncthing 部署链路上的 gotcha”。它们共同提醒一点不要在日志只有一条笼统错误时直接怀疑数据库先确认基础设施层是否健康。5.3 容器持久化数据是否会被 Syncthing 自身同步在 NAS 上用容器跑 Syncthing 时容易产生另一个隐蔽坑容器内部的应用数据被持久化到某个数据卷而这个数据卷恰好又被 Syncthing 自身共享给其他设备。例如Syncthing 的 Web 管理界面本身会保存配置数据库里面存放设备 ID、文件夹路径、同步状态等信息。如果这个配置目录被错误地放进了一个同步文件夹就会出现“同步工具本身的数据被自己同步”的情况轻则配置冲突重则导致配置数据库损坏。处理方法是把 Syncthing 的配置目录和真正要同步的业务目录严格分开并且不要让 Syncthing 的共享根目录包含自己的配置目录。这个原则同样适用于使用 SQLite 的应用应用数据卷不要放在同步根目录下。6. 常见错误现象排查速查表在实际工作中遇到 Syncthing 与 SQLite 相关问题时可以参考下面这张速查表从现象直接定位到处理方向。问题现象可能原因检查方式处理建议对端数据库打开报database disk image is malformed主文件与 WAL/journal 文件同步不同步PRAGMA integrity_check;停止同步、备份、使用.recover抢救报file is not a database对端拿到的是临时文件、空文件或截断文件查看文件大小对比两端ls -l恢复数据库重新同步报SQLITE_BUSY: database is locked两台设备同时写入同一 SQLite 文件分别在两端执行lsof或fuser确认写进程改为单写者模式或改用快照同步数据库能打开但缺少部分数据WAL 文件未同步到对端最近事务丢失比对两端数据条数恢复快照检查 WAL 文件管理出现大量sync-conflict文件两台设备分别修改了同一文件检查 Syncthing Web 界面冲突文件列表明确单写者或改用数据库后端同步Syncthing 安装时报Failed up action卷权限、镜像拉取、系统元数据问题查看任务日志和系统事件按基础设施层排查这张表不用等到问题发生才看可以在搭建 Syncthing 同步方案之前先过一遍很多坑是可以在设计阶段规避的。7. 最佳实践把同步策略和数据库模型一起设计7.1 决策清单在决定“要不要用 Syncthing 同步 SQLite 数据库”之前先回答下面几个问题这个数据库是否必须被多台设备直接读写如果是就要重新考虑同步方案。这个数据库允许丢失最近几分钟的数据吗如果不允许快照同步不满足需求。这台设备是否是唯一的写者如果不是需要引入冲突解决机制。数据库损坏后是否有一套经过验证的恢复流程如果没有风险极高。数据库文件是否放在 NAS 的同步目录里如果是检查它与 Syncthing 配置目录是否隔离。如果“多设备直接读写”和“数据零丢失”都必须满足SQLite 文件同步方案已经不适合应该换成支持分布式多写者的数据库或者使用基于主从复制的同步策略。SQLite 的强项是单机可靠跨设备场景需要靠应用层导出、备份、快照来解决。7.2 落地执行路径推荐的学习环境和生产环境组合如下学习环境用 Syncthing 同步一个普通文档目录体会文件同步的正常行为再在一个隔离目录里做 SQLite 损坏实验。开发环境明确数据库的写者把数据库文件放在应用专用数据目录不让 Syncthing 直接接触。测试环境验证应用在数据库文件缺失、对端文件不完整、WAL 文件未同步时是否能优雅降级。生产环境使用VACUUM INTO定期生成快照快照目录交给 Syncthing或者使用数据库应用自身的备份机制。一个可复用的检查清单如下检查项期望结果数据库是否在同步目录中否是否开启 WAL视单/多写者场景决定多写者必须关闭写者数量1 个是否有定时一致性快照是是否有定期PRAGMA integrity_check是Syncthing 配置目录是否与业务目录隔离是是否有损坏后的恢复演练记录是7.3 往多写者方向扩展时怎么办如果业务确实需要多台设备共同读写同一个 SQLite 数据库直接使用文件同步不是正确答案。可以往三个方向扩展数据库服务化把 SQLite 放进一个中心设备其他设备通过局域网访问Syncthing 只负责同步其他文件。数据合并模式每台设备各自维护本地 SQLite定期导出增量数据再用应用层逻辑合并冲突。更换分布式存储使用支持多主写入或基于 CRDT 的数据层让数据模型本身具备冲突解决能力。无论选择哪个方向都要在方案设计阶段考虑“数据库文件已经损坏时业务系统是否还能继续运行”。增加数据库健康检查、启动时完整性校验、损坏时自动切换到最近快照这三件事比单纯提高同步频率更有价值。回到最核心的技术判断Syncthing 是一个优秀的文件同步工具但它不能替代数据库日志和事务机制。把 SQLite 数据库当作普通文件交给 Syncthing是在用文件同步的语义挑战数据库的一致性语义。真正的生产实践应该把“活跃数据库”和“可同步文件”分开活跃数据库放在本地专用目录通过应用层导出或VACUUM INTO生成一致性快照再把快照交给 Syncthing。这样既保留 Syncthing 的便捷性又不会让数据库在同步过程中变成不可用的损坏状态。下次再看到对端数据库报错先别急着恢复数据回头检查同步目录、WAL 文件和写者数量大概率能在十分钟内定位到根因。 Syncthing 同步 SQLite 数据库导致损坏：原因、复现与生产方案
在实际项目里Syncthing 和 SQLite 是一对看起来很互补、实际很容易踩坑的组合。Syncthing 负责在手机、电脑、NAS 之间自动同步文件夹SQLite 负责在本地文件里保存结构化数据。很多开发者会把笔记数据、爬虫结果、内部小系统的业务库直接放进 Syncthing 同步目录期待两台设备上的数据始终一致。结果某天另一台设备打开数据库时SQLite 突然报出database disk image is malformed或者提示file is not a database。这个问题不是普通的同步冲突而是 Syncthing 的文件同步模型和 SQLite 的持久化模型之间天然不匹配造成的 gotcha。只有理解了“Syncthing 同步的是文件SQLite 依赖的是多个文件的原子配合”才能真正避免数据库被同步坏。读完这篇内容你会知道这个坑是怎么触发的、如何最小复现、损坏后怎么抢救以及生产环境里应该选择哪种同步策略。1. 为什么 Syncthing 同步文件不等于同步数据库1.1 Syncthing 的同步单位是文件不是事务Syncthing 是一个去中心化的文件同步工具。它的核心工作方式不是把数据写入同一个中心服务器而是让每台设备都保存文件的元数据并通过版本向量判断哪个文件是新版本。发现差异后Syncthing 会按块传输文件内容最终在另一端重组成完整文件。这种设计对普通文件非常合适。因为普通文件的语义是“整个文件作为一个整体”你改了文件里的几个字节Syncthing 只需要把改动过的块传过去接收端拼出来的仍然是一个完整的文件。问题在于Syncthing 不感知“两个文件之间存在事务关系”。它把两个文件当成两个独立对象来同步。如果事务 A 修改了文件 1事务 B 修改了文件 2Syncthing 可能先同步文件 1再同步文件 2也可能只同步了其中一个就发生了断开。对于互相之间有依赖关系的文件这个时间窗口就是隐患。1.2 SQLite 一个数据库由多个文件协同组成SQLite 常常被理解成“一个数据库就是一个 .db 文件”这个印象在绝大多数静态场景下是对的但数据库文件并不是独立存在的。在默认的 DELETE journal 模式下SQLite 执行写事务时会先创建主数据库文件对应的-journal回滚日志文件把原始页写入日志再修改主数据库文件。事务提交后日志文件被删除。如果数据库崩溃SQLite 打开数据库时会根据-journal是否存在来决定是否回滚事务。在 WALWrite-Ahead Logging模式下文件关系更复杂。SQLite 会把新写入的内容先追加到-wal文件主数据库文件可能暂时没有变化之后通过 checkpoint 机制把 WAL 中的页合并回主文件。另外还会创建-shm文件作为共享内存索引用于多进程并发访问。也就是说一个正在使用的 SQLite 数据库实际包含这些文件文件后缀在 DELETE 模式下在 WAL 模式下是否适合被同步.db主数据库文件主数据库文件单独同步有风险-journal事务回滚日志不使用不适合同步-wal不使用事务内容暂存区不适合同步-shm不使用共享内存索引完全不需要同步1.3 gotcha 的本质多文件原子性无法在两台设备之间保证SQLite 的一致性依赖一个关键前提主数据库文件和它的日志文件必须在同一时刻保持一致。这个保证在单机环境下由 SQLite 自己通过文件锁、页校验和、事务机制来实现但 Syncthing 无法提供这种跨文件的事务性。最典型的损坏过程是这样的设备 A 上的应用使用 WAL 模式写入 SQLite 数据库。写入后的主数据库文件是 v1WAL 文件是 v2其中 v2 包含了尚未合并进 v1 的新数据。Syncthing 扫描到两个文件都发生了变化分别开始同步。设备 B 先收到主数据库文件 v1后收到 WAL 文件 v2或者只收到其中一个。设备 B 上的 SQLite 打开数据库时发现主文件内容和 WAL 内容对不上于是报出数据库损坏。另一种常见情况是两端同时有应用进程在写同一个 SQLite 文件。设备 A 写入事务 A设备 B 写入事务 B两个事务各自产生独立的 WAL 状态。Syncthing 把 A、B 两个方向的改动合并到两端后任何一端都无法拼出一套自洽的“主文件 日志文件”组合。所以这个 gotcha 的本质不是“SQLite 文件损坏了”而是“Syncthing 成功同步了所有文件但同步后的文件组合是一个从未在单机数据库引擎里出现过的不一致状态”。2. 先复现一次数据库损坏亲眼看看报错2.1 环境准备为了验证这个 gotcha不需要准备物理上的两台设备。最简单的方式是准备两台虚拟机或者在 Linux 机器上通过两个目录模拟两端。下面这些组件需要提前确认组件用途建议版本Linux/macOS 主机运行 Syncthing 和 SQLite 实验不限Syncthing文件同步1.23 以上即可sqlite3 CLI操作和验证数据库3.37 以上Python 3可选做批量写入脚本3.8 以上在 Debian/Ubuntu 类系统上Syncthing 可以通过官方仓库或直接下载二进制安装。为了快速实验也可以下载官方 Linux 包后解压运行curl -s https://api.github.com/repos/syncthing/syncthing/releases/latest \ | grep linux-amd64 | cut -d -f 4 \ | wget -qi - tar -xzf syncthing-linux-amd64-*.tar.gz cd syncthing-linux-amd64-* ./syncthing serve --home/tmp/syncthing-a这里把 Syncthing 的配置目录放在/tmp/syncthing-a主要是为了隔离实验环境避免影响本机已有的 Syncthing 服务。两个目录需要先创建好mkdir -p /tmp/sync-a /tmp/sync-b2.2 构造双机同步场景Syncthing 最少需要两台设备才能同步。可以在一台主机上启动两个 Syncthing 实例分别使用不同的配置目录和监听端口然后互相添加设备 ID完成配对。这样可以完全模拟两台机器之间的文件传输。配对完成后在第一个实例中把/tmp/sync-a添加为共享文件夹第二个实例中也添加/tmp/sync-b然后确认两端目录都显示为已连接并且文件夹状态为“已同步”。这个实验的关键点是让 SQLite 的 WAL 文件持续存在并在同步尚未完成时制造中断。为了让 WAL 文件存在需要保持 SQLite 连接不关闭同时在事务中写入足够多的数据import sqlite3 conn sqlite3.connect(/tmp/sync-a/app.db) conn.execute(PRAGMA journal_modeWAL) conn.execute(CREATE TABLE IF NOT EXISTS t(id INTEGER PRIMARY KEY, payload TEXT)) # 写入多批数据让 WAL 文件持续增长 for i in range(200000): conn.execute( INSERT INTO t(payload) VALUES (?), (frow-{i}, ), ) conn.commit() input(连接保持中。此时 app.db-wal 应该存在按 Enter 结束进程并断开……) conn.close()运行脚本后在另一个终端观察/tmp/sync-a下的文件ls -lh /tmp/sync-a/ # 期望能看到 app.db、app.db-wal可能还有 app.db-shmWAL 文件越大主数据库文件和 WAL 文件之间的不一致窗口就越容易被 Syncthing 观察到。2.3 触发损坏并验证接下来有两种方式触发问题在同步传输过程中强制关掉其中一个 Syncthing 进程让主文件和 WAL 文件只同步过去一部分。在/tmp/sync-b还没收到完整的 WAL 文件时直接用 SQLite 打开app.db。最直接的验证方式是在写入脚本还保持连接时把/tmp/sync-b里已经收到的文件手动拷贝出来或者中途暂停另一个 Syncthing 进程然后执行sqlite3 /tmp/sync-b/app.db PRAGMA integrity_check;正常情况会输出ok如果文件组合不一致则可能看到*** in database main *** Page 123: ... database disk image is malformed或者干脆报file is not a database这里要注意这个实验不一定每次都能复现因为 Syncthing 在局域网内同步速度很快主文件和 WAL 文件可能几乎同时到达。但通过人为制造网络断开、进程停止、写入大量数据等方式可以显著提高复现概率。实际生产环境里恰好赶上同步窗口与数据库写入窗口重合是真实发生过的。注意不要在自己正在使用的真实数据库目录里做这个实验因为结果很可能是数据库损坏。实验结束后可以直接删除/tmp/sync-a和/tmp/sync-b。3. 用 sqlite3 和 DB Browser for SQLite 判断损坏程度3.1 先用命令行工具确认数据库状态收到“数据库损坏”的报错后第一件事不是急着修复而是判断损坏范围。SQLite 自带的命令行工具是最可靠的判断方式。先做一个只读完整性检查sqlite3 readonly /path/to/app.db PRAGMA integrity_check;readonly参数让 SQLite 以只读方式打开数据库避免检查过程本身引入新的写入。输出结果为ok时表示主文件内部页结构没有异常。此时如果应用可以正常读写说明问题可能只出现在某个历史 WAL 文件上实际数据并未完全损坏。如果检查结果出现了大量Page ... is malformed说明主数据库文件本身已经存在问题。此时需要进一步检查sqlite3 readonly /path/to/app.db PRAGMA foreign_key_check;foreign_key_check用于检查外键引用是否一致。它不会修复数据但能帮助确认有多少数据表存在关联完整性问题。3.2 用 DB Browser for SQLite 打开数据库DB Browser for SQLite简称 DB4S是一个图形化工具适合在不确定损坏原因时快速查看数据和导出表内容。用命令行工具判断损坏再用 DB4S 可视化确认是一个比较稳妥的流程。打开 DB4S 后把出现问题的.db文件拖入窗口。如果文件损坏程度较轻可以看到表结构并且在“浏览数据”页查看部分行数据。如果一个表完全无法打开通常说明该表的 B-tree 页已经损坏。如果数据库是使用 SQLCipher 加密过的普通版本 DB4S 无法直接打开需要使用支持 SQLCipher 的版本并在打开文件时正确配置加密算法和密码。不要在没有备份的情况下尝试使用强制修复功能图形化工具同样会写数据库文件。3.3 损坏数据的抢救流程损坏发生后一定要按顺序操作避免二次破坏立即停止 Syncthing 对这些目录的同步尤其要暂停另一端设备的自动恢复行为。停止所有正在访问该数据库的应用进程。把整个目录复制一份备份包括.db、-wal、-journal、-shm文件。使用.recover命令尝试导出可读数据sqlite3 /path/to/corrupt.db .recover /tmp/recovered.sql sqlite3 /path/to/recovered.db /tmp/recovered.sql.recover命令是 SQLite 提供的恢复工具会遍历数据库中的可访问页把能读取的表、索引、触发器等输出为 SQL 文件。它无法保证恢复全部数据但通常能救回大部分业务数据。恢复完成后立即对recovered.db执行PRAGMA integrity_check;确认恢复结果本身是健康的。把恢复出的数据导入到一个全新的数据库文件中通过应用的导入脚本完成数据迁移。常见错误是恢复成功后直接拿recovered.db覆盖原文件然后继续放在 Syncthing 同步目录里。这样做没有解决根本问题下次同步仍然可能损坏。4. 生产环境可行的四种方案4.1 方案一根因规避同步目录不直放数据库文件最稳妥的方案是把 SQLite 数据库文件从 Syncthing 同步目录里移出去。数据库文件放到应用数据目录、容器卷或者本地磁盘的专用目录Syncthing 只负责同步应用生成的非数据库产物例如导入文件、导出文件、日志、图片、文档。如果一个应用必须把数据库文件同步到其他设备可以考虑把“导出后的数据文件”作为同步对象而不是同步原始数据库文件。例如笔记应用每天定时导出一个 JSON 或 Markdown 压缩包Syncthing 只同步这个导出包。对端设备需要恢复时再通过导入流程重建 SQLite 数据库。这个方案牺牲了“实时多设备读取同一数据库”的体验但换来的是数据安全。对于绝大多数业务系统来说这个取舍是值得的。4.2 方案二降低风险关闭 WAL 并保证单写者如果确实无法避免同步数据库文件可以通过调整 SQLite 参数降低损坏概率但无法彻底消除。关闭 WAL 模式是最直接的一步PRAGMA journal_modeDELETE;把日志模式改为 DELETE 后SQLite 不再依赖-wal和-shm文件事务回滚信息只使用-journal文件。这样 Syncthing 需要关心的文件从三个减少到两个文件组合不一致的概率会下降。同时必须保证同一时间只有一个写者。如果设备 A 和设备 B 各自都有应用进程在写同一个 SQLite 文件即使关闭 WAL两台设备之间仍然可能因为各自的-journal状态不同而产生冲突。想让这种方案可用必须约定业务数据库只允许一台设备写入其他设备作为只读副本或下载端。可以设置一个busy_timeout让 SQLite 在遇到锁冲突时等待而不是立刻报错PRAGMA busy_timeout5000;不建议为了提升同步成功率把PRAGMA synchronousOFF。这个参数牺牲的是崩溃时的数据安全在数据库文件本身跨越两台设备时任何一致性缺陷都可能被放大。4.3 方案三用 .stignore 排除日志文件但别把它当银弹Syncthing 支持在每个共享文件夹下放置.stignore文件用于忽略指定模式的文件和目录。如果数据库开启了 WAL 模式可以尝试把日志类文件排除在同步之外*.db-wal *.db-shm *.db-journal这样做的好处是Syncthing 只会同步主.db文件避免三份文件由于到达顺序不同导致的不一致。但这个方案有非常明显的前提限制主数据库文件本身必须总是处于自洽状态。如果应用写了一半主文件还没完成 checkpoint那么单独同步主文件仍然可能把不完整状态传到另一端。对端设备如果在本地也打开同一个数据库SQLite 会认为-wal文件不存在可能根据主文件内容推断事务状态从而和数据实际状态不符。.stignore只影响新文件的同步已经同步到本地的-wal、-shm文件不会被自动清理需要手动处理。所以这个方案更适合“数据库只是定期备份到另一端不在另一端直接访问”的场景而不是“两台设备同时读写同一 SQLite 库”的场景。4.4 方案四定期生成一致性快照再交给 Syncthing如果要让 Syncthing 最终同步到的数据库在逻辑上完整最干净的手段是通过 SQLite 自身生成一致性快照再让 Syncthing 同步快照文件。SQLite 3.27 以上支持VACUUM INTO语法可以离线生成当前数据库的一个完整副本sqlite3 /var/lib/app/app.db VACUUM INTO /srv/syncthing/app-snapshot/app.db因为这个快照是 SQLite 引擎自己生成的新数据库文件它不包含 WAL 文件也不会把当前未提交的事务带入快照。Syncthing 同步的是快照目录而不是活跃数据库目录。可以把生成快照写成定时任务#!/usr/bin/env bash set -euo pipefail DB_PATH/var/lib/app/app.db SNAP_DIR/srv/syncthing/app-snapshot TMP_FILE${SNAP_DIR}/app.db.tmp sqlite3 ${DB_PATH} VACUUM INTO ${TMP_FILE} mv ${TMP_FILE} ${SNAP_DIR}/app.db执行完脚本后app-snapshot/app.db是一个独立的、逻辑完整的数据库文件Syncthing 同步它时不需要关心 WAL 或 journal 状态。对端设备拿到这个文件后可以原样使用。这个方案的缺点是快照不是实时的数据恢复最多恢复到最近一次快照的时间点。但它把“同步”和“数据库一致性”彻底解耦了是最稳妥的生产方案之一。方案实时性损坏风险适合场景同步目录不直放数据库低很低大部分业务系统关闭 WAL 单写者中中单写者、双机备份.stignore 排除日志文件中较高只备份、不在对端直接访问VACUUM INTO 快照低很低多端只读下载、定时备份5. NAS 上部署 Syncthing 时另一个常见的 gotcha5.1 威联通和 TrueNAS SCALE 的安装差异Syncthing 最常见的部署场景之一就是 NAS。很多人的规划是让 NAS 在后台挂机同步笔记本和手机只在需要时连接。威联通QNAP上常用 Container Station 安装 Syncthing 的 Docker 镜像TrueNAS SCALE 则通过应用商店安装官方或社区 Chart。这两个平台安装方式不同但有一个共同点应用安装本身出问题时排查入口都比较隐蔽。如果只是想在 NAS 上先跑通 Syncthing建议先关注三个基础条件存储池空间是否充足尤其是系统应用数据集的剩余空间。NAS 的时间是否准确NTP 时钟漂移会影响证书和设备认证。安装路径中是否包含特殊字符或中文目录某些容器模板对路径解析敏感。5.2 [EFAULT] Failed up action for syncthing app 的排查顺序在 TrueNAS SCALE 上安装 Syncthing 时有时任务会直接失败提示[EFAULT] Failed up action for syncthing app.这个报错非常笼统它只是说明应用在启动阶段没有成功进入运行状态并没有给出具体原因。建议按以下顺序排查查看任务日志和系统事件日志定位失败发生在下载镜像还是容器启动阶段。确认系统应用池是否有足够空间App 环境自身也需要存储空间。确认自定义数据集权限是否正确Syncthing 需要能够写入配置目录和数据目录。检查是否残留了上一次安装失败的 release 元数据如果有需要清理后重装。如果容器镜像来自外部仓库确认 NAS 能正常拉取镜像并检查是否因网络原因导致镜像下载超时。这类问题和 SQLite 文件同步损坏不是同一件事但都属于“Syncthing 部署链路上的 gotcha”。它们共同提醒一点不要在日志只有一条笼统错误时直接怀疑数据库先确认基础设施层是否健康。5.3 容器持久化数据是否会被 Syncthing 自身同步在 NAS 上用容器跑 Syncthing 时容易产生另一个隐蔽坑容器内部的应用数据被持久化到某个数据卷而这个数据卷恰好又被 Syncthing 自身共享给其他设备。例如Syncthing 的 Web 管理界面本身会保存配置数据库里面存放设备 ID、文件夹路径、同步状态等信息。如果这个配置目录被错误地放进了一个同步文件夹就会出现“同步工具本身的数据被自己同步”的情况轻则配置冲突重则导致配置数据库损坏。处理方法是把 Syncthing 的配置目录和真正要同步的业务目录严格分开并且不要让 Syncthing 的共享根目录包含自己的配置目录。这个原则同样适用于使用 SQLite 的应用应用数据卷不要放在同步根目录下。6. 常见错误现象排查速查表在实际工作中遇到 Syncthing 与 SQLite 相关问题时可以参考下面这张速查表从现象直接定位到处理方向。问题现象可能原因检查方式处理建议对端数据库打开报database disk image is malformed主文件与 WAL/journal 文件同步不同步PRAGMA integrity_check;停止同步、备份、使用.recover抢救报file is not a database对端拿到的是临时文件、空文件或截断文件查看文件大小对比两端ls -l恢复数据库重新同步报SQLITE_BUSY: database is locked两台设备同时写入同一 SQLite 文件分别在两端执行lsof或fuser确认写进程改为单写者模式或改用快照同步数据库能打开但缺少部分数据WAL 文件未同步到对端最近事务丢失比对两端数据条数恢复快照检查 WAL 文件管理出现大量sync-conflict文件两台设备分别修改了同一文件检查 Syncthing Web 界面冲突文件列表明确单写者或改用数据库后端同步Syncthing 安装时报Failed up action卷权限、镜像拉取、系统元数据问题查看任务日志和系统事件按基础设施层排查这张表不用等到问题发生才看可以在搭建 Syncthing 同步方案之前先过一遍很多坑是可以在设计阶段规避的。7. 最佳实践把同步策略和数据库模型一起设计7.1 决策清单在决定“要不要用 Syncthing 同步 SQLite 数据库”之前先回答下面几个问题这个数据库是否必须被多台设备直接读写如果是就要重新考虑同步方案。这个数据库允许丢失最近几分钟的数据吗如果不允许快照同步不满足需求。这台设备是否是唯一的写者如果不是需要引入冲突解决机制。数据库损坏后是否有一套经过验证的恢复流程如果没有风险极高。数据库文件是否放在 NAS 的同步目录里如果是检查它与 Syncthing 配置目录是否隔离。如果“多设备直接读写”和“数据零丢失”都必须满足SQLite 文件同步方案已经不适合应该换成支持分布式多写者的数据库或者使用基于主从复制的同步策略。SQLite 的强项是单机可靠跨设备场景需要靠应用层导出、备份、快照来解决。7.2 落地执行路径推荐的学习环境和生产环境组合如下学习环境用 Syncthing 同步一个普通文档目录体会文件同步的正常行为再在一个隔离目录里做 SQLite 损坏实验。开发环境明确数据库的写者把数据库文件放在应用专用数据目录不让 Syncthing 直接接触。测试环境验证应用在数据库文件缺失、对端文件不完整、WAL 文件未同步时是否能优雅降级。生产环境使用VACUUM INTO定期生成快照快照目录交给 Syncthing或者使用数据库应用自身的备份机制。一个可复用的检查清单如下检查项期望结果数据库是否在同步目录中否是否开启 WAL视单/多写者场景决定多写者必须关闭写者数量1 个是否有定时一致性快照是是否有定期PRAGMA integrity_check是Syncthing 配置目录是否与业务目录隔离是是否有损坏后的恢复演练记录是7.3 往多写者方向扩展时怎么办如果业务确实需要多台设备共同读写同一个 SQLite 数据库直接使用文件同步不是正确答案。可以往三个方向扩展数据库服务化把 SQLite 放进一个中心设备其他设备通过局域网访问Syncthing 只负责同步其他文件。数据合并模式每台设备各自维护本地 SQLite定期导出增量数据再用应用层逻辑合并冲突。更换分布式存储使用支持多主写入或基于 CRDT 的数据层让数据模型本身具备冲突解决能力。无论选择哪个方向都要在方案设计阶段考虑“数据库文件已经损坏时业务系统是否还能继续运行”。增加数据库健康检查、启动时完整性校验、损坏时自动切换到最近快照这三件事比单纯提高同步频率更有价值。回到最核心的技术判断Syncthing 是一个优秀的文件同步工具但它不能替代数据库日志和事务机制。把 SQLite 数据库当作普通文件交给 Syncthing是在用文件同步的语义挑战数据库的一致性语义。真正的生产实践应该把“活跃数据库”和“可同步文件”分开活跃数据库放在本地专用目录通过应用层导出或VACUUM INTO生成一致性快照再把快照交给 Syncthing。这样既保留 Syncthing 的便捷性又不会让数据库在同步过程中变成不可用的损坏状态。下次再看到对端数据库报错先别急着恢复数据回头检查同步目录、WAL 文件和写者数量大概率能在十分钟内定位到根因。