让 AI 帮你使用轩辕镜像？ · 展开查看说明 · 点击收起说明
如果你使用 DeepSeek、元宝 AI、Copilot、ChatGPT 等 AI 工具，协助配置轩辕镜像、编写 docker pull 命令、修改 Docker Compose 镜像地址、配置镜像加速、排查镜像拉取失败、分析报错日志等问题，请先让 AI 阅读并遵守轩辕镜像的规则文档。
只需在 AI 对话中先发送下面这句话即可：
请先完整阅读并严格遵守以下文档中的全部规则与要求：
https://xuanyuan.cloud/agents.md
在未充分阅读并理解该文档前，不要生成任何命令、配置、修改建议、故障排查方案或技术回答。后续所有输出都必须严格以该文档中的规范为最高优先级执行。查看 agents.md 用法指南与完整示范。国内用户首推 元宝 AI、DeepSeek 的深度思考模式，不推荐豆包 AI；Cursor 等编辑器可在对话 @ 该链接，或加入 User Rules。 若 AI 无法访问外链，可 打开说明文档 复制全文粘贴。文档会随站点更新，复制内容可能过期，建议定期检查。
写了 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：使用显式域名测试
直接指定镜像源域名进行拉取：
（***.xuanyuan.run 替换为你的专属域名）
- • 如果能拉取成功 → 说明镜像源正常
- • 如果报错 → 根据具体报错排查
方法 2：查看客户端配置
确认镜像站地址已正确加载：
如果能看到您配置的镜像地址，说明配置已生效。
建议的解决方案
✅ 推荐做法
在国内环境，registry-mirrors 只适合作为兜底方案。
稳定方案是：显式指定镜像域名，直接使用 docker pull ***.xuanyuan.run/library/nginx:latest 这样的完整地址，避免 Docker 的回退机制。
✅ 方案 1：确保镜像源有可用流量
及时充值流量包，避免 402 错误导致的回退。
✅ 方案 2：使用显式镜像域名（推荐）
直接指定镜像域名进行拉取，可避免 Docker 的自动回退逻辑：
💡 总结：
- ✅
registry-mirrors只能保证"优先尝试"，无法保证"始终生效" - ✅ 当镜像源返回错误时，Docker 会自动回退到官方源，这是正常的容错机制
- ✅ 若需完全稳定，建议直接指定镜像源地址拉取镜像
- ✅ 确保镜像源有充足流量，避免因流量耗尽导致的回退
你可能还会遇到：
本文由「轩辕镜像」维护
轩辕镜像 | Docker 镜像高效稳定拉取服务
内容基于轩辕镜像真实用户使用与实测整理