Ubuntu 22.04 rsync 安装与命令参数详解

在 Ubuntu 22.04 上从零安装 rsync 3.2.7（在线 apt 与离线 deb 两种方式），并逐条实测全部命令参数、本地与 ssh 远程同步的真实输出，附 3.2.7 与 3.1.3 版本差异与命令速查表

Linux 文件管理与传输rsyncUbuntu 22.042026/10/07

Ubuntu 22.04 rsync 安装与命令参数详解

目标：说明 rsync 这一高效文件同步工具在 Ubuntu 22.04（amd64 / x86_64）上的完整安装（在线 apt 与离线 deb 两种方式）、全部命令参数的逐条实测结果，以及 rsync 3.2.7 与旧版 3.1.3 的真实行为差异，已在真实环境中逐条实测通过。

一、环境信息

  • 操作系统：Ubuntu 22.04 LTS（amd64 / x86_64，Ubuntu 22.04.5 LTS）
  • 工具版本：rsync 3.2.7（Debian 包版本 3.2.7-0ubuntu0.22.04.7，实测 rsync --version 输出 rsync version 3.2.7 protocol version 31）
  • CPU 核数：6 核（nproc 实测）
  • 内存：31Gi（free -h 实测 total 31Gi、used 7.3Gi）
  • 安装来源仓库：Ubuntu 官方仓库 archive.ubuntu.com（jammy-updates/main，包 3.2.7-0ubuntu0.22.04.7）
  • 本机内网 IP：172.17.0.6；对端服务器（CentOS 8）内网 IP：172.17.0.5（用于 -e ssh 远程同步实测，两机已配置 ssh 密钥免密登录）
  • systemd 单元：deb 包自带 /lib/systemd/system/rsync.service（disabled，静态）与 /etc/init.d/rsync、/etc/default/rsync
  • 说明：rsync 3.2.7 位于官方仓库 jammy-updates 的 main 组件，在线安装无需添加任何第三方源。

二、工具概览

rsync（remote sync）是一个开源的、基于 GPL 协议的高效文件传输与目录同步工具，由 Andrew Tridgell、Wayne Davison 等人开发维护。它使用「增量传输 + 滚动校验（delta-xfer）」算法，只传输两端有差异的数据块，特别适合大文件增量备份、目录镜像、定期任务等场景。

相比 scp / cp，rsync 的核心优势在于：

  • 两种远程通道：通过远程 shell（如 ssh，HOST:SRC 单冒号语法）传输；或通过 rsync daemon（HOST::SRC 双冒号 / rsync:// 协议，默认端口 873）传输；
  • 属性全保留：递归、符号链接、权限、时间戳、属主/属组、ACL、xattr、atime 等均可按需保留（-a 归档模式一键开启）；
  • 增量算法：仅传输变化的数据块，配合 -z 压缩（3.2.x 默认 zstd，压缩率更高）、--bwlimit 限速可大幅节省带宽；
  • 删除策略：--delete 系列选项可保持目标目录与源严格一致；
  • 演练模式：-n/--dry-run 预览将要执行的操作而不实际改动任何文件，备份前预检必备。

本文档下文所有命令均以 root 用户在本机终端执行，输出为真实回显逐字照抄。

三、在线安装

3.1 查看当前包状态

命令：dpkg -l rsync 查看 rsync 是否已安装及其精确包版本。

dpkg -l rsync

Desired=Unknown/Install/Remove/Purge/Hold
| Status=Not/Inst/Conf-files/Unpacked/halF-conf/Half-inst/trig-aWait/Trig-pend
|/ Err?=(none)/Reinst-required (Status,Err: uppercase=bad)
||/ Name           Version                Architecture Description
+++-==============-======================-============-=====================================================
ii  rsync          3.2.7-0ubuntu0.22.04.7 amd64        fast, versatile, remote (and local) file-copying tool

说明：ii 表示已安装（installed），包全名为 rsync，版本 3.2.7-0ubuntu0.22.04.7，架构 amd64，描述为「快速、多用途、支持远程（及本地）的文件复制工具」。该版本是 Ubuntu 22.04（jammy）官方仓库中的上游 rsync 3.2.7 的安全更新再打包（-0ubuntu0.22.04.7）。

3.2 在线安装 / 重装

命令：apt-get install -y rsync 在线安装；已安装时可用 --reinstall 强制重装（真实回显如下）。

apt-get install -y --reinstall rsync

Reading package lists...
Building dependency tree...
Reading state information...
0 upgraded, 0 newly installed, 1 reinstalled, 0 to remove and 10 not upgraded.
Need to get 445 kB of archives.
After this operation, 0 B of additional disk space will be used.
Get:1 http://archive.ubuntu.com/ubuntu jammy-updates/main amd64 rsync amd64 3.2.7-0ubuntu0.22.04.7 [445 kB]
debconf: delaying package configuration, since apt-utils is not installed
Fetched 445 kB in 2s (239 kB/s)
(Reading database ... 10612 files and directories currently installed.)
Preparing to unpack .../rsync_3.2.7-0ubuntu0.22.04.7_amd64.deb ...
Unpacking rsync (3.2.7-0ubuntu0.22.04.7) over (3.2.7-0ubuntu0.22.04.7) ...
Setting up rsync (3.2.7-0ubuntu0.22.04.7) ...
invoke-rc.d: policy-rc.d denied execution of restart.
/usr/sbin/policy-rc.d returned 101, not running 'restart rsync.service'

说明：1 reinstalled 表示重装一个包；包体 445 kB，从 archive.ubuntu.com（jammy-updates/main）获取。debconf: delaying package configuration, since apt-utils is not installed 是本机未安装 apt-utils 时的正常提示。末尾 invoke-rc.d: policy-rc.d denied execution of restart 是系统策略禁止在包安装时自动重启 rsync.service 的提示，rsync 服务默认 disabled 且本场景仅用客户端模式，属正常现象，不影响安装结果（详见第六章 6.1）。

3.3 在线安装后的版本验证

命令：rsync --version 验证版本与编译能力。

rsync --version

rsync  version 3.2.7  protocol version 31
Copyright (C) 1996-2022 by Andrew Tridgell, Wayne Davison, and others.
Web site: https://rsync.samba.org/
Capabilities:
    64-bit files, 64-bit inums, 64-bit timestamps, 64-bit long ints,
    socketpairs, symlinks, symtimes, hardlinks, hardlink-specials,
    hardlink-symlinks, IPv6, atimes, batchfiles, inplace, append, ACLs,
    xattrs, optional secluded-args, iconv, prealloc, stop-at, no crtimes
Optimizations:
    SIMD-roll, no asm-roll, openssl-crypto, no asm-MD5
Checksum list:
    xxh128 xxh3 xxh64 (xxhash) md5 md4 sha1 none
Compress list:
    zstd lz4 zlibx zlib none
Daemon auth list:
    sha512 sha256 sha1 md5 md4

rsync comes with ABSOLUTELY NO WARRANTY.  This is free software, and you
are welcome to redistribute it under certain conditions.  See the GNU
General Public Licence for details.

说明：与 3.1.3 相比，3.2.7 的 Capabilities 多出 atimes、hardlink-specials、stop-at 等；Checksum list 与 Compress list 行是 3.2 新增的输出，明确列出默认 xxh128 校验算法与 zstd 压缩算法（详见第六章版本对照表）。

四、离线安装

离线场景（目标机无法联网）下，可在可联网机器上先把 deb 包下载到本地，再拷贝到目标机用 dpkg -i 安装。rsync 依赖极少，主包即可独立安装。

4.1 下载 deb 包到指定目录

命令：apt-get install -y --download-only -o Dir::Cache::archives=/root/off-rsync rsync 只下载不安装，-o Dir::Cache::archives= 指定包落盘目录。注意：当 rsync 已安装且为最新版时，--download-only 不会触发重新下载（真实回显如下）：

mkdir -p /root/off-rsync
apt-get install -y --download-only -o Dir::Cache::archives=/root/off-rsync rsync

Reading package lists...
Building dependency tree...
Reading state information...
rsync is already the newest version (3.2.7-0ubuntu0.22.04.7).
0 upgraded, 0 newly installed, 0 to remove and 10 not upgraded.

说明：已装最新版时 apt 判定无需下载。此时需加 --reinstall 强制重新下载，才能把 deb 落到指定目录（真实回显如下）：

apt-get install -y --reinstall --download-only -o Dir::Cache::archives=/root/off-rsync rsync

Reading package lists...
Building dependency tree...
Reading state information...
0 upgraded, 0 newly installed, 1 reinstalled, 0 to remove and 10 not upgraded.
Need to get 0 B/445 kB of archives.
After this operation, 0 B of additional disk space will be used.
Download complete and in download only mode

💡 说明：Download complete and in download only mode 表示只下载未安装；rsync 对应的包文件 rsync_3.2.7-0ubuntu0.22.04.7_amd64.deb 已落在 /root/off-rsync 目录。

4.2 离线包清单

命令：ls 查看下载目录，确认 rsync 的 deb 已就位。

ls -la /root/off-rsync/

total 448
drwxr-xr-x 3 root root   4096 Oct  6 15:39 .
drwx------ 1 root root   4096 Oct  6 16:35 ..
-rw-r----- 1 root root      0 Oct  6 15:39 lock
drwx------ 2 _apt root   4096 Oct  6 15:39 partial
-rw-r--r-- 1 root root 444910 Jun  8 16:38 rsync_3.2.7-0ubuntu0.22.04.7_amd64.deb

说明：目录中 rsync_3.2.7-0ubuntu0.22.04.7_amd64.deb（444,910 字节）已确认在列；lock 与 partial 是 apt 缓存目录自身的锁文件与暂存目录，可忽略。

4.3 离线安装

命令：dpkg -i 直接安装本地 deb 包（真实回显如下）。

dpkg -i /root/off-rsync/rsync_3.2.7-0ubuntu0.22.04.7_amd64.deb

(Reading database ... 10804 files and directories currently installed.)
Preparing to unpack .../rsync_3.2.7-0ubuntu0.22.04.7_amd64.deb ...
Unpacking rsync (3.2.7-0ubuntu0.22.04.7) over (3.2.7-0ubuntu0.22.04.7) ...
Setting up rsync (3.2.7-0ubuntu0.22.04.7) ...
invoke-rc.d: policy-rc.d denied execution of restart.
/usr/sbin/policy-rc.d returned 101, not running 'restart rsync.service'

说明：Unpacking ... over (...) 表示解包覆盖同版本；Setting up 表示配置完成。末尾 policy-rc.d 提示同 3.2 节说明，不影响安装结果。

4.4 离线安装后的版本验证

rsync --version

rsync  version 3.2.7  protocol version 31

五、全部命令参数实测

以下是 rsync 3.2.7 全部常用命令行参数的逐条实测。测试数据统一放置在 /root/src（源）与 /root/dst（目标）目录，源内含普通文件、子目录、符号链接与 20 MiB 随机大文件。

准备命令（均无输出）：

rm -rf /root/src /root/dst
mkdir -p /root/src/subdir /root/dst
echo "hello rsync on Ubuntu 22.04" > /root/src/file1.txt
echo "second file for rsync testing" > /root/src/file2.txt
echo "nested file under subdir" > /root/src/subdir/file3.txt
ln -s file1.txt /root/src/link1
chmod 750 /root/src/file2.txt
touch -d "2026-10-01 10:00:00" /root/src/file1.txt
dd if=/dev/urandom of=/root/src/big.bin bs=1M count=20

dd 生成大文件回显（20 MiB 随机数据）：

20+0 records in
20+0 records out
20971520 bytes (21 MB, 20 MiB) copied, 0.0741512 s, 283 MB/s

5.1 -V / --version：打印版本信息

作用：输出 rsync 版本号、协议版本与编译能力后退出。3.2.7 同时支持 -V 与 --version 两种写法（3.1.3 只有 --version）。

rsync -V

rsync  version 3.2.7  protocol version 31
Copyright (C) 1996-2022 by Andrew Tridgell, Wayne Davison, and others.
Web site: https://rsync.samba.org/
Capabilities:
    64-bit files, 64-bit inums, 64-bit timestamps, 64-bit long ints,
    socketpairs, symlinks, symtimes, hardlinks, hardlink-specials,
    hardlink-symlinks, IPv6, atimes, batchfiles, inplace, append, ACLs,
    xattrs, optional secluded-args, iconv, prealloc, stop-at, no crtimes
Optimizations:
    SIMD-roll, no asm-roll, openssl-crypto, no asm-MD5
Checksum list:
    xxh128 xxh3 xxh64 (xxhash) md5 md4 sha1 none
Compress list:
    zstd lz4 zlibx zlib none
Daemon auth list:
    sha512 sha256 sha1 md5 md4

rsync comes with ABSOLUTELY NO WARRANTY.  This is free software, and you
are welcome to redistribute it under certain conditions.  See the GNU
General Public Licence for details.

5.2 基本同步（本地目录间）

作用：最基本的本地文件复制，不带任何属性选项（仅按内容传输文件本身）。

rsync -v /root/src/file1.txt /root/dst/

file1.txt

sent 110 bytes  received 35 bytes  290.00 bytes/sec
total size is 28  speedup is 0.19

说明：-v 输出文件名与统计行；total size is 28 为源文件实际大小（file1.txt 仅 28 字节）。与 3.1.3 相比，同文件（28 字节）发送流量为 110 字节（3.1.3 为 105 字节），是协议打包的细微差异，不影响功能。

5.3 -a / --archive：归档模式

作用：归档模式，等价于 -rlptgoD（递归 + 保留链接/权限/时间/属主/属组/设备与特殊文件），不含 -H/-A/-X/-U/-N。是日常同步最常用的选项。

rm -rf /root/dst/* && rsync -a -v /root/src/ /root/dst/

sending incremental file list
./
big.bin
file1.txt
file2.txt
link1 -> file1.txt
subdir/
subdir/file3.txt

sent 20,977,106 bytes  received 106 bytes  41,954,424.00 bytes/sec
total size is 20,971,612  speedup is 1.00

说明：link1 -> file1.txt 表示符号链接被原样保留（-l 生效）；本地首传为全量复制（speedup 1.00），sent 20,977,106 bytes 与源目录数据量一致。

5.4 -v / -vv：详细输出

作用：-v 输出每个被传输的文件；-vv 更详细，显示跳过原因与增量匹配统计。

rsync -avv /root/src/file1.txt /root/dst/

sending incremental file list
delta-transmission disabled for local transfer or --whole-file
file1.txt is uptodate
total: matches=0  hash_hits=0  false_alarms=0 data=0

sent 61 bytes  received 112 bytes  346.00 bytes/sec
total size is 28  speedup is 0.16

说明：delta-transmission disabled for local transfer or --whole-file 表示本地传输不启用增量校验块；file1.txt is uptodate 说明目标文件与源大小、时间匹配而被跳过；total: matches=0... 是 -vv 才有的增量匹配统计。

5.5 -z / --compress：传输时压缩

作用：对传输数据做压缩，适合低带宽链路与文本类数据。3.2.7 默认使用 zstd 压缩（--compress-choice 可切换 zstd/lz4/zlibx/zlib/none）。先在源创建 5 MB 可压缩重复文本：

rm -rf /root/dst/* && yes "compressible text data for rsync -z demo" | head -c 5000000 > /root/src/compressible.txt
rsync -az --stats /root/src/compressible.txt /root/dst/


Number of files: 1 (reg: 1)
Number of created files: 1 (reg: 1)
Number of deleted files: 0
Number of regular files transferred: 1
Total file size: 5,000,000 bytes
Total transferred file size: 5,000,000 bytes
Literal data: 5,000,000 bytes
Matched data: 0 bytes
File list size: 0
File list generation time: 0.001 seconds
File list transfer time: 0.000 seconds
Total bytes sent: 623
Total bytes received: 35

sent 623 bytes  received 35 bytes  1,316.00 bytes/sec
total size is 5,000,000  speedup is 7,598.78

说明：5,000,000 字节的文件经 -z 压缩后实际仅发送 623 字节（speedup 7,598.78），压缩收益极为显著。对比 CentOS 8 的 3.1.3（zlib，同文件发送 14,705 字节、speedup 339.21），3.2.7 的默认 zstd 压缩率高出约 23 倍，这是版本间最直观的行为差异之一。

5.6 -h / --human-readable：人类可读数字

作用：把字节数显示为 K/M/G 单位。注意：单独执行 rsync -h 等价于 --help（帮助文本注明 * -h is help only on its own），与其它选项组合时才是 human-readable。

rm -rf /root/dst/* && rsync -ah --stats /root/src/big.bin /root/dst/


Number of files: 1 (reg: 1)
Number of created files: 1 (reg: 1)
Number of deleted files: 0
Number of regular files transferred: 1
Total file size: 20.97M bytes
Total transferred file size: 20.97M bytes
Literal data: 20.97M bytes
Matched data: 0 bytes
File list size: 0
File list generation time: 0.001 seconds
File list transfer time: 0.000 seconds
Total bytes sent: 20.98M
Total bytes received: 35

sent 20.98M bytes  received 35 bytes  41.95M bytes/sec
total size is 20.97M  speedup is 1.00

说明：Total file size: 20.97M bytes、Total bytes sent: 20.98M 均为人类可读单位；不加 -h 时这些数字显示为原始字节（如 20,971,520）。

5.7 --progress / -P：传输进度

作用：--progress 显示每个文件的传输进度（字节、百分比、速率、剩余时间）；-P 是 --partial --progress 的组合简写。

rm -rf /root/dst/* && rsync -aP /root/src/big.bin /root/dst/

sending incremental file list
big.bin
     20,971,520 100%  475.45MB/s    0:00:00 (xfr#1, to-chk=0/1)

说明：进度行格式为 已传字节 百分比 速率 用时 (xfr#序号, to-chk=剩余/总数)。本地传输极快，进度瞬间到达 100%；远程大文件场景中 -P 是观察进度的标准方式。

5.8 -n / --dry-run：演练模式

作用：仅模拟执行、不实际改动任何文件，常用于备份前预检。

rm -rf /root/dst/* && rsync -an -v /root/src/ /root/dst/ && echo "--- dst 实际内容 ---" && ls -la /root/dst/

sending incremental file list
./
big.bin
compressible.txt
file1.txt
file2.txt
link1 -> file1.txt
subdir/
subdir/file3.txt

sent 279 bytes  received 41 bytes  640.00 bytes/sec
total size is 25,971,612  speedup is 81,161.29 (DRY RUN)
--- dst 实际内容 ---
total 8
drwxr-xr-x 2 root root 4096 Oct  6 16:33 .
drwx------ 1 root root 4096 Oct  6 16:32 ..

说明：统计行末尾的 (DRY RUN) 是演练模式标志；随后的 ls 显示 dst 实际为空，证实未做任何改动。预检时推荐配合 -v 观察将要传输的文件清单。

5.9 --delete 与 --delete-after：删除目标多余文件

作用：--delete 使目标与源严格一致，删除目标中源不存在的多余文件；--delete-after 在传输完成之后才执行删除（默认 --delete 等价 --delete-during，传输过程中删除）。

rm -rf /root/dst/* && rsync -a /root/src/ /root/dst/ && touch /root/dst/extra.txt && rsync -a --delete -v /root/src/ /root/dst/

sending incremental file list
deleting extra.txt
./

sent 254 bytes  received 36 bytes  580.00 bytes/sec
total size is 25,971,612  speedup is 89,557.28

说明：deleting extra.txt 即 --delete 删除的目标多余文件；文件列表只剩余目录项 ./（其余文件与源一致无需重传）。

touch /root/dst/extra2.txt && rsync -a --delete-after -v /root/src/ /root/dst/

building file list ... done
./
deleting extra2.txt

sent 277 bytes  received 18 bytes  590.00 bytes/sec
total size is 25,971,623  speedup is 88,039.40

说明：--delete-after 的输出以 building file list ... done 开头（与 --delete 的 sending incremental file list 不同），删除动作发生在传输完成后。二者删除效果一致，选择依据是删除时机偏好。

5.10 --exclude / --include / --exclude-from：文件过滤

作用：--exclude=PATTERN 排除匹配模式的文件；--include=PATTERN 与 --exclude='*' 组合实现「只包含」；--exclude-from=FILE 从文件读取排除规则（每行一条）。

rm -rf /root/dst/* && rsync -a --exclude="subdir" -v /root/src/ /root/dst/

sending incremental file list
./
big.bin
compressible.txt
file1.txt
file2.txt
link1 -> file1.txt

sent 25,978,272 bytes  received 98 bytes  51,956,740.00 bytes/sec
total size is 25,971,587  speedup is 1.00

说明：文件列表中 subdir 及其中的 file3.txt 被排除，其余文件正常传输。

rm -rf /root/dst/* && rsync -a --include="*.txt" --exclude="*" -v /root/src/ /root/dst/

sending incremental file list
./
compressible.txt
file1.txt
file2.txt

sent 5,001,538 bytes  received 76 bytes  10,003,228.00 bytes/sec
total size is 5,000,058  speedup is 1.00

说明：--include="*.txt" --exclude="*" 组合实现「只传输 txt 文件」，big.bin、link1、subdir 均被排除。注意规则按序匹配，先 include 后 exclude 才有效。

echo "big.bin" > /root/exclude.list && rm -rf /root/dst/* && rsync -a --exclude-from=/root/exclude.list -v /root/src/ /root/dst/

sending incremental file list
./
compressible.txt
file1.txt
file2.txt
link1 -> file1.txt
subdir/
subdir/file3.txt

sent 5,001,708 bytes  received 106 bytes  10,003,628.00 bytes/sec
total size is 5,000,092  speedup is 1.00

说明：排除规则写入 /root/exclude.list（本例内容为一行 big.bin），读取后 big.bin 被跳过；模式文件可用 # 注释、每行一条，适合规则较多的场景。

5.11 -u / --update：跳过接收端较新的文件

作用：当目标文件比源文件新（mtime 更新）时跳过不覆盖，防止用旧数据覆盖新数据（常见于双机互为备份的场景）。

rm -rf /root/dst/* && rsync -a /root/src/ /root/dst/ && touch -d "2026-10-05 08:00:00" /root/dst/file1.txt && rsync -au -v /root/src/ /root/dst/

sending incremental file list

sent 251 bytes  received 13 bytes  528.00 bytes/sec
total size is 25,971,612  speedup is 98,377.32

说明：dst 的 file1.txt 被 touch 为 2026-10-05（比源 10-01 更新），-u 模式下该文件被跳过，文件列表为空（sending incremental file list 后无文件行）。

5.12 -c / --checksum：基于内容校验和判断

作用：默认按「大小 + 修改时间」快速判断是否传输；-c 改为对文件内容做校验和比对，判断更准确（内容相同即跳过）但代价更高。3.2.7 默认校验算法为 xxh128（3.1.3 为 md5，前者更快）。演示：先同步使两端一致，再把目标 mtime 改旧，对比两种模式：

rsync -a --itemize-changes /root/src/ /root/dst/ && echo "--- checksum 模式 ---" && rsync -ac --itemize-changes /root/src/ /root/dst/

>f..t...... file1.txt
--- checksum 模式 ---

说明：默认模式因 file1.txt 时间戳不同而重新传输（>f..t...... 中 t 表示时间戳变化）；加 -c 后按内容校验和判定相同，直接跳过（无输出）。代价：需对每个候选文件计算校验和，大目录同步明显变慢。

5.13 --bwlimit：限制传输带宽

作用：限制 socket I/O 带宽，单位默认 KB/s（支持 K/M/G 后缀），用于避免同步任务挤占业务带宽。

rm -rf /root/dst/* && rsync -a --bwlimit=2048 -v /root/src/big.bin /root/dst/

sending incremental file list
big.bin

sent 20,976,737 bytes  received 35 bytes  1,997,787.81 bytes/sec
total size is 20,971,520  speedup is 1.00

说明：设定 --bwlimit=2048（2048 KB/s）后实测平均速率 1,997,787 bytes/s ≈ 1950 KB/s，限速生效；无 --bwlimit 时本地传输约 41 MB/s（见 5.3 节），远程场景同样按限速值生效。

5.14 --partial：保留部分传输文件

作用：传输中断时保留已传的部分数据；默认（不带 --partial）rsync 中断会删除不完整文件。以下用 timeout 2 在 2 秒后中断 128 KB/s 限速的 20 MB 传输做对照。

先看不加 --partial：

rm -rf /root/dst/* && timeout 2 rsync -a --bwlimit=128 /root/src/big.bin /root/dst/; echo "exit=$?"; ls -la /root/dst/

rsync error: received SIGINT, SIGTERM, or SIGHUP (code 20) at rsync.c(716) [sender=3.2.7]
rsync error: received SIGUSR1 (code 19) at main.c(1635) [generator=3.2.7]
exit=124
total 8
drwxr-xr-x 2 root root 4096 Oct  6 16:34 .
drwx------ 1 root root 4096 Oct  6 16:33 ..

说明：中断（timeout 返回 124）后目标目录为空，不完整文件已被清理，下次同步需重新开始。3.2.7 的错误行号为 rsync.c(716)/main.c(1635)，与 3.1.3 的 rsync.c(644) 不同。

再加 --partial：

rm -rf /root/dst/* && timeout 2 rsync -a --partial --bwlimit=128 /root/src/big.bin /root/dst/; echo "exit=$?"; ls -la /root/dst/

rsync error: received SIGINT, SIGTERM, or SIGHUP (code 20) at rsync.c(716) [sender=3.2.7]
rsync error: received SIGINT, SIGTERM, or SIGHUP (code 20) at io.c(519) [generator=3.2.7]
exit=124
total 232
drwxr-xr-x 2 root root   4096 Oct  6 16:35 .
drwx------ 1 root root   4096 Oct  6 16:33 ..
-rw-r--r-- 1 root root 229376 Jan  1  1970 big.bin

说明：--partial 保留了已传输的 229,376 字节（约 224 KB）big.bin，下次同步将在此基础上续传（配合 -P 可观察到续传进度），对超大数据量的断点续传意义重大。

5.15 -e ssh：基于 ssh 的远程同步

作用：-e ssh 指定以 ssh 作为远程传输通道（HOST:SRC 单冒号语法），数据经加密通道传输。本机（172.17.0.6）与对端 CentOS 8 服务器（172.17.0.5）已配置 ssh 密钥免密登录。

拉取（对端 → 本机）：

rsync -avz -e "ssh -o StrictHostKeyChecking=no" root@172.17.0.5:/root/src/ /root/remote-pull/

receiving incremental file list
created directory /root/remote-pull
./
big.bin
compressible.txt
file1.txt
file2.txt
link1 -> file1.txt
subdir/
subdir/file3.txt

sent 133 bytes  received 20,998,596 bytes  13,999,152.67 bytes/sec
total size is 25,971,608  speedup is 1.24

说明：拉取方向输出以 receiving incremental file list 开头，sent 与 received 数值对调（本机只发文件列表、收数据体）；created directory /root/remote-pull 表示目标目录不存在时自动创建。

推送（本机 → 对端）：

rsync -avz -e "ssh -o StrictHostKeyChecking=no" /root/src/ root@172.17.0.5:/root/remote-dst2/

sending incremental file list
created directory /root/remote-dst2
./
big.bin
compressible.txt
file1.txt
file2.txt
link1 -> file1.txt
subdir/
subdir/file3.txt

sent 20,998,653 bytes  received 165 bytes  13,999,212.00 bytes/sec
total size is 25,971,623  speedup is 1.24

说明：推送方向输出以 sending incremental file list 开头，-z 压缩使增量收益体现为 speedup 1.24。-e ssh 复用系统 ssh 密钥链，是远程同步的标准安全方式。

5.16 --stats：传输统计

作用：输出文件数、传输字节、字面数据/匹配数据、速率等详细统计，便于评估同步量。

rm -rf /root/dst/* && rsync -a --stats /root/src/ /root/dst/


Number of files: 8 (reg: 5, dir: 2, link: 1)
Number of created files: 7 (reg: 5, dir: 1, link: 1)
Number of deleted files: 0
Number of regular files transferred: 5
Total file size: 25,971,612 bytes
Total transferred file size: 25,971,603 bytes
Literal data: 25,971,603 bytes
Matched data: 0 bytes
File list size: 0
File list generation time: 0.001 seconds
File list transfer time: 0.000 seconds
Total bytes sent: 25,978,410
Total bytes received: 125

sent 25,978,410 bytes  received 125 bytes  51,957,070.00 bytes/sec
total size is 25,971,612  speedup is 1.00

说明：Number of files: 8 (reg: 5, dir: 2, link: 1) 与源目录结构一致（5 个普通文件、2 个目录、1 个符号链接）；Matched data: 0 表示首传无增量命中。

5.17 -r / --recursive：递归目录

作用：仅递归复制目录内容，不保留链接、权限、时间等属性（区别于 -a）。

rm -rf /root/dst/* && rsync -r -v /root/src/ /root/dst/

sending incremental file list
skipping non-regular file "link1"
big.bin
compressible.txt
file1.txt
file2.txt
subdir/
subdir/file3.txt

sent 25,978,382 bytes  received 157 bytes  51,957,078.00 bytes/sec
total size is 25,971,612  speedup is 1.00

说明：skipping non-regular file "link1"——未加 -l 时符号链接被安全跳过（rsync 默认不复制也不跟随链接）。-a 归档模式等价 -rlptgoD，已隐含 -r。

5.18 -l / --links：保留符号链接

作用：将符号链接作为链接本身复制（而非跟随其指向的真实文件）。

rm -rf /root/dst/* && rsync -l -v /root/src/link1 /root/dst/ && ls -la /root/dst/

link1 -> file1.txt

sent 53 bytes  received 19 bytes  144.00 bytes/sec
total size is 9  speedup is 0.12
total 8
drwxr-xr-x 2 root root 4096 Oct  6 16:35 .
drwx------ 1 root root 4096 Oct  6 16:35 ..
lrwxrwxrwx 1 root root    9 Oct  6 16:35 link1 -> file1.txt

说明：目标中 link1 仍是符号链接（lrwxrwxrwx，指向 file1.txt）。若改用 -L（copy-links），复制的是链接指向的真实文件内容。

5.19 -p / --perms：保留权限

作用：保留文件权限位（rwx 组合），配合 -v 观察传输结果。

rm -rf /root/dst/* && rsync -p -v /root/src/file2.txt /root/dst/ && ls -l /root/dst/file2.txt

file2.txt

sent 117 bytes  received 35 bytes  304.00 bytes/sec
total size is 30  speedup is 0.20
-rwxr-x--- 1 root root 30 Oct  6 16:35 /root/dst/file2.txt

说明：源 file2.txt 权限为 750（准备命令中 chmod 750），-p 后目标权限完全一致（-rwxr-x---）；不带 -p 时目标按默认 umask 生成权限。

5.20 -t / --times：保留修改时间

作用：保留源文件的修改时间（mtime），时间一致也是后续增量判断「无需传输」的基础。

rm -rf /root/dst/* && rsync -t -v /root/src/file1.txt /root/dst/ && ls -l /root/dst/file1.txt

file1.txt

sent 110 bytes  received 35 bytes  290.00 bytes/sec
total size is 28  speedup is 0.19
-rw-r--r-- 1 root root 28 Oct  1 10:00 /root/dst/file1.txt

说明：源 file1.txt 的 mtime 为 2026-10-01 10:00（准备时 touch -d 设定），-t 后目标时间戳一致；配合 -u/-c 决定跳过策略。

5.21 -g / -o：保留属组 / 属主

作用：-g 保留组、-o 保留属主（super-user 专属）。先将源 file2.txt 属主改为 nobody:nogroup 再同步：

chown nobody:nogroup /root/src/file2.txt && rm -rf /root/dst/* && rsync -g -o -v /root/src/file2.txt /root/dst/ && ls -l /root/dst/file2.txt

file2.txt

sent 156 bytes  received 35 bytes  382.00 bytes/sec
total size is 30  speedup is 0.16
-rwxr-x--- 1 nobody nogroup 30 Oct  6 16:36 /root/dst/file2.txt

说明：目标 file2.txt 属主/属组为 nobody:nogroup，与源一致（-a 归档模式已隐含 -g、-o）。非 root 用户执行时 -o 会被忽略。

5.22 --inplace：就地更新目标文件

作用：直接在目标文件原有位置写入新数据（默认策略是写入临时文件、完成后原子替换），适合目标文件被占用/锁定或磁盘空间受限的场景。注意 --inplace 中断时目标文件会处于不完整状态。

rm -rf /root/dst/* && rsync -a --inplace --itemize-changes /root/src/big.bin /root/dst/ && echo "extra data" >> /root/src/big.bin && echo "--- 修改源后 inplace 更新 ---" && rsync -a --inplace --itemize-changes /root/src/big.bin /root/dst/

>f+++++++++ big.bin
--- 修改源后 inplace 更新 ---
>f.st...... big.bin

说明：首传 >f+++++++++（新建文件）；源追加内容后二次同步 >f.st......（s=大小变化、t=时间变化），在目标原文件上就地更新。

5.23 --remove-source-files：同步后删除源文件

作用：传输成功后自动删除源侧已同步的非目录文件（目录保留），常用于「移动而非复制」类任务。

echo "temp file to be removed" > /root/src/remove-me.txt && rsync -a --remove-source-files -v /root/src/remove-me.txt /root/dst/ && echo "--- src 目录现状 ---" && ls /root/src/

sending incremental file list
remove-me.txt

sent 133 bytes  received 59 bytes  384.00 bytes/sec
total size is 24  speedup is 0.12
--- src 目录现状 ---
big.bin
compressible.txt
file1.txt
file2.txt
link1
subdir

说明：传输成功后 src 中的 remove-me.txt 已被自动删除（目录列表不再包含它），而 dst 已完整接收。

5.24 --list-only：仅列出文件

作用：以 ls -l 风格列出源端文件清单（权限、大小、时间），不进行任何传输。

rsync --list-only /root/src/

drwxr-xr-x          4,096 2026/10/06 16:36:31 .
-rw-r--r--     20,971,531 2026/10/06 16:36:19 big.bin
-rw-r--r--      5,000,000 2026/10/06 16:32:54 compressible.txt
-rw-r--r--             28 2026/10/01 10:00:00 file1.txt
-rwxr-x---             30 2026/10/06 16:32:12 file2.txt
lrwxrwxrwx              9 2026/10/06 16:32:12 link1
drwxr-xr-x          4,096 2026/10/06 16:32:12 subdir

说明：输出格式为「类型权限、大小、修改时间、名称」，可配合 --exclude 等过滤选项实现目录清单预览（对远程路径同样有效）。

5.25 --max-size / --min-size：按文件大小过滤

作用：--max-size=SIZE 不传输大于指定大小的文件；--min-size=SIZE 不传输小于指定大小的文件。默认两者均无限制。

rm -rf /root/dst/* && rsync -a --max-size=1K -v /root/src/ /root/dst/

sending incremental file list
./
file1.txt
file2.txt
link1 -> file1.txt
subdir/
subdir/file3.txt

sent 510 bytes  received 87 bytes  1,194.00 bytes/sec
total size is 25,971,623  speedup is 43,503.56

说明：20 MB 的 big.bin 与 5 MB 的 compressible.txt 均大于 1K 被跳过，仅传输小文件（总流量 510 字节，speedup 达 43,503.56）。

rm -rf /root/dst/* && rsync -a --min-size=10K -v /root/src/ /root/dst/

sending incremental file list
./
big.bin
compressible.txt
link1 -> file1.txt
subdir/

sent 25,978,243 bytes  received 68 bytes  51,956,622.00 bytes/sec
total size is 25,971,623  speedup is 1.00

说明：--min-size=10K 时仅 big.bin 与 compressible.txt 被传输，24/30 字节的小文本文件被跳过（subdir 目录本身仍创建，因目录不计大小过滤）。

六、常见问题与真实行为

6.1 现象：apt 安装 / 重装时输出 invoke-rc.d: policy-rc.d denied execution of restart

原因：系统策略（policy-rc.d）禁止在软件包安装 / 升级时自动重启或启动服务，apt 在 Setting up rsync 阶段尝试 restart rsync.service 被策略拒绝并返回 101。该机器的 rsync.service 默认 disabled，且本场景仅使用 rsync 客户端命令，服务是否常驻不影响使用。解决：无需处理；若确需 rsync daemon，安装后手动 systemctl enable --now rsync 即可。

6.2 现象：apt-get install --download-only 未触发下载

原因：rsync 已安装且为仓库最新版时，apt 判定无需下载（实测输出 rsync is already the newest version (3.2.7-0ubuntu0.22.04.7)，无任何 Get 行）。解决：离线打包时需追加 --reinstall 强制重新下载（实测输出 Download complete and in download only mode，deb 落盘到 -o Dir::Cache::archives= 指定目录）。

6.3 现象：Ubuntu 的 rsync 包自带 rsync.service，CentOS 8 没有

原因：Ubuntu 22.04 的 deb 包附带 /lib/systemd/system/rsync.service（disabled，静态）、/etc/init.d/rsync 与 /etc/default/rsync，用于按需启动 rsync daemon（默认端口 873）；CentOS 8 的 rpm 包仅安装 /usr/bin/rsync 与文档，systemctl list-unit-files | grep rsync 无输出。解决：按需使用；本机均无需启动 daemon。

6.4 现象：3.2.7 与 3.1.3 的行为差异

这是本工具最需注意的跨版本差异，实测对比汇总如下：

对比项Ubuntu 22.04（rsync 3.2.7）CentOS 8（rsync 3.1.3）
版本选项-V / --version 均可用仅 --version（-V 报 unknown option）
默认校验算法xxh128（xxhash 系列，更快）md5
压缩算法zstd / lz4 / zlibx / zlib（--compress-choice 可选，默认 zstd）仅 zlib
实测压缩效果（5 MB 重复文本）Total bytes sent 623（speedup 7,598.78）Total bytes sent 14,705（speedup 339.21）
3.2 新增参数--mkpath、--atimes/-U、--crtimes/-N、--open-noatime、--stop-after、--stop-at、--fsync、--secluded-args、--compress-choice 等无
帮助格式--verbose, -v（长选项在前）-v, --verbose（短选项在前）
Capabilities 输出多出 atimes、hardlink-specials、stop-at 等无 Checksum list / Compress list 行
systemd 单元rsync.service（disabled，静态）+ /etc/init.d/rsync无
包来源jammy-updates/main（deb 3.2.7-0ubuntu0.22.04.7）BaseOS（rpm 3.1.3-12.el8）

⚠️ 注意：3.1.3 与 3.2.7 同属协议版本 31，常规参数（-a/-v/-z/--delete/--bwlimit 等）行为一致，可放心跨版本混合使用；仅默认压缩/校验算法与 3.2 新增参数存在差异。

6.5 现象：中断传输时错误回显与部分文件行为

不带 --partial 中断时，rsync 会删除不完整文件（实测目标目录为空）；带 --partial 时保留部分文件（实测保留 229,376 字节）。3.2.7 与 3.1.3 行为一致，仅错误信息行号不同（3.2.7 为 rsync.c(716)/io.c(519)/main.c(1635)，3.1.3 为 rsync.c(644)）。

七、命令与参数速查表

参数/命令含义实测说明/默认值
rsync [OPTION]... SRC DEST本地同步SRC 以 / 结尾表示目录内容；HOST:SRC 走远程 shell（ssh），HOST::SRC 走 daemon
-a / --archive归档模式等价 -rlptgoD（不含 -H/-A/-X/-U/-N），最常用
-v / -vv详细 / 更详细输出-vv 显示跳过原因与增量匹配统计
-r递归目录不保留属性；符号链接默认跳过
-l符号链接作为链接复制不带时输出 skipping non-regular file
-p保留权限默认按 umask 生成目标权限
-t保留修改时间时间一致是增量跳过依据
-g / -o保留属组 / 属主-o 需 super-user；-a 已隐含
-D设备 + 特殊文件-a 已隐含
-z传输时压缩3.2.7 默认 zstd（--compress-choice 可选）；默认关闭
-h人类可读数字单独使用等价 --help
-n / --dry-run演练模式不改动文件，统计带 (DRY RUN) 标记
-c / --checksum基于内容校验和判断默认「大小+时间」快速判断，校验算法默认 xxh128
-u / --update跳过目标较新文件防旧数据覆盖新数据
--delete删除目标多余文件等价 --delete-during（传输中删除）
--delete-after传输后删除回显以 building file list ... done 开头
--exclude=PATTERN排除匹配文件可多次使用
--include=PATTERN组合 include 实现只包含与 --exclude='*' 配对，先 include 后 exclude
--exclude-from=FILE从文件读取排除规则每行一条模式，支持 # 注释
--bwlimit=RATE限制带宽默认无限制；单位 KB/s（支持 K/M/G 后缀）
--partial保留不完整文件默认中断删除；-P = --partial --progress
--progress传输进度-P 组合简写
-e ssh指定远程 shell免密配置后直接远程同步
--stats传输统计文件数 / 字节 / 速率
--inplace目标就地更新不写临时文件；中断时目标不完整
--remove-source-files同步后删源文件仅非目录文件
--list-only仅列出清单ls -l 风格，不传输
--max-size=SIZE / --min-size=SIZE按大小过滤默认无限制
-V / --version打印版本3.2.7 两种写法均可用
--mkpath自动创建目标缺失路径3.2 新增
--atimes / -U保留访问时间3.2 新增（-a 不含 -U）
--stop-after=MINS运行 N 分钟后停止3.2 新增
apt-get install -y rsync在线安装源为 archive.ubuntu.com jammy-updates/main
apt-get install -y --reinstall rsync在线重装实测 1 reinstalled（445 kB）
apt-get install -y --reinstall --download-only -o Dir::Cache::archives=<目录> rsync离线只下载不安装已装最新版时 --download-only 无效，需加 --reinstall
dpkg -i /root/off-rsync/rsync_3.2.7-0ubuntu0.22.04.7_amd64.deb离线安装本地 deb实测回显见第四章
apt-get remove -y rsync卸载见第八章

八、卸载方式

在线安装的 rsync 使用 apt-get 卸载：

apt-get remove -y rsync

如需连同配置文件一起彻底清除：

apt-get purge -y rsync

离线场景（使用 dpkg -i 安装）可先用 dpkg -l rsync 确认包状态，再执行上述 apt-get remove/purge，或直接：

dpkg -r rsync

卸载后可用 dpkg -l rsync 或 rsync --version 确认已移除。

💡 说明：Ubuntu 22.04 的 rsync 包自带 /lib/systemd/system/rsync.service（默认 disabled）与 /etc/default/rsync、/etc/init.d/rsync；apt-get remove 会移除二进制与单元文件，apt-get purge 会进一步删除 /etc/default/rsync 等配置文件。若曾手工配置 rsync daemon（如自建 /etc/rsyncd.conf 与防火墙规则），需一并清理。