Docker 容器 DNS 解析失败排查与修复：从临时调试到生产配置

快速答案

• 核心结论：Docker 容器 DNS 解析失败通常由默认 bridge 网络限制、systemd-resolved 干扰或全局 DNS 配置错误引起，解决方案按场景分层。
• 第一排查步骤：用 docker run --dns=8.8.8.8 busybox nslookup example.com 测试容器能否通过公共 DNS 解析；用 docker exec <container> cat /etc/resolv.conf 查看容器内实际 DNS 配置。
• 最小修复命令：临时修复用 docker run --dns=8.8.8.8 --dns=8.8.4.4；持久化全局修复在 /etc/docker/daemon.json 中添加 {"dns": ["8.8.8.8", "8.8.4.4"]} 后重启 Docker。
• 适用环境边界：--network host 模式仅 Linux 有效；用户自定义网络（非默认 bridge）才支持容器名服务发现；Docker Compose 自动创建的网络已内置 DNS 解析。

它解决什么问题 / 适用场景

Docker 容器内 DNS 解析失败是容器化部署中最常见的网络问题之一。典型场景包括：

• 微服务架构：容器 A 需要通过容器名（如 database）访问容器 B，但默认 bridge 网络不支持容器名解析。
• 外部 API 调用：容器内运行的应用（如 Node.js、Python 服务）无法解析外部域名（如 api.github.com），导致 ECONNREFUSED 或 ENOTFOUND 错误。
• 数据库连接：容器化应用连接外部 PostgreSQL、Redis 等数据库时，因 DNS 解析失败而超时。
• CI/CD 环境：在 Docker 内运行测试或构建任务时，无法拉取外部依赖包（如 npm install、pip install）。

本指南适用于所有主流大模型和框架，因为 DNS 解析是底层网络问题，与上层应用无关。

核心配置 / 参数说明

Docker 提供多个层级和粒度的 DNS 配置选项，下表总结了所有关键参数及其作用域：

全局 DNS 配置（daemon.json）

创建或编辑 /etc/docker/daemon.json，添加以下内容：

JSON
{
  "dns": ["8.8.8.8", "8.8.4.4"],
  "dns-search": ["example.com"],
  "dns-opts": ["timeout:2", "attempts:3"]
}

关键注意事项：

• 修改后必须重启 Docker 守护进程：sudo systemctl restart docker
• 重启会影响所有运行中的容器，建议在维护窗口操作
• JSON 格式必须严格正确，缺少逗号会导致 Docker 启动失败

Docker Compose 服务级 DNS 配置

YAML
version: '3.8'
services:
  web:
    image: nginx
    dns:
      - 8.8.8.8
      - 8.8.4.4
    dns_search: example.com
    dns_opt:
      - timeout:2
      - attempts:3
    networks:
      - mynet

networks:
  mynet:
    driver: bridge

常见报错与排查

错误 1：ping: example.com: Temporary failure in name resolution

根因：容器内 DNS 服务器不可达或未配置。常见于 systemd-resolved 环境，Docker 错误继承 127.0.0.53 作为 DNS 服务器。

排查步骤：

BASH
# 1. 检查容器内 DNS 配置
docker exec <container> cat /etc/resolv.conf

# 2. 测试使用公共 DNS 能否解析
docker run --dns=8.8.8.8 busybox nslookup example.com

# 3. 如果有效，持久化到 daemon.json
# 编辑 /etc/docker/daemon.json 添加：
# {"dns": ["8.8.8.8", "8.8.4.4"]}
# 然后重启 Docker
sudo systemctl restart docker

错误 2：curl: (6) Could not resolve host: api.example.com

根因：容器 DNS 配置正确但无法解析特定域名，或容器未在用户自定义网络上。

排查步骤：

BASH
# 1. 确认容器网络模式
docker inspect <container> --format='{{.HostConfig.NetworkMode}}'

# 2. 检查容器内 DNS 配置
docker exec <container> cat /etc/resolv.conf

# 3. 如果是默认 bridge，创建用户自定义网络
docker network create mynet
docker network connect mynet <container>

# 4. 或直接在 docker-compose.yml 中显式设置 DNS

错误 3：ping: bad address 'database'

根因：容器名解析失败，通常因为两个容器不在同一个用户自定义网络上。

解决方案：

BASH
# 1. 创建用户自定义网络
docker network create mynetwork

# 2. 启动所有相关容器时指定该网络
docker run --network mynetwork --name database postgres
docker run --network mynetwork --name web nginx

# 3. 验证容器名解析
docker exec web ping database

错误 4：nslookup: can't resolve 'example.com': Name does not resolve

根因：DNS 服务器本身无法解析，或网络连接问题。

排查步骤：

BASH
# 1. 直接测试公共 DNS 服务器
docker run busybox nslookup example.com 8.8.8.8

# 2. 如果成功，说明是 Docker DNS 配置问题
# 如果失败，检查宿主机网络和防火墙
ping 8.8.8.8

生产环境实践与注意事项

1. 使用内部 DNS 服务器

生产环境强烈建议使用内部 DNS 服务器而非公共 DNS：

• 安全性：公共 DNS 会记录所有查询，可能泄露内部服务域名
• 性能：内部 DNS 响应更快，且能解析私有域名
• 合规性：许多企业要求所有 DNS 查询经过内部基础设施

配置示例（daemon.json）：

JSON
{
  "dns": ["10.0.0.1", "8.8.8.8"]
}

将内部 DNS 放在首位作为主服务器，公共 DNS 作为故障转移。

2. 用户自定义网络最佳实践

BASH
# 创建网络时指定子网和网关
docker network create \
  --driver bridge \
  --subnet 172.20.0.0/16 \
  --gateway 172.20.0.1 \
  mynet

# 启动容器时指定网络
docker run --network mynet --name app myapp

3. 关键限制与避坑

4. 故障排查工具箱

BASH
# 快速诊断脚本
echo "=== 容器 DNS 配置 ==="
docker exec $1 cat /etc/resolv.conf

echo "=== 容器网络模式 ==="
docker inspect $1 --format='{{.HostConfig.NetworkMode}}'

echo "=== 测试 DNS 解析 ==="
docker exec $1 nslookup example.com

echo "=== 测试公共 DNS ==="
docker exec $1 nslookup example.com 8.8.8.8

echo "=== 宿主机 DNS 配置 ==="
cat /etc/resolv.conf

常见问题 FAQ

Q: 为什么我的容器在默认 bridge 网络上无法通过容器名 ping 通另一个容器？

A: Docker 的默认 bridge 网络不支持内嵌 DNS 服务（127.0.0.11）。容器只能通过 IP 地址通信。要使用容器名进行服务发现，必须创建并使用用户自定义网络（如 docker network create mynet），然后使用 --network mynet 启动所有相关容器。Docker Compose 会自动为每个项目创建默认网络并启用此功能。

Q: 我修改了 /etc/docker/daemon.json 并重启了 Docker，但新启动的容器仍然无法解析外部域名，为什么？

A: 可能的原因：1) 检查 daemon.json 的 JSON 格式是否正确（如缺少逗号）。2) 确认 Docker 守护进程已成功重启（sudo systemctl status docker）。3) 检查宿主机自身的 DNS 配置是否正常（cat /etc/resolv.conf），因为 Docker 的 DNS 配置最终依赖于宿主机网络。4) 如果宿主机使用 systemd-resolved，Docker 可能仍然看到 127.0.0.53，需要在 daemon.json 中明确指定外部 DNS 服务器。

Q: 在生产环境中，我应该使用公共 DNS（如 8.8.8.8）还是内部 DNS 服务器？

A: 强烈建议使用内部 DNS 服务器，原因如下：1) 安全性：公共 DNS 会记录所有查询，可能泄露内部服务域名。2) 性能：内部 DNS 服务器通常响应更快，且能解析私有域名（如 my-internal-service.corp）。3) 合规性：许多企业要求所有 DNS 查询必须经过内部基础设施。配置方法：在 daemon.json 或 docker-compose.yml 中设置 dns: ["10.0.0.1", "8.8.8.8"]，将内部 DNS 放在首位作为主服务器，公共 DNS 作为故障转移。

Q: 如何在不重启 Docker 守护进程的情况下临时修复 DNS 问题？

A: 使用 docker run --dns=8.8.8.8 启动新容器进行临时测试。对于已运行的容器，可以：1) 使用 docker exec 手动修改 /etc/resolv.conf（但重启容器后会丢失）。2) 使用 docker network connect 将容器连接到用户自定义网络。3) 在 docker-compose.yml 中为服务添加 dns 配置后重新创建容器（docker-compose up -d --force-recreate <service>）。