教程：使用 Azure 存储和 Azure DevOps 搭建缓存

cmd

信息

这些操作在 'CMD' 中无法便捷执行，请选择此消息上方的 'PowerShell' 或 'Bash' 选项。

kmpkg 支持使用 Azure 存储容器上传和还原资产及二进制包。但为认证配置预共享的长期 SAS 令牌时，需要手动轮换密钥，这一过程容易出错。工作负载标识联合提供了一种机制，可由 Azure DevOps 自动处理密钥轮换和管理，且该机制可与 kmpkg 配合使用。

注意

这些操作会向所用的流水线授予充当该托管标识的权限。此外，kmpkg 缓存的机制可能导致受入侵的构建任务使其他构建任务使用缓存中受入侵的资产。

请勿允许运行不受信任的第三方构建请求的机器，向用于正式构建的缓存写入数据。

前提条件

cmd

信息

这些操作在 'CMD' 中无法便捷执行，请选择页面顶部的 'PowerShell' 或 'Bash' 选项。

powershell

• 安装了 Azure PowerShell 的终端
• kmpkg
• 一个 Azure 存储订阅，以及你希望用于存储二进制文件的容器

bash

• 安装了 Azure CLI 的终端
• kmpkg
• 一个 Azure 存储订阅，以及你希望用于存储二进制文件的容器

1 - 创建 Entra 托管标识

若你已配置好要使用的托管标识，可跳过此步骤。

在 Azure 门户中：

1. 打开你希望创建托管标识的资源组页面
2. 点击“+ 创建”
3. 在“搜索市场”输入框中输入“用户分配的托管标识”
4. 选择微软提供的“用户分配的托管标识”
5. 点击“用户分配的托管标识”方案旁的“创建”
6. 为该标识命名（本教程使用 kmpkg-docs-identity 作为名称，你也可按需选择资源所在区域）
7. 点击“查看并创建”
8. 核对设置后点击“创建”。

资源部署可能需要几分钟时间。

2 - 在 Azure 存储与 Azure DevOps 之间配置工作负载标识联合

信息

这些操作步骤应与 Azure DevOps 官方文档中的说明一致。若本教程的步骤过时，请遵循 Azure DevOps 团队提供的最新指引。

在你希望运行流水线的 Azure DevOps 项目门户中，点击左下角的“项目设置”。然后在左侧选择“服务连接”，再点击右侧的“新建服务连接”。选择“Azure 资源管理器”单选按钮并点击“下一步”，接着选择“工作负载标识联合（手动）”并点击“下一步”。为该服务连接命名后点击“下一步”（本教程中将服务连接命名为 kmpkg-docs-identity-connection）。此时 Azure DevOps 会显示颁发者（issuer）和主体标识符（subject identifier）。

打开新标签页，进入 Azure 门户并导航至步骤1中创建的托管标识。在左侧选择“设置/联合凭据”，然后点击“添加凭据”。在下拉菜单中选择“其他”，将 Azure DevOps 中的“颁发者 URL”和“主体标识符”复制到表单中，为该联合凭据命名后点击“添加”（本教程中命名为 azure-devops-credential）。

3 - 为存储账户容器分配托管标识权限

若你已为托管标识授予存储账户容器的权限，可跳过此步骤。

在 Azure 门户中，导航至要使用的存储账户页面。在左侧选择“数据存储/容器”，并选中你要使用的容器（此时门户会打开该容器的属性页面）。在左侧选择“访问控制 (IAM)”，然后点击“添加 -> 添加角色分配”。若需只读权限，选择“Azure Blob 数据读取者”；若需读写权限，选择“Azure Blob 数据参与者”，然后点击“下一步”。选中“托管标识”单选按钮并点击“+ 选择成员”，选择步骤1中创建的托管标识，然后连续两次点击“查看并分配”。

回到该存储账户容器的页面，再次在左侧选择“访问控制 (IAM)”，点击“添加 -> 添加角色分配”。选择“存储 Blob 委托者”并点击“下一步”，选中“托管标识”单选按钮并点击“+ 选择成员”，选择步骤1中创建的托管标识，然后连续两次点击“查看并分配”。

4 - 生成 SAS 令牌并将其用于缓存

cmd

信息

这些操作在 'CMD' 中无法便捷执行，请选择页面顶部的 'PowerShell' 或 'Bash' 选项。

bash-powershell

在 Azure DevOps 中调用 kmpkg 的 yml 文件里，使用 AzureCLI@2 任务生成 SAS 令牌并调用 kmpkg，示例如下：

powershell

steps:
- task: AzureCLI@2
  displayName: 'Build with kmpkg'
  inputs:
    azureSubscription: 'kmpkg-docs-identity-connection' # 这是步骤2中创建的服务连接名称
    scriptType: 'pscore'                                
    scriptLocation: 'inlineScript'
    inlineScript: |
      # 确定 SAS 令牌的过期时间。该时间应基于你预期的流水线最长运行时长。
      $current = Get-Date -AsUtc
      $end = $current.AddHours(2)
      # 将 container-name 和 storage-account-name 替换为步骤3中的实际值。
      # 根据所需权限，将 'rcl' 权限替换为 'rc' 或 'rclw'。
      # 可参考 https://pub.kumose.cc/rest/api/storageservices/create-service-sas#permissions-for-a-directory-container-or-blob 查看支持的权限列表。
      $ctx = New-AzStorageContext -StorageAccountName storage-account-name -UseConnectedAccount
      $sas = New-AzStorageContainerSASToken -Context $ctx -Name container-name -Permission rclw -ExpiryTime $end
      # Azure PowerShell 不同版本中，生成的 SAS 令牌开头是否包含 ? 存在差异：
      if ($sas.StartsWith("?")) {
        $sas = sas.Substring(1)
      }
      # 现在将 SAS 令牌用于资产缓存；请确保再次替换 storage-account-name 和 container-name：
      $env:X_KMPKG_ASSET_SOURCES = "x-azurl,https://storage-account-name.blob.core.windows.net/container-name,$sas,readwrite"
      # ... 或用于二进制缓存：
      kmpkg install --binarysource "clear;x-azblob,https://storage-account-name.blob.core.windows.net/container-name,$sas,readwrite"

bash

steps:
- task: AzureCLI@2
  displayName: 'Build with kmpkg'
  inputs:
    azureSubscription: 'kmpkg-docs-identity-connection' # 这是步骤2中创建的服务连接名称
    scriptType: 'bash'                                  
    scriptLocation: 'inlineScript'
    inlineScript: |
      # 确定 SAS 令牌的过期时间。该时间应基于你预期的流水线最长运行时长。
      export end=`date -u -d "2 hours" '+%Y-%m-%dT%H:%MZ'
      # 将 container-name 和 storage-account-name 替换为步骤3中的实际值。
      # 根据所需权限，将 'rcl' 权限替换为 'rc' 或 'rclw'。
      # 可参考 https://www.microsoft.com/cli/azure/storage/container?view=azure-cli-latest#az-storage-container-generate-sas-optional-parameters 查看支持的权限列表。
      # 此处触发工作负载标识联合的关键参数是 '--as-user' 和 '--auth-mode login'
      export sas=`az storage container generate-sas --name container-name --account-name storage-account-name --as-user --auth-mode login --https-only --permissions rclw --expiry $end -o tsv`
      # 现在将 SAS 令牌用于资产缓存；请确保再次替换 storage-account-name 和 container-name：
      export X_KMPKG_ASSET_SOURCES=x-azurl,https://storage-account-name.blob.core.windows.net/container-name,$sas,readwrite
      # ... 或用于二进制缓存：
      kmpkg install --binarysource "clear;x-azblob,https://storage-account-name.blob.core.windows.net/container-name,$sas,readwrite"

后续步骤

你可尝试完成以下后续操作：

• 搭建本地二进制缓存
• 查看在 Azure DevOps 流水线中使用 kmpkg 的端到端 CI 场景