JuiceFS sync 是一款强大的数据同步工具，支持在对象存储、JuiceFS、本地文件系统之间进行数据同步。sync 能将大规模全量迁移的效率提升到接近链路带宽上限，使 PB 级数据迁移通常具备"按天/周"量级的可行性（具体时长取决于带宽与云端限速）除此之外，还支持通过 SSH 访问远程目录、HDFS、WebDAV 等，同时提供增量同步、模式匹配（类似 rsync）、分布式同步等高级功能。
本文将围绕 sync 的核心执行原理展开，介绍其在单机与集群模式下的架构与任务调度机制，并详细说明如何通过并发优化提升性能。同时，还将介绍 sync 提供的多维过滤能力、灵活的路径模式匹配方式，以及数据一致性校验机制，帮助用户更好地理解并使用这一工具进行高效、可靠的数据同步。
01 核心原理
sync 在单机模式与集群模式下的核心执行原理是一致的，主要区别体现在部署方式与任务分发通道上。因此，本节以单机模式为例进行原理讲解，集群模式的差异将在后文单独说明。
如下图所示，sync 的整体架构可抽象为典型的 Producer--Consumer（生产者--消费者）模型：
- Producer 负责遍历源端和目标端对象存储中的全部 key，并对两端的有序结果进行归并（merge），据此判断对象是否需要同步、删除或校验，并将生成的任务写入任务队列；
- Consumer 则从队列中不断取出任务，完成实际操作。
在单机模式下，Producer 和 Consumer 运行在同一进程内，通过 goroutine（轻量级协程）并发协作。
在 Producer 阶段，之所以需要同时遍历目标端，是因为 sync 不仅要同步源端数据，还支持按配置删除目标端多余对象，并结合对象在目标端的存在与差异状态，为每个 key 决定生成何种任务。目前支持五类任务：同步、删除源端、删除目标端、拷贝权限、校验。
接下来进一步展开 Producer 阶段任务生成的具体机制。
为了提升任务生成效率，sync 要求对象存储的遍历（list）接口返回结果必须是有序的，即按 key 递增（例如按字典序）排列。依赖这种有序性，Producer 可以同时对源端和目标端对象存储进行线性扫描，并逐一比较当前 key 的值，以判定是否需要生成同步任务。
以图中展示的归并过程为例，sync 同步遍历源端与目标端，分别读取当前位置的 key，例如源端为 file1，目标端为 file2：
- 若 src key < dst key（例如：file1 < file2）需生成一个同步任务；随后源端指针前移，继续与目标端当前 key 比较；
- 若两端当前 key 相同（例如：均为 file2），说明该对象在两端均存在，可根据策略判断是否跳过或执行进一步校验；此时两个指针同时前移；
- 若 src key > dst key（例如：file4 > file3)，说明目标端存在多余对象，可能需生成删除任务；随后目标端指针前移。
这种比较逻辑会持续进行，直到源端和目标端的所有 key 都被遍历完毕，从而构建出完整的任务队列。该策略的最大优势在于仅需线性扫描次数就能判断所有对象的状态，并快速生成任务。
02 性能优化
在理解了 Producer/Consumer 的职责之后，我们再看性能瓶颈主要出现在哪些环节以及如何优化。
producer 侧优化
在 Producer 执行过程中，对象存储的 list 操作可能成为性能瓶颈。大多数对象存储的 list 接口不支持通过 Range 来指定返回某个"区间"的结果，无法像分段下载那样将同一目录的 list 操作拆分为多个区间并行执行。因此，sync 的优化思路是：在单个目录内顺序执行 list，但在多个目录之间并发执行 list，并将各目录的结果汇总成完整的 key 集合。
从遍历方式上看，整个过程可以理解为：第一步在目录树上进行一次限定深度的"广度优先遍历"，找到所有的子目录，实现目录层级拆分；第二步针对每个子目录进行全量遍历，列出该前缀下的所有对象，这一步要求 list 对象是有序的。
Consumer 侧优化
整个传输过程可以看作一条端到端的流水线：consumer 从源端读取数据，直接写入目标端，中间不经过本地磁盘。因此，源端读取或目标端写入的任何一侧速度瓶颈，都可能成为同步流程的瓶颈。
在上传过程中，sync 支持多任务并发执行，由多个 goroutine 分担不同的同步任务。从任务层面看，系统具备一定的并行传输能力，优化重点在于提升大文件的读写并发能力。
因此，sync 利用对象存储的 Multipart Upload 能力，将一个大文件拆为多个分块，由多个 goroutine 并行上传，最后再通过合并接口完成拼接。
对于超大文件，我们可以进一步对分块进行拆分：先上传若干中间对象，再利用 UploadPartCopy 接口，在对象存储端对这些中间对象进行二次分块与合并。这样对同一文件执行"两级分块 + 两次合并"，能显著提高超大文件传输的并发度和效率。
与写入路径相比，读侧的并发逻辑相对简单：首先将对象按块切分，随后并发地读取每个块。这些并发读取的块构成一个"预读窗口"，即在当前读取位置（offset）之前，尽量提前下载并缓存部分后续数据。通过预读机制，可以减少源端读取性能不足或网络抖动时的等待时间，避免读端成为传输链路的性能瓶颈。
03 集群模式
在数据规模更大、单机吞吐不足时，sync 还支持集群模式，通过将 Worker 横向扩展到多台机器上并行执行任务，以进一步提升整体同步效率。
需要强调的是，集群模式并没有引入新的同步算法，相对单机模式的变化主要体现在物理部署方式和任务分发通道的差异。
物理部署差异
在单机模式中，Producer 和 Consumer 运行在同一进程内，通过不同的 goroutine 协同工作；而在集群模式下，consumer 可独立部署到多台机器上作为 worker 节点，而 producer 作为 manager 节点从而实现横向扩展。
启用集群模式前，需要配置 manager 与各 worker 节点之间的 SSH 免密登录。启动集群模式后，manager 会将 juicefs 二进制分发到各 worker 节点的 /tmp 目录，并通过 SSH 在远程启动 worker 进程，加入同步任务。
任务分发机制差异
在单机模式中，producer 和 consumer 通过 Go 的 chan 在进程内传递任务；而在集群模式中，任务分发改为基于 HTTP 的方式------manager 提供任务分配 API，各 worker 通过轮询定期从 manager 拉取任务并执行。除了通信方式外，其余流程与单机模式一致。
04 任务过滤
在实际同步场景中，用户通常只希望对符合特定条件的对象执行同步或清理操作。Sync 支持在任务生成阶段从多个维度对对象进行筛选，并根据筛选结果决定是否生成任务及其类型。总体而言，过滤与调整主要包括以下几类：
- 基于时间：依据文件的 mtime 对 key 进行过滤；
- 基于大小：依据文件的 size 对 key 进行过滤；
- 基于 Key：通过路径/名称的模式匹配规则对 key 进行过滤；
- 基于结果：结合 key 在目标端的存在状态或差异情况进行过滤或任务类型调整。
其中，基于 Key 的过滤最常用也最灵活，Sync 通过 --exclude 和 --include 参数进行路径的模式匹配。以精确控制同步范围。
目前支持两种匹配模式：逐层过滤模式和完整路径过滤模式。逐层过滤兼容 rsync 的规则，但使用相对复杂，若有需要可以点击此处进一步了解。下文将重点介绍更直观易用的完整路径过滤模式。
自 v1.2.0 起，sync 命令新增 --match-full-path 选项，用于启用完整路径过滤模式。在该模式下，Sync 会将待匹配对象的完整路径依次与配置的多条规则进行匹配；一旦某条规则命中，即立即确定该对象的处理结果（同步或排除），后续规则不再参与匹配。
例如有一个路径为 a1/b1/c1.txt 的文件，以及 3 个匹配模式 --include 'a*.txt' --include 'c1.txt' --exclude 'c*.txt'。在完整路径过滤模式下，会直接将 a1/b1/c1.txt 这个字符串与匹配模式依次进行匹配。具体步骤为：
- 尝试将
a1/b1/c1.txt与--include 'a*.txt'匹配，结果是不匹配。因为 * 不能匹配 / 字符，参见「匹配规则」； - 尝试将
a1/b1/c1.txt与--inlude 'c1.txt'匹配，此时根据匹配规则将会匹配成功。后续的--exclude 'c*.txt'虽然根据匹配规则也能匹配上，但是根据完整路径过滤模式的逻辑，一旦匹配上某个模式，后续的模式将不再尝试匹配。所以最终的匹配结果是「同步」。
以下是更多示例：
--exclude '/foo**'将排除所有根目录名为foo的文件或目录；--exclude '**foo/**'将排除所有以foo结尾的目录；--include '*/' --include '*.c' --exclude '*'将只包含所有目录和后缀名为.c的文件，除此之外的所有文件和目录都会被排除；--include 'foo/bar.c' --exclude '*'将只包含foo目录和foo/bar.c文件。
05 数据完整性校验
在高并发传输之外，数据同步的关键是结果必须正确。为降低网络抖动、同步期间的并发写入，以及不同存储后端一致性语义差异所带来的风险，juicefs sync 提供了多级数据完整性校验机制，使用户能够根据业务需求在可靠性与资源开销之间进行权衡。
具体而言，Sync 在执行同步任务时支持不同强度的校验等级：校验越严格，对源端与目标端数据一致性的保障越强，但会引入更高的读放大和 CPU 消耗；校验越宽松，对性能影响越小，但对潜在不一致的容忍度也相应提高。用户可结合数据重要性与性能成本，选择适合的校验参数。
以校验强度最高的 check-all 为例，其流程可概括为以下三步：
- 传输前比对：在判定对象是否需要同步时，Sync 会读取源端与目标端的数据内容进行比较；若两端内容不一致，则生成并执行同步任务。
- 在极端场景中，可能需要读到最后一个字节才能确认不一致。此时，源端与目标端在传输前各发生一次全量读取，带来约 1 倍的额外读流量。
- 传输过程校验：执行同步时，源端数据会被再次完整读取并写入目标端，形成源端约 1 倍读流量与目标端约 1 倍写流量；同时，Sync 会在读取源端数据的过程中计算 checksum，并在读完后得到该对象的校验值。
- 传输后复核：为验证网络传输与目标端写入的正确性，Sync 会再读取一次目标端对象并计算 checksum，与传输过程中得到的 checksum 做对比；若不一致，则认为发生数据错误并报错。
check-new 可以视为 check-all 的子集：仅对新增或需要传输的对象执行上述内容校验，从而在较高可靠性与较低开销之间取得平衡。
check-change 则采用更弱的校验思路：不直接比对内容，而是通过 mtime 与 size 等元数据推断对象是否发生变化。由于该策略不验证真实内容，存在元数据未变但内容不一致的可能性，因此校验强度最低，但性能开销也最小。
本文系统介绍了 JuiceFS sync 的架构设计、性能优化、集群模式以及任务过滤机制，旨在帮助用户更深入理解其实现原理与使用方式。我们也将持续优化和演进 sync，欢迎大家提出反馈建议，或投稿分享实战经验。
我们希望本文中的一些实践经验，能为正在面临类似问题的开发者提供参考，如果有其他疑问欢迎加入 JuiceFS 社区与大家共同交流。