Docker Build-Push-Action 常见问题排查指南

Docker Build-Push-Action 常见问题排查指南

【免费下载链接】build-push-action GitHub Action to build and push Docker images with Buildx 项目地址: https://gitcode.com/gh_mirrors/bu/build-push-action

前言

在使用 Docker Build-Push-Action 进行镜像构建和推送时，开发者可能会遇到各种问题。本文针对常见问题提供详细的排查方法和解决方案，帮助开发者快速定位和解决问题。

镜像推送问题排查

常见错误类型

在向镜像仓库推送时，可能会遇到以下类型的错误：

1. 内容摘要校验失败
   • failed commit on ref "layer-sha256:...": invalid content digest in response: invalid checksum digest format
2. 无响应错误
   • failed commit on ref "layer-sha256:...": no response
3. 请求错误
   • failed commit on ref "manifest-sha256:...": unexpected status: 400 Bad Request
4. 认证错误
   • failed commit on ref "manifest-sha256:...": unexpected status: 401 Unauthorized
   • unexpected response: 401 Unauthorized

这些错误通常与底层组件(Buildx、BuildKit、containerd)或目标镜像仓库有关，而非直接由 Build-Push-Action 引起。

排查步骤

第一步：启用调试日志

1. 在 setup-buildx 步骤中启用调试模式
2. 获取 BuildKit 容器日志
3. 分析日志中的详细错误信息

第二步：使用 containerd 验证

如果问题持续存在，可以使用 containerd 进行验证测试：

steps:
  - name: 设置 QEMU
    uses: docker/setup-qemu-action@v3
  
  - name: 设置 Docker Buildx
    uses: docker/setup-buildx-action@v3
    with:
      buildkitd-flags: --debug
  
  - name: 设置 containerd
    uses: crazy-max/ghaction-setup-containerd@v2
  
  - name: 构建 Docker 镜像
    uses: docker/build-push-action@v6
    with:
      context: .
      platforms: linux/amd64,linux/arm64
      tags: docker.io/user/app:latest
      outputs: type=oci,dest=/tmp/image.tar
  
  - name: 导入镜像到 containerd
    run: |
      sudo ctr i import --base-name docker.io/user/app --digests --all-platforms /tmp/image.tar
  
  - name: 使用 containerd 推送镜像
    run: |
      sudo ctr --debug i push --user "${{ secrets.DOCKER_USERNAME }}:${{ secrets.DOCKER_PASSWORD }}" docker.io/user/app:latest

如果 containerd 可以成功推送，则问题可能出在 BuildKit 实现上。

仓库名称必须小写问题

问题表现

当使用包含大写字母的仓库名称时，会出现以下错误：

#6 ERROR: invalid reference format: repository name must be lowercase

解决方案

方法一：使用元数据 Action 自动处理

- name: 生成 Docker 元数据
  id: meta
  uses: docker/metadata-action@v4
  with:
    images: ghcr.io/${{ github.repository }}
    tags: latest

- name: 构建并推送
  uses: docker/build-push-action@v6
  with:
    context: .
    push: true
    tags: ${{ steps.meta.outputs.tags }}

方法二：手动转换小写

- name: 转换仓库名称为小写
  uses: actions/github-script@v6
  id: repo_slug
  with:
    result-encoding: string
    script: return 'ghcr.io/${{ github.repository }}'.toLowerCase()

- name: 构建并推送
  uses: docker/build-push-action@v6
  with:
    context: .
    push: true
    tags: ${{ steps.repo_slug.outputs.result }}:latest

最佳实践建议

1. 始终使用小写字母的仓库名称
2. 在开发阶段启用调试日志
3. 对于复杂构建场景，先使用 containerd 验证基本功能
4. 考虑使用元数据 Action 自动处理标签生成

总结

本文介绍了 Docker Build-Push-Action 使用过程中的常见问题及其解决方案。通过理解底层组件的工作原理和遵循最佳实践，可以显著减少构建和推送过程中遇到的问题。当遇到问题时，建议按照文中提供的步骤进行系统性排查。

【免费下载链接】build-push-action GitHub Action to build and push Docker images with Buildx 项目地址: https://gitcode.com/gh_mirrors/bu/build-push-action