Docker登录、推送和拉取失败常见问题

docker login失败

为什么docker login失败？

登录失败时，参考如下步骤进行排查。

• 您使用了阿里云账户的登录密码，而不是Registry的独立登录密码。Registry的登录密码是在容器镜像服务控制上设置与修改的，操作步骤如下。

  1. 登录容器镜像服务控制

  2. 在实例列表页面单击实例卡片，进入实例详情页。

  3. 在左侧导航栏选择实例管理 > 访问凭证。

  4. 在访问凭证页面，单击右上角的设置固定密码。

  5. 在设置固定密码对话框，设定Registry的登录密码，然后单击确定。

• 您使用了sudo进行登录。使用sudo时，系统第一个要求输入的密码是Linux的用户密码。您可能在这里输入了Registry的登录密码，导致登录操作失败。

  区分这个错误的方式很简单，Linux的用户密码大多允许尝试三次，错误时会提示try again。而Registry的登录密码错误一次之后就会退出，并返回以下错误。

  Error response from daemon: Get https://registry.cn-hangzhou.aliyuncs.com/v2/: unauthorized: authentication required                    

• 如果您使用的是RAM用户，请勿使用阿里云账号设置的密码登录镜像仓库，您需要在容器镜像控制台设置密码，然后使用该密码登录镜像仓库。具体操作，请参见配置访问凭证。

为什么 docker login 报错 Bad Request？

ECS 节点配置了 HTTPS_PROXY 代理时，Docker 请求经代理转发可能出现异常，返回 Bad Request 错误。排查步骤如下：

1. 检查 /etc/systemd/system/docker.service.d 路径下是否存在代理相关配置文件（如 http-proxy.conf 或 https-proxy.conf）。

2. 备份并删除该路径下的代理配置文件。

3. 执行以下命令重载配置并重启 Docker：

   systemctl daemon-reload && systemctl restart docker

4. 清除代理配置后重新执行 docker login。

为什么docker login超时？

检查您的网络是否可以正常使用。如果您的网络不能正常使用，将无法访问到实例，从而会导致docker login超时，详情请参见网络访问控制。

docker pull失败

docker pull失败，报错提示Error: image xxx not found

报错提示Error: image xxx not found

下载失败时，请参考如下步骤进行排查。

• 检查镜像地址：

  • 确认您输入的镜像地址是正确的，特别是在使用公共镜像时。

  • 可以在容器镜像服务控制中查看镜像的具体地址和版本。

• 私有仓库的登录状态：

  • 使用cat ~/.docker/config.json查看已登录的 Registry 域名，确保您的私有仓库域名在其中。

  • 如果未登录，需使用docker login命令进行登录。

• 账户权限：

  • 确认您使用的账户有权限访问或下载该镜像，尤其是使用子账户时，默认情况下可能没有相关权限。

  • 可以在仓库的访问控制设置中进行权限管理。关于仓库的访问控制授权，请参见仓库访问控制。

为什么在企业版实例匿名拉取镜像会失败？

您需要在概览页面右侧实例设置区域打开公开匿名拉取，您才可以匿名拉取镜像。

为什么海外镜像仓库源拉取失败？

由于运营商网络等不稳定因素，可能会导致从海外镜像仓库拉取指定版本的容器镜像失败。详情请参见官方镜像加速。

docker pull 报错 manifest unknown，但仓库中确实存在该镜像怎么办？

该问题通常由客户端与镜像的 CPU 架构不匹配导致。例如客户端为 ARM 架构，而镜像仅包含 AMD64 架构的 manifest。排查步骤如下：

1. 确认客户端环境的 CPU 架构（ARM 或 AMD64），可执行 uname -m 或 docker info 查看。

2. 尝试在对应架构的服务器上执行 docker pull，验证是否能正常拉取。

3. 若无法提供账号供复现，建议重新构建并推送一个新的 Tag。构建时多架构配置异常可能导致特定 Tag 的 manifest 信息不完整，重新构建推送通常可解决该问题。

docker push失败

docker push失败，报错提示denied: requested access to the resource is denied

上传失败时，主要的排查步骤和docker pull基本一致，只是授权要求的级别比docker pull更高。

为什么docker push会失败？

推送镜像之前请确保镜像已创建镜像仓库。如果没有镜像仓库，请确保命名空间已开启自动创建仓库功能。

推送失败与安全组及用户权限问题

ACR 本身没有安全组配置，推送失败通常不是客户端安全组导致的。建议检查以下项目：

• 切换到 root 用户执行 docker login 和 docker push 操作。

• 避免使用 sudo 或非 root 用户（如 Mac、麒麟系统）操作。不同用户的 Docker 凭证存储路径不同，可能导致无法准确更新本地凭证信息。

推送报错 certificate has expired or is not yet valid

处理方法如下：

1. 备份并删除客户端 ~/.docker/config.json 文件中的旧配置信息。

2. 登录 ACR 控制台，获取新的登录命令或设置新的访问凭证。

3. 执行 docker login 重新登录后再尝试推送。

Token 失效后的自动刷新机制

当执行 docker push 时，如果 token 已失效或不存在，Docker 客户端会自动使用 ~/.docker/config.json 中存储的用户名和密码（auth 字段 Base64 解码后的信息）向 dockerauth 服务发起请求，重新获取新 token，无需人工干预。

ACR 对单个流式 layer 推送的大小限制是多少？

ACR 对单个流式 layer 推送的大小没有强制限制，但建议单层大小尽量不要超过 100 GB，以避免推送超时或失败。