技能 Tech

文件同步配置

文件同步(Syncthing/rclone/rsync/Dropbox/iCloud)的预检清单与忽略模式 — 保护 git 工作树、虚拟环境和构建产物。

概述

文件同步配置收录了每个双向文件同步器在接触网络之前所需的预检规则。在配置 Syncthing、rclone bisync、Dropbox/iCloud/Google Drive 共享文件夹、周期性 rsync 任务、自定义的 git 感知同步引擎或任何自定义同步层之前加载它。不要为单向备份或 CI 产物传输加载 — 它们有不同的风险模型。

为何重要(创始事故)

<TASK-ID>(2026-04-25):Syncthing 的第一个 .stignore 有 28 个模式,遗漏了 .venv、__pycache__、target/、*.db,并且未能整体排除嵌套的 git 仓库。结果:1 个实际发生的生产同步冲突,一周内 60+ 个 .sync-conflict 文件,14 个 git 仓库在各主机间工作树分叉,以及真实的跨平台损坏风险(macOS Mach-O 与 Linux ELF 二进制)。将模式集从 28 扩展到 66 后,文件数从 40,361 降至 2,206(−95%)。

预检清单(强制)

在开启同步之前,针对源根目录对每个问题类别运行 find — 清单发现的任何内容必须在首次同步前加入忽略列表:

  • 第三方依赖 / 构建产物 — node_modules、.venv/venv、__pycache__、target、.next/.turbo/.nuxt、.cache/.parcel-cache、coverage/.nyc_output、dist/build/.build、DerivedData、.pytest_cache/.mypy_cache/.ruff_cache
  • 嵌套的 .git 目录(关键)— 同步根目录下的每个 .git/
  • 本地数据库 / 状态文件 — *.db、*.sqlite/*.sqlite3、*.duckdb、*.db-journal
  • 编译后的二进制文件(跨平台不安全)— *.so、*.dylib、*.dll、*.exe
  • IDE / 操作系统垃圾文件 — .idea、.vscode、.DS_Store、Thumbs.db

决策树:同步工作树还是 git pull

对于同步根目录内发现的每个 .git/,问:第二个节点是否在此仓库中承载实时编辑、代理或生产运行时?

  • 是 → 不要同步工作树。整体排除 /path/to/repo。通过第二个节点上的 git pull cron 更新(参见 workspace-pull.sh 模式)。
  • 否 → 工作树可作为只读镜像同步,但仍需排除 .git/ — 每个节点保留自己的提交历史。

默认选“是” — 几乎每个第二个节点最终都会变为“活跃”(新代理、部署脚本、手动编辑)。过度保护胜过恢复。

可复用的 .stignore 模板(Syncthing,<TASK-ID> v2)

加固后的模板覆盖九个类别:

  1. 项目源代码(独立的 git 仓库)— /Projects/*/code、/Projects/<project>/sources
  2. 拥有自己 git/venv 的 AI 代理 — /AI_agents/Email Agent、Screen reader、Remove-Watermark、Agent Dreamer
  3. 工作流 / 运行时状态 — .git、.dreamer、.meta、.claude、.githooks
  4. Datarim 覆盖前备份 — datarim/.backups、.backups(主机本地恢复副本;同步它们会催生它们所防范的冲突文件)
  5. 构建 / 依赖 — node_modules、dist、build、.next、.turbo、.nuxt、.cache、.parcel-cache、coverage、.nyc_output、target
  6. Python 环境 / 缓存 — .venv、venv、__pycache__、*.pyc、.pytest_cache、.mypy_cache、.ruff_cache
  7. Swift 构建产物 — .build、DerivedData、*.xcuserstate
  8. 编译后的二进制文件 — *.so、*.dylib、*.dll、*.exe、*.o、*.a
  9. 数据库 / 状态文件 — *.db、*.sqlite、*.sqlite3、*.duckdb、*.db-journal、*.db-shm、*.db-wal

外加密钥/临时/操作系统垃圾文件:*.tmp、*.log、.env*、.DS_Store、Thumbs.db、.Spotlight-V100、.Trashes、.fseventsd。

模式语法速查表

Syncthing(.stignore):node_modules 在任意深度匹配,/Projects/*/code 为路径锚定,(?d)pattern 删除已同步的文件,(?i) 不区分大小写,!important.log 取反。

rclone:尾部 / 仅匹配文件夹,** 跨文件夹递归,/path/to/exclude/** 为路径锚定。

rsync:不区分文件/目录,/relative/path 锚定在起始目录,**/*.tmp 用于递归通配。

Git 管理仓库的工作流(当文件同步被排除时)

  1. Cron git pull 脚本 — 推荐模式是 workspace-pull.sh:获取上游,若本地==远程则跳过,若分支 ≠ main/master 则跳过,暂存本地编辑,仅快进拉取并以合并回退,然后以 CLI Claude 冲突解决器回退,若未解决则通过运维通知器告警,弹出暂存。
  2. CI/CD 自托管运行器 — 第二个节点上的 GitHub Actions 运行器在推送到 main 时拉取(事件驱动,无轮询)。
  3. 手动 — 操作员按需运行 git pull。适用于很少更新的仓库。

合规检查

  • 已对每个问题类别完成预检清单
  • 发现的每个类别都存在于忽略模式中
  • 每个嵌套的 .git/ 要么被完全排除,要么记录为只读镜像
  • 若跨操作系统同步,则排除跨平台二进制类别(.venv、target、*.so/*.dylib/*.dll)
  • 数据库文件(*.db、*.sqlite)作为主机本地状态排除
  • 已应用锁定(globalAnnounce=false,无公共发现,传输限制在私有网络如 Tailscale)
  • 已保留变更前配置的备份(config.xml.pre-{TASK-ID})
  • 已记录运行手册(拓扑、运维、回滚)
  • 已执行双向冒烟测试