Spring Boot 3.2.x+Gradle+bootBuildImage在Bitbucket Pipelines遇Docker API 403错误

问题原因 #

Bitbucket Pipelines的Docker服务默认通过/var/run/docker.sock Unix套接字提供访问，而非无认证的TCP端口2375。直接使用TCP连接会因缺少认证触发403禁止错误，即使指定172.17.0.1也无法绕过权限校验。

解决方案 #

方案1：通过环境变量指定Unix套接字连接 #

修改bitbucket-pipelines.yml的脚本部分，添加DOCKER_HOST环境变量指向Unix套接字：

pipelines:
  default:
    - step:
        name: Build
        image: gradle:8.7-jdk21
        services:
          - docker
        script:
          - export DOCKER_HOST=unix:///var/run/docker.sock
          - gradle bootBuildImage

方案2：在Gradle构建脚本中配置Docker连接 #

在项目的build.gradle或build.gradle.kts中直接指定Docker主机地址：

// build.gradle
bootBuildImage {
    docker {
        host = "unix:///var/run/docker.sock"
    }
}

// build.gradle.kts
bootBuildImage {
    docker {
        host.set("unix:///var/run/docker.sock")
    }
}

修改后无需在Pipeline脚本中额外设置环境变量，直接执行gradle bootBuildImage即可。

方案3：调整Docker套接字权限（可选） #

如果仍出现权限问题，可在脚本中临时调整Docker套接字的权限：

pipelines:
  default:
    - step:
        name: Build
        image: gradle:8.7-jdk21
        services:
          - docker
        script:
          - sudo chmod 666 /var/run/docker.sock
          - gradle bootBuildImage

注意：此方法会降低套接字的安全性，仅在必要时使用。

验证逻辑 #

本地环境正常是因为Docker默认配置允许本地用户通过Unix套接字访问，而Bitbucket Pipelines的容器环境中，gradle用户默认可能没有访问/var/run/docker.sock的权限，或默认使用TCP连接导致认证失败。切换到Unix套接字连接后，会使用容器内的权限直接访问挂载的Docker服务，避免TCP端口的认证问题。

内容的提问来源于stack exchange，提问作者armijo