claude-code-router/brew

Homebrew 自动更新、备份和恢复系统

概述

这是一个完整的 Homebrew 自动化维护系统，支持每日自动更新、备份和一键恢复功能。适配 Mac Studio / Apple Silicon 架构。

目录结构

~/ops/
├── logs/                      # 运行日志
├── backups/                   # Brew 备份产物
└── brew/                      # Homebrew 维护模块
    ├── brew_maintain.sh       # 每日维护（更新/升级/清理/导出 Brewfile）
    ├── brew_backup.sh         # 手动/CI 触发备份
    ├── brew_restore.sh        # 恢复脚本（新机执行）
    ├── com.ljwx.brew.maintenance.plist # 定时任务配置
    └── README.md              # 本文档
~/Library/LaunchAgents/com.ljwx.brew.maintenance.plist

功能特性

1. 每日自动维护 (brew_maintain.sh)

• ✅ 每天 03:30 自动执行
• ✅ brew update (更新包索引)
• ✅ brew upgrade (升级所有包和 cask)
• ✅ brew autoremove (移除不需要的依赖)
• ✅ brew cleanup -s (清理旧版本缓存)
• ✅ 自动导出 Brewfile (用于恢复)
• ✅ 生成包清单快照
• ✅ 自动日志管理和备份保留策略

2. 手动备份 (brew_backup.sh)

• ✅ 按需触发完整备份
• ✅ 导出当前环境的 Brewfile
• ✅ 生成包和 cask 的详细清单
• ✅ 打包为时间戳命名的压缩文件

3. 一键恢复 (brew_restore.sh)

• ✅ 自动安装 Xcode 命令行工具
• ✅ 自动安装 Homebrew (如果未安装)
• ✅ 从 Brewfile 一键恢复所有包和 cask
• ✅ 支持指定备份文件恢复

快速开始

1. 创建目录结构

mkdir -p ~/ops/{logs,backups}

2. 设置每日自动维护

chmod +x ~/ops/brew/brew_maintain.sh
launchctl unload ~/Library/LaunchAgents/com.ljwx.brew.maintenance.plist 2>/dev/null || true
launchctl load -w ~/Library/LaunchAgents/com.ljwx.brew.maintenance.plist

3. 立即测试运行

~/ops/brew/brew_maintain.sh

使用说明

查看运行状态

# 查看定时任务状态
launchctl list | grep brew

# 查看最新日志
tail -f ~/ops/logs/brew_maintain_$(date +%F).log

手动备份

~/ops/brew/brew_backup.sh
# 输出: ✅ 备份完成：/Users/username/ops/backups/brew_backup_2025-10-19_120000.tar.gz

新机恢复

# 默认使用最新备份
~/ops/brew/brew_restore.sh

# 或指定特定备份文件
~/ops/brew/brew_restore.sh ~/ops/backups/Brewfile_2025-10-19.brew

配置说明

定时任务时间调整

编辑 ~/Library/LaunchAgents/com.ljwx.brew.maintenance.plist 中的 StartCalendarInterval:

<key>StartCalendarInterval</key>
<dict>
  <key>Hour</key><integer>3</integer>    <!-- 修改为想要的小时 -->
  <key>Minute</key><integer>30</integer> <!-- 修改为想要的分钟 -->
</dict>

日志保留策略

• 日志文件保留 14 天
• Brewfile 备份保留 60 天
• 可在脚本中调整 find 命令的 -mtime 参数

故障排除

定时任务未执行

# 检查 launchd 状态
launchctl list | grep com.ljwx.brew.maintenance

# 重新加载
launchctl unload ~/Library/LaunchAgents/com.ljwx.brew.maintenance.plist
launchctl load -w ~/Library/LaunchAgents/com.ljwx.brew.maintenance.plist

# 手动测试
~/ops/brew/brew_maintain.sh

权限问题

# 确保脚本可执行
chmod +x ~/ops/brew/*.sh

# 确保目录权限正确
chmod 755 ~/ops
chmod 755 ~/ops/logs
chmod 755 ~/ops/backups

恢复过程中的问题

• GUI 应用需要手动授权 (macOS 安全机制)
• 某些 cask 可能需要首次启动配置
• 建议恢复后运行 brew doctor 检查

高级配置

环境变量

脚本自动设置 PATH 以支持 launchd 环境:

export PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"

备份策略扩展

可以考虑将备份同步到云存储:

# 示例: 同步到 iCloud
rsync -av ~/ops/backups/ ~/Library/Mobile\ Documents/com~apple~CloudDocs/ops-backups/

项目结构扩展

这个 macos 项目未来可以扩展为模块化结构：

~/ops/
├── logs/                      # 统一日志目录
├── backups/                   # 统一备份目录
├── brew/                      # Homebrew 维护模块
│   ├── brew_maintain.sh       # 每日维护脚本
│   ├── brew_backup.sh         # 备份脚本
│   ├── brew_restore.sh        # 恢复脚本
│   ├── com.ljwx.brew.maintenance.plist # 定时任务
│   └── README.md              # Brew 模块文档
├── [其他模块]/                 # 未来可添加其他模块
│   ├── [模块脚本]
│   └── README.md
└── README.md                  # 项目总文档

注意事项

• 图形类 cask 恢复可能需要手动授权
• 建议定期检查备份文件完整性
• 重大系统更新前建议手动备份
• 脚本设计为幂等性，可安全重复执行

许可证

MIT License - 可自由使用和修改