Docker Build-Push Action 中 GitHub Actions Cache 服务迁移指南

背景概述

近期在使用 Docker 官方提供的 build-push-action 进行容器镜像构建时，许多用户遇到了关于 GitHub Actions Cache 服务的报错信息。该错误提示旧版缓存服务即将在 2025 年 4 月 15 日停止服务，要求用户尽快迁移到新版服务。

问题本质

这个问题的根源在于 GitHub 对其缓存服务架构进行了重大升级，废弃了旧版 v1 缓存服务，全面转向 v2 服务。旧版服务基于特定的 API 实现，而新版服务采用了完全不同的技术架构。

技术解决方案

关键组件版本要求

要解决这个问题，需要确保构建环境中的几个关键组件满足最低版本要求：

1. BuildKit：必须使用 0.20.0 或更高版本
2. Buildx：需要 0.21.0 或更高版本
3. build-push-action：建议使用最新稳定版（当前为 v6）

具体配置方法

在 GitHub Actions 工作流中，应进行如下配置：

- name: 设置 Docker Buildx
  uses: docker/setup-buildx-action@v3
  with:
    version: latest  # 确保获取最新版 Buildx

对于使用自托管运行器的场景，还需要特别注意：

1. 确保自托管环境中的 BuildKit 版本不低于 0.20.0
2. 可以通过指定镜像方式使用新版 BuildKit

with:
  driver-opts: image=moby/buildkit:v0.20.0

技术原理深入

新版缓存服务 v2 与旧版的主要区别在于：

1. 协议支持：v2 服务采用了完全重新设计的通信协议
2. 性能优化：新版服务在缓存命中率和传输效率上有显著提升
3. 安全性增强：改进了认证和授权机制

底层实现上，Docker 工具链通过 tonistiigi/go-actions-cache 这个专门的 Go 库与 GitHub Actions 缓存服务交互，而不是直接使用 Node.js 的 @actions/cache 模块。

最佳实践建议

1. 版本锁定策略：虽然可以使用 latest 标签获取最新版本，但在生产环境中建议锁定经过验证的具体版本号
2. 缓存策略优化：考虑使用 mode=max 参数来最大化缓存利用率
3. 回退方案：在迁移过渡期，可以临时使用 no-cache: true 参数关闭缓存功能，但要注意这会导致构建时间增加
4. 监控机制：建立构建时长监控，确保缓存功能正常工作

常见问题排查

如果按照上述方案配置后仍然出现问题，可以检查以下方面：

1. 确认所有相关组件版本符合要求
2. 检查构建日志中是否显示正确加载了指定版本的 Buildx 和 BuildKit
3. 验证 GitHub Token 的权限设置是否正确
4. 对于复杂构建场景，考虑分阶段迁移和测试

未来展望

随着容器构建技术的持续发展，建议开发者：

1. 定期关注 Docker 和 GitHub 官方文档的更新
2. 建立自动化的依赖更新机制
3. 参与相关开源社区讨论，及时获取技术动态

通过正确配置和及时迁移，开发者可以继续充分利用 GitHub Actions 提供的强大缓存功能，保持高效的 CI/CD 流水线性能。