甘剑平1. 三台机器的混乱日常：这个同步方案到底在解决什么问题
先说一个我自己的真实场景：办公室一台台式机，家里一台主力开发机，出差还带着一台轻便笔记本。以前没做跨机同步的时候，项目代码基本靠U盘拷贝加聊天软件文件传输顶着，经常出现一种很魔幻的状态——周一到周三改的代码在办公室电脑上，周四在家继续写只能凭记忆把改动重新敲一遍，出差的时候干脆就是看别人的旧代码。更麻烦的是，同一份项目在每台机器上都有自己的配置、缓存和临时文件，时间一长，三台机器上的"同一项目"已经悄悄变成了三个不兼容的分支。
这次要聊的"整体设计定稿之35项目跨机同步方案之2"，就是专门解决这个问题的方案设计文档。文档编号20260207，定稿时间在二月初。方案1踩了不少坑，这次是彻底复盘之后的修订版。整个方案的核心思路是用 codebuddy 作为项目开发主工具，把多台机器的项目文件、配置、AI助手的工作状态统一到一个可同步的架构里，真正做到"在哪台机器上打开都是同一个项目"。
1.1 同一天出现三个版本的代码
我统计过自己一周的工作流变化：早上在办公室台式机写核心模块，下午带着笔记本去会议室联调，晚上回家在主力机上想继续改同一个接口。如果没有同步机制，每一次换机器都是一次手工合并，这个合并的代价根本不是几分钟，而是"忘改一个地方"带来的连锁问题。
有一次我印象特别深，在笔记本上修了一个接口的返回字段，忘记同步到台式机。第二天在台式机上跑测试，怎么跑怎么不对。排查了半天，最后发现是两台机器的代码根本不一样，联调阶段暴露出来的问题其实在昨天就已经修掉了——代码却停在旧版本上。这种情况只要出现过两次，你就一定会认真考虑跨机同步这件事。
跨机同步要解决的痛点，首先不是"如何把文件复制过去"，而是"如何保证多台机器之间的工作状态一致"。所谓工作状态，包括代码文件本身，也包括依赖配置、环境变量、本地构建产物，还有开发工具的运行记忆。
1.2 不只是代码：环境配置和AI助手的记忆也要跟得上
很多人第一反应是"代码同步用Git不就完了"。Git确实解决了版本管理的问题，但跨机同步比这要复杂得多。项目里有一堆不该进仓库的东西，却必须在多台机器之间保持一致，比如：
- 本地配置文件，像
.env、.codebuddy这类工具的私有配置，里面有不同机器的差异化信息，又不能随便丢。 - AI编程助手的会话上下文、索引缓存、用户自定义指令，这些数据在换机器之后如果丢了，等于让AI助手失忆。
- 构建工具产生的本地依赖目录，比如
node_modules、vendor，虽然可以重新安装，但在没有网络或者网络很慢的环境下重新拉取一遍代价很大。 - 数据库的本地副本、缓存目录、甚至IDE的窗口布局和工作区列表。
这些内容单独看都不大，但它们共同构成了"我在这台机器上正常工作"的环境。跨机同步方案要做的，就是把这些状态按优先级和敏感度分级，用不同的同步策略去处理，而不是简单地用网盘同步整个文件夹。
1.3 方案1失败之后，方案2的基本盘
方案1当初的想法很天真：直接用一个同步工具把整个项目目录做双向实时同步，碰到冲突靠"后来者覆盖"。结果实战中问题一堆，最典型的是构建工具在后台写文件时触发了同步风暴，还有两台机器同时改同一个文件导致版本互相覆盖。
方案2从根上换了一套思路：先明确数据分区的边界，再决定每一类数据用什么方式同步，最后才谈工具选型。 不是"我要同步"，而是"什么东西值得同步、什么东西不需要同步、什么东西必须串行修改"。这套思路确立之后，后面的技术选型和工作流设计都变得清爽很多。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 选型复盘：为什么最终是"Git主干+增量镜像"的组合架构
跨机同步方案的选型，市面上常见的选择其实就那么几类：网盘同步、自建NAS、版本库拉取、增量文件镜像。每一类我都实际用过一段时间，各有各的问题。
2.1 常见同步工具的硬伤
先说网盘同步。网盘类工具的优势是傻瓜化、无感，但在项目场景下有几个致命伤。第一，实时扫描文件变化会带来明显的CPU和磁盘占用，项目一大，目录里文件成千上万，每次文件变动都要触发扫描和上传，整个机器都会变卡。第二，网盘的同步粒度是"文件级"，但对项目内大量临时文件毫无辨别能力，很容易把 node_modules、cache 这堆垃圾也传到云端，浪费空间不说，还让文件变更极其频繁。第三，它没有真正的冲突处理机制，同一文件在两台机器同时被修改时，经常是生成一个"某某的冲突副本"，这种副本多了之后项目目录就一团糟。
再说自建NAS。NAS做个人文件备份确实稳，但对于项目同步，它的延迟和同步双向性不够灵活。NAS适合"集中存储"，不适合"多机协作"。特别是网络不稳定的时候，NAS的同步任务挂着不动，也不告诉你为什么不动。
Git仓库本身是跨机代码同步的基础，但它只管"提交过的代码"，没法管本地的工作状态。如果你每天多次在机器之间切换，每次都要求提交推到远端、到另一台机器再拉取，手动操作成本太高，而且 .codebuddy 这类本地配置目录通常被 .gitignore 排除了，根本不会跟着仓库走。
增量镜像工具是我最后选定的底层方案。这类工具做的是"目录状态的一致性镜像"，只同步变化的文件块，支持断点续传，也可以对传输过程做校验。配合Git主干，代码走版本库、工作状态走镜像，两边互补。
2.2 codebuddy在同步链路中的实际角色
codebuddy 在方案里不是同步工具，它是项目开发的主入口，也就是"每次打开项目都会启动的工具"。正因为如此，它的配置目录和运行状态必须被纳入同步范围。
codebuddy 的本地目录里一般包含几个东西：用户自定义的规则文件、模型的上下文索引、最近打开的项目列表、某些会话记录。这些内容如果不跨机同步，就会出现一个很出戏的现象：在办公室机器上AI助手非常了解这个项目，换到笔记本上它就像个新来的同事，什么都需要重新解释。这个问题靠记忆去填充太累了，直接把它的工作目录纳入镜像同步是最省事的。
在同步架构图里，codebuddy 扮演"客户端"的角色，它不是同步的中枢，而是整个工作流里最需要数据保真的一个消费者。方案2刻意没有让codebuddy直接参与文件收发，而是让它把数据落在标准目录里，由同步镜像统一处理，这样职责单一，出问题也好排查。
2.3 三层同步模型和目录分区
方案2的核心架构可以概括成三层同步模型：
- 第一层：Git主干，负责源代码的版本管理。所有被跟踪的代码文件，以Git仓库为唯一的版本真相。
- 第二层：增量镜像，负责项目目录里非代码类状态的同步。包括配置文件、本地依赖的元信息、工具状态目录。
- 第三层：按需拉取，负责处理那些不需要实时同步的大块数据，比如容器镜像缓存、模型文件、历史构建产物，需要在特定机器上使用时再按需拉取。
这三层模型的好处是：职责清晰，互不干扰。Git管"代码演进"，镜像管"工作现场"，按需管"大体积数据"。每一层的失败影响面都是局部的，不会互相拖累。
这三个分区在目录里怎么落地，我放在下一节详细说。
3. 同步规则设计：35号文档里最重要的目录约定
跨机同步方案最怕的是"什么都同步"。方案2在设计之初就做了目录分区，把项目根目录下的内容分成三个区：强制同步区、条件同步区、禁止同步区。这个分区不是写在文档里的概念，而是体现在具体的同步规则文件里。
3.1 强制同步区、条件同步区、禁止同步区
强制同步区，指的是"不同步就一定会出事故"的目录，主要就是开发工具的配置目录。以codebuddy为例，它的配置目录、项目级规则文件、索引文件，被明确划入强制同步区。这部分数据要的是"实时性"，任何一台机器上的修改都要快速传播到其他机器，所以在同步规则里被标记为优先级最高。
条件同步区，指的是"可以同步，但要有条件地同步"的目录，例如本地依赖目录、缓存目录。node_modules 这种目录体积大、文件数量多，直接全量同步会把网络和磁盘都压垮。方案2的做法是：不以实时镜像为条件，而是以"是否在目标机器上可用"为条件。当目标机器需要运行项目而本地依赖不存在或版本不匹配时，才触发一次同步或重装。依赖目录本身在同步规则里被排除，但依赖清单文件如 package-lock.json、pnpm-lock.yaml 是强制同步的，因为它们代表了"依赖的真相"。
禁止同步区，包括日志目录、临时文件夹、构建输出目录。这些目录内容变动极其频繁，同步它们只有坏处没有好处。在规则里直接忽略掉，能大幅降低同步引擎的无效工作。
3.2 ignore规则是怎么一条条磨出来的
真实项目的目录结构远比预想的复杂，ignore规则的制定需要实际跑几轮才能磨出来。我给的示例是这样的：
gitignore复制# 依赖与构建产物
node_modules/
vendor/
dist/
build/
target/
# 临时文件与系统文件
.DS_Store
Thumbs.db
*.tmp
*.swp
.cache/
# 日志与运行时数据
logs/
*.log
/run/
# 本地环境差异化配置
.env.local
*.local.config
# 工具私有缓存（不跨机共享的部分）
.idea/workspace.xml
.vscode/.untracked/
这里有一个经验之谈：规则宁可先宽松再收紧，不要一开始就追求绝对精确。 宽松的规则副作用是浪费一点带宽和存储，但收紧过头就会漏掉关键文件，导致某台机器的工作状态不一致。刚开始跑的时候，我会开着同步日志观察一周，看看哪些文件经常被同步但确实没必要，再逐步调整。ignore规则是越磨越准的，没有一蹴而就的完美方案。
3.3 冲突处理的三个档次
多机同步一定会出现冲突，问题是冲突发生后怎么处理。方案2把冲突处理分成三个档次：
第一档，自动合并。适用于文本类配置文件，比如 .env.example、项目说明文档。这类文件如果两边都有修改，同步工具会尝试做一个文本级别的合并，能自动合并就合并，不能合并就进入第二档。
第二档，版本保留。适用于真正不可无损合并的文件，比如数据库的本地快照、证书文件、序列化状态文件。这类文件一旦冲突，自动合并是绝对错误的做法。同步工具会把两个人的版本都保留下来，一个命名为 filename.conflict.办公室，另一个命名为 filename.conflict.笔记本，由我手动决定保留哪个。
第三档，锁定的串行修改。适用于那些"必须单机修改"的文件，例如codebuddy的索引数据库。它的设计是这样的：某台机器在修改这类文件之前，先向同步系统申请一个"写锁"，拿到锁之后其他机器只读不能写，修改完成释放锁再做增量同步。
这一套配置看起来复杂，实际上配置一次就能长期生效。我最大的体会是：冲突处理必须分级，自动化不能包打一切，过度自动化在关键数据上的风险比手动处理大得多。
4. 冷启动流程：从零到多机一致需要几步
方案设计归设计，真正考验它的是冷启动——一台新机器加入同步体系，从零开始把整个项目状态拉起来，需要几步、耗时多久、会不会出错。这一节我把方案2设计好的冷启动流程完整展开，这也是我实际跑通后觉得最值得分享的部分。
4.1 初始化与基线版本建立
冷启动的第一步不是同步文件，而是建立"基线"。所谓基线，就是一个确认过的、干净的、所有机器都认可的初始状态。
机器A（主力开发机）作为初始节点，需要做三件事。
第一，整理工作区目录，依据上一节的三个分区约定，把该忽略的内容排除掉。第二，用同步工具做一次"导出"，生成一个快照清单。这个清单会记录当前项目目录下每一个同步文件的大小、路径、校验值。第三，把这份快照清单保存到Git仓库里，作为项目的元数据文件之一。
新机器B加入时，流程相反：先克隆Git仓库，拿到源代码和快照清单，然后用同步工具根据快照清单从机器A拉取所有非Git管理的工作状态文件。整个过程分阶段执行，不是一股脑全拉下来。
4.2 分片传输与校验
跨机同步的传输环节，方案2没有用"一次性完整文件复制"的方式，而是用一个我踩过坑才总结出来的策略：把文件按固定大小分片，以分片为单位传输和校验。
举个例子，一个300MB的数据库快照文件，如果整体复制，中间断一次网就得重来。分片之后，每个分片独立传输、独立校验，已经传完的分片不会被后续失败影响，重连后只需要续传剩余分片。这个思路和下载工具的分片下载类似，但在目录同步里同样适用。
分片大小我建议根据网络环境调整。局域网场景可以用4MB到8MB的分片，公网场景建议调到1MB到2MB。分片太小会有严重的元数据开销，分片太大则失去断点续传的意义。校验算法用SHA-256就足够了，不需要追求更强。
每台机器的同步目录里会保存一个"传输状态文件"，记录每个分片的接收情况。传输中断后再次同步，先检查状态文件，跳过已经成功的分片，只处理未完成的部分。
4.3 恢复演练：拔网线、断电、误删
冷启动流程完整跑通之后，我强烈建议做一次恢复演练。方案2里专门加了一个章节，要求在正式启用前模拟三种故障场景：
第一种，拔网线。同步进行到一半，直接把网络断开，然后重新连接。观察同步能否在短时间内恢复，已经传完的数据会不会丢失。
第二种，断电。在A机器同步读取数据的时候直接关机，回到B机器检查传输状态文件的恢复情况。
第三种，误删。在一台机器上删除了项目目录里的一个非Git文件，同步之后检查其他机器上的版本是否恢复了正确的逻辑。
这个演练跑下来，最大的收获不是验证工具多么稳定，而是认识到"恢复策略"本身就是同步方案的一部分。没有演练之前，我以为同步做得好就行；演练之后我才意识到，同步工具的能力边界就在那里，重要的是在边界之外设计好兜底手段。
恢复演练结束之后，整个冷启动流程才算真正验收通过。新机器不再是"接入即碰运气"，而是有了一套可以复现、可以度量的标准化流程。
5. 踩坑记录：方案1留给我的五条教训
方案1不是没有跑通过，而是跑通之后暴露了太多问题。这些问题在方案2的设计里几乎全被重做了一遍。我觉得把这些坑原原本本记录下来，比介绍方案本身更有价值，至少能让你少走一两个月的弯路。
5.1 符号链接和文件权限在跨机传输中的丢失
方案1第一次同步完成之后，我发现一个诡异的问题：项目正常启动，但运行到某个环节时总是报"找不到文件"。后来排查发现，项目里有个目录其实是指向另一个目录的符号链接，方案1的同步工具在传输过程中把符号链接当成普通文件复制了，链接关系彻底丢失。
这个问题在Windows和macOS混用的环境里尤其突出。Windows的目录链接、macOS的符号链接、Linux的软链，三者的语义完全不同，跨机同步时务必要确认同步工具支持"链接语义"的保留。方案2在选型时把这个作为硬性要求，并且在同步完成后会做一次链接完整性检查。
5.2 大小写不敏感的目录导致"幽灵冲突"
Mac和Windows默认文件系统大小写不敏感，但Linux大小写敏感。这导致一个尴尬的局面：在Mac上创建的文件是 Config.json，在Linux机器上同步时变成了 config.json，而Linux机器本来还有一个 config.json。两个文件同时存在，看起来就像是冲突产生了两个版本，实际是文件系统对待大小写的规则不一致。
这个坑特别隐蔽，因为不触发场景几乎感觉不到。方案2的做法是：在同步配置里强制约定所有文件名一律使用小写，并且在一台机器上做统一重命名，再重新同步。这是唯一可靠的解法，靠工具自动处理大小写差异永远有边界情况。
5.3 IDE临时文件污染基线
方案1当时的同步范围是"整个项目目录"，结果IDE在项目里产生的临时文件、编辑器锁文件全部进入同步链路。最典型的是 .idea/workspace.xml 这类文件，每打开一次项目就变一次，两个机器同时打开时频繁互相覆盖，完全是无意义的同步开销。
这类文件的共同特征是：没有版本价值、变化频率高、只跟本机工作状态相关。方案2把它们整体归入禁止同步区。判断标准很简单：如果这个文件删掉之后不影响项目代码和工具配置，那它就不该被同步。
5.4 大文件不分片直接卡死
方案1第一次同步时，项目里有个接近2GB的本地数据库快照。当时用的同步工具是整文件复制策略，同步开始后不久网络波动，传输直接卡死，系统里的同步任务队列被堵住，其他文件全部排队等待。最后只能强制结束任务，清掉重来。
这个坑让我认识到：跨机同步不仅仅要解决"文件对不对"，还要解决"网络波动时能不能继续"。大文件分片之后，即使分片传输失败，重试的代价也很小；整文件复制失败，代价则是整个文件重新来过。
5.5 同步确认机制缺失
方案1采用的是"一边监听文件变化一边同步"的实时模式，导致一个致命问题：某台机器上的文件被修改后，同步工具立刻把修改推送到其他机器，但推送本身没有确认机制。如果推送的是半截文件（比如还在写入中的日志），到另一台机器就成了损坏文件。
方案2引入了一个"静默期"概念：文件变更触发同步前，要求文件内容在30秒内保持稳定，才认为写入完成。这个机制大大减少了"半截文件"同步造成的损坏问题。代价是文件变更的同步时延增加了30秒，但对于非实时协作场景完全可接受。
这五条教训，每一条都是真金白银换来的。方案2的目录分区、分片传输、静默期机制，本质上都是针对这些教训的针对性设计。
6. 落地效果与后续演进：多机协作的节奏感
方案2从定稿到跑稳定，我大概用了两周时间。第一周做冷启动和基础同步，第二周在日常开发里实际使用，一边用一边微调同步规则。目前的状态是：办公室台式机、家用主力机、出差笔记本三台机器完全打通，每天切换机器的成本几乎为零。
6.1 日常使用中的同步节奏
实际使用下来，最直观的体验是"不用再想同步这件事"。到办公室打开电脑，项目就是昨天的状态；回家打开笔记本，下午在办公室改的代码和codebuddy的上下文都已经就位。
一个重要的节奏设置是：实时同步保持开启，但只对强制同步区生效。条件同步区里的依赖目录采用"按需拉取"模式，程序检测到本地缺少依赖时才会请求同步，而不是天天在后台做全量比对。这个设计让同步引擎的CPU占用常年保持在1%以下。
6.2 后续演进的几个方向
这个方案跑通之后，我还在思考几个扩展方向。第一个方向是多分支工作区，就是同一项目的不同特性分支分别在多台机器上开发，同步系统能识别当前分支并决定哪些文件属于当前工作区的活跃状态。第二个方向是引入更细粒度的权限控制，给团队其他成员开放同步入口时，可以限制他们访问某些敏感目录。第三个方向是自动化健康检查，每周自动跑一次全量校验，对比所有同步文件的校验值，提前发现文件损坏的风险。
这些方向目前还在规划中，但底层的目录分区和三层同步模型已经为它们留好了扩展空间。
最后分享一个我个人的小习惯：每周末花五分钟看一次同步日志，重点关注那些被反复同步的文件。这个习惯帮我发现了不少ignore规则漏掉的"问题文件"，也让整个同步方案始终处于良性运行状态。跨机同步不是配好就一劳永逸的事情，它需要随着项目结构的变化持续调整，把它当成一个需要维护的系统来对待，比指望一次配置永久稳定要现实得多。