通过

注册表登录故障排除

本文可帮助你排查使用 Azure 容器注册表登录、进行身份验证或授权时可能会遇到的问题。

症状

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

  • 无法使用 docker login 和/或 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 资源管理器操作 - 解决方案
  • 凭据已过期 - 解决方案
  • 如果使用 Microsoft Entra 基于角色的访问控制 （RBAC） 管理 Microsoft Entra 标识（用户、托管标识或服务主体）的注册表权限，则标识可能具有注册表权限，但不能具有存储库权限 - 解决方案

进一步诊断

运行 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）来访问注册表，请确认服务的注册表配置。
  • 如果运行了带有 az acr login 选项的 --expose-token，以允许在不使用 Docker 守护程序的情况下登录注册表，请确保使用用户名 00000000-0000-0000-0000-000000000000 进行身份验证。
  • 如果注册表配置为 匿名拉取访问，则从以前的 Docker 登录名存储的现有 Docker 凭据可能会阻止匿名访问。 先运行 docker logout，再在注册表上尝试匿名拉取操作。

相关链接：

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

  • 如果你的权限最近更改为允许通过门户访问注册表，你可能需要尝试在浏览器中使用 incognito 或专用会话，以避免使用任何过时的浏览器缓存或 Cookie。
  • 你或注册表所有者必须在订阅中拥有足够的权限，才能添加、修改或删除Microsoft Entra 角色分配。 由 Role Based Access Control Administrator 角色授予管理 Microsoft Entra 角色分配的权限。
  • 若要在门户中访问注册表或要使用 Azure CLI 进行注册表管理，至少需要用于执行 Azure 资源管理器操作的 Container Registry Contributor and Data Access Configuration Administrator 角色或等效权限。

验证标识权限和角色分配

  • 如果使用 Microsoft Entra 基于角色的访问控制（RBAC）来管理注册表权限，请确认标识（用户、托管标识或服务主体）具有正确的角色分配和权限。
    • 如果“注册表角色分配权限模式”（在 Azure 门户的“属性”边栏选项卡中）设置为新的“RBAC 注册表 + ABAC 存储库权限”选项，并且标识无法推送、拉取或删除映像，则标识可能无权访问映像位于的特定存储库。
      • 检查现有角色分配和角色分配 ABAC 条件，以确保身份具有访问存储库的正确权限。
      • 具有“RBAC 注册表 + ABAC 存储库权限”模式的注册表不认现有 AcrPull、AcrPush 或 AcrDelete 角色。
      • 相反，此类注册表只接受在注册表中的存储库内读取、写入或删除映像的 Container Registry Repository Reader、Container Registry Repository Writer 和 Container Registry Repository Contributor 角色。 这些角色可能有可选的 ABAC 条件，用于限制授予特定存储库的权限。
      • 请注意，这些角色不会向目录列表授予列出注册表中的存储库的权限。 若要列出存储库（但不读取存储库中的内容），必须单独将 Container Registry Repository Catalog Lister 角色分配给标识。 此角色不支持 ABAC 条件，因此它授予列出注册表中的所有存储库的权限。
      • 有关详细信息，请参阅针对基于 Microsoft Entra 的存储库权限的 Microsoft Entra 基于属性的访问控制 (ABAC)。
    • 如果“注册表角色分配权限模式”设置为旧的“RBAC 注册表权限”选项，则标识可能无权访问注册表及其存储库。
      • 检查现有角色分配，确保标识具有访问注册表及其存储库的正确权限。
      • 具有“RBAC 注册表权限”模式的注册表仅允许AcrPullAcrPushAcrDelete角色在注册表的存储库中读取、写入或删除映像。
      • 有关详细信息，请参阅 Azure 容器注册表Microsoft Entra 权限和角色概述。

相关链接：

检查凭据是否未过期

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

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

相关链接：

高级故障排除

如果在注册表中启用了 资源日志集合 ，请查看 ContainerRegistryLoginEvents 日志。 此日志存储身份验证事件和状态，包括传入标识和 IP 地址。 查询日志以查找 注册表身份验证失败。

相关链接：

后续步骤

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