將容器映像匯入到容器登錄

2025-05-04

您可以輕易地將容器映像匯入 (複製) 到 Azure 容器登錄，不用使用 Docker 命令。例如，從開發登錄將映像匯入到生產環境登錄，或者從公用登錄複製基底映像。

Azure Container Registry 會處理許多從現有登錄複製映像和其他成品的常見案例：

從公用登錄匯入映像
在相同或不同的 Azure 訂用帳戶或租用戶中匯入映像或 OCI 成品，包括來自另一個 Azure 容器登錄的 Helm 3 圖表
從非 Azure 私人容器登錄匯入

匯入到 Azure 容器登錄的映像相較於使用 Docker CLI 命令，具有下列優點：

因為您的用戶端環境不需要本機 Docker 安裝，所以可以匯入任何容器映像，無論支援的作業系統類型是什麼。
如果您匯入多架構映像 (例如，官方 Docker 映像)，則會複製資訊清單中指定和所有架構與平台的映像。
如果您有目標登錄的存取權，則不需要登錄的公用端點。

重要

匯入映像需要外部登錄支援 RFC 7233。建議您使用支援 RFC 7233 範圍的登錄，同時搭配登錄 URI 使用 az acr import 命令以避免失敗。

限制

所匯入映像的資訊清單數目上限為 50。

Azure CLI
Azure PowerShell

為了匯入容器映像，本文會要求您在 Azure Cloud Shell 或在本機執行 Azure CLI (建議使用 2.0.55 版或更新版本)。執行 az --version 以尋找版本。如果您需要安裝或升級，請參閱安裝 Azure CLI。

注意

如果您需要將相同的容器映射分散到多個 Azure 區域，Azure Container Registry 也支援異地復寫。藉由異地複寫登錄 (需要進階服務層級)，您可以使用來自單一登錄的相同映像和標記名稱，為多個區域提供服務。

重要

自 2021 年 1 月起，已引進兩個 Azure 容器登錄之間映像匯入的變更：

匯入或從網路限制的 Azure 容器登錄需要受限制的登錄，才能 允許受信任的服務存取 ，以略過網路。根據預設，會啟用設定，允許匯入。如果未在具有私人端點或登錄防火牆規則的新建登錄中啟用設定，匯入將會失敗。
在用作匯入來源或目標的現有網路受限 Azure 容器登錄中，啟用此網路安全性功能是選用的，但建議使用。

如果您還沒有 Azure 容器登錄，請建立登錄。如需步驟，請參閱快速入門：使用 Azure CLI 建立私人容器登錄。

若要將映像匯入 Azure Container Registry，您的身分識別必須具有在目標登錄上觸發匯入的許可權（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 docker.io/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 docker.io/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 docker.io/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 docker.io -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 docker.io -SourceImage tensorflow/tensorflow:latest-gpu -Username <Docker Hub user name> -Password <Docker Hub token>

從 Microsoft 容器登錄匯入

例如，從 Microsoft 容器登錄中的 ltsc2019 存放庫匯入 windows Windows Server Core 映像。

Azure CLI
Azure PowerShell

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

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

以相同的 AD 租用戶從 Azure 容器登錄匯入

您可以使用整合的 Microsoft Entra 權限，以相同的 AD 租用戶從 Azure 容器登錄匯入映像。

您的身分識別必須具有從來源註冊表檢視和提取映像、標籤及 OCI 參考資料的許可權。
- 針對已啟用 ABAC 的來源登錄，您必須在來源登錄上同時擁有 Container Registry Repository Reader 和 Container Registry Repository Catalog Lister 角色。
- 針對非 ABAC 來源註冊表，您必須在來源註冊表上擁有 AcrPull 角色。
您的身分識別也必須具有讀取映像和觸發目標登錄（Container Registry Data Importer and Data Reader 角色）匯入的許可權。
登錄可以位於相同 Active Directory 租用戶中的相同或不同 Azure 訂用帳戶。
已停用對來源登錄的公共存取。如果停用公用存取，請依資源識別碼指定來源登錄，而不是依登錄登入伺服器名稱進行此動作。
具有私人端點或登錄防火牆規則的來源登錄和/或目標登錄，必須確保受限制的登錄允許受信任的服務存取網路。

從相同訂用帳戶中的登錄匯入

例如，將 aci-helloworld:latest 映像從來源登錄 mysourceregistry 匯入到相同 Azure 訂用帳戶中的 myregistry。

Azure CLI
Azure PowerShell

az acr import \
  --name myregistry \
  --source mysourceregistry.azurecr.io/aci-helloworld:latest \
  --image aci-helloworld:latest

下列範例會將 aci-helloworld:latest 映像檔從來源登錄 mysourceregistry 匯入至 myregistry，其中已停用對登錄公用端點的存取權。提供來源登錄的資源識別碼與 --registry。請注意，--source 參數只會指定來源存放庫和標籤，不會提供登錄登入伺服器名稱。

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

下列範例會依據資訊清單摘要 (SHA-256 雜湊，表示為 sha256:...) 來匯入映像，而非依據標記：

az acr import \
  --name myregistry \
  --source mysourceregistry.azurecr.io/aci-helloworld@sha256:123456abcdefg

Import-AzContainerRegistryImage -RegistryName myregistry -ResourceGroupName myResourceGroup -SourceRegistryUri mysourceregistry.azurecr.io -SourceImage aci-helloworld:latest

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

下列範例會依據資訊清單摘要 (SHA-256 雜湊，表示為 sha256:...) 來匯入映像，而非依據標記：

Import-AzContainerRegistryImage -RegistryName myregistry -ResourceGroupName myResourceGroup -SourceRegistryUri mysourceregistry.azurecr.io -SourceImage aci-helloworld@sha256:123456abcdefg

從不同的訂用帳戶匯入登錄

注意

若要將映像從一個登錄匯入到另一個登錄，來源和目標登錄必須確定這兩個區域都已在訂用帳戶的資源提供者下註冊 Azure Container Registry (ACR)。

Azure CLI
Azure PowerShell

在下列範例中，mysourceregistry 位於與 myregistry 相同 Active Directory 租用戶中的不同訂用帳戶。提供來源登錄的資源識別碼與 --registry。請注意，--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 服務主體的 appID 和密碼。

若為Microsoft Entra 服務主體，請確定 Container Registry Repository Reader 已套用（適用於已啟用 ABAC 的登錄）或 AcrPull （適用於非 ABAC 登錄）。

在建置系統和其他必須將映像匯入到登錄的自動化系統時，使用服務主體將有其效用。

Azure CLI
Azure PowerShell

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

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

以不同的 AD 租用戶從 Azure 容器登錄匯入

若要以不同的 Microsoft Entra 租用戶從 Azure 容器登錄匯入，請依登入伺服器名稱指定來源登錄，並提供可對登錄啟用提取存取的認證。

不支援透過公用存取停用登錄的跨租用戶匯入。

利用使用者名稱和密碼進行跨租用戶匯入

例如，使用非 Microsoft 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.io/sourcerrepo:tag \
  --image targetimage:tag \
  --username <SP_App_ID> \
  --password <SP_Passwd>

Import-AzContainerRegistryImage -RegistryName myregistry -ResourceGroupName myResourceGroup -SourceRegistryUri sourceregistry.azurecr.io -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 login --identity --username <identity_ID>

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

# Login to Azure PowerShell with the identity, for example a user-assigned managed identity
Connect-AzAccount -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.io -SourceImage sourcerrepo:tag -Password <access-token>

從非 Azure 私人容器登錄匯入

藉由指定可對登錄啟用提取存取的認證，從非 Azure 私人登錄匯入映像。例如，從私人 Docker 登錄提取映像：

Azure CLI
Azure PowerShell

az acr import \
  --name myregistry \
  --source docker.io/sourcerepo/sourceimage:tag \
  --image sourceimage:tag \
  --username <username> \
  --password <password>

Import-AzContainerRegistryImage -RegistryName myregistry -ResourceGroupName myResourceGroup -SourceRegistryUri docker.io/sourcerepo -SourceImage sourcerrepo:tag -Username <username> -Password <password>

注意

如果您要從具有IP規則的非 Azure 私人登錄匯入，請遵循下列步驟。

針對匯入容器映像進行疑難排解

徵兆和原因

The remote server may not be RFC 7233 compliant
- 分配規範允許使用範圍標頭形式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 租用戶中的容器登錄。如需詳細資訊，請參閱手動將容器登錄移至另一個區域。
停用來自網路有限制的容器註冊庫的構件導出。