注册表登录故障排除

  • 项目

本文将帮助你排查在登录 Azure 容器注册表时可能遇到的问题。

症状

可能包括以下一项或多项：

  • 无法使用 docker login azure --cloud-name AzureChinaCloud 和/或 az acr login 登录到注册表
  • 无法登录到注册表，出现错误 unauthorized: authentication required 或 unauthorized: Application not registered with AAD
  • 无法登录到注册表，出现 Azure CLI 错误 Could not connect to the registry login server
  • 无法推送或拉取映像，出现 Docker 错误 unauthorized: authentication required
  • 无法使用 az acr login 访问注册表，并且收到错误 CONNECTIVITY_REFRESH_TOKEN_ERROR. Access to registry was denied. Response code: 403. Unable to get admin user credentials with message: Admin user is disabled. Unable to authenticate using AAD or admin login credentials.
  • 无法从 Azure Kubernetes 服务、Azure DevOps 或其他 Azure 服务访问注册表
  • 无法访问注册表，出现错误 Error response from daemon: login attempt failed with status: 403 Forbidden - 请参阅排查与注册表相关的网络问题
  • 无法在 Azure 门户中访问或查看注册表设置，或者无法使用 Azure CLI 管理注册表

原因

  • 在你的环境中未正确配置 Docker - 解决方案
  • 注册表不存在或名称不正确 - 解决方案
  • 注册表凭据无效 - 解决方案
  • 禁用注册表公共访问。 注册表上的公用网络访问规则阻止访问 - 解决方案
  • 凭据未被授权用于推送、拉取或 Azure 资源管理器操作 - 解决方案
  • 凭据已过期 - 解决方案

进一步诊断

运行 az acr check-health 命令可详细了解注册表环境的运行状况，以及对目标注册表的访问（可选）。 例如，诊断 Docker 配置错误或 Microsoft Entra 登录问题。

参阅检查 Azure 容器注册表的运行状况以查看命令示例。 如果报告了错误，请查看错误参考和以下部分，以了解建议的解决方案。

如果无法将 ACR 中的映像拉取到 AKS 群集，请按照 AKS 支持文档中的说明进行操作。

注意

如果存在阻止访问注册表的防火墙或网络配置，也会发生某些身份验证或授权错误。 请参阅排查与注册表相关的网络问题。

可能的解决方案

检查 Docker 配置

大多数 Azure 容器注册表身份验证流需要本地 Docker 安装，因此你可以向注册表进行身份验证，以便执行推送和拉取映像等操作。 确认 Docker CLI 客户端和守护程序（Docker 引擎）正在环境中运行。 你需要 Docker 客户端版本 18.03 或更高版本。

相关链接：

指定正确的注册表名称

使用 docker login 时，请提供注册表的完整登录服务器名称，如 myregistry.azurecr.cn。 请确保只使用小写字母。 示例：

docker login myregistry.azurecr.cn

将 az acr login 与 Microsoft Entra 标识配合使用时，请先登录到 Azure CLI，然后指定注册表的 Azure 资源名称。 资源名称是在创建注册表时提供的名称，如 myregistry（没有域后缀）。 示例：

az acr login --name myregistry

相关链接：

确认用于访问注册表的凭据

检查用于你的方案的凭据或由注册表所有者提供给你的凭据的有效性。 一些可能的问题：

  • 如果使用 Active Directory 服务主体，请确保在 Active Directory 租户中使用正确的凭据：
    • 用户名 - 服务主体应用程序 ID（也称为客户端 ID）
    • 密码 - 服务主体密码（也称为客户端密码）
  • 如果使用 Azure 服务（如 Azure Kubernetes 服务或 Azure DevOps）来访问注册表，请确认服务的注册表配置。
  • 如果运行了带有 --expose-token 选项的 az acr login，以允许在不使用 Docker 守护程序的情况下登录注册表，请确保使用用户名 00000000-0000-0000-0000-000000000000 进行身份验证。
  • 如果将注册表配置为匿名拉取访问，则以前的 Docker 登录名存储的现有 Docker 凭据可阻止匿名访问。 先运行 docker logout，再在注册表上尝试匿名拉取操作。

相关链接：

确认凭据已被授权访问注册表

确认与凭据关联的注册表权限，例如用于从注册表拉取映像的Azure 角色 AcrPull，或用于推送映像的 AcrPush 角色。

若要在门户中访问注册表或要使用 Azure CLI 进行注册表管理，至少需要用于执行 Azure 资源管理器操作的 Reader 角色或等效权限。

如果你的权限最近更改为允许通过门户访问注册表，你可能需要尝试在浏览器中使用 incognito 或专用会话，以避免使用任何过时的浏览器缓存或 Cookie。

你或注册表所有者必须在订阅中具有足够的权限，才能添加或删除角色分配。

相关链接：

检查凭据是否未过期

令牌和 Active Directory 凭据可能会在定义的时间段后过期，从而阻止访问注册表。 若要允许访问注册表，可能需要重置或重新生成凭据。

  • 如果将单个 AD 标识、托管标识或服务主体用于注册表登录，AD 令牌将在 3 小时后过期。 请再次登录到注册表。
  • 如果将 AD 服务主体与已过期的客户端密码配合使用，则订阅所有者或帐户管理员需要重置凭据或生成新的服务主体。
  • 如果使用存储库范围内的令牌，则注册表所有者可能需要重置密码或生成新令牌。

相关链接：

高级故障排除

如果在注册表中启用了收集资源日志，请查看 ContainerRegistryLoginEvents 日志。 此日志存储身份验证事件和状态，包括传入标识和 IP 地址。 查询此日志可获得有关注册表身份验证失败的信息。

相关链接：

后续步骤

如果此处无法解决你的问题，请参阅以下选项。