Azure DevOps容器作业中PHP Composer依赖缓存问题排查

问题描述 #

我有一条用于构建和部署PHP Web应用的Azure DevOps流水线，Azure代理会基于镜像mycustomimage/pipeline-build-php8启动容器，所有构建部署操作都在容器内完成。我想知道在使用容器作业时，如何缓存PHP Composer依赖？我清楚Cache@2任务运行在Azure代理所在主机（AzureAgentServer）而非容器内部。

运行流水线后，在Azure DevOps「流水线 > 作业」中看到如下输出：

• Cache Composer Job Succeeded
• CmdLine Job Succeeded
• Post-job: Cache Composer ERROR

Getting a pipeline cache artifact with one of the following fingerprints: Fingerprint: composer|"Linux"|VtM/KI+cqM9cqvMUIO/MUln2YuE4vqOqlDb4t8f2NFc=
There is a cache miss.
tar: /home/azagent/azagentworker/_work/18/.composer: Cannot open: No such file or directory
tar: Error is not recoverable: exiting now

• Post-job: Checkout Succeeded

我的流水线配置如下：

trigger:
  branches:
    include:
      - UAT

variables:
- group: 'Pipeline Secrets'

jobs:
- job: DeploytoUAT
  displayName: 'Deploy to UAT'
  condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/UAT'))
  pool:
    name: 'UAT Pool Linux'
    vmImage: 'AzureAgentServer'
  container:
    image: mycustomimage/pipeline-build-php8
  steps:
  - task: DownloadSecureFile@1
    name: AZagentSSHkey
    displayName: 'Download SSH key for Azure container user'
    inputs:
      secureFile: 'azagent_azpcontainer_ssh.key'
  - task: Cache@2
    displayName: 'Cache Composer'
    inputs:
      key: 'composer | "$(Agent.OS)" | composer.lock'
      restoreKeys: |
        composer | "$(Agent.OS)"
        composer
      path: | 
        $(Pipeline.Workspace)/.composer
  - script: |
      # Add credentials so that the azagent_azpcontainer can SSH to hosts (web servers) without password
      mkdir ~/.ssh/ && cp $(AZagentSSHkey.secureFilePath) ~/.ssh/id_rsa && chmod 600 ~/.ssh/id_rsa
      composer config --global --auth http-basic.dev.azure.com token $AZURE_DEVOPS_EXT_PAT
      composer update myproject/anotherprojectrepo --no-interaction
      composer install --no-interaction --no-progress --prefer-dist --no-dev
      composer dump-autoload --no-dev --classmap-authoritative
      composer global require deployer/deployer --dev --ignore-platform-reqs
      export PATH=$PATH:~/.config/composer/vendor/bin/
      dep deploy uat
    env:
      AZURE_DEVOPS_EXT_PAT: $(AZURE_DEVOPS_PAT)

问题原因 #

错误核心在于：Cache@2任务在主机上找不到$(Pipeline.Workspace)/.composer目录——所有Composer操作都在容器内执行，容器内的目录与主机目录未映射，主机无法访问容器内生成的Composer缓存文件。

解决步骤 #

1. 统一缓存目录到共享路径 #

Azure DevOps的$(Pipeline.Workspace)目录默认是主机与容器共享的，需要让容器内的Composer将依赖缓存到这个共享路径下。

2. 修改流水线配置 #

修正后的Cache任务（路径无需修改）

- task: Cache@2
  displayName: 'Cache Composer'
  inputs:
    key: 'composer | "$(Agent.OS)" | composer.lock'
    restoreKeys: |
      composer | "$(Agent.OS)"
      composer
    path: $(Pipeline.Workspace)/.composer

修正后的脚本任务

添加Composer全局缓存目录配置，同时调整Deployer的PATH路径：

- script: |
    # 创建SSH目录并配置密钥
    mkdir ~/.ssh/ && cp $(AZagentSSHkey.secureFilePath) ~/.ssh/id_rsa && chmod 600 ~/.ssh/id_rsa
    # 配置Composer全局缓存到主机与容器共享的路径
    composer config --global cache-dir $(Pipeline.Workspace)/.composer
    # 配置Azure DevOps PAT认证
    composer config --global --auth http-basic.dev.azure.com token $AZURE_DEVOPS_EXT_PAT
    # 执行Composer操作
    composer update myproject/anotherprojectrepo --no-interaction
    composer install --no-interaction --no-progress --prefer-dist --no-dev
    composer dump-autoload --no-dev --classmap-authoritative
    # 全局安装Deployer
    composer global require deployer/deployer --dev --ignore-platform-reqs
    # 更新PATH指向共享缓存目录下的vendor/bin
    export PATH=$PATH:$(Pipeline.Workspace)/.composer/vendor/bin/
    dep deploy uat
  env:
    AZURE_DEVOPS_EXT_PAT: $(AZURE_DEVOPS_PAT)

额外说明 #

• 确保自定义镜像mycustomimage/pipeline-build-php8的运行用户对$(Pipeline.Workspace)/.composer目录有读写权限，若使用非root用户，需提前配置权限。
• 如果需要缓存项目的vendor目录，可在Cache任务的path中添加$(Build.SourcesDirectory)/vendor，同时保持缓存key包含composer.lock以保证缓存有效性。

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