rdiff-backup 常用 CLI 命令详解

目标：逐条实测 rdiff-backup 2.2.7 的常用 CLI 命令——备份、时点查询、恢复、校验比对、增量清理、仓库修复、统计计算与双机远程全流程，全部命令附真实回显。选项与语法的系统梳理见《rdiff-backup 配置参数详解》，安装与双机免密配置见《Ubuntu 22.04 安装 rdiff-backup 指南》。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（x86_64）；发起端主机名 backup-server，远端备份目标 remote-server（SSH 免密已打通）；
软件版本：rdiff-backup 2.2.7（两端一致）；
实验数据目录：
- 三代备份链：源 /root/dtest/src（a.txt、b.txt、docs/app.conf，中间代曾含 c.txt），仓库 /root/dtest/bak；
- 修复实验：源 /root/dtest/ck-src（f.txt），仓库 /root/dtest/bakR；
- 远程实验仓库：root@remote-server::/root/dtest-bak。

二、工具概览

rdiff-backup 2.2.x 采用「全局选项 + 动作 + 动作选项 + 位置参数」的命令结构，常用动作一览（全部在本篇实测）：

动作	用途	本文实测小节
`backup`	执行一次备份（首轮建镜像，之后存反向增量）	四
`list files/increments`	查询镜像文件清单/历史增量	五
`restore`	从仓库恢复任意时点数据	六
`verify`	校验仓库文件哈希	七
`compare`	比对源目录与仓库（meta/full/hash 三种方法）	七
`remove increments`	清理过期增量	八
`regress`	把仓库回退到上一个一致状态	九
`calculate`	对 session_statistics 做统计计算	十
`test`	测试远端连通性	十一（另见配置篇 7.3）

两个通用语法要素：

位置形态：本地为 [源/仓库路径]；远端为 [USER@]HOST::PATH 三段式；
时间表达式：B（backup，按备份次数）、D/W/M/Y（日/周/月/年）、now（当前），如 2B（两代备份之前）、1M（一个月前）、--at now。适配 --at、--changed-since、--older-than 等时间类选项。

三、前置条件

已安装 rdiff-backup 2.2.7 并完成版本验证（rdiff-backup --version → rdiff-backup 2.2.7）；
双机场景需 SSH 免密与远端安装（安装篇第七章实测流程）；
了解目标仓库现状：操作前先 list increments 确认时间线，清理/修复类命令尤其如此。

四、备份命令详解（backup）

4.1 基本备份与统计输出

首轮备份建立镜像，后续备份记录反向增量：

rdiff-backup backup /root/dtest/src /root/dtest/bak

实测回显（首轮；加 --print-statistics 可输出统计表）：

NOTE: Starting mirror from source path /root/dtest/src to destination path /root/dtest/bak

带统计的增量备份（源目录经历「改 a.txt、增 c.txt」后第二轮）：

rdiff-backup backup --print-statistics /root/dtest/src /root/dtest/bak

实测回显：

NOTE: Starting increment operation from source path /root/dtest/src to destination path /root/dtest/bak
--------------[ Session statistics ]--------------
StartTime 1792647048.00 (Thu Oct 22 06:04:08 2026)
EndTime 1792647048.06 (Thu Oct 22 06:04:08 2026)
ElapsedTime 0.06 (0.06 seconds)
SourceFiles 5
SourceFileSize 39 (39 bytes)
MirrorFiles 4
MirrorFileSize 30 (30 bytes)
NewFiles 1
NewFileSize 9 (9 bytes)
DeletedFiles 0
DeletedFileSize 0 (0 bytes)
ChangedFiles 1
ChangedSourceSize 9 (9 bytes)
ChangedMirrorSize 8 (8 bytes)
IncrementFiles 2
IncrementFileSize 134 (134 bytes)
TotalDestinationSizeChange 143 (143 bytes)
Errors 0
--------------------------------------------------

💡 统计字段解读：SourceFiles/SourceFileSize 本轮源端规模；MirrorFiles/MirrorFileSize 备份前镜像规模；NewFiles 新增；DeletedFiles 删除；ChangedFiles 变更；IncrementFiles 写出的增量文件数；TotalDestinationSizeChange 备份目录净变化；Errors 错误数（0 为健康）。每轮统计同时落盘到 rdiff-backup-data/session_statistics.*.data（第十章用它做计算）。

4.2 include/exclude 规则实测

备份时用筛选参数控制入库范围，规则按命令行顺序「首个匹配生效」：

rdiff-backup backup --exclude "**/*.log" /root/optest/src /root/optest/bak-e3
rdiff-backup list files /root/optest/bak-e3

实测回显：

.
a.txt
big.bin
sub1
sub1/c1.conf
sub1/sub11
sub1/sub11/deep.txt
sub2

💡 说明：**/*.log 跨层级排除了 b.log 与 sub2/app.log。filelist 文件（--include-filelist/--exclude-filelist/--include-globbing-filelist）、null 分隔与「尾部 include 冗余保护」的完整实测见《rdiff-backup 配置参数详解》第五章。

4.3 --current-time：构造可控时间线（测试/实验）

rdiff-backup --current-time 1791740012 backup /root/dtest/ck-src /root/dtest/bakR
rdiff-backup --current-time 1791826412 backup /root/dtest/ck-src /root/dtest/bakR
rdiff-backup list increments /root/dtest/bakR

实测回显：

Found 1 increments:
    increments.2026-10-11T17:33:32Z.dir   Sun Oct 11 17:33:32 2026
Current mirror: Mon Oct 12 17:33:32 2026

💡 说明：两轮备份被伪造成 10 月 11 日与 10 月 12 日，时间线完全可控——模拟「长期增量链」的实验利器。生产脚本中不要使用；连续真实备份间隔小于 1 秒会报 ERROR: The last backup is not in the past. Aborting.（实测）。

五、查询命令详解（list）

5.1 list files：清单、时点与变更

三代链现状：gen1 建（a/b/docs），gen2 改 a.txt、增 c.txt，gen3 改 docs/app.conf、删 c.txt。

rdiff-backup list files /root/dtest/bak                  # 当前镜像
rdiff-backup list files --at 2B /root/dtest/bak          # 两代备份之前
rdiff-backup list files --changed-since 2B /root/dtest/bak

实测回显：

.
a.txt
b.txt
docs
docs/app.conf

.
a.txt
b.txt
docs
docs/app.conf

changed .
changed a.txt
changed docs/app.conf

💡 说明：--at 2B 回看两代（无 c.txt 的 gen1 状态）；--changed-since 2B 列出其间发生变化的路径（changed 前缀）。时间表达式 B 按备份次数计，1D/1W/1M/1Y 按自然时间计。

5.2 list increments 与增量文件格式

rdiff-backup list increments /root/dtest/bak
ls -R /root/dtest/bak/rdiff-backup-data/increments/

实测回显：

Found 2 increments:
    increments.2026-10-22T06:04:08Z.dir   Thu Oct 22 06:04:08 2026
    increments.2026-10-22T06:04:10Z.dir   Thu Oct 22 06:04:10 2026
Current mirror: Thu Oct 22 06:04:12 2026

/root/dtest/bak/rdiff-backup-data/increments/:
a.txt.2026-10-22T06:04:08Z.diff.gz
c.txt.2026-10-22T06:04:08Z.missing
c.txt.2026-10-22T06:04:10Z.snapshot.gz
docs
docs.2026-10-22T06:04:10Z.dir

/root/dtest/bak/rdiff-backup-data/increments/docs:
app.conf.2026-10-22T06:04:10Z.diff.gz

💡 增量文件类型解读（以实测清单为准）：

<文件>.<时间戳>Z.diff.gz：相对上一状态的反向差分（文本类 gzip 压缩，二进制同后缀无 .gz 取决于压缩策略）；

<文件>.<时间戳>Z.snapshot.gz：新文件首次入库的完整快照（如 gen2 新增的 c.txt）；

<文件>.<时间戳>Z.missing：删除标记（gen3 删除的 c.txt）；

increments.<时间戳>Z.dir：会话快照壳目录，list increments 逐行展示的就是它们；

时间戳格式统一为 UTC YYYY-MM-DDTHH:MM:SSZ。

六、恢复命令详解（restore）

6.1 --at/--now 指定时间点恢复

rdiff-backup restore --at now /root/dtest/bak/a.txt /root/dtest/restored-a.txt
cat /root/dtest/restored-a.txt
rdiff-backup restore --at 2B /root/dtest/bak/a.txt /root/dtest/restored-a-v1.txt
cat /root/dtest/restored-a-v1.txt

实测回显：

version-2
version-1

💡 说明：--at now 取镜像当前态（version-2），--at 2B 回退两代（version-1）——反向增量把镜像「往回推」到目标时点。被删除的文件同样可恢复（c.txt 在 gen2 存在）：

rdiff-backup restore --at 1B /root/dtest/bak/c.txt /root/dtest/restored-c.txt
cat /root/dtest/restored-c.txt

实测回显：

new-file

6.2 整目录恢复与 --force 覆盖

rdiff-backup restore --at now /root/dtest/bak /root/dtest/restored-whole
ls /root/dtest/restored-whole

实测回显：

a.txt
b.txt
docs

目标已存在且非空时，实测报错并明确提示加 --force：

rdiff-backup restore --at now /root/dtest/bak /root/dtest/restored-whole

ERROR: Target path /root/dtest/restored-whole exists and isn't empty, call with '--force' to overwrite
ERROR: Action restore failed on step check

--force 是全局选项，必须写在动作之前（写在动作后会报 usage 错，实测）：

rdiff-backup --force restore --at now /root/dtest/bak /root/dtest/restored-whole

实测回显（覆盖成功，无 ERROR）：

（无错误输出，目录被覆盖为镜像当前态）

⚠️ 注意：--force 覆盖恢复不删除目标目录中的多余文件，只覆盖同名路径；需要干净恢复目标时先自行清空目标目录。

七、校验与比对（verify / compare）

7.1 verify：哈希校验

rdiff-backup verify /root/dtest/bak
rdiff-backup verify --at 2B /root/dtest/bak

实测回显：

NOTE: All files verified successfully
NOTE: All files verified successfully

💡 说明：verify 对仓库（默认当前镜像，--at 指定历史时点）逐一重算哈希与元数据记录比对；大仓库耗时与数据量成正比，适合定期低频执行。

7.2 compare：三种比对方法

compare 支持 --method {meta,full,hash}（compare --help 实测）：meta 只比元数据（默认）、full 逐字节全量比对、hash 重算内容哈希比对；--at 可与历史时点比。

rdiff-backup compare /root/dtest/src /root/dtest/bak
rdiff-backup compare --method hash /root/dtest/src /root/dtest/bak
rdiff-backup compare --method full /root/dtest/src /root/dtest/bak
rdiff-backup compare --method full --at 2B /root/dtest/src /root/dtest/bak

实测回显：

NOTE: No changes found. Directory matches archive data.
NOTE: No changes found. Directory matches archive data.
NOTE: No changes found. Directory matches archive data.
ERROR: Action compare failed on step run
changed: .
deleted: c.txt
metadata changed, data changed: docs/app.conf

💡 说明：前三条（与当前镜像比）无差异；第四条与两代前状态比对时报告 changed/deleted/metadata changed 明细，且发现差异时以 ERROR 结束（非零退出码）——可直接用于脚本化一致性检查。hash 与 full 的差别：full 传输比对全部字节，hash 只在本地重算哈希后比对仓库记录，远端场景 hash 更省带宽。

7.3 旧式比对选项的兼容现状

旧语法 --compare-hash 在 2.2.7 仍被兼容（实测）：

rdiff-backup --compare-hash /root/dtest/src /root/dtest/bak

NOTE: No changes found. Directory matches archive data.

而老版本的 --compare-verify-atime 已移除，实测报 usage 错误（rdiff-backup --help all 中亦无任何 atime 选项）。新脚本一律使用 compare --method ...。

八、增量清理（remove increments）

8.1 --older-than 清理实测

rdiff-backup list increments /root/dtest/bak
rdiff-backup remove increments --older-than 1B /root/dtest/bak
rdiff-backup list increments /root/dtest/bak

实测回显：

Found 2 increments:
    increments.2026-10-22T06:04:08Z.dir   Thu Oct 22 06:04:08 2026
    increments.2026-10-22T06:04:10Z.dir   Thu Oct 22 06:04:10 2026
Current mirror: Thu Oct 22 06:04:12 2026

NOTE: Deleting increment at date/time: Thu Oct 22 06:04:08 2026

Found 1 increments:
    increments.2026-10-22T06:04:10Z.dir   Thu Oct 22 06:04:10 2026
Current mirror: Thu Oct 22 06:04:12 2026

💡 说明：--older-than 1B 删除「1 代备份之前」的增量（只删 06:04:08，保留 06:04:10），对应时点（gen1）从此不可恢复。镜像本身不受影响。保留策略建议：生产上按容量与恢复窗口定一个 3M（三个月）级别的阈值，放进 cron/timer 周期执行。

8.2 --force 的适用边界

实测 2.2.7 中 remove increments 未强制要求 --force（连 --older-than now 删光全部增量也直接执行，实测回显 NOTE: Deleting increment at date/time: ...）；--force 真正被强制要求的是恢复覆盖非空目录等危险动作（见 6.2 实测报错）。执行 remove 前先 list increments 核对时间线，是比 --force 更可靠的保护。

九、仓库修复（regress）

9.1 备份中断的两种实测结局

结局一：中段击杀备份进程，下次备份直接续完。 对 800MB 级源目录在备份进行到 3 秒时 kill -9 备份进程（实测），仓库留下已写入的镜像与 current_mirror 标记；随后再次执行 backup：

rdiff-backup backup /root/dtest/bigsrc /root/dtest/bigr

实测回显（直接继续并完成，未要求 regress）：

NOTE: Starting increment operation from source path /root/dtest/bigsrc to destination path /root/dtest/bigr

结局二：仓库遗留「双 current_mirror 标记」（中断会话的落盘特征），备份被拒。 用三代链仓库复制一份更早时间的标记模拟（实测构造方法：cp current_mirror.<新>.data current_mirror.<旧>.data）：

rdiff-backup backup /root/dtest/ck-src /root/dtest/bakR

实测回显（直接备份被拒）：

ERROR: Either there is more than one current_mirror or the last backup is not in the past. Aborting.
ERROR: Action backup failed on step run

9.2 自动 regress 与手动 regress

同一双标记仓库再跑 backup 时，rdiff-backup 在会话开头自动 regress 后继续备份（实测）：

NOTE: Regressing to date/time Sun Oct 11 17:33:32 2026
NOTE: Starting increment operation from source path /root/dtest/ck-src to destination path /root/dtest/bakR

也可在备份前手动 regress（实测）：

rdiff-backup regress /root/dtest/bakR
ls /root/dtest/bakR/rdiff-backup-data/current_mirror*

实测回显：

NOTE: Regressing to date/time Sun Oct 11 17:33:32 2026
current_mirror.2026-10-11T17:33:32Z.data

💡 说明：regress 把仓库回退到最早的 current_mirror 标记时间，清理其后未完成的增量与多余标记（实测标记从两个收敛为一个）；随后备份正常执行。健康仓库执行 regress 会实测提示 NOTE: Given repository doesn't need to be regressed，无副作用，可放心作为「备份报错后的第一步」。

十、统计计算（calculate）

calculate 对落盘的 session_statistics 文件做统计（默认 average，多文件求平均）：

rdiff-backup calculate /root/dtest/bak/rdiff-backup-data/session_statistics.*.data

实测回显：

--------------[ Average of 1 stat files ]--------------
ElapsedTime 0.57 (0.57 seconds)
SourceFiles 5.0
SourceFileSize 22.0 (22 bytes)
MirrorFiles 6.0
MirrorFileSize 31.0 (31 bytes)
NewFiles 0.0
NewFileSize 0.0 (0 bytes)
DeletedFiles 1.0
DeletedFileSize 9.0 (9 bytes)
ChangedFiles 3.0
ChangedSourceSize 7.0 (7 bytes)
ChangedMirrorSize 7.0 (7 bytes)
IncrementFiles 4.0
IncrementFileSize 133.0 (133 bytes)
TotalDestinationSizeChange 124.0 (124 bytes)

⚠️ 注意：average 不是位置子命令而是 --method 选项（calculate --help 实测：usage: calculate [-h] [--method {average}] STATISTIC_FILE ...）。误写成 rdiff-backup calculate average <文件> 会把 "average" 当文件名，实测报 FileNotFoundError: [Errno 2] No such file or directory: b'average'。老版本的 --backup-statistics（分析 file_statistics）在 2.2.7 已移除（实测报 usage 错）。

十一、双机 remote 场景（user@host::/path）

四类核心动作全部支持远端三段式语法（远端 remote-server 已装 2.2.7 并免密）：

rdiff-backup backup /root/dtest/ck-src root@remote-server::/root/dtest-bak
rdiff-backup list files root@remote-server::/root/dtest-bak
rdiff-backup list increments root@remote-server::/root/dtest-bak
rdiff-backup restore root@remote-server::/root/dtest-bak/f.txt /root/dtest/remote-f.txt
cat /root/dtest/remote-f.txt
rdiff-backup remove increments --older-than now root@remote-server::/root/dtest-bak
rdiff-backup list increments root@remote-server::/root/dtest-bak

实测回显：

.
f.txt

Found 0 increments:
Current mirror: Thu Oct 22 06:13:15 2026

v2

Found 0 increments:
Current mirror: Thu Oct 22 06:13:15 2026

💡 说明：list/restore/remove 只需把仓库路径换成 user@host::path 即可对远端仓库操作，输出与本地完全同构；备份方向相反时（pull 模式）把源写成远端路径、目标写本地路径即可。连接失败排查先用 rdiff-backup test root@remote-server::/root/dtest-bak（实测 - Server OK）。远端启动命令、--remote-schema/--remote-tempdir/--no-ssh-compression 的实测见《rdiff-backup 配置参数详解》第七章。

十二、注意事项

危险命令先查时间线：remove increments、regress 前先 list increments；增量删除后对应时点不可恢复；
全局选项位置：--force、--null-separator、--current-time、--api-version 等必须写在动作名之前，写在动作后实测报 unrecognized arguments；
备份间隔：连续两次备份间隔不足 1 秒会被拒（The last backup is not in the past.），脚本中 sleep 1 以上；
同版本对同版本：跨机两端保持同一 2.2.x 版本；2.0.5 不识别新动作语法（实测 Switches missing or wrong number of arguments，见配置篇 9.3）；
恢复验证：重要恢复操作后用 verify + compare（或抽查 cat）确认内容正确，本文 6.1 的 cat 回显即示范。

十三、常见问题（FAQ）

Q1：rdiff-backup backup 报 Either there is more than one current_mirror or the last backup is not in the past. Aborting.？ 仓库有中断会话遗留的双 current_mirror 标记（9.1 实测复现）。处理：执行 rdiff-backup regress <仓库>（或直接重跑 backup，2.2.7 会自动 regress），回显 NOTE: Regressing to date/time ... 即修复完成。

Q2：restore 报 Target path ... exists and isn't empty, call with '--force' to overwrite？ 按提示把 --force 写在动作之前：rdiff-backup --force restore ...（写在动作后是 usage 错误，实测）。

Q3：calculate 报 FileNotFoundError: ... b'average'？ average 是 --method 选项不是子命令：rdiff-backup calculate <统计文件...>（默认 average），写法见第十章。

Q4：remove increments --older-than 删错了还能恢复吗？ 不能——被删除增量对应时点的历史即刻消失，镜像（当前态）不受影响。误删后唯一补救是从仍存在的增量恢复较早时点（list increments 先看剩余时间线）。

十四、参考链接

官方 man 手册：https://rdiff-backup.net/rdiff-backup.1.html
官方使用示例：https://rdiff-backup.net/examples.html
官方 FAQ：https://rdiff-backup.net/FAQ.html
站内相关篇目：《rdiff-backup 介绍与选型指南》、《Ubuntu 22.04 安装 rdiff-backup 指南》、《rdiff-backup 配置参数详解》