通过

排查Azure 容器注册表身份验证问题

Azure 容器注册表（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：将“az acr login”命令与“--expose-token”参数一起使用

当 Docker 守护程序未在环境中运行时，如果需要使用 ACR 进行身份验证，请使用 带有 --expose-token 参数的 az acr login 命令。 如果需要运行不需要 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 客户端。 若要解决此错误，请在 az acr login -n <acr-name> 安装 Docker 守护程序的环境中运行该命令。

解决方案 2：将“az acr login”命令与“--expose-token”参数一起使用

该 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 时身份验证失败。 当运行 az acr login 用户名和/或密码不正确或 docker login 凭据过期的命令（使用服务主体、具有范围映射的令牌或管理员用户时），可能会出现此错误。

解决方案：使用正确的/有效的用户名和密码

  • 如果使用管理员用户进行身份验证，请检查访问密钥边栏选项卡中的凭据，以及它们是否是你在或az acr login命令中使用的docker login凭据。

    显示 ACR“访问密钥”边栏选项卡的屏幕截图。

    注意

    以前使用的密码可能已重新生成。

  • 如果使用与范围映射关联的令牌，请检查所使用的凭据。 为令牌生成密码后，必须检索并安全地存储凭据，因为关闭屏幕后不再显示密码。 请参阅以下屏幕截图中的消息：

    显示“生成后安全地存储凭据”消息的屏幕截图。

    如果不确定所使用的密码，请考虑 重新 生成密码。

  • 如果使用与范围映射关联的令牌，则可以为密码设置过期日期。 若要查看到期日期，可以运行“显示令牌详细信息”中所述的 Azure CLI 命令，或在Azure 门户中打开令牌，并按以下屏幕截图检查到期日期：

    显示“到期日期”列的屏幕截图。

  • 如果使用服务主体，请确保它具有使用 ACR 进行身份验证的特定权限。 若要查找特定权限和可用的内置角色，请参阅Azure 容器注册表角色和权限。

  • 如果使用服务主体，请检查使用的凭据。 生成机密后，必须检索并安全地存储凭据，因为关闭屏幕后不再显示密码。 请参阅以下屏幕截图中的消息：

    显示“在离开页面之前保存机密”消息的屏幕截图。

    如果不确定使用的机密值，请考虑 创建新的机密。

  • 如果使用服务主体，请确保机密未过期。

    可以通过运行 az ad app credential list 命令来检查机密有效性：

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

    或者，可以通过验证Azure 门户中的“过期”列来检查机密有效性：

    显示 ACR“过期”列的屏幕截图。

    如果机密已过期，可以考虑 创建新的机密。

错误 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 容器注册表角色和权限。

错误 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 专用链接私下连接到 Azure 容器注册表。

联系我们寻求帮助

如果你有任何疑问或需要帮助，请创建支持请求或联系 Azure 社区支持。 你还可以将产品反馈提交到 Azure 反馈社区。