合并文件
juicefs merge 在元数据层把多个文件拼接成一个文件。它按顺序把源文件的 chunk 引用追加到目标文件,因此源文件和目标文件共享同一批 chunk 对象。命令本身不读取、也不复制对象存储数据,并且不会删除源文件。
# 将两个文件合并为新文件
juicefs merge --output /mnt/jfs/merged /mnt/jfs/foo /mnt/jfs/bar
# 从文件读取源路径,每行一个
juicefs merge --output /mnt/jfs/merged --files-from list.txt
--files-from 需要 JuiceFS 5.4.1 及以上版本。
私有部署 跨分区合并仅适用于采用多分区元数据服务的私有部署。JuiceFS 云服务默认使用单分区元数据服务,因此云服务中的 merge 只会走下文所述的同一分区路径。
所有源文件和目标文件必须位于同一个 JuiceFS 文件系统内。目标文件不存在时会自动创建;如果已存在,需要指定 --overwrite 或 --append,否则命令会失败。
该操作不是原子的,且 --overwrite 会在合并开始前删除目标文件;详见注意事项。
工作原理
merge 按给定顺序遍历源文件,把它们的 chunk 引用追加到目标文件。源文件不会被修改或删除。合并后删除源文件只会减少引用;底层对象要等所有引用释放,并经过正常的回收站和垃圾回收流程后才会被清理。
由于合并后的文件引用原始 chunk,它的逻辑大小是源文件大小之和,但对象存储用量不会等量增加。合并后的逻辑大小仍会计入 df、du 和目录配额。
从对象存储导入的文件(包括按需导入)使用兼容格式,不能作为 merge 的源或目标。导入文件也没有可供 merge 拼接的 chunk 表。
什么时候会写入新对象
大多数情况下,merge 只修改元数据。以下两条路径会写入新对象:
| 场景 | 是否写入新对象 | 说明 |
|---|---|---|
| 同一分区,或单分区文件系统 | 否 | 只更新元数据;如果合并产生 slice,后续可能触发碎片合并。 |
| 跨分区,源文件元数据可以直接迁移 | 否 | 只迁移元数据,不复制对象数据。 |
| 跨分区,源文件元数据过大 | 可能写入,发生在 merge 返回前 | 客户端可能先对源文件做碎片合并,再重试迁移;仍无法迁移时 merge 失败。 |
| chunk 边界不对齐,后台碎片合并执行 | 是,异步 | 受影响的目标 chunk 会被重写。 |
| 合并后继续写或截断目标文件 | 是 | 属于写时复制,与 merge 本身无关。 |
跨分区元数据迁移
在多分区部署中,文件的元数据 属于某个分区。当源文件和目标文件位于不同分区时,merge 需要先把源文件的元数据迁移到目标文件所在的分区,然后才能追加 chunk 引用。
对于普通源文件,这一步只迁移元数据,不复制对象数据。如果源文件的元数据过大(例如文件很大,或历史 slice 很多),客户端可能会先对源文件做碎片合并,再重试迁移:读取相关 slice,把包含多个 slice 的 chunk 重写为新的 chunk 对象。这次碎片合并发生在 merge 返回前,会占用对象存储的读写带宽。
当源文件需要跨分区迁移时,默认限制约为每个文件 750GiB(按 64MiB chunk 计算)。超过这个上限时,merge 会直接失败,不会先做碎片合并。同一分区的合并不受此限制,实际部署也可能调整该上限。
如果碎片合并后仍然无法迁移,merge 会失败。碎片合并过程中写入的新对象不会自动回滚,而是按正常的引用计数和垃圾回收流程释放。
chunk 边界不对齐
JuiceFS 文件按 64MiB 逻辑 chunk 划分,对象存储中的 block 默认按 4MiB 组织。当目标文件长度不是 64MiB 的整数倍时,下一个源文件会从目标 chunk 的中间位置开始,它的 chunk 边界与目标 chunk 边界产生偏移。
例如,文件 A 为 10MiB,文件 B 为 130MiB,B 从合并后文件的偏移 10MiB 处开始。前三个目标 chunk 分别为 64MiB、64MiB 和 12MiB。此时每个目标 chunk 都包含两个相邻源 chunk 的数据,因此合并后的文件在每个 chunk 中都有多个 slice。
元数据服务会为受影响的 chunk 调度后台碎片合并。碎片合并读取每个目标 chunk 的多个 slice,写出一个新的 chunk 对象,并更新元数据引用。这就是为什么 merge 本身没有复制数据,但对象存储之后仍可能出现写入。
碎片合并按整个目标 chunk 处理,而不是按单个 4MiB block 处理。即使目标 chunk 内的所有 slice 都按 4MiB 对齐,碎片合并仍会把整个目标 chunk 重写为新的 chunk 对象。只有目标 chunk 能直接引用一个完整的源 chunk 时,才不会因为这次合并产生新对象。
如果文件 A 的长度正好是 64MiB 的整数倍,B 会从 chunk 边界开始,这次拼接不会产生边界 slice。但如果 B 本身已经包含多个 slice,后台碎片合并仍可能处理这些 chunk。
容量、配额和性能
merge刚完成时: 对象存储容量基本不变,只有元数据变化;合并操作本身很轻。- 碎片合并执行时: 受影响的 chunk 会被重写为新对象,旧对象在引用释放前仍然保留。如果源文件没有立即删除,受影响范围可能临时接近逻辑数据的两倍。
- 删除源文件后: 旧对象会按引用情况回收,最终容量回到逻辑数据量;
merge不会永久多占一份数据。 - 配额和文件系统用量: 合并后的文件按完整逻辑大小计入
df、du和目录配额。 - 性能: 后台碎片合并是异步的,不阻塞
merge返回;跨分区的源 文件碎片合并发生在merge返回前,会同步占用一部分读写带宽。
注意事项
merge不是原子操作。 源文件会分批提交;如果后续批次失败,前面的批次已经生效,目标文件可能处于部分合并状态。--overwrite会在合并开始前删除目标文件。 如果合并失败,原文件无法恢复。建议先合并到新路径,确认结果后再替换原文件。- 所有源文件和目标文件必须位于同一个 JuiceFS 文件系统内。 不要使用其他文件系统中的路径。
- 目标文件已存在时,必须指定
--overwrite或--append。 否则命令会在合并前失败。
实践建议
- 如果
merge后对象存储没有变化,说明走的是正常的元数据拼接路径。 - 如果
merge后看到对象存储写入,优先判断是否为后台碎片合并;它可能延迟触发,不一定是merge在同步复制数据。 - 对容量敏感的场景,建议先合并到新路径,确认结果后尽快删除源文件。
merge本身共享对象数据,对象存储用量不会翻倍;在删除源文件前,只有逻辑大小和配额会被重复计算。 - 不要对唯一一份数据使用
--overwrite:目标文件会在合并开始前被删除,而且merge不是原子操作,合并失败可能导致原文件丢失。 - 为减少边界 slice,除最后一个源文件外,尽量让每个源文件大小为 64MiB 的整数倍。源文件自身的 slice 仍可能触发碎片合并。
- 大规模合并建议安排在业务低峰,避免碎片合并的读写带宽影响其他业务。
- 多分区部署中,如果
merge返回「不支持」,通常是源文件的元数据或 chunk 数超过迁移上限。使用 JuiceFS 5.3.4 及以上版本可以启用自动碎片合并和重试,或联系 Juicedata 工程师。
常见问题
merge 会删除源文件吗? 不会。源文件保持不变,需要单独删除。
为什么删除源文件后对象存储容量没有立刻下降? 源文件和合并后的文件共享同一批 chunk 对象。删除源文件只会减少引用;对象要等回收站保留期结束并经过后台垃圾回收后才会释放。
为什么 merge 后看到对象存储有写入? 常见原因是 chunk 边界不对齐产生了 slice,后台碎片合并正在重写受影响的目标 chunk。跨分区元数据迁移也可能在重试前对较大的源文件做碎片合并。
碎片合并一定会发生吗? 不一定。没有 slice、后台任务未开启,或当前没有可用客户端执行任务时,碎片合并可能延迟或不会发生。合并后的文件仍然可以正常读取。
可以合并从对象存储导入的文件吗? 不可以。导入文件使用兼容格式,不能作为 merge 的源或目标。


