Restic 常用 CLI 命令详解

目标：系统讲解 restic v0.16.4 的常用命令行。restic 命令统一为 restic <command> <参数>，核心生命周期为「初始化仓库 → 创建备份 → 查看快照 → 校验 → 恢复还原 → 清理 → 密钥管理」。本文按此流程分组讲解，所有回显来自 S3 后端（MinIO）的真实执行。

一、环境信息与准备

restic 版本：v0.16.4
仓库后端：S3 兼容 MinIO（s3:http://127.0.0.1:9000/restic-backup）
数据源：/data/restic-src
恢复目录：/data/restic-restore

export RESTIC_REPOSITORY=s3:http://127.0.0.1:9000/restic-backup
export RESTIC_PASSWORD=q1w2e3r4
export AWS_ACCESS_KEY_ID=admin
export AWS_SECRET_ACCESS_KEY=q1w2e3r4
mkdir -p /data/restic-src
echo "alpha" > /data/restic-src/docs.md

二、仓库初始化

2.1 init —— 初始化仓库

restic init

实测输出：

created restic repository 7f294c0460 at s3:http://127.0.0.1:9000/restic-backup

Please note that knowledge of your password is required to access
the repository. Losing your password means that your data is
irrecoverably lost.

💡 init 仅执行一次；S3 后端会在端点自动创建桶（权限允许时）。口令即加密密钥，务必备份。

三、备份创建（backup）

3.1 首次全量备份

restic backup /data/restic-src

实测输出：

Files:           3 new,     0 changed,     0 unmodified
Dirs:            2 new,     0 changed,     0 unmodified
Added to the repository: 1.740 KiB (1.232 KiB stored)

processed 3 files, 25 B in 0:00
snapshot 364858d6 saved

💡 snapshot ... saved 即本次快照 ID；Added to the repository 显示去重+压缩后实际新增量。

3.2 增量备份（去重）

修改源文件后再次备份：

echo "line2" >> /data/restic-src/app.log
echo "notes" > /data/restic-src/notes.txt
restic backup /data/restic-src

实测输出：

using parent snapshot 364858d6

Files:           1 new,     1 changed,     2 unmodified
Dirs:            0 new,     2 changed,     0 unmodified
Added to the repository: 2.080 KiB (1.231 KiB stored)

processed 4 files, 37 B in 0:00
snapshot 10ebcd25 saved

💡 1 new, 1 changed, 2 unmodified：未改动文件直接复用上一快照的块，只有变动部分写入——证实 restic 块级去重。

3.3 带过滤备份

restic backup /data \
  --exclude '*.tmp' --exclude '/data/cache' \
  --exclude-caches --tag nightly

四、查看快照与统计

4.1 snapshots —— 列快照

restic snapshots

实测输出：

ID        Time                 Host        Tags        Paths
-----------------------------------------------------------------------
364858d6  2026-10-08 05:45:30  ops                     /data/restic-src
10ebcd25  2026-10-08 05:45:37  ops                     /data/restic-src
-----------------------------------------------------------------------
2 snapshots

按标签过滤：restic snapshots --tag nightly --latest 1。

4.2 stats —— 仓库统计

restic stats --mode=restore-size
# Stats in restore-size mode:
#      Total File Count:  11
#              Total Size:  62 B

4.3 diff —— 快照差异

restic diff 364858d6 10ebcd25

实测输出：

M    /data/restic-src/app.log
+    /data/restic-src/notes.txt

Files:           1 new,     0 removed,     1 changed
Dirs:            0 new,     0 removed
Data Blobs:      2 new,     1 removed

五、完整性校验（check）

restic check

实测输出：

check snapshots, trees and blobs
[0:00] 100.00%  2 / 2 snapshots

no errors were found

💡 默认校验索引与哈希。restic check --read-data 读取并校验每块数据，最彻底但最慢；可 --read-data-subset=10% 抽样折中。

六、恢复还原（restore）

6.1 恢复到指定目录

mkdir -p /data/restic-restore
restic restore latest --target /data/restic-restore

实测输出：

restoring <Snapshot 10ebcd25 of [/data/restic-src] ...> to /data/restic-restore
Summary: Restored 6 files/dirs (37 B) in 0:00

验证：

find /data/restic-restore -type f | sort
# /data/restic-restore/data/restic-src/app.log
# /data/restic-restore/data/restic-src/big.dat
# /data/restic-restore/data/restic-src/docs.md
# /data/restic-restore/data/restic-src/notes.txt
cat /data/restic-restore/data/restic-src/docs.md
# alpha

6.2 恢复指定快照 / 过滤

restic restore 364858d6 --target /data/restic-restore        # 指定快照
restic restore latest --target /data/restic-restore --include 'docs.md'  # 只恢复某文件

七、清理保留策略（forget + prune）

7.1 演练

restic forget --dry-run --keep-last 1 --keep-daily 7 --keep-weekly 4 --keep-monthly 6

7.2 实际清理 + 回收

restic forget --keep-daily 7 --keep-weekly 4 --keep-monthly 6 --prune

💡 forget 删除过期快照；--prune 随后回收仓库中不再被引用的数据块。务必先 --dry-run 确认将删哪些快照。

八、密钥管理（key）与挂载

# 密钥管理
restic key list        # 列出口令
restic key add         # 增口令
restic key passwd      # 换口令
restic key remove <id> # 删口令

# 挂载仓库浏览（只读）
mkdir -p /mnt/restic
restic mount /mnt/restic --snapshot latest
ls /mnt/restic/data/restic-src/
# 卸载
fusermount -u /mnt/restic

💡 restic key add 可在一仓库内维护多个口令，便于轮换；mount 用 FUSE 只读挂载快照，方便找回单个文件。

九、端到端实测链路（S3 后端）

export RESTIC_REPOSITORY=s3:http://127.0.0.1:9000/restic-backup
export RESTIC_PASSWORD=q1w2e3r4
export AWS_ACCESS_KEY_ID=admin
export AWS_SECRET_ACCESS_KEY=q1w2e3r4

# 1. 初始化 + 首备 + 增量
restic init
restic backup --tag day1 /data/restic-src
echo "more" >> /data/restic-src/app.log
restic backup --tag day2 /data/restic-src

# 2. 校验
restic check

# 3. 恢复
mkdir -p /data/restic-restore
restic restore lastest --target /data/restic-restore

# 4. 清理
restic forget --dry-run --keep-last 2
restic forget --keep-last 2 --prune

十、常见问题

Q1：restic init 报 client.BucketExists ... connect: connection refused？

后端端点不可达。核对 RESTIC_REPOSITORY 地址/端口、MinIO 已启动、网络可路由到 S3 服务。

Q2：restore 后文件路径多出 /data/restic-src？

restic 还原保留去根相对结构。按需 cd 到期望目录或配 --include 过滤；--target 指定落地根。

Q3：forget 与 prune 区别？

forget 只删快照元数据引用；prune 才物理回收仓库数据块。不加 --prune 的 forget 不会立即释放空间。

Q4：备份占用空间大于预期？

先 --exclude-caches、--exclude '*.tmp' 减少量；确认不是重复备份不同路径；用 restic stats 看仓库实际占用。

参考链接

restic 命令索引：https://restic.readthedocs.io/en/stable/Manual.html
restic backup：https://restic.readthedocs.io/en/stable/040_backup.html
restic forget：https://restic.readthedocs.io/en/stable/060_forget.html