dotfiles/RECOVERY-DRILL.md

Recovery Drill Checklist

这份文档用于定期做“恢复演练”，验证 dotfiles、Homebrew 基线、私有资产归档 和本机 secrets 流程是否真的足够恢复一台新机器。

建议频率：

• 每次大规模改 shell / Clash / secrets 结构后做一次
• 至少每季度做一次

演练范围

本演练覆盖：

• dotfiles 仓库可访问
• Brewfile / Brewfile.lock.json 可用于恢复软件基线
• ~/.zshrc 与 ~/.zshrc.d 可由仓库重建
• ~/.config/secrets 可由骨架恢复，再由私有归档补真实值
• SSH / GPG / kube / Docker / Clash 私有配置可从私有归档恢复

本演练不自动覆盖：

• macOS Keychain
• 浏览器登录态
• OrbStack volume / VM 数据
• 大体积本地模型和下载目录

演练前提

准备好以下资产：

1. dotfiles 仓库地址可访问
2. 一份最近生成的私有归档，例如：

~/Backups/dotfiles-private/private-assets-YYYYMMDD-HHMMSS.tgz
~/Backups/dotfiles-private/private-assets-YYYYMMDD-HHMMSS.tgz.sha256

3. 一台可接受的演练环境：

• 新 macOS 机器
• 新建测试用户
• 或最少在隔离目录里做非破坏性演练

Phase 1: 归档验证

1. 验证私有归档校验和：

shasum -a 256 -c ~/Backups/dotfiles-private/private-assets-YYYYMMDD-HHMMSS.tgz.sha256

通过标准：

• 输出 OK

2. 查看归档顶层结构：

tar -tzf ~/Backups/dotfiles-private/private-assets-YYYYMMDD-HHMMSS.tgz \
  | awk -F/ 'NF{root=($1=="."?$2:$1); if(root!="") print root}' \
  | sort -u

通过标准：

• 至少看到 Users 和 metadata

3. 查看归档里的手工项说明：

tar -xOf ~/Backups/dotfiles-private/private-assets-YYYYMMDD-HHMMSS.tgz metadata/manual-steps.txt

通过标准：

• 能看到 Keychain、浏览器、OrbStack 等手工项提醒

Phase 2: 仓库恢复验证

1. 克隆仓库：

mkdir -p ~/work/codes/tools/macos
git clone http://192.168.1.83:33000/gao/dotfiles.git ~/work/codes/tools/macos/dotfiles
cd ~/work/codes/tools/macos/dotfiles

2. 检查仓库结构：

test -f Brewfile
test -f RECOVERY.md
test -f RECOVERY-DRILL.md
test -f config/homebrew/Brewfile.lock.json
test -f config/clash/clashx.public.yaml
test -f config/recovery/private-assets.tsv

通过标准：

• 上述文件都存在

Phase 3: 软件基线恢复验证

1. 安装基础开发工具：

xcode-select --install
# 安装 Homebrew

2. 恢复 Homebrew 基线：

brew bundle --file Brewfile

3. 抽样对照版本快照：

jq '.formulae[] | select(.name=="git" or .name=="jq" or .name=="zsh")' config/homebrew/Brewfile.lock.json

通过标准：

• 关键工具已安装
• 与 Brewfile.lock.json 相比，差异是可接受的

Phase 4: Shell 接入验证

1. 接入 shell 配置：

./install/doctor.sh || true
./install/link.sh
source ~/.zshrc

2. 验证核心入口：

command -v codex
command -v codex-direct
bash ./install/doctor.sh
bash ./scripts/shell/lint-zsh.sh

通过标准：

• codex 指向 ~/bin/codex
• install/doctor.sh 全部通过或仅有预期 warn
• lint-zsh.sh 全部 ok

Phase 5: 私有资产恢复验证

1. 先跑清单检查：

./scripts/backup/check-private-assets.sh

2. 从私有归档恢复到测试环境：

mkdir -p /tmp/dotfiles-restore-test
tar -xzf ~/Backups/dotfiles-private/private-assets-YYYYMMDD-HHMMSS.tgz -C /tmp/dotfiles-restore-test
find /tmp/dotfiles-restore-test -maxdepth 3 | sed -n '1,80p'

3. 抽样确认这些路径存在：

• Users/.../.ssh
• Users/.../.gnupg
• Users/.../.config/secrets
• Users/.../.kube/config
• Users/.../.docker/config.json
• Users/.../.config/clash/clashx.yaml

通过标准：

• 私有归档包含关键文件
• metadata/private-assets.tsv 与实际内容一致

Phase 6: Secrets 与代理验证

1. 初始化 secrets 骨架：

./scripts/secrets/bootstrap.sh

2. 恢复真实 secrets 文件后，验证 shell 变量：

source ~/.zshrc
printf '%s\n' "$ANTHROPIC_BASE_URL"

3. 验证 codex 代理路径：

codex-proxy-status

通过标准：

• secrets 文件被正确加载
• codex 使用 Clash 的 7890 本地代理

Phase 7: Clash 恢复验证

1. 用仓库里的公开模板和私有节点信息重建 live config
2. 保证 ClashX 的基础端口来自 config/clash/config.public.yaml
3. 重载后检查：

./scripts/clash/check-openai-route.sh

通过标准：

• chatgpt.com / openai.com 相关请求走同一稳定代理组
• external-controller 可访问

Phase 8: 手工项确认

必须人工确认：

1. Keychain 中关键 token 和证书是否恢复
2. 浏览器登录态是否需要恢复
3. OrbStack volume / VM 数据是否需要恢复
4. 本地模型、下载目录、工作缓存是否需要恢复

Phase 9: 验收

演练完成后，至少确认：

command -v codex
command -v kubectl
command -v java
command -v pnpm
./scripts/backup/check-private-assets.sh
./scripts/clash/check-openai-route.sh

通过标准：

• dotfiles 可以独立恢复 shell 和 wrapper
• 私有归档确实能补齐非版本化关键资产
• 手工项清单足够指导最后一段恢复

演练记录建议

每次演练后记录：

1. 演练日期
2. 使用的归档文件名
3. 失败点
4. 缺失资产
5. 需要新增到 dotfiles 的恢复步骤

建议把记录追加到你自己的运维日志，而不是直接覆盖本文件。