docker pull 报 pull access denied 怎么解决？镜像拉取被拒的 5 种原因

现象：拉镜像被拒

pull access denied for myapp/api, repository does not exist or may
require 'docker login': denied: requested access to the resource is denied

一行结论：Docker Hub（或你用的 registry）拒绝匿名拉取这个镜像。拒绝的原因只有两类：要么「这个仓库根本不存在」，要么「存在但你没权限」。报错故意含糊（安全考虑，不区分两者），排查就是逐一排除。

五种原因，按概率排序

1. 镜像名拼错了（最常见）

Docker 镜像名的解析规则先搞清楚：

nginx                    → docker.io/library/nginx（官方镜像）
bitnami/nginx            → docker.io/bitnami/nginx（用户/组织镜像）
registry.example.com/app → 私有 registry 上的镜像

两个高频错误：把个人镜像当官方镜像拉（docker pull myapp 找的是 library/myapp，不存在）；或者多打/少打一段名字。先去 Docker Hub 页面确认镜像的完整路径和拼写。

2. tag 不存在

manifest for myapp/api:v1.2 not found 是近亲错误——仓库存在但 tag 写错了。特别是假设镜像有 latest tag 是经典陷阱：官方镜像基本都有 latest，个人镜像经常只 push 过具体版本号。去 Hub 页面的 Tags 列表核对，别凭感觉写。

3. 私有仓库没登录（或登错账号）

docker login                       # 默认 Docker Hub
docker login registry.example.com  # 私有/自建 registry
cat ~/.docker/config.json          # 看登录了哪些 registry、哪个账号

常见坑：登录了公司账号去拉个人仓库（反之亦然）；CI 上的凭据过期；docker login 之后换了 context。重新 login 对应 registry 即可。

4. Docker Hub 限流（报错形态不同但要一起排查）

匿名拉取限 100 次/6 小时（按 IP）。超限的报错是 toomanyrequests: You have reached your pull rate limit——和 access denied 是两回事，但经常被混为一谈。免费账号登录后限额 200 次，基本够用。

5. 国内网络：配镜像加速器

国内直连 Docker Hub 经常超时或被重置，报错形态五花八门（timeout、EOF、unexpected status）。配加速器是标准解法，/etc/docker/daemon.json：

{
  "registry-mirrors": ["https://docker.m.daocloud.io"]
}

改完 sudo systemctl restart docker。注意 daemon.json 不能有尾逗号，改坏了 daemon 起不来——排查方法见：Cannot connect to the Docker daemon 排查。

排查路线（一分钟定位）

# 1. 完整报错是什么？（access denied / not found / rate limit 三者方向完全不同）
docker pull myapp/api:v1.2

# 2. 登录状态
docker login

# 3. 换个官方镜像试试——官方能拉说明是权限/名字问题，官方也拉不动说明是网络
docker pull hello-world

# 4. 网络问题时验证加速器是否生效
docker info | grep -A3 "Registry Mirrors"

第 3 步是分水岭：hello-world 都拉不动 → 网络/限流（原因 4/5）；只有你的镜像拉不动 → 名字/权限（原因 1/2/3）。

和相邻错误的分界

| 报错 | 含义 | 参考 | |---|---|---| | pull access denied | 仓库不存在或无权限 | 本篇 | | manifest ... not found | 仓库存在，tag 不对 | manifest unknown 排查 | | toomanyrequests | 拉取频率超限 | 登录或等待 | | i/o timeout / EOF | 网络不通 | 配加速器（本篇原因 5） |

排查清单

1. 镜像完整路径核对：官方无前缀、个人带用户名、私库带域名
2. tag 存在吗？Hub 页面 Tags 列表核对，别假设有 latest
3. docker login 对应 registry 了吗？~/.docker/config.json 看记录
4. 报错是 access denied 还是 rate limit？后者是登录/等待问题
5. docker pull hello-world 分水岭测试：判断是网络还是权限
6. 国内环境配 registry-mirrors 加速器

本文由 ToolVault 工具匣 提供。相关工具：Dockerfile 生成器、Linux 命令速查。相关阅读：manifest unknown 排查、Docker daemon 连不上、npm 换源指南（同类网络问题）。访问 首页 查看更多开发者工具。