2026年8月3日

file-sync-config 技能——双向同步的飞行前检查清单

Datarim 如何在配置 Syncthing、rclone 或任何双向文件同步层时防止同步冲突和跨平台损坏——包括强制性的清单盘点、针对 git 仓库的决策树,以及可复用的忽略模式模板。

跨多台机器的双向文件同步看起来很简单,直到它遇到嵌套的 git 仓库、为错误架构构建的 Python 虚拟环境,或者一个本不该出现在另一台主机上的本地 SQLite 数据库。file-sync-config 技能为任何双向同步设置在第一个字节移动之前提供了强制性的飞行前检查清单。

该技能适用于 Syncthing 文件夹设置、rclone bisync、Dropbox 和 iCloud 共享文件夹、定期 rsync 任务以及任何自定义同步层。它明确不适用于单向备份或 CI 制品传输,因为那里的风险模型不同。

创始事件

该技能的存在源于一次具体的失败。Syncthing 的初始 .stignore 有 28 个模式,没有覆盖 .venv、__pycache__、target/、*.db,也没有排除嵌套的 git 仓库。一周内的结果:生产环境 CLAUDE.md 文件中出现了一个实际发生的同步冲突,vault 中累积了 60 多个冲突文件,14 个 git 仓库以不同的检出分支作为普通工作树同步,以及为 macOS 构建的 Python 虚拟环境被复制到 Linux 主机带来的跨平台二进制风险。在将模式列表从 28 项扩展到 66 项后,同步文件数量从 40,361 降至 2,206——减少了 95%。

飞行前清单盘点

在开启同步之前,该技能要求在源主机上针对五类有问题的文件运行 find:构建产物和依赖目录(node_modules、.venv、target、.next 等)、嵌套的 git 仓库、本地数据库文件(*.db、*.sqlite)、编译后的二进制文件(*.so、*.dylib、*.dll),以及 IDE 和操作系统垃圾文件。清单盘点发现的每一类都必须在首次同步运行之前纳入忽略模式。

git 仓库的决策树

对于同步根目录内的每个 .git/ 目录,该技能会问一个问题:第二个节点是否在此仓库中有实时编辑、代理或生产运行时?如果是,则整个仓库路径从同步中排除,第二个节点改为通过 git pull cron 获取更新。如果否,则可以同步工作树,但 .git/ 目录本身仍被排除,以便每个节点保留自己的提交历史。

默认做法是将答案视为“是”。几乎任何第二个节点最终都会变得活跃——出现一个新代理、落地一个部署脚本、有人进行手动编辑。过度保护的成本低于恢复的成本。

合规检查清单

该技能包含一份针对基础设施任务的九点合规检查清单:完成飞行前清单盘点;所有发现的类别都在忽略模式中;每个嵌套的 git 目录要么被排除,要么记录为只读镜像;当同步跨越不同操作系统时排除跨平台二进制文件;排除数据库文件;应用锁定设置;存储配置备份;记录运行手册;并在两个方向上运行冒烟测试。

该技能还提供了用于 Syncthing 的可复用 .stignore 模板、涵盖 Syncthing、rclone 和 rsync 语法差异的模式语法速查表,以及使用 cron 拉取脚本或 CI/CD 自托管运行器在第二个节点上更新被 git 排除的仓库的工作流程。

在什么是 Datarim中了解更多关于 Datarim 流水线的信息,或查看finishing-a-development-branch 技能如何处理开发周期的结束。