Docker本地镜像推送异常：localhost:5000超时，127.0.0.1正常

问题场景 #

我按照Docker官方文档部署了本地Registry容器，容器运行状态正常，但在执行镜像推送时遇到了奇怪的差异现象：

• 执行 docker push localhost:5000/nginx 时触发超时错误：

  Get https://localhost:5000/v2/: net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)
  

• 但执行 docker push 127.0.0.1:5000/nginx 却能顺利完成镜像推送。

相关环境信息 #

• /etc/resolve.conf 内容：

  domain bskyb.com
  nameserver 172.20.220.26
  nameserver 172.20.220.25
  nameserver 10.5.212.21
  

• 命令执行输出：

  [mwa51@OSTML0253700 ~] 2018-01-17 16:16:08$ docker push localhost:5000/nginx
  The push refers to repository [localhost:5000/nginx]
  Get https://localhost:5000/v2/: net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)
  
  [mwa51@OSTML0253700 ~] 2018-01-17 16:16:31$ docker push 127.0.0.1:5000/nginx
  The push refers to repository [127.0.0.1:5000/nginx]
  a103d141fc98: Layer already exists
  73e2bd445514: Layer already exists
  2ec5c0a4cb57: Layer already exists
  1.13: digest: sha256:926b086e1234b6ae9a11589c4cece66b267890d24d1da388c96dd8795b2ffcfb size: 948
  a103d141fc98: Layer already exists
  73e2bd445514: Layer already exists
  2ec5c0a4cb57: Layer already exists
  latest: digest: sha256:926b086e1234b6ae9a11589c4cece66b267890d24d1da388c96dd8795b2ffcfb size: 948
  

• docker inspect registry 关键状态片段：

  [
    {
      "State": {
        "Status": "running",
        "Running": true
      },
      "HostConfig": {
        "PortBindings": {
          "5000/tcp": [ { "HostIp": "", "HostPort": "5000" } ]
        }
      },
      "NetworkSettings": {
        "Ports": {
          "5000/tcp": [ { "HostIp": "0.0.0.0", "HostPort": "5000" } ]
        }
      }
    }
  ]
  

• echo $DOCKER_HOST 返回空，说明Docker客户端直接连接本地daemon。

原因分析 #

这种差异的核心是**localhost的域名解析逻辑问题**：

1. 从你的/etc/resolv.conf可以看到，系统默认域名是bskyb.com，且配置了公司内部DNS服务器。
2. 如果你的/etc/hosts文件中缺失localhost到回环地址的映射（即没有127.0.0.1 localhost或::1 localhost条目，或者条目被注释），系统会尝试通过配置的DNS服务器解析localhost。
3. 公司内部DNS服务器通常不会处理localhost这个本地回环域名的解析请求，导致DNS查询超时，最终引发Docker推送请求超时。
4. 而127.0.0.1是明确的IPv4回环地址，系统不需要走DNS查询流程，直接访问本地端口，因此能成功连接Registry。

解决建议 #

1. 修复/etc/hosts文件的本地映射（优先方案） #

这是最直接的解决方案：

• 编辑/etc/hosts文件（需要sudo权限）：

  sudo vi /etc/hosts
  

• 确保文件中包含以下两行（如果缺失则添加，已存在则确认未被注释）：

  127.0.0.1   localhost
  ::1         localhost
  

• 保存文件后，重新执行推送命令：

  docker push localhost:5000/nginx
  

2. 验证解析结果（可选） #

可以通过以下命令验证localhost的解析是否正确：

# 检查ping的目标地址
ping localhost -c 2
# 查看解析结果
nslookup localhost

如果解析结果显示为127.0.0.1或::1，说明映射已生效。

3. 补充Docker不安全注册表配置（可选） #

如果你的Registry是未加密的HTTP服务（本地部署通常默认如此），建议确保Docker daemon允许不安全注册表访问：

• 编辑Docker daemon配置文件（通常是/etc/docker/daemon.json，不存在则创建）：

  {
    "insecure-registries": ["localhost:5000", "127.0.0.1:5000"]
  }
  

• 重启Docker daemon使配置生效：

  sudo systemctl restart docker
  

  （注：这一步主要是避免Docker默认尝试HTTPS访问Registry的警告，你的核心问题是解析，因此优先修复hosts映射）

内容的提问来源于stack exchange，提问作者the_witch_king_of_angmar