Bitbucket Pipeline无法拉取Docker Hub私有仓库最新容器求助

可能的原因 #

• Bitbucket Pipeline Docker缓存：Pipeline默认会缓存已拉取的Docker镜像，仓库转为私有后，旧的公开镜像仍在缓存中，Pipeline直接复用缓存版本，未触发从私有仓库拉取新镜像的逻辑。
• Docker Hub认证配置问题：仓库转私有后，若Pipeline未配置正确的Docker Hub认证信息，Docker无法访问私有仓库，会自动 fallback 到本地缓存的旧镜像，导致无法获取新推送的版本。
• 镜像标签重复使用：如果新推送的镜像使用了和旧镜像相同的标签（如latest），Docker在本地有缓存的情况下，会优先使用本地缓存，不会主动去远程仓库检查更新。

解决步骤 #

1. 强制拉取最新镜像（跳过缓存） #

在Pipeline的拉取命令中添加--no-cache参数，强制Docker忽略本地缓存，直接从私有仓库拉取最新版本：

docker pull --no-cache your-docker-hub-username/your-image-name:your-tag

2. 配置Docker Hub认证 #

在Bitbucket仓库的Repository settings > Repository variables中添加两个变量：

• DOCKER_HUB_USERNAME：你的Docker Hub用户名
• DOCKER_HUB_PASSWORD：你的Docker Hub访问令牌（推荐使用令牌而非明文密码）

然后在bitbucket-pipelines.yml中加入登录步骤，确保Pipeline有权限访问私有仓库：

pipelines:
  default:
    - step:
        name: Pull latest private Docker image
        script:
          - echo $DOCKER_HUB_PASSWORD | docker login -u $DOCKER_HUB_USERNAME --password-stdin
          - docker pull your-docker-hub-username/your-image-name:your-tag
        services:
          - docker

3. 清理Pipeline缓存 #

若上述方法无效，可手动清理Bitbucket Pipeline的缓存：

1. 进入仓库的Pipelines > Settings > Caches
2. 找到与Docker相关的缓存条目，点击删除

4. 使用唯一镜像标签 #

避免重复使用latest这类通用标签，每次推送新镜像时使用唯一标签（如基于Commit哈希、版本号或时间戳）：

# 推送时打唯一标签
docker tag your-image your-docker-hub-username/your-image:v1.0.1-$(git rev-parse --short HEAD)
docker push your-docker-hub-username/your-image:v1.0.1-$(git rev-parse --short HEAD)

# Pipeline中拉取该唯一标签
docker pull your-docker-hub-username/your-image:v1.0.1-$(git rev-parse --short HEAD)

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