針對 Azure Container Registry 驗證問題進行疑難解答

Azure Container Registry （ACR） 是私人登錄服務。 若要執行推送或提取之類的作業（除了匿名提取作業除外），您必須先對 ACR 進行驗證。

本文可協助您針對 ACR 驗證問題進行疑難解答，並提供從容器登錄提取映射時所發生的最常見錯誤解決方案。

初始疑難排解

1. 識別您使用的驗證選項。 選擇一個之後，請重現驗證問題以取得錯誤。

2. 藉由檢查 Azure 容器登錄的健康情況開始進行疑難解答。

   若要檢查容器登錄的健康情況，請執行下列命令：

   az acr check-health --name <acr-name> --ignore-errors --yes
   

   如果偵測到問題，命令輸出會提供錯誤碼和描述。 如需錯誤碼和可能解決方案的詳細資訊，請參閱 健康情況檢查錯誤參考。

   注意

   如果您收到與 Helm 或 Notary 相關的錯誤，這並不表示您有影響容器登錄或裝置的問題。 它只會指出 Helm 或 Notary 未安裝，或 Azure CLI 與目前安裝的 Helm 或 Notary 版本不相容。

錯誤 1：「DOCKER_COMMAND_ERROR請確認 Docker 用戶端是否已安裝並執行」

以下是錯誤詳細資料的範例：

You may want to use 'az acr login -n <acr-name> --expose-token' to get an access token, which does not require Docker to be installed.
<date and time> An error occurred: DOCKER_COMMAND_ERROR
Please verify if Docker client is installed and running.

解決方案 1：確定已安裝 Docker

命令 az acr login 會呼叫 命令， docker login 並使用 Microsoft Entra 存取令牌來驗證 ACR。 它需要將 Docker 用戶端和 Docker 精靈安裝在您執行命令的電腦上。 若要安裝 Docker，請參閱 安裝 Docker 引擎。

解決方案 2：搭配 “--public-token” 參數使用 “az acr login” 命令

當您的環境中未執行 Docker 精靈時，如果您需要向 ACR 進行驗證，請使用 az acr login 命令搭配 --expose-token 參數。 當您需要執行不需要 Docker 精靈但只有 Docker CLI 的腳本時，此命令會很有説明（例如，使用 Azure Cloud Shell 時）。

錯誤 2：「此命令需要執行 Azure Cloud Shell 不支援的 Docker 精靈」

以下是錯誤詳細資料的範例：

This command requires running the docker daemon, which is not supported in Azure Cloud Shell. You may want to use 'az acr login -n <acr-name> --expose-token' to get an access token, which does not require Docker to be installed.

解決方案 1：在另一個環境中執行 “az acr login -n <acr-name>” 命令

命令 az acr login -n <acr-name> 需要 Docker 用戶端和 Docker 精靈才能執行。 Azure Cloud Shell 僅提供 Docker 用戶端。 若要解決此錯誤，請在安裝 Docker 精靈的環境中執行 az acr login -n <acr-name> 命令。

解決方案 2：搭配 “--public-token” 參數使用 “az acr login” 命令

命令 az acr login -n <acr-name> 需要 Docker 用戶端和 Docker 精靈才能執行。 Azure Cloud Shell 僅提供 Docker 用戶端。 不過，az acr login具有 參數的--expose-token命令適用於沒有 Docker 精靈的環境，例如 Azure Cloud Shell。

錯誤 3：「未經授權：需要驗證」

以下是錯誤詳細資料的範例：

Error response from daemon: Get "https://<acr-name>.azurecr.io/v2/": unauthorized: {"errors":[{"code":"UNAUTHORIZED","message":"authentication required, visit https://aka.ms/acr/authorization for more information."}]}

錯誤表示存取 ACR 時驗證失敗。 使用不正確的使用者名稱和/或密碼或過期認證執行 或 docker login 命令時az acr login，可能會發生此錯誤（使用服務主體、具有範圍對應或系統管理員使用者的令牌時）。

解決方案：使用正確/有效的使用者名稱和密碼

• 如果您使用系統管理員使用者進行驗證，請檢查 [存取金鑰] 刀鋒視窗中的認證，以及它們是否為您在 或 az acr login 命令中使用的docker login認證。

  

  注意

  先前使用的密碼可能已重新產生。

• 如果您使用與範圍對應相關聯的令牌，請檢查所使用的認證。 當您產生令牌的密碼之後，您必須擷取並安全地儲存認證，因為關閉畫面之後不會再顯示密碼。 請參閱下列螢幕快照中的訊息：

  

  如果您不確定所使用的密碼，請考慮 重新產生 密碼。

• 如果您使用與範圍對應相關聯的令牌，則可以為密碼設定到期日。 若要檢視到期日，您可以執行顯示令牌詳細數據中所述的 Azure CLI 命令，或在 Azure 入口網站 中開啟令牌，然後根據下列螢幕快照檢查到期日：

  

• 如果您使用服務主體，請確定其具有向 ACR 進行驗證的特定許可權。 若要尋找特定許可權和可用的內建角色，請參閱 Azure Container Registry 角色和許可權。

• 如果您使用服務主體，請檢查所使用的認證。 產生秘密之後，您必須擷取並安全地儲存認證，因為關閉畫面之後不會再顯示密碼。 請參閱下列螢幕快照中的訊息：

  

  如果您不確定所使用的秘密值，請考慮 建立新的秘密。

• 如果您使用服務主體，請確定密碼未過期。

  您可以執行 az ad app credential list 命令來檢查秘密有效性：

  az ad app credential list --id "$SP_ID" --query "[].endDateTime" -o tsv
  

  或者，您可以藉由驗證 Azure 入口網站 中的 [到期] 資料行來檢查秘密有效性：

  

  如果密碼已過期，您可以考慮 建立新的秘密。

錯誤 4：“無法取得系統管理員用戶認證”

以下是錯誤詳細資料的範例：

Unable to get AAD authorization tokens with message: <date> <time> An error occurred: CONNECTIVITY_REFRESH_TOKEN_ERROR
Access to registry '<acr-name>.azurecr.io' was denied. Response code: 401. Please try running 'az login' again to refresh permissions.
Unable to get admin user credentials with message: The resource with name '<acr-name>' and type 'Microsoft.ContainerRegistry/registries' could not be found in subscription '<subscription-name> (<subscription-id>)'.

解決方案：確定所使用的身分識別具有特定許可權

請確定用來驗證的身分識別（例如使用者或受控識別）具有特定許可權。 若要尋找特定許可權和可用的內建角色，請參閱 Azure Container Registry 角色和許可權。

錯誤 5：「不允許 IP IP 位址>的<用戶端存取」

以下是錯誤詳細資料的範例：

Unable to get AAD authorization tokens with message: <date> <time> An error occurred: CONNECTIVITY_REFRESH_TOKEN_ERROR
Access to registry '<acr-name>.azurecr.io' was denied. Response code: 403. Please try running 'az login' again to refresh permissions.
Error response from daemon: Get "https://<acr-name>.azurecr.io/v2/": denied: {"errors":[{"code":"DENIED","message":"client with IP \u0027<ip-address>\u0027 is not allowed access. Refer https://aka.ms/acr/firewall to grant access."}]}

解決方案：請確定您嘗試驗證的裝置具有與 ACR 的連線能力

ACR 具有內建防火牆，這是限制公用存取的機制。 它可以允許完整存取、只允許存取特定網路，或完全停用公用存取。 不過，成功驗證需要適當的連線能力。 請確定您的IP位址允許存取並登入登錄。 如需設定公用存取的詳細資訊，請參閱 設定公用IP網路規則。

或者，您也可以考慮 使用 Azure Private Link 私下連線到 Azure 容器登錄。

與我們連絡，以取得說明

如果您有問題或需要相關協助，請建立支援要求，或詢問 Azure community 支援。 您也可以向 Azure 意見反應社群提交產品意見反應。