让 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 无法访问外链，可 打开说明文档 复制全文粘贴。文档会随站点更新，复制内容可能过期，建议定期检查。
Docker pull 时 DNS 解析超时或连不上仓库怎么办？
本文适用于：
- • Docker 20+ / 24+
- • 国内网络环境
- • Windows WSL / Docker Desktop 用户
- • Docker 使用的 DNS 服务器无法访问外网
- • 遇到 DNS 解析超时错误
⚠️ 重要提示
这是 Docker 使用的 DNS 服务器无法访问外网导致的，不是镜像仓库的问题。
解决方案优先级：
- ✅ 方案 1：配置 Docker 公共 DNS（推荐，适用于所有系统）
- ✅ 方案 2：修复 WSL/Docker Desktop DNS（Windows 特有）
- ✅ 方案 3：使用 hosts 文件（临时方案）
✅ 推荐做法
在 /etc/docker/daemon.json 中配置公共 DNS（223.5.5.5、114.114.114.114）。Windows WSL 用户需要额外修改 /etc/resolv.conf 并禁止自动重置。
当您在拉取镜像时遇到 DNS 解析超时错误，Docker 无法解析镜像仓库域名，导致 docker pull 无法正常工作。
错误示例
错误含义
核心报错信息：
这是 DNS 解析超时错误。Docker 尝试向本地 DNS 服务器（172.27.32.1:53）发送域名解析请求，但在超时时间内没有收到响应。
简而言之：Docker 客户端无法解析域名 → 镜像仓库地址解析失败 → docker pull 无法进行
常见原因
| 原因类型 | 说明 |
|---|---|
| 1️⃣ Docker DNS 不可用 | Docker 默认使用宿主机的 DNS，但 WSL 或 Docker Desktop 内部虚拟网卡（如 172.27.32.1）的 DNS 无法访问外网 |
| 2️⃣ 宿主机 DNS 配置错误 | /etc/resolv.conf 配置不正确或指向的 DNS 服务器无响应 |
| 3️⃣ 域名解析问题 | 自定义域名（如 *.xuanyuan.run）在公网 DNS 中无法正确解析 |
| 4️⃣ 网络干扰 | 防火墙、公司网络策略或代理工具阻断了 DNS 请求 |
解决方案
✅ 方案 1：在 Docker 配置中手动指定公共 DNS
步骤 1：编辑 Docker 配置文件（Linux 通常位于 /etc/docker/daemon.json）
步骤 2：添加或修改为以下内容：
步骤 3：保存后重启 Docker 服务
步骤 4：重新尝试拉取镜像
✅ 方案 2：验证域名解析并配置 hosts（如果 DNS 无法解析）
步骤 1：在宿主机或容器中测试域名解析
如果超时或返回 SERVFAIL，说明 DNS 确实存在问题。
步骤 2：可以尝试使用本地 hosts 文件解析（临时方案）
添加一行（请替换为实际的 IP 地址）：
保存后再次尝试拉取镜像
✅ 方案 3：修复 Docker Desktop / WSL 网络（Windows 常见问题）
如果您在 Windows 下运行 Docker（特别是 WSL2 模式），DNS 默认走虚拟网卡（172.27.x.x），容易出错。
步骤 1：检查 WSL 的 DNS 配置
如果看到类似 nameserver 172.27.32.1，说明是 WSL 的内部 DNS。
步骤 2：手动修改 DNS 为公共 DNS
步骤 3：禁止 WSL 自动重置 resolv.conf
编辑 /etc/wsl.conf：
添加以下内容：
步骤 4：重新启动 WSL（在 PowerShell 中执行）
✅ 方案 4：检查网络连通性
使用以下检查点验证网络状态：
| ✅ | nslookup ***.xuanyuan.run 能解析域名 |
| ✅ | curl https://***.xuanyuan.run/v2/ 能连上 |
| ✅ | Docker 配置了公共 DNS（223.5.5.5、114.114.114.114） |
| ⚠️ | 若仍超时，检查宿主机防火墙、代理设置 |
💡 总结：
- ✅ DNS 解析超时通常是 Docker 使用的 DNS 服务器无法访问外网导致
- ✅ 最直接的解决方法是在
/etc/docker/daemon.json中配置公共 DNS（223.5.5.5、114.114.114.114） - ✅ Windows WSL 用户需要特别注意修改
/etc/resolv.conf并禁止自动重置 - ✅ 确保网络畅通、防火墙未阻断 DNS 请求（UDP 53 端口）
你可能还会遇到：
本文由「轩辕镜像」维护
轩辕镜像 | Docker 镜像高效稳定拉取服务
内容基于轩辕镜像真实用户使用与实测整理