Restic 家目录备份

为 Linux 家目录交付一套生产就绪、无人值守的 restic 备份工作流，覆盖加密、去重、版本化保留、systemd 定时调度、瞬态错误重试、持久化日志记录、邮件告警及恢复验证。

技能契约

• 名称：restic-home-backup
• 版本：2.0.0
• 解决的问题：Linux 家目录的可靠、加密、版本化备份。支持 SSH/SFTP 远程仓库、夏令时安全（DST-safe）调度、瞬态错误自动重试、用户级安装（无需 root 权限）、一次性恢复审计定时器，以及可复用的多主机批量部署能力。
• 输入参数：
  • 备份源用户及路径
  • 仓库端点/传输协议（local、sftp、s3、b2 等）
  • 时区（默认 America/Los_Angeles）
  • 保留策略（默认：14 个每日快照 / 8 个每周快照 / 12 个每月快照）
  • 排除模式（exclude patterns）
  • 告警邮箱地址
• 输出内容：
  • 已安装并初始化的 restic 仓库
  • 位于 /usr/local/bin/ 下的备份 / 清理（prune） / 校验（check） / 审计演练（audit）脚本
  • 结构化日志包装器，每项任务均记录开始时间、结束时间、耗时、退出码
  • systemd 服务单元与定时器单元（支持系统级或用户级）
  • 一次性恢复审计定时器（one-time restore audit timer）
  • 针对瞬态失败的重试逻辑（从不重试认证/权限类错误）
  • 验证证据：快照列表、恢复演练、完整性校验
  • 受控故障演练：密钥错误 / 仓库不可达 / 环境变量文件损坏
  • 运维手册（references/runbook.md）
  • 运维检查清单（references/ops-checklist.md）
• 安全边界（绝对禁止违反）：
  • 绝不以明文形式在聊天窗口、日志输出或脚本中打印密钥或令牌。
  • 未经用户明确确认，绝不删除任何快照或整个仓库。
  • 绝不放宽凭据文件的权限设置（最低权限必须为 0600）。
  • 未校验退出状态码及快照列表前，绝不声称备份成功。
  • 默认启用 PLAN-ONLY 模式；执行系统变更必须显式指定 --apply 参数。
  • 初始部署阶段禁止删除快照；使用 --dry-run-prune 预览清理效果。

工作流

1) 收集备份契约

最低必需字段：

• 源路径（例如：/home/alice）
• 仓库地址（例如：sftp:backupsvc@10.50.8.24:/srv/backups/home/devbox17）
• 保留策略
• 本地时区下的首选调度时间

若任一关键值缺失，请提出针对性问题予以澄清。

2) 展示执行计划（无变更预览）

bash scripts/bootstrap_restic_home.sh 
  --user alice 
  --repo "sftp:backupsvc@10.50.8.24:/srv/backups/home/devbox17"

该命令将完整输出执行计划：涉及文件、调度策略、保留规则、密钥管理方式、重试逻辑、遗留 cron 条目归档方案，以及 --dry-run 模式下的 prune 预览。全程不进行任何实际变更。

3) 应用系统级变更

sudo bash scripts/bootstrap_restic_home.sh 
  --user alice 
  --repo "sftp:backupsvc@10.50.8.24:/srv/backups/home/devbox17" 
  --hostname devbox17 
  --timezone "America/Los_Angeles" 
  --mail-to sre-oncall@example.com 
  --keep-daily 14 --keep-weekly 8 --keep-monthly 12 
  --config-dir /etc/home-backup 
  --log-dir /var/log/home-backup 
  --apply 
  --init-repo 
  --enable-timers 
  --run-initial-backup 
  --archive-legacy-cron 
  --dry-run-prune

该命令按顺序执行以下操作：

1. 创建 /etc/home-backup/ 目录（权限 0700），生成密码文件（权限 0600，永不打印）
2. 写入环境变量文件（权限 0600）和排除列表文件
3. 创建日志目录 /var/log/home-backup/
4. 安装带日志与重试功能的包装脚本（restic-home-log-run.sh）
5. 安装 4 个核心运维脚本（backup、prune、check、audit-drill）
6. 生成 8 个 systemd 单元文件（4 个 service + 4 个 timer）
7. 归档并移除旧的 root 用户 crontab 条目
8. 启用所有 timer 并执行 daemon-reload
9. 初始化仓库（若仓库已存在则跳过）
10. 通过 systemd 启动首次备份任务
11. 显示 restic forget --dry-run 输出结果（不执行任何删除操作）

4) 用户级安装（无需 root 权限 —— 例如 labvm3/bob）

bash scripts/install_userlevel_restic.sh 
  --repo /mnt/offsite/backups/labvm3-home 
  --hostname labvm3 
  --timezone "America/Los_Angeles" 
  --mail-to sre-oncall@example.com 
  --apply --init-repo --enable-timers --run-initial-backup

# 启用 linger（仅需执行一次，需 sudo 权限）：
sudo loginctl enable-linger bob

# 管理方式：
systemctl --user list-timers 'restic-home-*'    # 查看定时器列表
systemctl --user start restic-home-backup.service  # 手动触发备份
bash scripts/install_userlevel_restic.sh --remove  # 移除定时调度

5) 端到端验证

sudo bash scripts/validate_restic_setup.sh

执行以下验证项：

• 列出当前所有快照
• 执行恢复演练至 /tmp/restore-drill（校验 .ssh/config、Documents/roadmap.md、.config/git/config 是否完整还原）
• 清理临时恢复目录
• 执行仓库完整性校验（restic check）
• 三项受控故障演练：密钥错误 / 仓库不可达 / 环境变量文件不可读（每项均输出失败命令及一行修正建议）

6) 一次性恢复审计定时器

初始化脚本会创建 restic-home-audit.timer，用于单次调度的恢复演练。默认时间为：2026-04-17 17:00:00 America/Los_Angeles。

# 查看定时器状态：
systemctl list-timers restic-home-audit.timer --no-pager

# 取消定时器：
systemctl disable --now restic-home-audit.timer

# 立即执行：
systemctl start restic-home-audit.service

7) 通过 ClawHub 打包并发布

# 验证技能结构：
clawhub validate .

# 发布技能：
clawhub publish .

# 验证干净安装（全新环境，不携带任何已有密钥）：
mkdir /tmp/clawhub-verify && cd /tmp/clawhub-verify
clawhub install restic-home-backup
# 仅运行 plan 模式，确认脚本存在且具备可执行权限：
bash restic-home-backup/scripts/bootstrap_restic_home.sh 
  --user testuser --repo sftp:test@localhost:/test

本技能所含文件

scripts/
  bootstrap_restic_home.sh     系统级安装脚本（支持 plan + apply）
  install_userlevel_restic.sh  非 root 主机的用户级安装脚本
  validate_restic_setup.sh     端到端验证 + 故障演练脚本

references/
  runbook.md      完整运维手册（共 13 节）
  ops-checklist.md  日常 / 周度 / 月度快速参考清单

响应风格要求

• 精确引用文件路径、服务名与命令。
• 明确说明变更内容及验证方法。
• 严禁打印任何密码或令牌。
• 多步骤任务结尾须给出明确完成状态。
• 日常运维请参考 references/runbook.md 获取第二日（Day-2）操作指南。