Azure Pipelines中Docker多阶段构建缓存失效问题求助

问题描述 #

优化Azure Pipelines时发现，unit-testing和integration-testing阶段会重复构建相同依赖层，运行效率极低。已执行以下操作但未解决：

• 构建指定--target development的镜像，通过Cache@2存入缓存；
• UnitTest阶段成功用docker load -i从缓存加载镜像（docker images确认镜像存在）；
• 运行unit-tests时使用--cache-from和--target unit-tests参数；
• 流水线已识别缓存，但仍会重新构建development镜像应包含的阶段，日志显示重新拉取python-base层。

错误原因分析 #

1. 多阶段构建依赖链断裂：development阶段直接基于python-base而非builder-base，仅通过COPY --from=builder-base复制文件，导致Docker无法将builder-base的构建层关联到development镜像，缓存无法跨阶段传递；
2. BuildKit缓存匹配逻辑限制：--cache-from默认仅匹配最终镜像的层，无法识别多阶段构建中的中间层关联，导致即使缓存了development镜像，BuildKit仍会重新构建前置阶段；
3. 缓存键未关联依赖文件：当前缓存键docker | "$(Agent.OS)" | cache未包含poetry.lock、pyproject.toml等依赖文件的哈希，无法精准触发缓存更新或命中；
4. 手动缓存操作的局限性：通过docker save/load保存的镜像，其层元数据可能在加载后无法被BuildKit完整识别，导致缓存匹配失败。

解决方案 #

1. 修复Dockerfile阶段依赖链 #

修改development阶段的基础镜像，让阶段依赖连续，确保BuildKit能识别中间层缓存：

# ./api/docker/Dockerfile 修改片段
# 原代码：
# FROM python-base as development

# 修改后：
FROM builder-base as development

修改后development直接继承builder-base的所有构建层，后续unit-tests阶段基于development时，可直接复用前置阶段的缓存。

2. 优化缓存键，关联依赖文件哈希 #

更新Cache@2任务的缓存键，加入依赖文件的哈希值，确保依赖变更时触发重新构建，否则命中有效缓存：

# Build阶段和UnitTest阶段的Cache@2任务统一更新：
- task: Cache@2
  displayName: Creating cache...
  inputs: 
    key: 'docker | "$(Agent.OS)" | $(Build.SourcesDirectory)/$(service)/poetry.lock | $(Build.SourcesDirectory)/$(service)/pyproject.toml'
    path: $(Pipeline.Workspace)/docker
    cacheHitVar: CACHE_RESTORED

3. 调整UnitTest阶段的Docker构建命令 #

明确指定--cache-from的镜像标签，并确保构建上下文与Build阶段一致：

- task: Docker@2
  displayName: Running unit-tests...
  inputs:
    command: 'build'
    repository: $(imageRepository)-$(service)
    dockerfile: $(dockerFilePath)/$(service)/docker/Dockerfile
    buildContext: $(dockerFilePath)/$(service)
    arguments: |
      --cache-from=$(imageRepository)-$(service):pr-development
      --target unit-tests
  env:
    DOCKER_BUILDKIT: 1

同时在Build阶段构建时，给development镜像添加明确标签：

- task: Docker@2
  displayName: Building image for tests...
  inputs:
    command: 'build'
    repository: $(imageRepository)-$(service)
    dockerfile: $(dockerFilePath)/$(service)/docker/Dockerfile
    buildContext: $(dockerFilePath)/$(service)
    arguments: |
      --target development
    tags: |
      pr-development
  env:
    DOCKER_BUILDKIT: 1

4. 替代手动缓存：使用Docker任务内置层缓存（推荐） #

放弃手动docker save/load操作，直接使用Docker任务的cacheFrom参数，让任务自动处理层缓存，更高效且避免元数据丢失：

# Build阶段任务简化：
- task: Docker@2
  displayName: Build development image
  inputs:
    command: build
    repository: $(imageRepository)-$(service)
    dockerfile: $(dockerFilePath)/$(service)/docker/Dockerfile
    buildContext: $(dockerFilePath)/$(service)
    arguments: --target development
    tags: pr-development
    cacheFrom: $(imageRepository)-$(service):pr-development
  env:
    DOCKER_BUILDKIT: 1

# UnitTest阶段任务简化：
- task: Docker@2
  displayName: Running unit-tests...
  inputs:
    command: 'build'
    repository: $(imageRepository)-$(service)
    dockerfile: $(dockerFilePath)/$(service)/docker/Dockerfile
    buildContext: $(dockerFilePath)/$(service)
    arguments: |
      --cache-from=$(imageRepository)-$(service):pr-development
      --target unit-tests
  env:
    DOCKER_BUILDKIT: 1

验证标准 #

执行流水线后，查看UnitTest阶段的Docker构建日志，若出现CACHED标记，说明缓存已生效：

#5 [python-base 1/1] FROM docker.io/library/python:3.9-slim
#5 CACHED
#6 [builder-base 1/4] RUN apt-get update && apt-get install --no-install-recommends -y curl build-essential
#6 CACHED

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