restic

Restic

Restic 是一款备份 CLI，而不是守护进程。应将计划任务或服务管理器视为执行层。任何可用的备份设计都必须证明四件事：已捕获源数据、仓库可读取、保留策略经过审慎规划，并且已在单独的目标位置成功恢复。

运行约定

1. 更改任何内容前先了解情况：restic 版本、后端类型、仓库格式、源路径、凭据机制、计划任务、保留策略和恢复目标。
2. 不要将仓库密码和后端凭据写入命令历史记录、日志、模板或聊天内容。优先使用 root/用户可读的密码文件或密钥管理器命令，而不是内联值。
3. 进行任何更改前，确认目标仓库、源范围、排除项、保留分组、计划任务、维护窗口以及回滚/恢复路径。只读检查无需确认即可进行。
4. 使用稳定的主机和标签约定进行备份。检查生成的快照，然后测试将数据恢复到一个空的、独立的目标位置。备份成功退出并不能证明数据可恢复。
5. 将 forget、prune、key remove、rebuild-index、repair、migrate 和后端生命周期规则视为影响重大的操作。尽可能先预览，并保留已知可靠的恢复路径。

首先进行只读检查

scripts/restic-preflight.sh
restic version
restic snapshots --json
restic stats --mode raw-data

在运行打开仓库的命令之前，通过环境变量或命令标志设置仓库位置和密码来源。不要将明文密码导出到共享的 Shell 历史记录中。请参阅仓库和后端设置。

不适用场景

对于一次性未加密文件复制、restic 无法创建的数据库备份格式，或没有 restic 仓库的特定提供商对象存储管理，请勿加载此内容。为确保数据一致性，请使用相应应用的备份流程，然后使用此技能保护生成的文件。

选择路径

需求	首先阅读
安装或选择受支持的二进制文件	基础知识和安装
初始化仓库或选择本地、SFTP、对象存储、REST 或 rclone 后端	仓库和后端
设计源数据、排除项、标签、计划任务或服务管理器自动化	备份设计和自动化
编写无人值守任务、处理退出代码、解析 JSON 或了解锁的工作方式	脚本编写和命令约定
定义保留策略、执行维护、验证完整性或开展恢复演练	保留策略、完整性和恢复
对密钥、访问权限、勒索软件或凭据进行威胁建模	安全和威胁模型
缩短运行时间、控制带宽/缓存或收集有用的证据	性能和可观测性
诊断故障、锁、损坏、后端错误，或处理复制/迁移工作	故障排除和迁移
检查源范围、版本时效性或后端相关声明	来源索引

安全工作流

生成的数据： 将数据库导出内容嵌入备份作业前，请阅读 脚本与命令约定。 --stdin-from-command 会在 -- 后准确运行一条生成命令；外层 shell 管道不属于该生成命令。对于压缩或转换，请将经过测试的包装程序作为生成命令传入，或者仅在启用 pipefail 并进行显式错误处理的情况下使用 backup --stdin。

# 1. Read-only preflight. It never prints secret values.
scripts/restic-preflight.sh

# 2. Initialize only after confirming the intended empty target.
restic init --repo /path/to/repository --password-file /secure/path/restic-password

# 3. Create a tagged snapshot, then inspect it.
restic --repo /path/to/repository --password-file /secure/path/restic-password \
  backup /data --tag production --tag files
restic --repo /path/to/repository --password-file /secure/path/restic-password snapshots

# 4. Restore to an empty, separate directory and inspect the result.
restic --repo /path/to/repository --password-file /secure/path/restic-password \
  restore latest --target /var/tmp/restic-restore-test

使用 templates/backup-policy.env.example 记录非机密策略，并使用 templates/restore-drill.md 记录有证据支持的恢复测试。对于 Linux 定时任务，可改编 templates/systemd/restic-backup.service 和 templates/systemd/restic-backup.timer；将机密路径和源路径保留在本地，不要提交。

脚本

• scripts/restic-preflight.sh — 只读的本地配置和 CLI 检查；会对值脱敏，且不会打开仓库。
• scripts/restic-verify.sh — 范围受限的仓库验证：默认检查元数据，可选读取抽样数据或全部数据。不会更改保留策略或清理数据。
• scripts/test-restic-preflight.sh — 使用伪造的 restic 可执行文件进行的确定性 shell 测试。
• scripts/test-restic-verify.sh — 用于构造范围受限的 check 命令的确定性 shell 测试。

从技能根目录运行脚本。它们需要 Bash 和 restic；restic-verify.sh 还需要已配置的仓库和密码机制。

严格边界

• 除非已了解其耗时和对锁的影响，否则切勿在唯一备份作业的同一非人工值守时段运行 prune。
• 切勿将 forget 等同于释放存储空间。forget 会移除快照引用；之后 prune 才会移除不再被引用的数据。
• 恢复时切勿将数据直接覆盖到生产源路径。先恢复到其他位置并验证，然后再有意执行切换。
• 备份受阻时，切勿仅因此就使用 unlock。应先确认是否有其他 restic 进程正在运行，以及锁是否已过期。
• 切勿根据通用 S3 URL 推断提供商的不可变性、保留策略、权限或对象锁语义。请核实特定后端的策略，并在演练中恢复数据。

退出标准

只有在相关操作边界有证据证明时，所请求的操作才算完成：安装操作报告了预期的二进制文件；备份已生成并列出快照；维护操作后执行了 check；恢复操作已恢复到独立目标，并检查了恢复的数据。