Azure Pipeline Docker任务缓存失效问题求助

背景 #

本地构建时Docker缓存正常生效（仅最后一层随源码变更重建），但Azure DevOps流水线中，仅FROM和ARG INDEX_URL层复用缓存，后续ENV、COPY requirements.txt、RUN pip install等层每次都重新构建。

已确认核心原因：PipAuthenticate@1生成的PIP_EXTRA_INDEX_URL是每次构建唯一、有效期1-2天的带临时凭证的URL，而该ARG在Dockerfile靠前位置，导致后续所有依赖此ARG的层（包括ENV、RUN等）缓存全部失效。

当前Dockerfile：

FROM my_teams_own_baseimage

# Set index for package installation of our own python packages
ARG INDEX_URL
ENV PIP_EXTRA_INDEX_URL=$INDEX_URL

# Copy the requirements file, set the working directory, and install 
# python requirements for this project.
COPY requirements.txt /work/
WORKDIR /work
RUN python -m pip install pip --upgrade \
  && pip install --no-cache -r requirements.txt

# Copy all the remaining stuff into /work
COPY . /work/

当前Azure DevOps流水线关键步骤：

- task: PipAuthenticate@1
  displayName: 'Pip authenticate'
  inputs:
    artifactFeeds: $(ArtifactFeed)
    onlyAddExtraIndex: true

- task: Docker@1
  displayName: 'Docker login'
  inputs:
    containerregistrytype: 'Azure Container Registry'
    azureSubscriptionEndpoint: '$(AzureSubscription)'
    azureContainerRegistry: '$(ACR)'
    command: 'login'

- script: "docker pull $(ACR)/$(ImagePrefix)$(ImageName):latest"
  displayName: "Pull latest image for layer caching"
  continueOnError: true # for first build, no cache

- task: Docker@1
  displayName: 'Build image'
  inputs:
    containerregistrytype: 'Azure Container Registry'
    azureSubscriptionEndpoint: '$(AzureSubscription)'
    azureContainerRegistry: '$(ACR)'
    command: 'Build an image'
    dockerFile: 'Dockerfile'
    arguments: |
      --cache-from $(ACR)/$(ImagePrefix)$(ImageName):latest
      --build-arg INDEX_URL=$(PIP_EXTRA_INDEX_URL)
    imageName: '$(ACR)/$(ImagePrefix)$(ImageName):$(ImageTag)'

可行解决方案 #

方案1：将PIP认证逻辑移出Docker构建，主机层处理pip配置 #

无需把PIP_EXTRA_INDEX_URL传入Docker构建，而是在Azure DevOps代理主机上生成pip配置文件，再复制到镜像中，避免动态ARG/ENV影响缓存。

步骤：

1. PipAuthenticate@1执行后，会自动生成临时pip配置文件，路径通过PIP_CONFIG_FILE环境变量获取。
2. 修改Dockerfile，移除ARG和ENV指令，改为复制主机的pip配置：

FROM my_teams_own_baseimage

# 复制主机上的pip配置文件（包含认证信息）
COPY pip.conf /etc/pip.conf  # Linux环境，Windows对应路径为C:\ProgramData\pip\pip.ini

# Copy the requirements file, set the working directory, and install 
# python requirements for this project.
COPY requirements.txt /work/
WORKDIR /work
RUN python -m pip install pip --upgrade \
  && pip install --no-cache -r requirements.txt

# Copy all the remaining stuff into /work
COPY . /work/

3. 修改流水线，将主机的pip配置复制到构建上下文：

- task: PipAuthenticate@1
  displayName: 'Pip authenticate'
  inputs:
    artifactFeeds: $(ArtifactFeed)
    onlyAddExtraIndex: true

- script: "cp $PIP_CONFIG_FILE $(Build.SourcesDirectory)/pip.conf"
  displayName: 'Copy pip config to build context'
  condition: eq(variables['Agent.OS'], 'Linux')

- script: "copy %PIP_CONFIG_FILE% $(Build.SourcesDirectory)\\pip.ini"
  displayName: 'Copy pip config to build context'
  condition: eq(variables['Agent.OS'], 'Windows_NT')

# 后续Docker login、pull缓存镜像、build步骤不变，移除--build-arg INDEX_URL参数
- task: Docker@1
  displayName: 'Build image'
  inputs:
    containerregistrytype: 'Azure Container Registry'
    azureSubscriptionEndpoint: '$(AzureSubscription)'
    azureContainerRegistry: '$(ACR)'
    command: 'Build an image'
    dockerFile: 'Dockerfile'
    arguments: |
      --cache-from $(ACR)/$(ImagePrefix)$(ImageName):latest
    imageName: '$(ACR)/$(ImagePrefix)$(ImageName):$(ImageTag)'

仅当requirements.txt或pip配置文件变化时，RUN pip install层才会重建，其他层可正常复用缓存。

方案2：使用Docker BuildKit秘密挂载，避免认证信息写入镜像层 #

Docker BuildKit支持构建时临时挂载秘密文件，不通过ARG/ENV传入认证信息，也不会写入镜像层，同时不影响缓存哈希。

步骤：

1. 启用Docker BuildKit：在Docker build步骤前设置环境变量DOCKER_BUILDKIT=1。
2. 修改Dockerfile，添加BuildKit语法声明，使用RUN --mount=type=secret挂载pip配置：

# syntax=docker/dockerfile:1.2
FROM my_teams_own_baseimage

WORKDIR /work

# 挂载主机的pip.conf秘密文件，临时用于pip安装
RUN --mount=type=secret,id=pip_config,target=/etc/pip.conf \
    python -m pip install pip --upgrade \
    && pip install --no-cache -r requirements.txt

COPY requirements.txt /work/
COPY . /work/

注意：第一行的syntax=docker/dockerfile:1.2必须添加，以启用BuildKit特性。
3. 修改流水线，将PIP_CONFIG_FILE作为秘密传入Docker build：

- task: PipAuthenticate@1
  displayName: 'Pip authenticate'
  inputs:
    artifactFeeds: $(ArtifactFeed)
    onlyAddExtraIndex: true

- script: "export DOCKER_BUILDKIT=1"
  displayName: 'Enable Docker BuildKit'

- task: Docker@1
  displayName: 'Build image'
  inputs:
    containerregistrytype: 'Azure Container Registry'
    azureSubscriptionEndpoint: '$(AzureSubscription)'
    azureContainerRegistry: '$(ACR)'
    command: 'Build an image'
    dockerFile: 'Dockerfile'
    arguments: |
      --cache-from $(ACR)/$(ImagePrefix)$(ImageName):latest
      --secret id=pip_config,src=$(PIP_CONFIG_FILE)
    imageName: '$(ACR)/$(ImagePrefix)$(ImageName):$(ImageTag)'

认证信息仅在RUN pip install步骤临时可用，不会写入镜像层，且RUN层缓存哈希不受认证信息变化影响，只要requirements.txt不变就能复用缓存。

方案3：拆分镜像为基础依赖层和应用层，独立构建基础层 #

将依赖安装部分拆为单独的基础镜像，仅当requirements.txt变化时才重建基础镜像，应用层基于该基础镜像构建，避免每次因认证信息变化重建依赖层。

步骤：

1. 创建Dockerfile.base构建依赖基础镜像：

FROM my_teams_own_baseimage

ARG INDEX_URL
ENV PIP_EXTRA_INDEX_URL=$INDEX_URL

COPY requirements.txt /work/
WORKDIR /work
RUN python -m pip install pip --upgrade \
  && pip install --no-cache -r requirements.txt

2. 主Dockerfile改为基于基础镜像：

FROM $(ACR)/$(ImagePrefix)$(ImageName)-base:latest

WORKDIR /work
COPY . /work/

3. 修改流水线，先构建基础镜像（仅当requirements.txt变化时触发），再构建应用镜像：

# 检测requirements.txt是否变化，决定是否构建基础镜像
- task: ChangedFiles@1
  displayName: 'Check if requirements.txt changed'
  inputs:
    targetPath: 'requirements.txt'
    changeType: 'modified'
  name: RequirementsChanged

# 构建基础镜像（仅当requirements变化时执行）
- task: Docker@1
  displayName: 'Build base image'
  inputs:
    containerregistrytype: 'Azure Container Registry'
    azureSubscriptionEndpoint: '$(AzureSubscription)'
    azureContainerRegistry: '$(ACR)'
    command: 'Build an image'
    dockerFile: 'Dockerfile.base'
    arguments: |
      --cache-from $(ACR)/$(ImagePrefix)$(ImageName)-base:latest
      --build-arg INDEX_URL=$(PIP_EXTRA_INDEX_URL)
    imageName: '$(ACR)/$(ImagePrefix)$(ImageName)-base:latest'
  condition: eq(variables['RequirementsChanged.changed'], 'true')

# 构建应用镜像，基于基础镜像
- task: Docker@1
  displayName: 'Build application image'
  inputs:
    containerregistrytype: 'Azure Container Registry'
    azureSubscriptionEndpoint: '$(AzureSubscription)'
    azureContainerRegistry: '$(ACR)'
    command: 'Build an image'
    dockerFile: 'Dockerfile'
    arguments: |
      --cache-from $(ACR)/$(ImagePrefix)$(ImageName):latest
    imageName: '$(ACR)/$(ImagePrefix)$(ImageName):$(ImageTag)'

基础镜像仅在requirements.txt变化时才会因认证信息变化重建，日常代码变更仅需构建应用层，大幅缩短构建时间。

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