Restic 备份与恢复完整指南（基于 Openlist的S3 对象存储）

本文档基于 Restic 官方文档 整理,适用于 Linux / macOS / Windows 环境,以 S3 兼容对象存储(推荐使用 OpenList 提供的 S3 协议)作为后端,覆盖安装、配置、备份、恢复、保留策略与自动化运维的完整流程。

示例基于 restic v0.16+;个别参数在旧版本不可用,一切以 restic <command> --help 输出为准。

一、Restic 简介

Restic 是一个快速、高效、安全、跨平台的开源备份工具,核心特性:

• 加密备份:所有数据在上传前自动加密(AES-256 + Poly1305),服务端只存密文,密钥由用户掌控。
• 去重(Deduplication):按内容分块,只上传仓库中不存在的数据块,第二次起的增量备份几乎零成本。
• 快照(Snapshot)机制:每次备份生成一个不可变快照,支持任意时间点恢复。
• 内置压缩:仓库版本 2(restic 0.14+ 默认)使用 zstd 自动压缩,文本/日志类数据节省显著。
• 自校验设计:所有数据块带校验和,restic check 可验证仓库完整性,防止静默损坏。
• 跨平台支持:Linux、macOS、Windows、BSD、Docker 等。
• 后端灵活:本地目录、S3 兼容存储(推荐 OpenList)、B2、Azure Blob、Google Cloud Storage、SFTP、REST Server 等。
• 命令行驱动:全部功能皆可脚本化,适合自动化。

二、安装 Restic

1. Linux(Debian/Ubuntu)

sudo apt install restic

发行版仓库里的版本通常偏旧,需要新特性建议用下面的手动安装。

2. macOS(Homebrew)

brew install restic

3. Windows

# 任选其一
winget install restic.restic
scoop install restic
choco install restic

4. 手动安装(推荐,始终最新版)

到 GitHub Releases 下载对应平台的二进制文件:

# 示例:Linux x86_64(版本号以 Releases 页最新为准)
wget https://github.com/restic/restic/releases/download/v0.17.2/restic_0.17.2_linux_amd64.bz2
bunzip2 restic_0.17.2_linux_amd64.bz2
chmod +x restic_0.17.2_linux_amd64
sudo mv restic_0.17.2_linux_amd64 /usr/local/bin/restic

# 手动安装版以后可原地升级
sudo restic self-update

5. Docker 方式

docker run --rm \
  -v /data:/data:ro \
  -v restic-cache:/root/.cache/restic \
  -e RESTIC_REPOSITORY="s3:http://192.168.0.200:5246/my-backup-bucket" \
  -e RESTIC_PASSWORD="your-strong-password" \
  -e AWS_ACCESS_KEY_ID=xxx -e AWS_SECRET_ACCESS_KEY=yyy \
  restic/restic backup /data --tag docker

容器内访问宿主机服务时,127.0.0.1 要换成宿主机内网地址,或干脆 --network host。

验证安装:

restic version
# 输出示例:restic 0.17.2 compiled with go1.23.x on linux/amd64

三、配置 S3 兼容存储库(以 OpenList 为例)

1. 准备存储桶与密钥

• 在 OpenList 管理后台启用 S3 服务(默认监听 5246 端口),桶名对应一个已挂载的存储路径;
• 生成 Access Key ID 和 Secret Access Key;
• 使用阿里云 OSS、腾讯云 COS、MinIO、Cloudflare R2 等其他 S3 服务同理。

2. 存储库地址格式(易错点!)

s3:endpoint/bucket[/子目录前缀]

⚠️ 必须写明协议:地址不以 http:// / https:// 开头时,restic 默认按 HTTPS 连接。本机 OpenList 是明文 HTTP,漏掉 http:// 会直接连接/握手失败——这是最常见的踩坑点。仓库地址末尾还可以追加 /子目录,把多个仓库放进同一个桶。

3. 设置环境变量

export RESTIC_REPOSITORY="s3:http://127.0.0.1:5246/my-backup-bucket"
export RESTIC_PASSWORD="your-strong-password"      # 备份加密密码
export AWS_ACCESS_KEY_ID="your-access-key"
export AWS_SECRET_ACCESS_KEY="your-secret-key"
export AWS_DEFAULT_REGION="us-east-1"              # 自建 S3/OpenList 随意填
# export AWS_ENDPOINT="http://127.0.0.1:5246"      # 端点也可独立配置(旧式写法,二选一)

💡 关于 RESTIC_PASSWORD:

• 它就是加密密钥,丢失 = 数据永久无法恢复,务必在密码管理器/纸质等离线处另存一份;
• 自建 S3 常见报错 Bucket region detection failed 时,把 AWS_DEFAULT_REGION 设成 us-east-1 即可解决;
• 明文 export 只适合临时测试,正式自动化请改用 RESTIC_PASSWORD_FILE / RESTIC_PASSWORD_COMMAND(见第八章),避免密码出现在脚本和进程列表里。

四、初始化存储库

首次使用前必须初始化:

restic init

输出示例:

created restic repository 1a2b3c4d5e at s3:http://127.0.0.1:5246/my-backup-bucket

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

• restic 0.14+ 默认创建仓库版本 2,支持 zstd 压缩与更高效的清理;也可显式指定 restic init --repository-version 2;
• 初始化成功后,桶内会出现 config 文件和 data/、index/、keys/、snapshots/ 等目录。

五、执行备份

1. 基本命令

restic backup /path/to/backup
# 例:
restic backup /home/user/documents

输出包含快照 ID、处理文件数、新增数据量等。第二次起只上传变化块,速度极快。

2. 常用参数详解

3. 排除规则语法速记

• 规则匹配相对路径;/ 开头表示从备份目标根锚定:/cache/* 只排除目标下的一级 cache;
• * 匹配一段路径,** 跨多级:**/*.log 匹配任意深度的日志;
• 以 / 结尾的规则只匹配目录;默认大小写敏感(--iexclude 反之);
• --exclude-caches 依靠目录内的 CACHEDIR.TAG 标准标记文件识别,开发机特别好用。

4. 实战示例

# 网站目录:排除缓存与日志,打双标签
restic backup /var/www/html \
  --tag website,daily \
  --exclude "/var/www/html/cache" \
  --exclude "*.log"

# 用排除文件,顺带忽略大小写
printf '*.tmp\nThumbs.db\ntarget/\n' > exclude.txt
restic backup /home --exclude-file exclude.txt

# 整机备份:不跨文件系统 + 只要小于 500M 的文件
restic backup / -x --exclude-larger-than 500M --tag system

# 演练:看看这次会备份哪些文件(不写入)
restic backup /data --dry-run

# 备份数据库管道输出,无需中间落盘文件
mysqldump --all-databases | restic backup --stdin --stdin-filename all-databases.sql --tag mysql

5. 退出码与监控

restic backup 的退出码:0 完全成功;3 部分源文件读取失败(权限、备份中文件消失等),快照仍会生成;其他非零值为严重错误。自动化脚本应检查退出码并告警(示例见第八章)。

六、快照管理与保留策略

1. 列出与过滤

restic snapshots                 # 全部快照
restic snapshots --tag website   # 按标签
restic snapshots --host myhost   # 按主机
restic snapshots --last          # 最近一次
restic snapshots --json          # 机器可读输出,供脚本处理

2. 浏览、检索与对比

restic ls latest                        # 列出最新快照中的文件
restic ls a1b2c3d4 /var/www/html        # 只看某个目录
restic find index.html                  # 全仓库搜索文件名(可加 --host / --tag)
restic diff a1b2c3d4 e5f6g7h8           # 对比两个快照的差异
restic stats latest                     # 恢复后的总大小
restic stats --mode raw-data            # 该快照独占的数据量(评估删除收益)

3. 修改快照标签

restic tags a1b2c3d4 --set keep         # 覆盖式设置
restic tags a1b2c3d4 --add important    # 追加
restic tags a1b2c3d4 --remove daily     # 移除

配合保留策略:打了 --keep-tag important 的快照永远不会被 forget 删除,可当"永久保留"用。

4. 保留策略(forget)详解

forget 按策略标记多余快照;--prune 才真正回收存储空间。

# 经典组合:每天 1 份留 7 天 + 4 周 + 12 个月,并立即回收空间
restic forget --keep-daily 7 --keep-weekly 4 --keep-monthly 12 --prune

# 时间窗写法:30 天内每天留 1 份,24 小时内每小时留 1 份
restic forget --keep-within-daily 30d --keep-within-hourly 1d --prune

# 永久保留打了 important 标签的快照
restic forget --keep-tag important --keep-daily 7 --prune

# 推荐习惯:先 --dry-run 演练,确认要删哪些,再去掉再真删
restic forget --keep-daily 7 --dry-run

• --keep-last 10:按时间顺序保留最近 10 个快照;
• 策略按 --group-by(默认 host,paths)分组独立评估,多主机/多路径互不干扰;
• 全部保留参数:--keep-last / --keep-hourly / --keep-daily / --keep-weekly / --keep-monthly / --keep-yearly / --keep-within / --keep-tag。

5. prune 与空间回收

restic forget --prune                 # 日常推荐:标记 + 回收一步完成
restic prune                          # 只回收空间,不删快照
restic prune --max-repack-size 2G     # 限制单次重打包数据量,分多批跑完
restic prune --max-unused 5%          # 允许残留 5% 垃圾,换取更快的 prune

⚠️ prune 需要全量读写仓库,耗时且占内存(超大仓库可 GOGC=20 restic prune 降内存、稍变慢),建议放在低峰期,并避免与备份并发执行。

6. 锁机制与解锁

仓库有锁机制防止并发写坏数据。若备份进程被强杀,可能残留过期锁:

restic unlock                # 清理过期锁(常规做法)
restic unlock --remove-all   # 确认当前没有任何 restic 在跑时,强制清掉全部锁

七、恢复数据

1. 恢复整个快照

restic restore a1b2c3d4 --target /restore/path
restic restore latest --target /restore/path --verify   # 恢复后逐文件校验

• --target:目标路径(需已存在);latest 表示最新快照。

2. 只恢复部分文件

restic restore latest --target /tmp/restore --include "/var/www/html/index.html"
restic restore latest --target /tmp/restore --include "/home/user/docs/**.pdf"
restic restore latest --target /tmp/restore --exclude "*.log"   # 排除法同样可用

3. 恢复到原始位置(覆盖)

sudo restic restore a1b2c3d4 --target /

⚠️ 会覆盖现有文件,先停相关服务再操作;Linux 下用 root 执行可保留原属主与权限。

4. 只取单个文件(不落目录)

restic dump latest /var/www/html/.env > env-restored.txt

5. 挂载为文件系统浏览(只读)

restic mount /mnt/restic
# 目录结构:/mnt/restic/hosts/<主机名>/<时间>、/ids/<快照ID>、/tags/<标签>/latest

Linux 需要 fuse,macOS 用 macFUSE;Windows 不支持 mount,用上面的 dump / restore 即可。适合"像翻本地目录一样找文件"式的恢复。

6. 跨机器恢复

换一台机器装上 restic,配好相同的 RESTIC_REPOSITORY 与 RESTIC_PASSWORD(S3 凭据同理),restic snapshots 确认后即可恢复任意快照——这正是把仓库放对象存储上的最大价值:机器没了也没关系,仓库在就行。

八、进阶配置与自动化

1. 密码文件化(告别明文 export)

# 方式一:密码文件(权限必须 600)
echo 'your-strong-password' > /root/.restic-password
chmod 600 /root/.restic-password
export RESTIC_PASSWORD_FILE="/root/.restic-password"

# 方式二:由命令动态取密(密码不落盘,适合配合 pass / 1Password CLI 等)
export RESTIC_PASSWORD_COMMAND="pass show backup/restic"

2. 生产级自动备份脚本

#!/usr/bin/env bash
set -euo pipefail

export RESTIC_REPOSITORY="s3:http://127.0.0.1:5246/my-backup-bucket"
export RESTIC_PASSWORD_FILE="/root/.restic-password"
export AWS_ACCESS_KEY_ID="xxx"
export AWS_SECRET_ACCESS_KEY="yyy"

LOGTAG="restic-backup"

# 备份;退出码 3 = 个别文件读取失败,视为基本成功
set +e
restic backup /data --tag auto-daily --exclude-caches
rc=$?
set -e
case "$rc" in
  0) : ;;
  3) logger -t "$LOGTAG" "备份完成,但部分文件读取失败 (rc=3)" ;;
  *) logger -t "$LOGTAG" "备份失败 rc=$rc"; exit "$rc" ;;
esac

# 保留策略 + 回收空间
restic forget --keep-daily 7 --keep-weekly 4 --keep-monthly 12 --prune

# 快速完整性检查(只查元数据,秒级)
restic check

logger -t "$LOGTAG" "备份完成"

💡 logger 把结果写进 syslog;失败分支里也可以换成 curl 推送到你的通知渠道(如 Server酱/Bark/企业微信机器人),实现失败告警。

3. systemd timer(比 cron 更可靠)

/etc/systemd/system/restic-backup.service:

[Unit]
Description=Restic backup job
Wants=network-online.target
After=network-online.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/restic-backup.sh
Nice=10
IOSchedulingClass=idle

/etc/systemd/system/restic-backup.timer:

[Unit]
Description=Run restic backup daily

[Timer]
OnCalendar=*-*-* 02:00:00
RandomizedDelaySec=30min
Persistent=true

[Install]
WantedBy=timers.target

sudo systemctl daemon-reload
sudo systemctl enable --now restic-backup.timer
systemctl list-timers restic-backup.*

Persistent=true 的价值:到点时正好关机,开机会补跑错过的任务——cron 做不到。

4. 轮换仓库密码(无需重新上传数据)

restic key list                 # 查看现有密钥
restic key add                  # 用当前密码认证,然后为新增密钥设置"新密码"
# 把环境变量换成新密码并验证:
restic snapshots
restic key remove <旧KeyID>     # 确认新密码可用后,再删除旧密钥

5. 缓存与性能调优

export RESTIC_CACHE_DIR="/var/cache/restic"   # 自定义缓存目录(默认 ~/.cache/restic)
restic cache --cleanup-old                    # 清理过期缓存目录
restic backup /data --no-cache                # 一次性任务/磁盘紧张时禁用缓存
GOGC=20 restic prune                          # 超大仓库 prune 时降低内存峰值(稍变慢)

• 首次全量最慢属正常,之后增量只传变化块;
• 带宽紧张时给备份 --limit-upload 限速,给恢复 --limit-download;
• 仓库定期 forget --prune 反而能让后续操作更快。

6. S3 进阶参数(-o 扩展选项)

# 低频访问层,省存储费(按需选择)
restic -o s3.storage-class=STANDARD_IA backup /data

# 自建 MinIO/OpenList 排障时可强制 path 风格寻址(0.16+)
restic -o s3.bucket-lookup=path snapshots

• s3.storage-class 常用值:STANDARD / STANDARD_IA / ONEZONE_IA / INTELLIGENT_TIERING;
• ⚠️ 别选 GLACIER / DEEP_ARCHIVE:对象进入冻结态后 restic 无法直接读取,恢复前需人工解冻。

7. Windows:VSS 卷影副本备份

被占用的文件(Outlook 的 pst、浏览器配置等)平时读不了,加 VSS 参数即可:

# 需管理员权限运行
restic backup --use-fs-snapshot C:\Users\me\Documents --tag win-docs

8. 完整性校验策略

restic check                            # 只校验元数据与索引,快,建议每次备份后跑
restic check --read-data-subsystem=10   # 抽查约 1/10 的数据块,可每月换着跑
restic check --read-data                # 全量读回校验,最彻底也最慢,季度低峰跑

九、常见问题

Q1:如何验证备份是否真的可用?

restic check 验证仓库完整性;但定期做恢复演练才是金标准——挑个快照 restore 到临时目录,抽查文件能否打开。

Q2:能否在不同机器上恢复?

可以!只要 RESTIC_REPOSITORY 和 RESTIC_PASSWORD 一致,任何装了 restic 的设备都能恢复(见七.6)。

Q3:备份速度慢怎么办?

• 首次最慢属正常,后续增量极快;
• 带宽被其他业务占用时,用 --limit-upload 限速让路;
• 本地读取慢可试 --read-concurrency;整机动不了的文件先排除。

Q4:密码忘记了怎么办?

无法恢复! Restic 的设计原则是"无后门",密码即密钥。请务必至少在两处离线保存。

Q5:报错 repository is already locked?

上一个 restic 进程异常退出残留了锁。确认没有其他 restic 在跑后执行 restic unlock。自动化场景可给备份加 --retry-lock 10m(0.17+),等锁释放而不是直接失败。

Q6:prune 又慢又吃内存?

低峰期跑;大仓库加 GOGC=20;--max-repack-size 分批;--max-unused 用少量空间浪费换速度。

Q7:忘了加排除,垃圾文件已经备进去了?

找到包含它的快照 restic forget <id> --prune 删掉重备即可——去重机制决定了重备代价很小。

十、参考资料

• Restic 官方文档
• 备份参数调优(Backup Reference)
• S3 后端配置
• 保留策略(Managing Snapshots)
• 官方 FAQ

✅ 备份无小事:定期 restic check、定期演练恢复、密码多处离线保存。本文档持续更新,建议结合官方文档使用。