rsync 增量同步实战：核心机制、参数选型与避坑指南

1. 为什么 rsync 是文件同步场景里的常青树

干运维这行十几年，经手的文件同步工具换了一茬又一茬，但每次遇到跨机数据搬运的活儿，我第一个想到的还是 rsync。这东西诞生于上世纪九十年代，放到今天看，它的设计思路依然不过时。核心原因就一个：它只传差异，不传全量。你有一万个文件，改了一个，它就只动那一个，剩下的碰都不碰。这个特性在带宽紧张或者文件体量巨大的场景下，价值被放得极大。

rsync 能做的事儿其实比很多人想象的要多。它不只是“把 A 目录复制到 B 目录”这么简单。你可以用它做本地目录镜像、跨机增量备份、定时任务里的数据搬运、代码发布时的文件分发，甚至配合 SSH 做加密通道下的安全传输。适合谁学？我觉得只要你的日常工作里涉及“把文件从这儿弄到那儿”这件事，不管是开发、运维、测试还是数据分析，都值得花半小时把 rsync 的常用参数摸透。它不像某些重型同步方案那样需要装 agent、配中心节点，一条命令就能跑起来，学习曲线平缓，但上限很高。

我见过太多人用 scp 或者 cp 硬扛大目录同步，每次全量拷贝，等得花儿都谢了。其实换成 rsync，第一次全量之后，后续每次同步都是秒级完成。这篇文章我会把 rsync 的核心机制、参数选型、实操步骤、踩坑经验全部拆开讲，尽量让刚接触的人也能照着做，同时把一些老手容易忽略的细节也点出来。

2. rsync 核心机制与方案选型拆解

2.1 增量同步的底层逻辑：为什么它快

rsync 的快，根源在于它的delta 传输算法。这个算法说起来也不复杂：源端和目标端各自把文件切成固定大小的块，然后对每个块计算校验和。目标端把自己所有块的校验和发给源端，源端拿这些校验和跟自己文件的块做比对，找出哪些块是目标端已经有的，哪些是缺失或不同的。最后只把差异部分打包传过去，目标端再根据这些差异和本地已有的块重组出完整文件。

这个过程里有一个关键角色叫滚动校验和。它允许块边界不必严格对齐，即使文件中间插入了一段内容，导致后续所有块的位置都偏移了，rsync 也能通过滚动计算快速找到匹配的块。这就避免了“改一个字节，后面全变”的尴尬。实际效果就是：你在一份大日志文件开头插了一行，rsync 不会把整个文件重传，而是只传插入的那部分和少量调整信息。

注意：增量传输的前提是目标端已经有一份旧版本的文件。如果目标端是空的，第一次同步仍然是全量传输，这是绕不开的。

2.2 同步方向与模式选择：推还是拉

rsync 支持两种基本模式：推送和拉取。推送是把本地文件传到远端，拉取是把远端文件拉到本地。语法上区分很简单，源路径在前，目标路径在后，远端路径用user@host:path的形式表示。

推模式适合：本地产生数据，需要备份到远端存储。比如你本机跑完一个任务，把结果目录推到备份服务器。拉模式适合：远端有数据，你需要定期取回本地处理。比如从数据采集机上把日志拉到分析机。

还有一种本地模式，源和目标都是本地路径，这时候 rsync 就相当于一个增强版的 cp，但带增量能力。很多人忽略了这个用法，其实在本地做目录镜像时，rsync -a --delete比cp -r好用得多，因为它能精确保持权限、时间戳，还能删除目标端多余的文件。

2.3 传输通道：SSH 与原生协议的选择

rsync 本身是一个独立协议，默认监听 873 端口。但在实际生产环境里，我几乎不用原生协议，而是走 SSH 通道。原因很直接：SSH 自带加密和认证，不需要额外配置 rsync 守护进程，也不需要开放额外端口。命令形式就是rsync -avz -e ssh source user@host:dest，其中-e ssh指定使用 SSH 作为远程 shell。

原生协议的优势在于可以配置模块化访问、带宽限制、并发连接等高级功能，适合做集中化的同步服务。但配置复杂度高，需要维护配置文件、设置认证方式。对于绝大多数“两台机器之间搬文件”的需求，SSH 通道足够用，而且更安全、更省事。

提示：如果 SSH 端口不是默认的 22，可以用-e "ssh -p 2222"来指定端口。这个细节很多人第一次用会卡住。

2.4 参数选型背后的考量

rsync 的参数非常多，但常用的就那么十几个。我挑几个最关键的说一下选型逻辑。

-a是归档模式，等价于-rlptgoD这一串。它保持文件权限、时间戳、属主属组、设备文件等。做备份时基本必加。-v是详细输出，能看到传输了哪些文件。-z是压缩传输，在带宽有限时能显著提速，但会消耗 CPU。如果两边 CPU 都很闲、网络是瓶颈，加-z；如果 CPU 吃紧、网络富余，就不加。

--delete是个双刃剑。它让目标端和源端保持完全一致，源端删了的文件目标端也删。做镜像同步时很有用，但用错了就是灾难。我一般会先用--dry-run跑一遍看看会删什么，确认无误再去掉这个参数正式执行。

--exclude和--include用于过滤文件。规则是从左到右匹配，先匹配到的生效。这个顺序很关键，写反了效果完全不对。比如你想排除所有.log文件但保留important.log，就得先写--include=important.log再写--exclude=*.log。

-P是--partial --progress的合体，断点续传加进度显示。传大文件时必加，不然中断了就得从头来。

3. 实操环境搭建与核心步骤拆解

3.1 环境准备与基础连通性验证

假设我们有两台机器：一台叫source-host，一台叫dest-host。目标是把source-host上的/data/app目录同步到dest-host的/backup/app。

第一步不是急着敲 rsync 命令，而是先确认 SSH 连通性。在source-host上执行ssh user@dest-host，能正常登录进去，说明认证没问题。如果用了密钥认证，确认~/.ssh/id_rsa存在且公钥已经追加到目标机的~/.ssh/authorized_keys里。

第二步确认 rsync 是否安装。两边都执行rsync --version，能看到版本号就行。大多数 Linux 发行版默认带了 rsync，如果没有，用包管理器装一下即可。

第三步确认目标目录存在且有写权限。ssh user@dest-host "mkdir -p /backup/app && touch /backup/app/.test && rm /backup/app/.test"，这条命令能跑通，说明目录创建和写入都没问题。

实操心得：我习惯在正式同步前先用rsync -av --dry-run跑一遍，看看文件列表和传输量是否符合预期。这个习惯帮我避免过好几次误删事故。

3.2 第一条同步命令的完整拆解

环境确认完毕后，在source-host上执行：

rsync -avz --progress -e ssh /data/app/ user@dest-host:/backup/app/

这条命令里每个部分都有讲究。-a归档模式，保持所有元信息。-v详细输出，让你看到每个文件的名字。-z压缩传输，适合网络带宽一般的情况。--progress显示传输进度和速度。-e ssh指定远程 shell 为 SSH。

源路径/data/app/末尾的斜杠很关键。有斜杠表示“同步这个目录里的内容”，没有斜杠表示“同步这个目录本身”。举个例子：/data/app/同步后目标端是/backup/app/下面直接是文件；/data/app同步后目标端是/backup/app/app/，多了一层。这个细节新手极容易搞错，我第一次用的时候就因为这个多套了一层目录，排查了半天。

目标路径/backup/app/末尾的斜杠加不加都行，rsync 会自动处理。

3.3 增量同步的验证方法

第一次同步完成后，源端和目标端的文件应该完全一致。怎么验证？最直接的方法是比对文件数量和总大小：

ssh user@dest-host "find /backup/app -type f | wc -l" find /data/app -type f | wc -l

两边数字一致，基本就没问题。更严格一点，可以用rsync -avn --delete再跑一次 dry-run，如果输出里没有任何文件需要传输或删除，说明两边完全同步。

然后我们做个增量测试：在源端新建一个文件echo "test" > /data/app/newfile.txt，再次执行同步命令。你会看到 rsync 只传输了newfile.txt这一个文件，其他文件全部跳过。这就是增量同步的直观体现。

再测试修改场景：往一个已有文件里追加一行内容，再次同步。rsync 会传输这个文件的差异部分，而不是整个文件。对于大文件来说，这个差异可能只有几百字节。

3.4 定时同步的配置方式

手动同步只适合临时任务，生产环境里通常是定时执行。最常用的方式是写一个 shell 脚本，然后挂到 crontab 里。

脚本内容示例：

#!/bin/bash RSYNC_CMD="rsync -avz --delete --exclude='*.tmp' --exclude='cache/' -e ssh /data/app/ user@dest-host:/backup/app/" LOG_FILE="/var/log/rsync_app.log" echo "$(date '+%Y-%m-%d %H:%M:%S') - 开始同步" >> $LOG_FILE $RSYNC_CMD >> $LOG_FILE 2>&1 echo "$(date '+%Y-%m-%d %H:%M:%S') - 同步结束，退出码: $?" >> $LOG_FILE

这个脚本里我加了--delete让目标端和源端保持严格一致，同时排除了临时文件和缓存目录。日志记录了两个时间点和退出码，方便排查问题。

crontab 配置示例，每 30 分钟执行一次：

*/30 * * * * /bin/bash /opt/scripts/rsync_app.sh

注意：crontab 里的环境变量和交互式 shell 不一样，脚本里最好用绝对路径，rsync 命令也写全路径，比如/usr/bin/rsync。我遇到过因为 PATH 问题导致 crontab 里 rsync 找不到的情况。

3.5 排除规则的高级用法

实际项目里，不是所有文件都需要同步。比如日志目录、缓存目录、临时文件、版本控制目录，这些通常都要排除掉。

基本的排除写法：

rsync -avz --exclude='*.log' --exclude='.git/' --exclude='node_modules/' /data/app/ user@dest-host:/backup/app/

如果排除规则很多，可以写到一个文件里，用--exclude-from指定：

rsync -avz --exclude-from='/opt/scripts/exclude.list' /data/app/ user@dest-host:/backup/app/

exclude.list内容示例：

*.log *.tmp .git/ node_modules/ cache/ *.pid

这里有个容易踩的坑：排除规则里的路径是相对于源路径的。比如你写cache/，它排除的是源路径下所有名为cache的目录，不管层级多深。如果你想只排除根目录下的cache，得写/cache/，前面加斜杠表示锚定到根。

还有一个更隐蔽的坑：--exclude和--include的配合。rsync 的规则是从上到下匹配，一旦匹配到就停止。所以如果你想让某个文件不被排除，必须把--include写在对应的--exclude前面。比如：

rsync -avz --include='important.log' --exclude='*.log' /data/app/ user@dest-host:/backup/app/

这样important.log会被包含，其他.log文件被排除。如果顺序反过来，important.log也会被排除掉。

4. 常见问题排查与避坑指南

4.1 权限拒绝与认证失败

这是最常见的问题，报错信息通常是Permission denied (publickey)或者rsync: connection unexpectedly closed。

排查思路分几步走。先确认 SSH 本身能不能通：ssh user@dest-host能不能登录。如果 SSH 都登不上，那 rsync 肯定也不行，先去解决 SSH 的问题。如果 SSH 能登，但 rsync 报权限错误，检查目标路径的写权限：ssh user@dest-host "ls -ld /backup/app"，看看当前用户有没有写权限。

还有一种情况是目标机的 rsync 没有安装，或者路径不对。ssh user@dest-host "which rsync"确认一下 rsync 的位置。如果不在默认 PATH 里，可以用--rsync-path参数指定：rsync -avz --rsync-path='/usr/local/bin/rsync' ...。

密钥认证的问题也常见。确认~/.ssh/id_rsa的权限是 600，~/.ssh目录是 700。权限太开放 SSH 会拒绝使用密钥。目标机的authorized_keys权限也应该是 600。

4.2 文件被跳过或同步不完整

有时候你会发现某些文件明明改了，但 rsync 就是不同步。这种情况通常是时间戳精度或者文件大小判断的问题。

rsync 默认用“文件大小 + 修改时间”来判断文件是否需要传输。如果两个文件大小一样、修改时间也一样，rsync 就认为它们相同，跳过传输。但有些场景下，文件内容变了，大小没变，修改时间也没变（比如某些程序写入时保持了原始时间戳），rsync 就检测不到。

解决办法是用-c参数，让 rsync 基于校验和来判断，而不是时间戳和大小。但-c会显著增加 CPU 消耗，因为要读取所有文件内容计算校验和。只建议在确实需要时使用。

另一个原因是排除规则写错了，把不该排除的文件排掉了。用-v参数看详细输出，确认哪些文件被跳过了。如果输出里显示[sender] hiding file xxx，说明被排除规则命中了。

4.3 传输中断与断点续传

大文件传输时网络抖动导致中断，这是家常便饭。默认情况下 rsync 中断后重新执行会从头开始传。加上--partial参数后，rsync 会保留已传输的部分，下次执行时从断点继续。

更省事的做法是用-P，它等价于--partial --progress，既保留断点又显示进度。

rsync -avzP -e ssh /data/bigfile.iso user@dest-host:/backup/

如果中断频繁，可以考虑加上--timeout参数设置超时时间，避免卡死。--timeout=300表示 300 秒无数据传输就断开。

还有一种情况是传输过程中目标端磁盘满了，rsync 会报No space left on device。这时候先清理目标端空间，然后重新执行同步命令，配合--partial可以续传。

4.4 删除操作的安全防护

--delete参数威力很大，用不好就是数据丢失。我给自己定了几条规矩：

第一，永远先用--dry-run预览。rsync -avn --delete source/ dest/会列出所有将被删除的文件，确认无误后再去掉-n正式执行。

第二，给--delete加上保护条件。--max-delete=100限制单次最多删除 100 个文件，超过就中止。这能防止因为源端目录挂载失败导致目标端被清空。

第三，重要数据做二次备份。即使 rsync 同步出错，还有一份备份可以恢复。

实操心得：我曾经遇到过源端 NFS 挂载点掉线，源目录变成空目录，结果--delete把目标端所有文件都删了。从那以后，我在脚本里加了一个检查：源目录的文件数量如果少于预期值，直接退出不执行同步。

4.5 性能调优与带宽控制

rsync 的性能瓶颈通常在两处：网络带宽和磁盘 I/O。如果网络是瓶颈，加-z压缩能提升有效吞吐。如果磁盘 I/O 是瓶颈，可以试试--whole-file参数，让 rsync 直接整文件传输，跳过 delta 算法。这个参数在本地网络或者文件系统很快的场景下反而更快，因为省去了计算校验和的开销。

带宽控制用--bwlimit参数，单位是 KB/s。比如--bwlimit=5000表示限制在 5MB/s。这个参数在共享网络环境里很有用，避免 rsync 把带宽跑满影响其他服务。

并发方面，rsync 本身是单线程的。如果要同步多个独立目录，可以起多个 rsync 进程并行跑。但要注意目标端的磁盘 I/O 承受能力，别把磁盘跑挂了。

4.6 常见问题速查表

5. 进阶场景与个人经验沉淀

5.1 多目录批量同步的脚本化

实际项目里往往不止同步一个目录。比如一个应用有代码目录、配置目录、日志目录需要分别同步到不同位置。这时候写一个配置文件驱动的脚本会方便很多。

配置文件sync.conf示例：

/data/app/code|/backup/app/code|--exclude='.git/' --exclude='node_modules/' /data/app/config|/backup/app/config| /data/app/logs|/backup/app/logs|--exclude='*.gz'

脚本读取每一行，按|分割出源路径、目标路径、额外参数，然后拼出 rsync 命令执行。这样新增同步任务只需要改配置文件，不用动脚本逻辑。

#!/bin/bash CONF_FILE="/opt/scripts/sync.conf" DEST_HOST="user@dest-host" while IFS='|' read -r src dest extra; do [ -z "$src" ] && continue echo "同步: $src -> $dest" rsync -avz --delete $extra -e ssh "$src/" "$DEST_HOST:$dest/" done < "$CONF_FILE"

这个模式我用了好几年，稳定可靠。关键是配置文件格式简单，谁都能改，不需要懂 shell 脚本。

5.2 同步完成后的校验机制

同步完了不代表数据一定对。网络传输、磁盘写入都可能出问题。我习惯在同步脚本最后加一步校验：比对源端和目标端的文件数量和总大小。

SRC_COUNT=$(find /data/app -type f | wc -l) DST_COUNT=$(ssh user@dest-host "find /backup/app -type f | wc -l") if [ "$SRC_COUNT" -ne "$DST_COUNT" ]; then echo "文件数量不一致: 源端 $SRC_COUNT, 目标端 $DST_COUNT" exit 1 fi

更严格的校验可以用rsync -avn --delete做 dry-run，如果输出为空说明完全一致。但这个方式在大目录下比较耗时，适合在关键同步任务后执行。

5.3 日志轮转与监控告警

同步脚本的日志会越来越大，需要做轮转。最简单的办法是用logrotate，配置一个规则文件：

/var/log/rsync_app.log { daily rotate 7 compress missingok notifempty }

监控方面，我通常关注两个指标：同步是否成功、同步耗时是否异常。脚本里记录退出码和耗时，然后用一个简单的监控脚本读取日志，发现异常就发告警。告警方式可以用邮件或者 webhook，看团队习惯。

提示：rsync 的退出码有具体含义。0 表示成功，23 表示部分文件传输失败，24 表示部分文件在传输过程中消失。脚本里可以根据退出码做不同处理。

5.4 我踩过的几个印象深刻的坑

第一个坑是路径斜杠。刚用 rsync 那会儿，源路径没加斜杠，结果目标端多了一层目录，导致应用找不到文件。排查了半天才发现是斜杠的问题。从那以后，我写 rsync 命令时都会刻意确认一下源路径末尾的斜杠。

第二个坑是排除规则顺序。有一次想排除所有.log但保留error.log，结果写成了--exclude='*.log' --include='error.log'，顺序反了，error.log也被排除了。后来才明白 rsync 的规则是从上到下匹配，先匹配到的生效。

第三个坑是crontab 环境变量。脚本手动执行没问题，放到 crontab 里就报 rsync 找不到。原因是 crontab 的 PATH 和登录 shell 不一样。解决办法是在脚本开头显式设置 PATH，或者用 rsync 的绝对路径。

第四个坑是--delete的误删。前面提过，源端挂载点掉线导致目标端被清空。这个教训让我养成了加--max-delete和源端检查的习惯。

5.5 后续可以扩展的方向

rsync 本身已经足够稳定，但围绕它还能做不少事情。比如结合inotify做实时同步，文件一有变动就触发 rsync，而不是等定时任务。这个方案适合对同步延迟敏感的场景，但要注意 inotify 的监控数量和触发频率，避免 rsync 进程被频繁拉起。

另一个方向是加密存储。rsync 传输过程走 SSH 是加密的，但目标端的数据是明文。如果对静态数据加密有要求，可以在目标端用加密文件系统，或者同步前先加密再传。

还可以考虑用 rsync 做版本化备份。每次同步前，在目标端用硬链接创建一个快照目录，这样既能保留历史版本，又不占用额外空间。这个方案配合--link-dest参数可以实现，适合做类似时间机器那样的备份系统。

我个人在实际操作中的体会是，rsync 这个工具看似简单，但细节极多。参数组合不同，行为差异很大。最好的学习方式就是搭两台虚拟机，把常用参数一个个试过去，观察输出和结果。踩过的坑越多，对它的理解就越深。希望这篇内容能帮你少走一些弯路，把文件同步这件事做得更稳、更快、更放心。