rsync 删除文件过多时怎么用 --max-delete 保护目标目录

使用 rsync --delete 做镜像同步时，最危险的现场通常不是“复制变慢”，而是源目录突然少了很多文件，目标目录于是出现一大批删除候选。先不要把阈值调得很大：用 --max-delete 给目标端删除动作加一道数量闸门，再用退出码判断这次同步是否被保护机制拦住。

--max-delete=NUM 限制 rsync 最多删除 NUM 个文件或目录；超过上限后，后续删除会被跳过，并通常以退出码 25 结束。排查时可先用 --max-delete=0 观察删除风险，确认源路径和过滤规则没有问题后，再设置一个符合业务容忍度的正数。

先确认风险来自目标端删除

rsync 会比较源目录和目标目录。启用 --delete 后，目标端那些在源目录中已经不存在的项会进入删除候选；这和“源端有新文件要传过去”是两类动作。误把源目录挂载点、工作目录或过滤规则改错，就可能让候选删除数量突然上升。

因此，--max-delete=50 的含义不是“最多同步 50 个文件”，而是“最多执行 50 个目标端删除”。新增和更新文件仍按其它 rsync 选项处理，但删除动作达到阈值后，后续删除会被跳过。

先用预演找出异常删除规模

第一次处理“大量删除”时，优先使用预演。--dry-run 会让本次同步不改动目标目录；再配合 --itemize-changes，可以把变化类型列出来。下面的命令把删除上限设为 0，目的只是让 rsync 对目标端多余项发出提示，不执行删除。

#!/usr/bin/env bash
set -u

source_dir="/srv/app-current/"
target_dir="/srv/app-mirror/"

# 先预演并启用镜像删除语义，但不修改目标目录。
rsync -a --delete --dry-run --itemize-changes \
    --max-delete=0 "$source_dir" "$target_dir"
preview_status=$?

# 预演本身失败时先修正路径、权限或连接，不要进入正式删除。
if [ "$preview_status" -ne 0 ]; then
    echo "rsync preview failed: $preview_status" >&2
    exit "$preview_status"
fi

这里的重点不是追求一个“漂亮的输出”，而是确认删除候选是否符合预期：数量突然从几十变成几万，通常应先检查源目录是否挂载成功、路径末尾斜杠是否符合意图、--exclude 规则是否刚被修改，以及目标目录是否确实是要维护的镜像。

正式同步时设置删除上限

确认预演结果后，再把阈值设置成一个可解释的数量。例如业务允许一次镜像最多删除 50 个条目，可以这样写：

#!/usr/bin/env bash
set -u

source_dir="/srv/app-current/"
target_dir="/srv/app-mirror/"
delete_limit=50

# 正式同步允许更新内容，但把目标端删除数量限制在 50 个以内。
rsync -a --delete --itemize-changes \
    --max-delete="$delete_limit" "$source_dir" "$target_dir"
sync_status=$?

# 退出码 25 表示删除闸门触发，必须让调度系统看到这次未完整收敛。
if [ "$sync_status" -eq 25 ]; then
    echo "delete limit reached; inspect the source and filter rules" >&2
    exit 25
fi

# 其它非零值代表还有连接、权限或文件处理等执行问题。
if [ "$sync_status" -ne 0 ]; then
    echo "rsync failed: $sync_status" >&2
    exit "$sync_status"
fi

echo "mirror sync completed within the delete limit"

如果本次只跳过删除而其它文件已经传输，目标目录就可能处于“部分更新、部分旧文件仍在”的中间状态。调度脚本不应因为命令有输出或部分文件变化就记录为完整镜像；应保留退出码、同步日志和本次源目录版本，等原因修正后再重新规划一次同步。

退出码 25 应该怎么处理

rsync 手册把退出码 25 定义为“--max-delete 限制阻止了删除”。它和连接失败、权限错误、部分传输并不是同一类问题。脚本至少要把 25 单独记录，提醒值班人员先看删除候选，而不是简单重试同一条命令。

重复重试不会自动修复错误的源路径。如果源目录仍然为空、挂载还没就绪，或排除规则仍然把大量文件隐藏掉，每次重试都可能再次触发保护。更安全的顺序是：保留本次输出，确认源目录内容和过滤规则，必要时先恢复正确的源状态，再决定是否重新同步。

几个容易把阈值用错的现场

• 把它当成总文件数上限：--max-delete 只限制删除，不限制新文件传输或更新文件数量。
• 没有启用删除语义却期待它报警：若命令没有产生目标端删除候选，阈值不会凭空变成全局变更保护器。
• 把 0 当作“无限制”：现代 rsync 中，--max-delete=0 用于发现目标多余项而不删除；不能据此推断为无限允许删除。
• 只看退出码 0：成功退出只能说明本次命令没有报告错误，仍要结合命令参数确认自己是否真的启用了想要的镜像语义。

速查表：预演、正式同步和异常分支

排查清单

1. 确认目标目录是否真的是当前源目录的镜像，不要把生产目录误当成同步目标。
2. 先用 --dry-run --max-delete=0 看删除候选，再决定是否正式运行。
3. 检查源目录挂载、路径末尾斜杠、包含与排除规则，以及远端连接状态。
4. 正式运行时设置一个有业务含义的正数阈值，并保留输出与退出码。
5. 把退出码 25 与普通传输错误分开告警，不要静默重试原命令。
6. 确认保护触发后目标可能是部分更新状态，后续动作应以人工或修复后的新计划为准。

常见问题

--max-delete 能阻止源目录文件被删除吗？

不能。它限制的是同步过程中目标端的删除动作；源端文件是否删除取决于你是否使用了其它会删除源文件的选项或脚本。

--max-delete=0 和 --dry-run 有什么区别？

--dry-run 让整次同步不落地修改；--max-delete=0 专门把目标端删除上限设为 0，让多余项成为可见风险。排查阶段可以同时使用，含义更清楚。

退出码 25 后直接把阈值调大可以吗？

不建议。先确认删除数量变大的原因。如果是源目录错误或过滤规则错误，调大阈值只会放大误删范围；只有在候选删除确实符合镜像预期时，才重新选择阈值。

把 rsync 的删除保护落到实处，核心顺序就是“先预演、再限量、看退出码、修输入”。--max-delete 不是备份系统本身，却能为镜像同步增加一个明确的故障刹车点。