Restic 配置参数详解

目标：系统解析 restic v0.16.4 的配置体系。restic 的配置主要分四层：环境变量（RESTIC_*/AWS_*）、仓库后端与初始化（init）、备份行为参数（backup 的 exclude/tag/过滤）、快照管理参数（snapshots/forget/check/restore）。本文聚焦最常用参数的真实语义与默认值，默认值来自 0.16.4 实测。

一、环境信息

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

二、环境变量

2.1 仓库与口令

环境变量	作用	说明
`RESTIC_REPOSITORY`	仓库地址	本地路径或 `s3:`/`sftp:`/`rest:` 前缀
`RESTIC_PASSWORD`	仓库口令	即加密密钥；丢失不可恢复
`RESTIC_PASSWORD_COMMAND`	获取口令的命令	可调外部密钥管理
`RESTIC_CACHE_DIR`	本地缓存目录	默认 `~/.cache/restic`
`RESTIC_HOST`	覆盖快照 Host 字段	便于区分机器
`RESTIC_REPOSITORY_FILE`	从文件读仓库地址	与 `--repository-file` 等价

2.2 S3 后端凭据

环境变量	作用
`AWS_ACCESS_KEY_ID`	S3 访问密钥 ID
`AWS_SECRET_ACCESS_KEY`	S3 私密密钥
`AWS_DEFAULT_REGION`	S3 区域（MinIO 一般不强制）

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

💡 也可用 restic -r <repo>、--password-file 命令行参数替代环境变量；脚本/容器多用环境变量注入，避免写明文文件。

三、仓库后端与初始化（init）

3.1 后端 URL 前缀

前缀	后端	示例
无 / 路径	本地目录	`RESTIC_REPOSITORY=/data/restic-repo`
`s3:`	AWS S3 / MinIO / Ceph	`s3:http://127.0.0.1:9000/bucket`
`sftp:`	SFTP 远程	`sftp:user@host:/backups/repo`
`rest:`	REST 服务器	`rest:http://server:8000/repo`
`b2:`	Backblaze B2	`b2:bucket:path`
`azure:` / `gs:`	Azure / GCS	`azure:container:path`

3.2 初始化仓库

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

⚠️ init 仅执行一次；仓库口令（RESTIC_PASSWORD）作数据加密密钥，务必备份。S3 后端 init 会自动创建桶（若权限允许）。

3.3 查看仓库信息

restic cat config     # 查看仓库配置元数据
restic stats --mode=restore-size
# Stats in restore-size mode:
#      Total File Count:  11
#              Total Size:  62 B

四、备份行为参数（backup）

4.1 基本用法

restic backup /data/restic-src
# 一次性备份多个路径
restic backup /etc /srv/app --tag prod

4.2 排除与过滤

实测 restic backup --help 摘录：

选项	作用
`-e, --exclude pattern`	排除匹配模式（可多次）
`--exclude-file file`	从文件读排除规则（每行一个）
`--iexclude pattern`	忽略大小写的排除
`--exclude-caches`	跳过含 `CACHEDIR.TAG` 的缓存目录
`--exclude-if-present filename`	跳过含该标记文件的目录
`--exclude-larger-than size`	跳过超过大小的文件（如 `500m`）
`--include pattern`	仅含匹配项
`--tag tags`	为快照加标签，如 `--tag prod,.keep`

restic backup /data --exclude '*.tmp' --exclude '/data/cache' --exclude-file /etc/restic-exclude.txt --tag daily

💡 排除模式支持 shell 通配与 ** 等；--exclude-caches 对常见缓存目录（.git、node_modules 里的 CACHEDIR.TAG）很实用。

4.3 其它常用 flag

选项	说明
`--dry-run`	演练不真实备份
`--verbose` / `-v`	详细输出
`-q, --quiet`	只输出统计
`--files-from`	从文件读待备份路径
`--host host`	覆盖快照 Host
`--json`	JSON 输出
`--no-scan`	跳过初始扫描（耗时场景）
`--within`	基于时间限制（高级）

五、快照管理参数

5.1 snapshots

restic snapshots            # 列出全部快照
restic snapshots --tag prod # 按标签过滤
restic snapshots --latest 1 # 只列最近
restic snapshots --compact  # 紧凑输出

5.2 diff

restic diff <snap1> <snap2>
# M    /data/restic-src/app.log
# +    /data/restic-src/notes.txt
# Files:  1 new, 0 removed, 1 changed

5.3 check / 校验

restic check                 # 默认校验索引与哈希（较快）
restic check --read-data     # 读取并校验每块数据（最彻底，慢）
restic check --read-data-subset=10%  # 抽样校验部分数据（折中）

六、清除与保留策略（forget + prune）

forget 按策略删除快照，prune 回收无用数据块：

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

# 实际删除快照并回收空间
restic forget --keep-daily 7 --keep-weekly 4 --keep-monthly 6 --prune

选项	含义
`--keep-last N`	保留最近 N 个快照
`--keep-hourly N`	保留最近 N 个小时级
`--keep-daily N`	保留最近 N 个日级
`--keep-weekly N`	保留最近 N 个周级
`--keep-monthly N`	保留最近 N 个月级
`--keep-yearly N`	保留最近 N 个年级
`--keep-within duration`	保留距今指定时长内所有（如 `1y5m7d2h`）
`--prune`	forget 后同时回收无引用数据
`--dry-run`	演练不删除

⚠️ --prune 会实际删除仓库中不再被任何快照引用的数据块，删除不可逆，务必先 --dry-run。

七、恢复与密钥

7.1 restore

restic restore latest --target /data/restic-restore
restic restore <snapshot-id> --target /where/to/restore --include 'docs.md'

选项	说明
`--target dir`	恢复到目标目录
`--include` / `--exclude`	按路径过滤
`--host` / `--path`	按主机/路径筛选快照

7.2 key —— 密钥管理

restic key list                    # 列出所有口令/key
restic key add                     # 新增一个口令（交互）
restic key passwd                  # 更换口令
restic key remove <id>             # 删除一个口令

💡 restic 支持多个口令同时解密同一仓库（key add），便于轮换而不断点。

八、缓存与调优

restic cache                         # 查看/管理本地缓存
restic cache --cleanup               # 清理过期缓存目录
RESTIC_CACHE_DIR=/var/cache/restic restic backup /data   # 指定缓存目录

💡 restic 用本地缓存加速重复备份；大批量、低磁盘环境可用 --no-cache 关闭缓存（restic backup --no-cache）。

九、综合配置模板（每日增量 + 定期清理 + S3 后端）

cat > /etc/restic.env <<'EOF'
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
EOF
source /etc/restic.env

# 初始化（一次）
restic init

# 每日备份（排除临时/缓存）
restic backup /data/restic-src \
  --exclude '*.tmp' --exclude-caches --tag daily

# 每周清理（演练后执行）
restic forget --dry-run --keep-daily 7 --keep-weekly 4 --keep-monthly 6
restic forget --keep-daily 7 --keep-weekly 4 --keep-monthly 6 --prune

# 定期校验
restic check --read-data-subset=10%

💡 适配「服务器数据、每日增量备份到对象存储、按日月周保留」的生产场景。S3 端点指向 MinIO 即实现私有化对象存储备份。

十、常见问题

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

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

Q2：--keep-all 报 unrecognized？

restic 用 --keep-last/--keep-daily/--keep-weekly/--keep-monthly 组合，无 --keep-all。想保留全部就只用 --keep-last 很大数或不执行 forget。

Q3：restore 后路径带 /data/restic-src？

restic 还原保留去根后的相对结构，默认落在 --target 目录下；配合 --include/--path 或恢复到独立目录使用。

Q4：备份很慢或占满带宽？

restic 单线程逐文件；大批量可接受即可（restic 专注去重与加密）。如需限速配合外层 --limit-upload（S3）或系统 tc；加 --exclude-caches、--exclude-larger-than 减少量。

十一、参考链接

restic 环境变量：https://restic.readthedocs.io/en/stable/040_backup.html#environment-variables
restic 后端：https://restic.readthedocs.io/en/stable/030_preparing_a_new_repo.html
restic 保留策略：https://restic.readthedocs.io/en/stable/060_forget.html