📚 课程目录第4章升级前缓存快照备份

4. 升级前缓存快照备份：备份工具、备份范围、备份命名规范

适用场景

在 AGP 版本升级前，必须对当前构建缓存状态进行完整快照备份，以便在升级出现兼容性故障或构建回滚时能够快速恢复缓存，避免全量重新下载和编译。本 SOP 适用于以下具体场景：

AGP 主版本升级（如 7.x → 8.x）前
AGP 次版本或补丁版本升级（如 8.1 → 8.2）前，且构建系统较为复杂或存在自研 Gradle 插件
Gradle 版本与 AGP 版本同时升级前
需要将现有构建环境迁移至新开发机或 CI 节点前

前置条件

当前 AGP 构建环境已稳定运行至少一个完整构建周期，缓存目录完整
备份目标存储位置有足够磁盘空间（建议至少保留当前缓存总大小的 1.2 倍）
已确认缓存目录路径（默认 ~/.gradle/caches/，可通过 gradle --info build 日志确认实际路径）
备份工具已就绪：Linux/macOS 可使用 tar、gzip、rsync；Windows 推荐使用 7-Zip 或 PowerShell Compress-Archive
当前正在进行的构建任务已全部完成，避免备份时出现文件锁定或写入不一致

操作步骤

确认缓存目录结构
执行命令列出缓存根目录下的一级子目录，确认构建缓存、依赖缓存、转换缓存等关键子目录均存在且非空。
```
ls -la ~/.gradle/caches/
# 预期输出包含 modules-2, transforms-2, buildsnoop, jar-snapshots 等子目录
```
执行备份命令
根据操作系统选择合适的打包工具。以下为 Linux/macOS 示例，将整个缓存目录打包为压缩归档：
```
BACKUP_NAME="cache-backup-$(date +%Y%m%d-%H%M%S)-AGP-$(agp_version).tar.gz"
tar -czf /path/to/backup/$BACKUP_NAME -C ~/.gradle caches/
```
若磁盘空间紧张，可排除 caches/modules-2/files-2.1/ 中的大型远程依赖包（可重新下载），仅备份构建缓存和转换缓存：
```
tar -czf /path/to/backup/$BACKUP_NAME \
  --exclude='caches/modules-2/files-2.1' \
  -C ~/.gradle caches/
```
生成校验文件
计算备份文件的 SHA-256 摘要，用于后续完整性校验：
```
sha256sum /path/to/backup/$BACKUP_NAME > /path/to/backup/$BACKUP_NAME.sha256
```

记录备份元信息
在备份同目录下创建一个 manifest.json 文件，记录备份时间、AGP 版本、Gradle 版本、缓存大小、排除项等。

{
  "backup_time": "2025-02-18 14:30:00",
  "agp_version": "8.1.0",
  "gradle_version": "8.4",
  "origin_cache_dir": "/home/jenkins/.gradle/caches",
  "total_cache_size_mb": 2456,
  "excluded_dirs": ["modules-2/files-2.1"],
  "tool": "tar+gzip+sha256",
  "backup_file": "cache-backup-20250218-143000-AGP-8.1.0.tar.gz",
  "checksum": "a1b2c3d4e5..."
}

移动备份至安全存储
将备份归档、SHA256 文件和 manifest.json 一同移至专用备份服务器或对象存储（如 S3/MinIO）。保留本地副本至少 7 天。

输入输出物

类型	内容	格式/路径
输入	当前 Gradle 缓存目录	`~/.gradle/caches/`
输入	AGP 版本号（用于命名）	从 `build.gradle` 或 `gradle.properties` 获取
输入	备份工具与目标存储路径	由团队基础设施决定
输出	压缩的缓存快照文件	`cache-backup-{datetime}-AGP-{version}.tar.gz`
输出	SHA-256 校验文件	`{backup_file}.sha256`
输出	备份元信息清单	`manifest.json`

责任边界

构建管理员 / CI 运维：负责制定备份策略、编写备份脚本、验证备份可用性；在升级前执行快照备份。
开发团队：触发升级前通知运维，确认当前构建环境无异常；配合执行备份验证（如随机恢复一个构建场景）。
质量保证：验收备份文件的完整性，确认备份范围覆盖核心缓存。

记录材料

备份日志文件（backup-YYYYMMDD-HHMMSS.log）：包含备份命令执行输出、打包耗时、文件大小。
备份清单（manifest.json）：记录版本、时间、路径、校验和、排除策略。
备份存储目录结构截图（可选）：用于快速确认备份文件位置。

异常处理

异常场景	处理措施
磁盘空间不足	清理目标存储的旧备份（保留最近 3 次），或使用 `rsync` 直接同步到远端而非本地打包。
缓存目录被进程锁定	使用 `lsof` 或 `fuser` 找出占用进程，暂停非关键 Gradle 守护进程后重试。
备份文件校验失败	删除损坏的备份归档，重新执行备份命令；检查磁盘 I/O 错误或内存不足。
AGP 版本号获取失败	手动填写备份文件名中的版本字段，并在 manifest 中标记 `version_source: "manual"`。
备份超时（大型缓存 > 10GB）	使用 `nice -n 19` 降低优先级，或分卷打包（如 `split` 分割 tar 包）。

验收标准

备份文件大小与缓存目录实际占用偏差不超过 5%（排除的目录需在 manifest 中注明）。
SHA-256 校验通过：sha256sum -c {backup_file}.sha256 输出 OK。
随机抽取备份中的部分缓存文件（如 transforms-2/ 下的某个 jar），使用 tar -tzf 确认文件可正常列出，解压后内容无损坏。
备份命名遵循规范 cache-backup-YYYYMMDD-HHMMSS-AGP-{version}.tar.gz，且对应 manifest 存在。
备份已上传至指定安全存储，本地副本保留策略生效。