ljwx-harbor/brew

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

概述

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

🚀 快速开始（一键配置）

cd /Users/brunogao/work/codes/tools/macos/brew
./setup-auto-update.sh

配置完成后，系统将：

• ✅ 每天 03:30 自动运行 Homebrew 维护
• ✅ 自动更新所有软件包
• ✅ 自动清理缓存和旧版本
• ✅ 自动备份 Brewfile（可用于恢复）
• ✅ 生成详细的维护日志

🎯 快速管理命令

使用 brew-manager.sh 管理自动化服务：

# 查看服务状态
./brew-manager.sh status

# 手动执行备份
./brew-manager.sh backup

# 立即运行维护
./brew-manager.sh run

# 查看所有备份
./brew-manager.sh list

# 实时查看日志
./brew-manager.sh logs -f

# 停止/启动/重启服务
./brew-manager.sh stop
./brew-manager.sh start
./brew-manager.sh restart

目录结构

~/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                  # 项目总文档

⚠️ 故障排除

自动更新未生效

症状：每天 03:30 定时任务运行，但包一直没有更新

可能原因：

1. 某个 cask/formula 定义错误导致 brew update 失败
2. tap 仓库问题
3. 包冲突（如 vim/macvim 冲突）

诊断步骤：

# 1. 查看最近的日志
./brew-manager.sh status

# 2. 查看详细日志
tail -50 ~/ops/logs/brew_maintain_$(date +%F).log

# 3. 运行健康检查
./brew-manager.sh verify

# 4. 自动修复常见问题
./brew-manager.sh fix

常见问题和解决方案：

问题 1: vim/macvim 冲突

错误信息：

Error: Cannot install macvim because conflicting formulae are installed.

原因：同时安装了 vim 和 macvim，导致包链接冲突

解决方案：

# 检查你实际使用的编辑器
which vi vim nvim

# 如果使用 neovim（推荐）
brew uninstall vim macvim
# neovim 功能更强大，通过 alias 映射即可

# 如果使用 vim
brew uninstall macvim
brew upgrade vim

# 如果使用 macvim
brew uninstall vim
brew upgrade macvim

问题 2: 损坏的 cask 定义

错误信息：

Error: Cask 'xxx' definition is invalid

解决方案：

# 卸载有问题的 cask
brew uninstall --cask <cask_name>

# 运行自动修复
./brew-manager.sh fix

问题 3: 无效的 tap 仓库

错误信息：

ERROR: Repository not found.
fatal: Could not read from remote repository.

解决方案：

# 查看所有 tap
brew tap

# 移除有问题的 tap
brew untap <tap_name>

# 或使用自动修复
./brew-manager.sh fix

维护脚本容错性增强

更新内容（2025-12-30）：

维护脚本已从 set -euo pipefail 改为 set -uo pipefail，增强了容错能力：

修改前：

• 任何步骤失败立即退出
• 后续步骤不会执行
• 可能导致包长期未更新

修改后：

• 记录错误但继续执行
• 所有步骤都会尝试运行
• 最后报告错误总数
• 确保大部分包能正常更新

效果对比：

修改前：ollama-app 错误 → brew update 失败 → 脚本终止 ❌
修改后：ollama-app 错误 → 记录错误 → 继续升级其他包 ✅

性能优化建议

定期清理：

# 查看磁盘使用
./brew-stats.sh disk

# 查看最大的包
./brew-stats.sh top 20

# 手动清理
brew cleanup -s

备份验证：

# 验证最新备份
./brew-verify.sh brewfile ~/ops/backups/Brewfile.latest

# 对比两个备份
./brew-verify.sh compare \
  ~/ops/backups/Brewfile_2025-12-29.brew \
  ~/ops/backups/Brewfile_2025-12-30.brew

注意事项

• 图形类 cask 恢复可能需要手动授权
• 建议定期检查备份文件完整性
• 重大系统更新前建议手动备份
• 脚本设计为幂等性，可安全重复执行
• 维护脚本现在具有容错性，即使部分步骤失败也会继续执行

📝 快速参考卡

基础命令

操作	命令
一键配置	./setup-auto-update.sh
查看状态	./brew-manager.sh status
手动备份	./brew-manager.sh backup
立即维护	./brew-manager.sh run
查看日志	./brew-manager.sh logs -f
查看备份	./brew-manager.sh list
启动服务	./brew-manager.sh start
停止服务	./brew-manager.sh stop
恢复系统	./brew_restore.sh

🆕 高级功能（新增）

功能	命令	说明
📊 统计信息	./brew-manager.sh stats	查看安装包、备份、维护历史统计
🔍 验证备份	./brew-manager.sh verify	健康检查和备份完整性验证
📈 趋势分析	./brew-stats.sh trends	查看包安装趋势
💾 磁盘分析	./brew-stats.sh disk	分析 Homebrew 磁盘使用
🏆 最大包	./brew-stats.sh top 10	查看最占空间的包
📄 生成报告	./brew-stats.sh report	生成完整统计报告
✅ 验证 Brewfile	./brew-verify.sh brewfile <文件>	验证备份文件
🔀 对比备份	./brew-verify.sh compare <文件1> <文件2>	对比两个备份差异

新增工具说明

1. 通知系统 (brew-notify.sh)

• macOS 通知中心集成
• 维护完成/失败自动通知
• 支持自定义声音和消息

2. 增强维护脚本 (brew_maintain_enhanced.sh)

• 详细的错误处理和统计
• JSON 格式的维护数据
• 彩色输出和进度跟踪
• 可配置的清理策略
• 容错性增强：即使部分步骤失败也会继续执行

3. 备份验证工具 (brew-verify.sh)

# 验证 Brewfile
./brew-verify.sh brewfile ~/ops/backups/Brewfile.latest

# 验证压缩包
./brew-verify.sh archive ~/ops/backups/brew_backup_2025-12-28.tar.gz

# 对比两个备份
./brew-verify.sh compare Brewfile1.brew Brewfile2.brew

# 健康检查
./brew-verify.sh health

4. 统计报告工具 (brew-stats.sh)

# 查看摘要
./brew-stats.sh summary

# 最近维护历史（最近7天）
./brew-stats.sh recent 7

# 包安装趋势
./brew-stats.sh trends

# 磁盘使用情况
./brew-stats.sh disk

# 最大的包（Top 10）
./brew-stats.sh top 10

# 生成完整报告
./brew-stats.sh report ~/Desktop/brew_report.txt

关键文件位置

类型	路径
配置文件	~/Library/LaunchAgents/com.ljwx.brew.maintenance.plist
脚本目录	~/ops/brew/
日志目录	~/ops/logs/
备份目录	~/ops/backups/
最新快照	~/ops/backups/Brewfile.latest

自动维护任务

每天 03:30 自动执行：

1. brew update - 更新包索引
2. brew upgrade - 升级所有包
3. brew autoremove - 清理依赖
4. brew cleanup -s - 清理缓存
5. 导出 Brewfile 快照
6. 生成包清单列表

数据保留策略

• 日志文件：保留 14 天
• Brewfile 备份：保留 60 天
• 最新快照：始终保留

许可证

MIT License - 可自由使用和修改