Bitbucket Pipelines中Docker内联缓存复用不一致问题排查

问题背景 #

使用带固定SHA的AWS Lambda Python镜像作为Dockerfile基础镜像时，本地Mac环境可稳定复用缓存，但Bitbucket Pipelines中该基础镜像层时而命中缓存、时而重新下载，导致后续所有构建层均无法复用缓存，需要定位根因。

排查步骤 #

1. 确认Bitbucket Pipelines缓存配置 #

• 检查bitbucket-pipelines.yml是否开启Docker缓存卷：

  pipelines:
    default:
      - step:
          services:
            - docker
          caches:
            - docker  # 必须配置此条目以启用Docker镜像层缓存
          script:
            - docker build -t your-image .
  

• Bitbucket的Docker缓存基于工作空间隔离，若缓存超过有效期（默认30天）或存储空间不足，会被自动清理，导致重新拉取镜像。

2. 校验基础镜像SHA一致性 #

• 本地与Pipelines环境中拉取的基础镜像ID必须完全一致，执行以下命令对比：
  • 本地：docker inspect public.ecr.aws/lambda/python:3.12@sha256:<YOUR_SHA> | jq -r '.Id'
  • Pipelines脚本中新增：docker inspect public.ecr.aws/lambda/python:3.12@sha256:<YOUR_SHA> | grep Id
• 若ID不一致，大概率是Dockerfile中镜像地址书写错误（如漏写@sha256:前缀，导致拉取latest标签镜像）。

3. 排查构建上下文差异 #

• 确保Pipelines中docker build的上下文路径与本地完全一致（均为当前目录.）
• 检查.dockerignore文件是否在Pipelines中正常生效，避免无关文件进入构建上下文导致缓存键变更

4. 分析Pipeline缓存日志 #

• 查看Pipeline日志中缓存相关输出：
  • 缓存命中：Cache "docker": Downloaded
  • 缓存未命中：Cache "docker": Not found, generating
• 若频繁出现未命中，可能是Bitbucket缓存系统临时故障或缓存被手动清理。

5. 强制指定缓存源 #

• 使用--cache-from参数从镜像仓库拉取缓存层，避免依赖Pipelines本地缓存：

  docker build --cache-from your-registry/your-image:latest -t your-image .
  

• 前提是之前构建的镜像已推送到公开/私有镜像仓库。

6. 检查Runner环境（自托管场景） #

• 若使用自托管Runner，需确认Docker数据目录是否挂载持久卷，避免Runner重启后缓存丢失；托管Runner无需额外配置，但需接受其缓存回收机制。

日志参考 #

缓存生效示例 #

Step 1/10 : FROM public.ecr.aws/lambda/python:3.12@sha256:abc123
---> abc123456789
Using cache
---> abc123456789

缓存失效示例 #

Step 1/10 : FROM public.ecr.aws/lambda/python:3.12@sha256:abc123
---> Pulling from public.ecr.aws/lambda/python
abc123: Pulling fs layer
abc123: Verifying Checksum
abc123: Download complete
abc123: Pull complete
---> abc123456789

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