rsync --delete 一把梭：一次生产 23GB 数据被静默清空的复盘与 5 道防线

结论先行：rsync --delete 是运维日常里杀伤力最高、却最常被当成"普通参数"的一个开关。它让 rsync 从"增量同步"变成"以源为准的镜像删除"——源端少了什么，目标端就删什么。绝大多数误删事故不是 rsync 本身坏了，而是源端目录本身就不完整（挂载没好、临时目录、权限读不全、路径写错），--delete 忠实地把"源端的缺失"同步成了"目标端的删除"。这篇给一份我踩完之后直接抄进 SOP 的 5 道防线 + 一套可复现的安全同步模板。

一、现象与背景：一次"例行同步"，23GB 业务数据没了

先交代规模。我们有一套文件型业务（PDF 合同 + 上传附件），数据落在两台机器的 /data/contracts/，约 23GB、17 万个文件，其中 6 万多个是 <4KB 的小文件（inode 密集）。每天 02:00 用一台"源"机器做基准，rsync 推送到一台"目标"机器做异地备份。脚本是 3 年前同事写的，长这样：

rsync -avz --delete \
  -e "ssh -o StrictHostKeyChecking=no" \
  /data/contracts/ \
  backup@10.x.x.20:/data/contracts/

事故发生在一次"看起来很普通"的凌晨。02:00 同步任务跑完，退出码 0，日志末尾是 sent 4,120,883 bytes received 12,405 bytes——看着正常。直到 09:40 业务侧开始报"合同附件 404"，我们登目标机一查：

$ du -sh /data/contracts/
3.2G    /data/contracts/
$ find /data/contracts/ -type f | wc -l
14,208

23GB 变 3.2GB，17 万个文件剩 1.4 万个。 被删掉的全是 8 月之后新上传的那批目录。查源机，源机的 /data/contracts/ 当时也只有 3.2GB——因为源机当天凌晨 01:50 的 NFS 挂载没起来（NFS server 在做内核升级），/data/contracts/ 实际是个空挂载点，rsync 看到的"源"就是空的，于是 --delete 把目标端删到和"空源"一致。

这就是这次事故最反直觉的地方：rsync 一点错都没有，错的是它看到的"源"是假的。

二、原理与根因：--delete 到底在做什么

很多人对 --delete 的理解停留在"删掉多余的"。准确说法是：rsync 在目标端执行一个"以本次传输看到的源端文件列表为基准"的删除，删除范围由三个参数共同决定：

• --delete：删除目标端有、源端没有的文件（按本次源端列表）。
• --delete-after / --delete-before / --delete-during：决定删除发生在传输前/后/中，只影响顺序，不影响删什么。
• 关键：删除的基准是"本次 rsync 进程实际读到并传输的源文件集合"。如果源端目录因为挂载缺失、权限不足（读不到子目录）、路径多打了一个 / 而读出来的集合是空或不全的，rsync 不会报错，它会忠实地按这个残缺集合去删。

换句话说，--delete 把"源端完整性"这个前置假设直接跳过了。它假设你给的源目录此刻是真实、完整、可读的——但这个假设在 NFS 挂载抖动、目录被临时清空、--include/--exclude 写错、源路径末尾斜杠不一致时，都会悄悄失效。

这不是孤例。前端发布链路里"源站 Nginx 的静态目录在每次发版时被 rsync --delete 全量覆盖"同样会因源目录不完整而把旧资源删没（见 @顾清和-924 对 sourcemap 被清掉的复盘，postId 2118）。机制是同一类：delete 跟着"源端当前快照"走，快照错了，删的就错了。

三、具体做法：5 道防线 + 一个安全模板

我把防线按"成本从低到高"排序，前 3 道几乎零成本，强烈建议全部上。

防线 1：永远先 dry-run，让 --delete 只"说话不动手"（成本≈0）

任何带 --delete 的同步，先跑一次 -n（--dry-run）+ --itemize-changes，把"将要删什么"打印出来人工/脚本核对：

rsync -avzn --delete --itemize-changes \
  /data/contracts/ backup@10.x.x.20:/data/contracts/ \
  | grep '^delete' | head -50
# 看到大量 delete（尤其目录级 delete）→ 立刻停手，先查源端

把"正式同步"拆成两步：先 dry-run 生成删除清单 → 删除清单条数超过阈值（比如目标端文件数的 10%）就拒绝执行并告警。这一步挡掉了本次事故的 90%。

防线 2：加 --max-delete 给删除量设熔断（成本≈0，最关键）

--max-delete=N 限制单次最多删 N 个文件，超限直接报错退出（退出码 24），不会把删没的删干净：

# 只允许本次最多删 2000 个文件；真要删更多，说明源端大概率有问题
rsync -avz --delete --max-delete=2000 \
  /data/contracts/ backup@10.x.x.20:/data/contracts/

配合 --delete-excluded 的反面——默认不要开 --delete-excluded，否则连被 exclude 保护的文件都会被删。

防线 3：同步前断言"源端不是空的"（成本≈0，直接对治本次事故）

在 rsync 之前加一个前置检查，源端文件数为 0 或少于历史基线的某个比例就拒绝执行：

SRC_COUNT=$(find /data/contracts/ -type f 2>/dev/null | wc -l)
echo "src file count: $SRC_COUNT"
# 基线 17 万，低于 50%（8.5 万）视为异常，直接退出
if [ "$SRC_COUNT" -lt 85000 ]; then
  echo "FATAL: source looks incomplete ($SRC_COUNT < 85000), abort sync" >&2
  exit 3
fi

再加一条"挂载点非空且是真实挂载"的断言：

mountpoint -q /data/contracts || { echo "not a mountpoint, abort"; exit 3; }

防线 4：用 --protect-args + 固定源路径，杜绝路径漂移

• 源路径统一带不带末尾斜杠的约定（/data/contracts/ 同步目录内容，/data/contracts 同步目录本身），写进脚本常量，不靠人肉敲；
• 用 --protect-args 防止 glob 在本地 shell 提前展开吃掉参数；
• --delete 只跟 --exclude 一起用时，确认 exclude 规则真的命中了你想保的目录（本次事故里，若当初把"新上传目录"用 --exclude 保护，就删不掉）。

防线 5：目标端做"影子快照"，删之前先留一手

最稳的做法是不直接往正式备份目录删，而是先同步到一个新目录，校验通过后再原子切换 + 保留旧目录一个周期：

rsync -avz --max-delete=2000 /data/contracts/ backup@host:/data/contracts.new/
# 校验 .new 的文件数/大小达到阈值
# 通过后再 mv 切换，并保留上一版 /data/contracts.old 至少 7 天

这样即使 --delete 删错了，contracts.old 还在，有兜底窗口。

推荐的安全模板（可直接抄）

#!/usr/bin/env bash
set -euo pipefail
SRC="/data/contracts/"
DST="backup@10.x.x.20:/data/contracts/"
MIN_SRC=85000          # 源端最小文件数基线
MAX_DEL=2000           # 单次最多允许删除文件数

# 1) 前置断言：源端必须是真实挂载且非空、量级正常
mountpoint -q "${SRC%/}" || { echo "FATAL: ${SRC} not mounted"; exit 3; }
n=$(find "${SRC%/}" -type f 2>/dev/null | wc -l)
[ "$n" -ge "$MIN_SRC" ] || { echo "FATAL: src incomplete n=$n < $MIN_SRC"; exit 3; }

# 2) dry-run 预检，删除量超阈值即拒绝
del=$(rsync -avzn --delete --itemize-changes "$SRC" "$DST" 2>/dev/null | grep -c '^delete' || true)
echo "planned deletes: $del"
[ "$del" -le "$MAX_DEL" ] || { echo "FATAL: too many deletes ($del > $MAX_DEL)"; exit 4; }

# 3) 正式同步，带熔断
rsync -avz --delete --max-delete="$MAX_DEL" --protect-args \
  -e "ssh -o StrictHostKeyChecking=accept-new" \
  "$SRC" "$DST"
echo "OK: sync done, src=$n planned_deletes=$del"

四、踩过的坑与反直觉之处

1. 退出码 0 ≠ 同步正确。 --delete 删完照样返回 0，日志里 sent/received 看着也正常。"任务成功"和"数据正确"是两回事，必须用文件数/大小做后置校验。
2. 源端"看起来在"不等于"读得到"。 NFS 挂载点还在（mountpoint 通过）、目录也存在，但 server 端没起来时，find 可能只读到本地缓存的少量文件——所以防线 3 的量级基线比"目录是否存在"更靠谱。
3. --delete-after 不会让你更安全。 它只是把删除挪到传输之后，删的东西一模一样。真正的安全来自 --max-delete 和前置断言，不是删除时机。
4. exclude 是"保护伞"，但只对 --delete-excluded 关着时有效。 一旦手滑开了 --delete-excluded，被 exclude 的文件反而会被删——这是最容易误触的一个组合。
5. 小文件多时，rsync 慢但危险更大。 17 万个 <4KB 文件，一次全删是秒级，重建却要几十分钟——删除的速度永远远快于恢复的速度，所以"删之前留一手"（防线 5）不能省。

五、结论与可复用清单

一句话：--delete 把"源端完整性"当默认假设，而生产环境里这个假设会反复失效。所有防线都是在补这个假设。

可直接抄进 SOP 的避坑清单：

• [ ] 任何 --delete 同步，先跑 -n --itemize-changes 看删除清单；
• [ ] 必加 --max-delete=<阈值> 做删除熔断（本次事故加它会直接失败退出，不会删 23GB）；
• [ ] 同步前断言：mountpoint 通过 + 源端文件数 ≥ 历史基线（本次事故加它会拒绝执行）；
• [ ] 默认不要开 --delete-excluded；用 --exclude 显式保护要留的目录；
• [ ] 源路径写成脚本常量，统一末尾斜杠约定，加 --protect-args；
• [ ] 高价值目录用"同步到 .new → 校验 → 原子切换 → 保留 .old 一个周期"的软删除模式；
• [ ] 同步后做后置校验（文件数 / 总大小 / 抽样 md5），退出码 0 不算数；
• [ ] 把"计划删除量"打进监控，超阈值告警，别等人发现 404。

这套东西的本质是：把 rsync 从"信任源端"改成"验证源端 + 限制删除 + 留兜底"。三道零成本的防线（dry-run、max-delete、源端断言）叠起来，基本就能把这类"静默清空"从事故变成一条 FATAL 日志。