使用 rsync 上传下载文件：详解原理、目录同步和常见问题

在日常运维、开发和备份任务中，rsync 是一个非常实用且高效的文件同步工具。它不仅支持本地文件同步，还能通过网络将文件传输到远程服务器，广泛应用于应用部署、定时备份、集群同步等场景。若使用 rsync 协议的传输方式，可以参考我的另一篇文章基于 rsync + lsyncd 的高效文件传输系统架构设计及实践指南

一、什么是 rsync？

rsync（remote sync）是一个开源的远程数据同步工具，适用于类 Unix 系统。它可以高效地将文件或目录同步到本地或远程主机，并且几乎所有 Linux 发行版都内置了 rsync 工具。 rsync 的主要功能包括：

将本地文件/目录同步到远程主机
将远程主机的文件/目录同步到本地
支持断点续传和增量备份
支持压缩传输、保留文件权限、软链接、时间戳等属性
传输时只复制发生变化的部分，节省带宽和时间

二、rsync 的工作原理

rsync 使用一种名为 “差异算法”（delta-transfer algorithm）的技术，在源文件和目标文件之间进行比对，只同步修改部分，从而达到高效传输的目的。其传输过程一般包括以下步骤： 1、客户端和服务端协商文件列表和属性（文件大小、修改时间、权限等） 2、通过对比生成校验和，只传输有差异的部分 3、在传输过程中可选择压缩（如 -z 参数），进一步提升效率 4、支持基于 SSH 或 rsync 协议的传输方式

三、rsync 的基本用法

1、上传文件到远程服务器：

rsync -avhz –progress /path/to/local/file user@remote:/path/to/remote/

命令执行后，你需要输入 user@remote 账户的 SSH 登录密码，若不想输入需要提前配置免密认证，要实现免密认证登录，需要先生成 SSH 密钥对，然后将公钥复制到远程服务器上。 2、从远程服务器下载文件：

rsync -avhz –progress user@remote:/path/to/remote/file /path/to/local/

参数说明：

-a：归档模式，递归传输，并保留文件权限等
-v：显示详细信息（verbose）
-z：压缩数据传输
-h：以人类可读方式显示文件大小
-z：压缩数据传输
–progress：显示传输进度
-e ssh：通过 SSH 协议传输（默认也会使用）

四、目录同步的关键问题：斜杠（/）

这是 rsync 最容易引起误解的地方：

示例一：带斜杠

rsync -av /src/ /dst/

效果：将 /src/ 目录中的内容同步到 /dst/，不包含 /src/ 目录本身。

示例二：不带斜杠

rsync -av /src /dst/

效果：将整个 /src 目录（包括目录本身）复制到 /dst/，目标路径将变为 /dst/src/ 总结：是否加尾部 /，决定是否拷贝目录本身。这个差异在自动化脚本中尤其重要！

五、常见问题及处理方法

1、rsync: command not found

可能是目标主机未安装 rsync，执行以下命令安装：

Debian/Ubuntu:

sudo apt install rsync

CentOS/RHEL:

sudo yum install rsync

2、Permission denied

常见于使用 SSH 连接时没有权限。请确认：

是否可以 SSH 登录远程主机？
用户权限是否允许访问指定目录？
目标目录是否存在，权限是否可写？

3、目标文件被覆盖

请特别注意目录末尾的 / 问题，错误使用会导致结构不一致。例如本意是更新目录内容，但却替换了整个目录。

4、符号链接未正确复制

使用 -a 参数时默认会保持符号链接。如果需要将链接指向的真实文件复制，可以加 -L 参数：

rsync -avL /src/ /dst/

5、避免同步隐藏文件失败

rsync 默认会同步隐藏文件，但确保你的 shell 命令写法正确，例如：

rsync -av /src/ /dst/

不要遗漏目录前的 . 文件，建议使用通配符时加引号或用完整路径明确匹配。比如假设目录 /myapp/ 下有这些文件：

index.html
app.js
.env
.gitignore

错误写法：

rsync -av /myapp/* user@remote:/backup/

✅ 同步了 index.html 和 app.js ❌ 但 **没有同步 .env 和 **.gitignore，因为 * 不会匹配隐藏文件！

正确写法 1：加引号保留通配符，由 rsync 自己解析

rsync -av "/myapp/" user@remote:/backup/

或

rsync -av "/myapp/." user@remote:/backup/

✅ 这会同步整个目录内容，包括隐藏文件（注意尾部 / 或 /.）。

正确写法 2：用完整路径

rsync -av /myapp/ user@remote:/backup/

✅ 直接指定目录，不用通配符，就不会漏掉任何文件，包括隐藏文件。

六、附加技巧

1、干跑（预览）模式：

“干跑（预览）模式”是指在执行 rsync 命令时，不真的进行文件同步，而是模拟运行一遍，把即将执行的操作显示出来，让你提前知道哪些文件将被复制、删除或跳过。

rsync -avn /src/ /dst/

加 -n（或 –dry-run）参数可以预览同步内容，非常适合测试脚本或验证路径是否正确。

2、删除目标中多余文件（保持完全同步）：

rsync -av –delete /src/ /dst/

3、定时任务结合 cron 做定期同步：

编辑定时任务：

crontab -e

添加如下内容实现每晚 1 点同步：

0 1 * * * rsync -az /src/ user@remote:/backup/ >> /var/log/rsync.log 2>&1

4、限速同步（控制带宽占用）：

如果你在生产环境运行 rsync，为了防止占满网络带宽，可以加上 –bwlimit=KBps 参数。示例：

rsync -avz –bwlimit=500 –progress /src/ user@remote:/dst/

✅ 表示将同步速度限制为 500KB/s，避免影响其他业务。

使用建议：

值是每秒的最大传输速率（单位：KB/s）
特别适合在业务高峰期间同步大文件时使用

总结

rsync 是一款功能强大、配置灵活的同步工具。在使用时要特别注意目录路径的斜杠用法，以避免结构错误或误删除。配合 cron 等工具还能构建自动化备份方案。了解其原理和常见问题的解决方法，可以帮助你更加安全高效地使用 rsync。

结语

💬 重点提醒：喜欢请加关注哦！ 📣 更多原创内容、技术干货，欢迎关注「键上江湖」，与你一键相逢！

使用 rsync 上传下载文件：详解原理、目录同步和常见问题