为什么配置了 registry-mirrors 仍然访问官方仓库或报错？
本文适用于：
- • Docker 20+ / 24+
- • 国内网络环境
- • 使用 registry-mirrors 或专属镜像域名的用户
- • 配置了镜像源但仍遇到访问官方仓库的情况
⚠️ 重要提示
这不是配置失败，而是 Docker 的正常回退机制。
Docker 镜像拉取流程：
docker pull ↓ registry-mirror ↓ 失败/错误 docker.io（回退） ↓ 超时 错误提示
当镜像源返回错误或无法访问时，Docker 会自动回退到官方源，这是正常的容错机制。
当您配置了 registry-mirrors 后，发现 Docker 仍然尝试访问官方仓库 registry-1.docker.io 并报错超时，这是 Docker 的镜像拉取机制决定的，并不代表配置无效。
典型错误现象
配置了镜像源后，拉取镜像时仍然看到访问官方源的报错：
这说明 Docker 在镜像源失败后，自动回退到了官方源，但官方源无法访问导致超时。
registry-mirrors 的工作原理
核心机制：registry-mirrors 是"优先尝试"而非"强制代理"
当镜像源返回错误或无法访问时，Docker 客户端会自动回退到官方源（docker.io），这是正常的容错机制。
常见的回退场景
场景 1：镜像源无可用流量
当专属域名没有流量时，镜像源会返回 402 Payment Required 或其他错误。
Docker 收到错误后会自动回退到官方源，导致看起来"配置没生效"。实际上配置是正确的，只是镜像源暂时不可用。
场景 2：镜像确实不存在或未同步
如果镜像在镜像源或上游 docker.io 都不存在，会返回 manifest unknown（404）错误。
例如：
→ Error: manifest unknown
此时即使改为 docker pull scjtqs/wine-qq:latest，Docker 也可能尝试访问官方源，但最终仍会超时或报错。
场景 3：不同组件的回退逻辑差异
Docker（dockerd）、containerd、BuildKit 在不同版本中，对"镜像源返回错误"时是否回退到官方源的处理逻辑并不一致：
- • 有的版本遇到 404 会直接报错，不会尝试官方源
- • 有的版本则会自动重试官方仓库
- • 这导致在不同环境下表现可能不同
场景 4：配置未正确生效
- • 修改
daemon.json后未重启 Docker 服务 - • 配置文件 JSON 格式错误，导致
registry-mirrors被忽略 - • 配置路径错误或权限问题
场景 5：daemon.json 配置的镜像仅对 docker.io 生效，其他仓库镜像需要显性指定地址拉取
registry-mirrors 只作用于 docker.io（Docker Hub 官方仓库）。
对于其他 Registry（如 ghcr.io、quay.io、gcr.io 等），Docker 客户端不会去查 registry-mirrors，而是直接请求这些域名。
比如：
Docker 不会自动把它们代理到 registry-mirrors。
正确的方法是指定地址显性拉取：
如：
如何确认镜像源是否可用？
方法 1：使用显式域名测试
直接指定镜像源域名进行拉取：
（xxx.xuanyuan.run 替换为你的专属域名）
- • 如果能拉取成功 → 说明镜像源正常
- • 如果报错 → 根据具体报错排查
方法 2：查看客户端配置
确认镜像站地址已正确加载：
如果能看到您配置的镜像地址，说明配置已生效。
建议的解决方案
✅ 推荐做法
在国内环境，registry-mirrors 只适合作为兜底方案。
稳定方案是：显式指定镜像域名，直接使用 docker pull xxx.xuanyuan.run/library/nginx:latest 这样的完整地址，避免 Docker 的回退机制。
✅ 方案 1：确保镜像源有可用流量
及时充值流量包，避免 402 错误导致的回退。
✅ 方案 2：使用显式镜像域名（推荐）
直接指定镜像域名进行拉取，可避免 Docker 的自动回退逻辑：
💡 总结：
- ✅
registry-mirrors只能保证"优先尝试"，无法保证"始终生效" - ✅ 当镜像源返回错误时，Docker 会自动回退到官方源，这是正常的容错机制
- ✅ 若需完全稳定，建议直接指定镜像源地址拉取镜像
- ✅ 确保镜像源有充足流量，避免因流量耗尽导致的回退
你可能还会遇到：
本文由「xuanyuan.cloud」维护
专注国内 Docker / 镜像 / Registry 网络问题
内容基于真实用户环境与实测