使用 ARM 模板进行 ACR 传输

使用 ACR 转移，可以使用中间存储帐户在 Azure 容器注册表之间传输容器映像和 OCI 项目，非常适合用于隔离网络和跨云场景。有关功能的概述，请参阅将项目传输到另一个注册表。

完成所有先决条件

在尝试本文中的作之前，请先完成 ACR 传输先决条件中概述的先决条件。这表示：

在两个云中都有一个现有的高级 SKU 注册表。
在两个云中都有一个现有的存储帐户容器。
如果使用 SAS 令牌存储访问模式，请确保您现有的密钥保管库中存有一个机密，机密包含一个有效的 SAS 令牌，并在两个云中具有必要的权限。
如果使用 托管标识 存储访问模式，请确保管道的托管标识在存储帐户上具有适当的 RBAC 角色（例如 Storage Blob Data Contributor）。这需要 API 版本 2025-06-01-preview 或更高版本。
在两个云中都安装了最新版本的 Az CLI。

ACR 传输支持两种存储访问模式： SAS 令牌 和 托管标识。必须在 ARM 模板中通过 storageAccessMode 属性指定要使用的模式。有关详细比较，请参阅存储访问模式。

重要

ACR 传输由于技术限制支持层大小高达 8 GB 的工件。

考虑使用 Az CLI 扩展

对于大多数非自动用例，我们建议尽可能使用 Az CLI 扩展。可在此处查看 Az CLI 扩展的文档。

使用 Resource Manager 创建 ExportPipeline

使用Azure Resource Manager模板部署为源容器注册表创建 ExportPipeline 资源。

将 ExportPipeline Resource Manager template 文件复制到本地文件夹。

在文件中 azuredeploy.parameters.json输入以下参数值：

参数	价值
registryName	源容器注册表的名称
导出管道名称	为导出管道选择的名称
targetUri	源环境中存储容器的 URI（导出管道的目标）。示例： `https://sourcestorage.blob.core.chinacloudapi.cn/transfer`
KeyVaultName	源密钥保管库的名称。使用 SAS 令牌模式时是必需的。当使用托管标识模式时，可以提供任何现有的 Key Vault 名称（模板可能会有条件地跳过创建 Key Vault 访问策略）。
sasTokenSecretName	源 Key Vault 中 SAS 令牌密钥的名称。使用 SAS 令牌模式时必需。使用托管标识模式时，可以提供任何占位符值。示例：acrexportsas
存储访问模式	管道的存储访问模式。指定 `SasToken` 或 `ManagedIdentity`。

导出选项

导出管道的 options 属性支持可选的布尔值。建议使用以下值：

参数	价值
选项	OverwriteBlobs - 覆盖现有目标 blob ContinueOnErrors - 如果一个工件导出失败，则继续导出源注册表中的其余工件。

创建资源

运行 az deployment group create 以创建名为 exportPipeline 的资源，如以下示例所示。在部署之前设置 storageAccessMode 中的 azuredeploy.parameters.json 值。

默认情况下，示例模板在 ExportPipeline 资源中启用系统分配的标识。还可以提供用户分配的标识（请参阅选项 2）。

选项 1：使用系统分配的标识创建资源

az deployment group create \
  --resource-group $SOURCE_RG \
  --template-file azuredeploy.json \
  --name exportPipeline \
  --parameters azuredeploy.parameters.json

选项 2：使用用户分配的标识创建资源

在此命令中，以附加参数的形式提供用户分配标识的资源 ID。

az deployment group create \
  --resource-group $SOURCE_RG \
  --template-file azuredeploy.json \
  --name exportPipeline \
  --parameters azuredeploy.parameters.json \
  --parameters userAssignedIdentity="/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourcegroups/myResourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myUserAssignedIdentity"

在命令输出中，记下管道的资源 ID（id）。可以通过运行 az deployment group show 将此值存储在环境变量中供以后使用。例如：

EXPORT_RES_ID=$(az deployment group show \
  --resource-group $SOURCE_RG \
  --name exportPipeline \
  --query 'properties.outputResources[1].id' \
  --output tsv)

使用 Resource Manager 创建 ImportPipeline

使用Azure Resource Manager模板部署在目标容器注册表中创建 ImportPipeline 资源。默认情况下，当目标环境中的存储帐户具有工件 blob 时，管道将被启用以自动导入。

将 ImportPipeline Resource Manager template 文件复制到本地文件夹。

在文件中 azuredeploy.parameters.json输入以下参数值：

参数	价值
registryName	目标容器注册表的名称
importPipelineName	为导入管道选择的名称
sourceUri	目标环境中的存储容器的 URI（导入管道的源）。示例： `https://targetstorage.blob.core.chinacloudapi.cn/transfer`
KeyVaultName	目标Key Vault的名称。使用 SAS 令牌模式时是必需的。当使用托管标识模式时，可以提供任何现有的 Key Vault 名称（模板可能会有条件地跳过创建 Key Vault 访问策略）。
sasTokenSecretName	目标 Key Vault 中 SAS 令牌密钥的名称。使用 SAS 令牌模式时必需。使用托管标识模式时，可以提供任何占位符值。示例：acrimportsas
存储访问模式	管道的存储访问模式。指定 `SasToken` 或 `ManagedIdentity`。

导入选项

导入管道的 options 属性支持可选的布尔值。建议使用以下值：

参数	价值
选项	OverwriteTags - 覆盖现有目标标记 DeleteSourceBlobOnSuccess - 成功导入到目标注册表后删除源存储 blob ContinueOnErrors - 如果一个项目导入失败，则在目标注册表中继续导入其余项目。

创建资源

运行 az deployment group create 以创建名为 importPipeline 的资源，如以下示例所示。在部署之前设置 storageAccessMode 中的 azuredeploy.parameters.json 值。

默认情况下，示例模板在 ImportPipeline 资源中启用系统分配的标识。还可以提供用户分配的标识（请参阅选项 2）。

选项 1：使用系统分配的标识创建资源

az deployment group create \
  --resource-group $TARGET_RG \
  --template-file azuredeploy.json \
  --name importPipeline \
  --parameters azuredeploy.parameters.json

选项 2：使用用户分配的标识创建资源

在此命令中，以附加参数的形式提供用户分配标识的资源 ID。

az deployment group create \
  --resource-group $TARGET_RG \
  --template-file azuredeploy.json \
  --name importPipeline \
  --parameters azuredeploy.parameters.json \
  --parameters userAssignedIdentity="/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourcegroups/myResourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myUserAssignedIdentity"

如果计划手动运行导入，请记下管道的资源 ID（id）。可以通过运行 az deployment group show 命令将此值存储在环境变量中供以后使用。例如：

IMPORT_RES_ID=$(az deployment group show \
  --resource-group $TARGET_RG \
  --name importPipeline \
  --query 'properties.outputResources[1].id' \
  --output tsv)

使用 Resource Manager 创建 PipelineRun 进行导出

使用Azure Resource Manager模板部署为源容器注册表创建 PipelineRun 资源。此资源运行之前创建的 ExportPipeline 资源，并将指定的项目从容器注册表导出为 Blob 到源存储帐户。

将 PipelineRun Resource Manager template 文件复制到本地文件夹。

在文件中 azuredeploy.parameters.json输入以下参数值：

参数	价值
registryName	源容器注册表的名称
pipelineRunName（流水线运行名称）	为运行选择的名称
管道资源ID	导出管道的资源 ID。示例： `/subscriptions/<subscriptionID>/resourceGroups/<resourceGroupName>/providers/Microsoft.ContainerRegistry/registries/<sourceRegistryName>/exportPipelines/myExportPipeline`
targetName	为导出到源存储帐户的工件 Blob 选择的名称，例如 myblob
文物	要传输的源项目数组，作为标记或清单摘要示例： `["samples/hello-world:v1", "samples/nginx:v1", "myrepository@sha256:0a2e01852872..."]`

如果重新部署具有相同属性的 PipelineRun 资源，则还必须使用 forceUpdateTag 属性。

运行 az deployment group create 以创建 PipelineRun 资源。以下示例命名部署 exportPipelineRun。

az deployment group create \
  --resource-group $SOURCE_RG \
  --template-file azuredeploy.json \
  --name exportPipelineRun \
  --parameters azuredeploy.parameters.json

若要稍后使用，请将管道运行的资源 ID 存储在环境变量中：

EXPORT_RUN_RES_ID=$(az deployment group show \
  --resource-group $SOURCE_RG \
  --name exportPipelineRun \
  --query 'properties.outputResources[0].id' \
  --output tsv)

导出项目可能需要几分钟。部署成功完成后，通过在源存储帐户的传输容器中列出导出的 Blob 来验证项目导出。例如，运行 az storage blob list 命令：

az storage blob list \
  --account-name $SOURCE_SA \
  --container-name transfer \
  --output table

传输 Blob （可选）

使用 AzCopy 工具或其他方法将 blob 数据传输从源存储帐户到目标存储帐户。

例如，以下命令 azcopy copy 将 myblob 从源帐户中的传输容器复制到目标帐户中的传输容器。如果目标帐户中已存在 blob，则会被覆盖。此跨域复制的身份验证使用对源容器和目标容器具有适当权限的 SAS 令牌，无论管道使用的存储访问模式如何。（未显示创建令牌的步骤。

azcopy copy \
  'https://<source-storage-account-name>.blob.core.chinacloudapi.cn/transfer/myblob'$SOURCE_SAS \
  'https://<destination-storage-account-name>.blob.core.chinacloudapi.cn/transfer/myblob'$TARGET_SAS \
  --overwrite true

触发 ImportPipeline 资源

如果启用了 sourceTriggerStatus ImportPipeline（默认值）的参数，则会在 Blob 复制到目标存储帐户后触发管道。导入工件可能需要几分钟。导入成功完成后，请在目标容器注册表中列出存储库，以验证项目导入。例如，运行 az acr repository list：

az acr repository list --name <target-registry-name>

注释

源触发器将仅导入最近一次修改时间在 60 天以内的 Blob。如果打算使用源触发器导入早于此的 Blob，请通过向其添加 Blob 元数据来刷新 Blob 的上次修改时间，或者使用手动创建的管道运行导入它们。

如果未启用 sourceTriggerStatus 导入管道的参数，请手动运行 ImportPipeline 资源，如以下部分所示。

使用 Resource Manager 创建 PipelineRun 进行导入（可选）

还可以使用 PipelineRun 资源来触发 ImportPipeline，以将工件导入到您的目标容器注册表中。

将 PipelineRun Resource Manager template 文件复制到本地文件夹。

在文件中 azuredeploy.parameters.json输入以下参数值：

参数	价值
registryName	目标容器注册表的名称
pipelineRunName（流水线运行名称）	为运行选择的名称
管道资源ID	导入管道的资源 ID。示例： `/subscriptions/<subscriptionID>/resourceGroups/<resourceGroupName>/providers/Microsoft.ContainerRegistry/registries/<targetRegistryName>/importPipelines/myImportPipeline`
sourceName	存储帐户中导出项目的现有 Blob 的名称，例如 myblob

如果重新部署具有相同属性的 PipelineRun 资源，则还必须使用 forceUpdateTag 属性。

运行 az deployment group create 以运行资源。

az deployment group create \
  --resource-group $TARGET_RG \
  --name importPipelineRun \
  --template-file azuredeploy.json \
  --parameters azuredeploy.parameters.json

若要稍后使用，请将管道运行的资源 ID 存储在环境变量中：

IMPORT_RUN_RES_ID=$(az deployment group show \
  --resource-group $TARGET_RG \
  --name importPipelineRun \
  --query 'properties.outputResources[0].id' \
  --output tsv)

部署成功完成后，通过在目标容器注册表中列出存储库来验证项目导入。例如，运行 az acr repository list：

az acr repository list --name <target-registry-name>

重新部署 PipelineRun 资源

如果重新部署具有相同属性的 PipelineRun 资源，则必须利用 forceUpdateTag 属性。此属性指示即使配置未更改，也应重新创建 PipelineRun 资源。确保每次重新部署 PipelineRun 资源时 forceUpdateTag 不同。以下示例展示如何重新创建一个用于导出的 PipelineRun。当前日期/时间用于设置 forceUpdateTag，从而确保此属性始终是唯一的。

CURRENT_DATETIME=`date +"%Y-%m-%d:%T"`

az deployment group create \
  --resource-group $SOURCE_RG \
  --template-file azuredeploy.json \
  --name exportPipelineRun \
  --parameters azuredeploy.parameters.json \
  --parameters forceUpdateTag=$CURRENT_DATETIME

删除管道资源

以下示例命令使用 az resource delete 删除本文中创建的管道资源。资源 ID 以前存储在环境变量中。

# Delete export resources
az resource delete \
--resource-group $SOURCE_RG \
--ids $EXPORT_RES_ID $EXPORT_RUN_RES_ID \
--api-version 2025-06-01-preview

# Delete import resources
az resource delete \
--resource-group $TARGET_RG \
--ids $IMPORT_RES_ID $IMPORT_RUN_RES_ID \
--api-version 2025-06-01-preview

ACR 传输故障排除

查看 ACR 传输故障排除以获取故障排除指南。

后续步骤

了解如何从受网络限制的容器注册表中阻止创建导出管道。

Last updated on 2026-03-10

通过

使用 ARM 模板进行 ACR 传输

完成所有先决条件

考虑使用 Az CLI 扩展

使用 Resource Manager 创建 ExportPipeline

导出选项

创建资源

选项 1：使用系统分配的标识创建资源

选项 2：使用用户分配的标识创建资源

使用 Resource Manager 创建 ImportPipeline

导入选项

创建资源

选项 1：使用系统分配的标识创建资源

选项 2：使用用户分配的标识创建资源

使用 Resource Manager 创建 PipelineRun 进行导出

传输 Blob （可选）

触发 ImportPipeline 资源

使用 Resource Manager 创建 PipelineRun 进行导入（可选）

重新部署 PipelineRun 资源

删除管道资源

ACR 传输故障排除

后续步骤

其他资源