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

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

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

从公共注册表导入映像
从另一个或相同的 Azure 订阅或租户中的 Azure 容器注册表导入映像或 OCI 工件，包括 Helm 3 图表。
从非Azure专用容器注册表导入

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

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

重要

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

限制

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

Azure CLI
Azure PowerShell

若要导入容器映像，本文要求在本地运行Azure CLI（建议的版本 2.0.55 或更高版本）。运行 az --version 即可查找版本。如果需要安装或升级，请参阅 Install Azure CLI。

注意

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

重要

导入或导出网络受限的 Azure 容器注册表时，需要该受限注册表设置为允许受信任的服务访问以绕过网络限制。默认情况下，此设置处于启用状态，允许导入。如果刚创建的具有专用终结点或注册表防火墙规则的注册表中未启用该设置，导入将失败。

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

若要将镜像导入到 Azure 容器注册表，您的身份必须具备在目标注册表上触发导入的权限（Container Registry Data Importer and Data Reader 角色）。请参阅 Azure Container Registry 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 Container Registry 导入

例如，从 Azure Container Registry 中的 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

从同一 AD 租户中的Azure容器注册表导入

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

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

从同一订阅的注册表中导入

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

Azure CLI
Azure PowerShell

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

请注意，需要 --registry <source-registry-resource-id> 标志才能对源注册表使用 Entra 身份验证。

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 参数只指定源存储库和标记，而不指定注册表登录服务器名称。

请注意，需要 -SourceRegistryResourceId <source-registry-resource-id> 标志才能对源注册表使用 Entra 身份验证。

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 Container Registry (ACR)。

Azure CLI
Azure PowerShell

在以下示例中，mysourceregistry位于与同一Active Directory租户中的 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

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 service principal 的 appID 和密码，使其拥有对源注册表正确的角色分配访问权限。

对于Microsoft Entra服务主体，请确保已应用Container Registry Repository Reader（适用于 ABAC 启用的注册表）或AcrPull（适用于非 ABAC 注册表）。

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

Azure CLI
Azure PowerShell

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

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

从不同 AD 租户中的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/sourcerrepo:tag \
  --image targetimage:tag \
  --username <SP_App_ID> \
  --password <SP_Passwd>

Import-AzContainerRegistryImage -RegistryName myregistry -ResourceGroupName myResourceGroup -SourceRegistryUri sourceregistry.azurecr.cn -SourceImage sourcerrepo: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 Public Azure.

# 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/sourcerrepo:tag \
  --image targetimage:tag \
  --password <access-token>

# 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 sourcerrepo: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 sourcerrepo:tag -Username <username> -Password <password>

注意

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

排查导入容器映像问题

症状和原因

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 大小和范围标头决定。

后续步骤

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

Azure CLI
Azure PowerShell

关于其他映像导入选项，请参阅 az acr import 命令参考。

映像导入可以帮助您将内容移动到不同的 Azure 区域、订阅或 Microsoft Entra 租户中的容器注册表。
从受到网络限制的容器注册表禁用项目导出。

Last updated on 2026-03-10

Compartilhar via