向容器注册表导入容器映像

无需使用 Docker 命令即可轻松地将容器映像导入Azure容器注册表。例如，可以将映像从开发注册表导入生产注册表，或从公共注册表复制基础映像。

Azure 容器注册表处理许多常见方案，以便从现有注册表复制映像和其他项目：

从公共注册表导入映像。
从另一个 Azure 容器注册表导入映像或 OCI 工件（包括 Helm 3 图表包），该注册表可位于同一 Azure 订阅或 Azure 租户中，也可跨订阅和租户。
从非Azure专用容器注册表导入映像。

与使用 Docker CLI 命令相比，将映像导入到Azure容器注册表具有以下优势：

如果你的客户端环境不需要本地 Docker 安装，则可导入任何容器映像，无需考虑受支持的 OS 类型。
如果导入多体系结构映像（例如正式的 Docker 映像），则会复制清单列表中指定的所有体系结构和平台的映像。
如果有权访问目标注册表，则不需要注册表的公共终结点。

重要

导入映像需要外部注册表支持 RFC 7233。若要避免失败，请使用支持 RFC 7233 范围的注册表，同时将 az acr import 命令与注册表 URI 配合使用。

限制

对于导入的映像，清单的最大数目为 50。

Azure CLI
Azure PowerShell

若要导入容器映像，请在本地运行Azure CLI。

注意

如果需要在多个Azure区域中分发相同的容器映像，Azure 容器注册表还支持 geo-replication。通过对注册表（需要高级服务层）进行异地复制，可以使用单个注册表的相同映像和标记名称为多个区域提供服务。

重要

若要导入网络受限Azure容器注册表，受限制的注册表必须允许受信任的服务访问以绕过网络。默认情况下，该设置处于启用状态，因此导入工作。如果使用专用终结点或注册表防火墙规则创建注册表，但未启用该设置，则导入将失败。

如果还没有Azure容器注册表，请创建注册表。有关步骤，请参阅 Quickstart：使用 Azure CLI。

若要将镜像导入到 Azure 容器注册表，您的身份必须具备在目标注册表上触发导入的权限（Container Registry Data Importer and Data Reader 角色）。请参阅 Azure 容器注册表 Entra 权限和角色概述。

从公共注册表导入容器映像

重要

若要从公共注册表导入到受网络限制Azure容器注册表，受限制的注册表必须允许受信任的服务访问以绕过网络。默认情况下，此设置处于启用状态，因此导入工作。如果在具有专用终结点或注册表防火墙规则的新创建的注册表中禁用此设置，导入将失败。

从Docker Hub导入容器映像

Azure CLI
Azure PowerShell

例如，使用 az acr import 命令将多体系结构 hello-world:latest 映像从 Docker Hub 导入到名为 myregistry 的注册表。由于 hello-world 是来自Docker Hub的官方映像，因此此映像位于默认的 library 存储库中。 --source 映像参数的值中包含存储库名称和（可选）标记。（可以选择性根据映像的清单摘要而不是标签来标识映像，这确保映像为特定版本。）

az acr import \
  --name myregistry \
  --source dockerhub.azk8s.cn/library/hello-world:latest \
  --image hello-world:latest

可运行 az acr manifest list-metadata 命令来验证是否有多个清单与此映像关联：

az acr manifest list-metadata \
  --name hello-world \
  --registry myregistry

通过摘要导入项目而不添加标记：

az acr import \
   --name myregistry \
   --source dockerhub.azk8s.cn/library/hello-world@sha256:abc123 \
   --repository hello-world

如果你有Docker Hub帐户，则从Docker Hub导入映像时使用凭据。将Docker Hub用户名和密码或个人访问令牌作为参数传递给 az acr import。以下示例使用Docker Hub凭据从 Docker Hub 中的 tensorflow 存储库导入公共映像：

az acr import \
  --name myregistry \
  --source dockerhub.azk8s.cn/tensorflow/tensorflow:latest-gpu \
  --image tensorflow:latest-gpu \
  --username <Docker Hub user name> \
  --password <Docker Hub token>

例如，使用 Import-AzContainerRegistryImage 命令将多体系结构 hello-world:latest 映像从 Docker Hub 导入到名为 myregistry 的注册表。由于 hello-world 是来自Docker Hub的官方映像，因此此映像位于默认的 library 存储库中。在 -SourceImage 参数的值中，包含存储库名称，以及标记（可选）。（可以选择性根据映像的清单摘要而不是标签来标识映像，这确保映像为特定版本。）

Import-AzContainerRegistryImage -RegistryName myregistry -ResourceGroupName myResourceGroup -SourceRegistryUri dockerhub.azk8s.cn -SourceImage library/hello-world:latest

可以通过运行 Get-AzContainerRegistryManifest cmdlet 来验证是否多个清单与此映像关联：

Get-AzContainerRegistryManifest -RepositoryName library/hello-world -RegistryName myregistry

如果你有Docker Hub帐户，则从Docker Hub导入映像时使用凭据。将Docker Hub用户名和密码或个人访问令牌作为参数传递给 Import-AzContainerRegistryImage。以下示例使用Docker Hub凭据从 Docker Hub 中的 tensorflow 存储库导入公共映像：

Import-AzContainerRegistryImage -RegistryName myregistry -ResourceGroupName myResourceGroup -SourceRegistryUri dockerhub.azk8s.cn -SourceImage tensorflow/tensorflow:latest-gpu -Username <Docker Hub user name> -Password <Docker Hub token>

从Azure 容器注册表导入容器映像

例如，从 Azure 容器注册表中的 ltsc2022 存储库导入 windows Windows Server Core 映像。

Azure CLI
Azure PowerShell

az acr import \
--name myregistry \
--source mcr.microsoft.com/windows/servercore:ltsc2022 \
--image servercore:ltsc2022

Import-AzContainerRegistryImage -RegistryName myregistry -ResourceGroupName myResourceGroup -SourceRegistryUri mcr.microsoft.com -SourceImage windows/servercore:ltsc2022

从同一Microsoft Entra租户中的Azure容器注册表导入容器映像

可以使用集成Microsoft Entra权限从同一Microsoft Entra租户中的Azure容器注册表导入映像。

身份必须有权从源注册表查看和拉取映像、标签及 OCI 引用（在源注册表Container Registry Data Importer and Data Reader 上分配角色）。
标识还必须具有读取映像的权限和在目标注册表上触发导入的权限（Container Registry Data Importer and Data Reader 角色已在目标注册表上分配）。
注册表可以位于同一 Microsoft Entra 租户中的同一 Azure 订阅下，也可以位于该租户中的其他 Azure 订阅下。
已禁用对源注册表的公共访问。如果禁用了公共访问，请通过资源 ID 而不是注册表登录服务器名称指定源注册表。
具有专用终结点的源注册表和/或目标注册表或者注册表防火墙规则必须确保受限注册表允许受信任的服务访问网络。

从同一订阅中的注册表导入容器映像

例如，将 aci-helloworld:latest 映像从源注册表 mysourceregistry导入到同一Azure订阅中的 myregistry。

Azure CLI
Azure PowerShell

以下示例将 aci-helloworld:latest 映像从源注册表 mysourceregistry 导入到 myregistry，源注册表的公共终结点访问已被禁止。使用 --registry 参数提供源注册表的资源 ID。注意，--source 参数只指定源存储库和标记，而不指定注册表登录服务器名称。

若要使用 Microsoft Entra 身份验证向源注册表进行身份验证，请包含 --registry <source-registry-resource-id> 标志。

az acr import \
  --name myregistry \
  --source aci-helloworld:latest \
  --image aci-helloworld:latest \
  --registry /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/sourceResourceGroup/providers/Microsoft.ContainerRegistry/registries/mysourceregistry

以下示例将 aci-helloworld:latest 映像从源注册表 mysourceregistry 导入到 myregistry，源注册表的公共终结点访问已被禁止。使用 -SourceRegistryResourceId 参数提供源注册表的资源 ID。注意，-SourceImage 参数只指定源存储库和标记，而不指定注册表登录服务器名称。

若要对源注册表使用 Entra 身份验证，请包含 -SourceRegistryResourceId <source-registry-resource-id> 标志。

Import-AzContainerRegistryImage -RegistryName myregistry -ResourceGroupName myResourceGroup -SourceRegistryResourceId '/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/sourceResourceGroup/providers/Microsoft.ContainerRegistry/registries/mysourceregistry' -SourceImage aci-helloworld:latest

从不同订阅中的注册表导入容器映像

注意

若要将映像从一个注册表导入到另一个注册表，源注册表和目标注册表都必须确保其所在区域已在订阅的资源供应商下注册用于 Azure 容器注册表 (ACR)。

Azure CLI
Azure PowerShell

在以下示例中， mysourceregistry 与同一租户中的 myregistry 位于不同的订阅中。使用 --registry 参数提供源注册表的资源 ID。该 --source 参数仅指定源存储库和标记，而不是注册表登录服务器名称。

az acr import \
  --name myregistry \
  --source aci-helloworld:latest \
  --image aci-hello-world:latest \
  --registry /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/sourceResourceGroup/providers/Microsoft.ContainerRegistry/registries/mysourceregistry

在以下示例中， mysourceregistry 与同一租户中的 myregistry 位于不同的订阅中。使用 -SourceRegistryResourceId 参数提供源注册表的资源 ID。该 -SourceImage 参数仅指定源存储库和标记，而不是注册表登录服务器名称。

Import-AzContainerRegistryImage -RegistryName myregistry -ResourceGroupName myResourceGroup -SourceRegistryResourceId '/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/sourceResourceGroup/providers/Microsoft.ContainerRegistry/registries/mysourceregistry' -SourceImage aci-helloworld:latest

使用服务主体凭据从注册表导入容器映像

若要从无法使用集成Active Directory权限访问的注册表导入，请使用源注册表的服务主体凭据（如果可用）。输入对源注册表具有正确角色分配访问权限的 Microsoft Entra 服务主体的 appID 和密码。

对于 Microsoft Entra 服务主体，请确保已分配以下项之一：Container Registry Repository Reader（用于已启用 ABAC 的注册表）或 AcrPull（用于未启用 ABAC 的注册表）。

服务主体适用于需将映像导入到注册表的生成系统和其他无人参与系统。

Azure CLI
Azure PowerShell

az acr import \
  --name myregistry \
  --source sourceregistry.azurecr.cn/sourcerepo:tag \
  --image targetimage:tag \
  --username <SP_App_ID> \
  --password <SP_Passwd>

Import-AzContainerRegistryImage -RegistryName myregistry -ResourceGroupName myResourceGroup -SourceRegistryUri sourceregistry.azurecr.cn -SourceImage sourcerepo:tag -Username <SP_App_ID> -Password <SP_Passwd>

从不同租户中的Azure容器注册表导入容器映像

若要从位于其他 Microsoft Entra 租户中的 Azure 容器注册表导入映像，请通过登录服务器名称来指定源注册表，并提供具有该注册表拉取权限的凭据。

已禁用公共访问的注册表不支持跨租户导入。

使用用户名和密码进行跨租户导入

例如，使用非微软 Entra 存储库范围的令牌和密码，或者Microsoft Entra 服务主体的 appID 和密码，这些需要在源注册表中具有正确的角色分配。

对于 Microsoft Entra 服务主体，请确保以下两者之一已分配到源注册表：Container Registry Repository Reader（用于已启用 ABAC 的注册表）或 AcrPull（用于非 ABAC 注册表）。

Azure CLI
Azure PowerShell

az acr import \
  --name myregistry \
  --source sourceregistry.azurecr.cn/sourcerepo:tag \
  --image targetimage:tag \
  --username <SP_App_ID> \
  --password <SP_Passwd>

Import-AzContainerRegistryImage -RegistryName myregistry -ResourceGroupName myResourceGroup -SourceRegistryUri sourceregistry.azurecr.cn -SourceImage sourcerepo:tag -Username <SP_App_ID> -Password <SP_Passwd>

使用访问令牌进行跨租户导入

若要使用源租户中具有注册表权限的标识来访问源注册表，请获取访问令牌：

Azure CLI
Azure PowerShell

# Login to Azure CLI with the identity, for example a user-assigned managed identity
az cloud set -n AzureChinaCloud
az login --identity --username <identity_ID>
# az cloud set -n AzureCloud   //means return to Azure Public Cloud.

# Get access token returned by `az account get-access-token`
az account get-access-token

在目标租户中，将访问令牌作为密码传递给 az acr import 命令。源注册表指定登录服务器名称。此命令中不需要用户名：

az acr import \
  --name myregistry \
  --source sourceregistry.azurecr.cn/sourcerepo:tag \
  --image targetimage:tag \
  --password ($token|ConvertFrom-Json).accessToken

# Login to Azure PowerShell with the identity, for example a user-assigned managed identity
Connect-AzAccount -Environment AzureChinaCloud -Identity -AccountId <identity_ID>

# Get access token returned by `Get-AzAccessToken`
Get-AzAccessToken

在目标租户中，将访问令牌作为密码传递到 Import-AzContainerRegistryImage cmdlet。源注册表指定登录服务器名称。此命令中不需要用户名：

Import-AzContainerRegistryImage -RegistryName myregistry -ResourceGroupName myResourceGroup -SourceRegistryUri sourceregistry.azurecr.cn -SourceImage sourcerepo:tag -Password <access-token>

从非Azure专用容器注册表导入容器映像

通过指定启用对注册表的提取访问权限的凭据，从非 Azure 专用注册表导入映像。例如，从专用 Docker 注册表拉取映像：

Azure CLI
Azure PowerShell

az acr import \
  --name myregistry \
  --source dockerhub.azk8s.cn/sourcerepo/sourceimage:tag \
  --image sourceimage:tag \
  --username <username> \
  --password <password>

Import-AzContainerRegistryImage -RegistryName myregistry -ResourceGroupName myResourceGroup -SourceRegistryUri dockerhub.azk8s.cn/sourcerepo -SourceImage sourcerepo:tag -Username <username> -Password <password>

注意

如果要从具有 IP 规则的非Azure专用注册表导入，follow 这些步骤。

排查容器映像导入问题

如果在导入映像时看到错误，请查看下表了解详细信息。

错误消息	Explanation
`The remote server may not be RFC 7233 compliant`	distribution-spec 允许使用范围标头形式 `Range: bytes=<start>-<end>`。但是，远程服务器可能不符合 RFC 7233。
`Unexpected response status code`	执行范围查询时，从源存储库检索意外的响应状态代码。
`Unexpected length of body in response`	收到的内容长度与预期大小不匹配。预期大小由 blob 大小和 Range 标头决定。

后续步骤

本文介绍了如何从公共注册表或其他专用注册表将容器映像导入Azure容器注册表。

有关其他映像导入选项，请参阅 az acr import 或 Import-AzContainerRegistryImage 参考。
映像导入可以帮助您将内容移动到不同的 Azure 区域、订阅或 Microsoft Entra 租户中的容器注册表。

从受到网络限制的容器注册表禁用项目导出。

Last updated on 2026-07-03