rsync --partial 保留中断文件并控制重传的方法

大文件同步被网络中断后，rsync 默认会删除接收端尚未完成的临时文件，下一次执行时就可能重新传输。要保留这部分数据，可以使用 --partial；如果不希望半成品直接出现在正式文件名下，则使用 --partial-dir=.rsync-partial。前者简单，后者更适合生产目录。

官方地址：https://rsync.samba.org/

最稳妥的通用写法是 rsync -a --partial-dir=.rsync-partial：中断文件放到目标目录旁的隐藏暂存目录，下一次同步可以把它作为恢复依据；如果只需要快速保留半成品，才直接使用 --partial。

先分清中断文件会落在哪里

--partial 的作用是保留被中断的部分文件，让下一次传输有机会复用已经到达的数据。它并不替你创建一个独立的管理目录，因此半成品可能以目标文件名留在接收端。对发布目录、备份目录来说，这种状态需要额外注意：下游程序可能把它当作完整文件。

--partial-dir=DIR 也会启用保留逻辑，但会把部分文件放进指定目录。使用相对路径时，例如 .rsync-partial，这个目录位于对应目标文件的目录附近；传输完成后，rsync 会在文件已经服务完恢复用途时清理它。这样既保留了断点数据，又把半成品与正式文件名隔开。

只想保留半成品时使用 --partial

单文件或临时备份场景可以先使用最小命令。下面的写法保留归档文件的中断部分，并显示整个传输的进度。

rsync -a --partial --info=progress2 /srv/releases/app.tar.gz backup:/data/releases/
# --partial 保留目标端的中断文件，下一次同步可继续利用已有数据
# --info=progress2 显示整个任务的进度，不改变文件落点策略

再次执行同一条命令时，rsync 会重新比较源端和目标端的数据块。这里的“控制重传”不是承诺只发送剩余字节，而是让已有的部分文件成为增量传输的基础。源文件如果在中断后发生变化，原有部分数据不一定都能复用。

如果目标目录中的文件会被服务进程直接读取，建议不要把 --partial 作为唯一保护。半成品使用正式文件名时，应用必须能够识别文件尚未完成，或者同步应当落到隔离目录后再切换。

用 --partial-dir 隔离正式文件和中断文件

对备份、镜像、发布包等场景，更推荐显式指定相对暂存目录。它让恢复数据有稳定位置，同时避免把未完成内容暴露成最终文件。

rsync -a --partial-dir=.rsync-partial --info=progress2 \
  /srv/releases/ backup:/data/releases/
# 相对路径让每个目标目录旁都有自己的 .rsync-partial 暂存目录
# 完整文件仍写入正式路径，部分文件由暂存目录承载

这个目录不要放到所有任务共用且权限宽松的 /tmp。rsync 官方手册特别提醒，部分目录如果可被其他用户写入会带来安全风险。更稳妥的做法是让同步账号拥有目标目录和暂存目录，并把目录权限限制在必要范围。

还要预留暂存空间。暂存目录并不会让磁盘占用消失；传输中断时，目标正式文件、部分文件和临时数据可能在一段时间内同时存在。

重传异常通常来自参数组合

当你发现第二次同步仍然像“从头开始”，先不要立即增加更多参数。下面几组组合最容易改变 --partial-dir 的预期。

不要把 --append 当成普通断点续传

--append 适用于接收端已有内容确定与发送端前缀一致、并且文件只会继续变大的场景。它会跳过已经存在的前缀校验，把重点放在追加部分；如果文件可能被重写、截断或内容前缀不一致，就可能把错误前缀保留下来。

--append-verify 会在追加模式下做更完整的校验，代价是检查更多数据。普通大文件因网络中断而需要恢复时，优先考虑 --partial-dir，不要为了“续传”直接切换到 append 模式。

用一次复查确认策略真的可用

正式放进定时任务前，可以把问题拆成“文件落点、重试依据、清理条件”三层。命令本身不需要依赖本地运行结果才能理解，但运维复查应当保留日志和磁盘观察。

rsync -a --partial-dir=.rsync-partial --timeout=30 \
  --info=progress2 --log-file=/var/log/rsync-release.log \
  /srv/releases/ backup:/data/releases/
# --timeout 防止长时间没有 I/O 时无限等待
# --log-file 保存本次同步的文件级记录，便于判断是否重复发送
# 不要把 --whole-file 与断点恢复目标混在同一条固定任务中

复查时重点看三件事：

1. 中断后，正式目录里没有被业务误读的半成品；使用 --partial-dir 时，暂存目录位于预期位置。
2. 重试前没有被清理策略删除恢复依据；特别是不要让 --delete-before 抢先清空仍要复用的暂存数据。
3. 同步账号能读写暂存目录，暂存目录不对无关用户开放，目标文件系统有足够空间。

如果业务要求“所有文件一次性切换”，可以把 rsync 的目标目录作为内部 staging 区，再由发布动作切换目录名；这已经超出 --partial 本身的职责，但能进一步隔离未完成文件。

常见问题

-P 和 --partial 是什么关系？

-P 等价于 --partial --progress。它适合手工执行长传输；脚本中如果还需要整体进度、日志或超时，建议把长选项明确写出。

为什么指定了 --partial-dir 仍然没有恢复？

先检查是否启用了 --whole-file、是否改变了目标路径、暂存目录是否被删除，以及两端文件是否已经发生内容变化。partial-dir 提供恢复依据，不保证任何变化后的文件都能按字节续传。

暂存目录可以放到绝对路径吗？

可以，但绝对路径会把不同目标文件的部分文件集中到指定目录，路径规划和同名冲突需要由管理员负责。按目标目录使用相对 .rsync-partial 通常更容易管理。

结论

只想让中断文件留下来，用 --partial；不希望半成品占用正式文件名，用相对 --partial-dir=.rsync-partial。若重试仍全量传输，优先排查 --whole-file、错误使用 --append、删除时机、目录权限和磁盘空间，再决定是否调整命令。把“保留策略”和“发布切换”分开，才能既减少重传，又不让未完成文件污染生产目录。