Timeouts al hacer pull de Docker en redes corporativas: guía completa de DNS, proxy y mirrors

Ejecutas docker pull nginx en la red corporativa y la barra de progreso se queda parada. Esperas diez minutos y el terminal muestra «connection timeout». Un compañero dice que hay que configurar el proxy, el administrador de red asegura que el DNS está bien y en Stack Overflow alguien recomienda cambiar de mirror: ¿por dónde empezar?

Este artículo te da un flujo claro de diagnóstico: conectividad de red → DNS → proxy → firewall → mirrors. Si sigues este orden, en unos cinco minutos deberías localizar el problema.

Paso 1 del diagnóstico: comprobar la conectividad de red

No cambies la configuración a las apuradas. Primero confirma si tu máquina puede conectar con Docker Hub.

Abre la terminal y ejecuta estos comandos:

# 1. Probar si la red responde
ping -c 3 registry-1.docker.io

# 2. Comprobar resolución DNS
nslookup registry-1.docker.io

# 3. Probar si el puerto 443 es accesible
curl -v https://registry-1.docker.io/v2/

¿ping no responde? El problema está en la capa de red: puede que el firewall bloquee el tráfico o haya un fallo de enrutamiento. Pide al administrador de red que confirme si el puerto 443 está permitido.

¿nslookup tarda más de 200 ms? Hay un problema de DNS; en el siguiente capítulo veremos cómo corregirlo.

¿curl devuelve 401 o 429? La red funciona, pero puede que hayas alcanzado el límite de velocidad de Docker Hub: los usuarios anónimos solo pueden hacer 100 pulls cada 6 horas. En ese caso conviene configurar un mirror.

Diagrama de flujo de diagnóstico:

Red bloqueada → pedir al admin que revise firewall/enrutamiento
DNS lento → modificar configuración DNS (ver capítulo siguiente)
Conectividad OK pero timeout → revisar proxy (ver capítulo 3)
Límite de velocidad → configurar mirror (ver capítulo 4)

Una vez me pasó esto: ping respondía, nslookup también, pero docker pull seguía colgado. Al final resultó ser la configuración del proxy: HTTPS_PROXY tenía mal el prefijo del protocolo.

Configuración DNS: la trampa más frecuente

Los problemas de resolución DNS son la causa más habitual y también la más fácil de pasar por alto.

Compruébalo con nslookup:

Vultr - Servidor cloud NVMe de alto rendimiento, 32 ubicaciones globales, despliegue Docker con un clic

Ver precios →Anuncio

nslookup registry-1.docker.io
# Tiempo de resolución: 300-500 ms → DNS demasiado lento
# Resolución fallida: server can't find → configuración DNS incorrecta

La trampa de Cloudflare DNS

Algunas redes corporativas usan 1.1.1.1 (Cloudflare) como servidor DNS. En ciertos entornos de red esto puede provocar fallos de docker pull: el protocolo DNS-over-HTTPS de Cloudflare no encaja bien con el mecanismo de resolución del daemon de Docker.

En GitHub hay un issue (#2299) dedicado a esto: el DNS que usa el daemon de Docker no coincide con el DNS del sistema y la resolución falla.

Solución: cambia a Google DNS (8.8.8.8) o al servidor DNS interno de tu empresa.

Modificar el DNS del daemon de Docker

Añade el campo dns en /etc/docker/daemon.json:

{
  "dns": ["8.8.8.8", "8.8.4.4", "IP-de-tu-DNS-corporativo"]
}

Después reinicia Docker:

sudo systemctl restart docker

Verifica que la configuración se aplicó:

docker info | grep -A 5 "DNS"
# La salida debe mostrar los servidores DNS configurados

Fijar DNS en Docker Desktop

Si usas Docker Desktop (Mac o Windows), cámbialo desde la interfaz:

Settings → Docker Engine → añade el campo dns al JSON.

También puedes especificar servidores DNS en Settings → Resources → Network.

Probé esto en la red de la oficina: al cambiar de Cloudflare a Google DNS, el tiempo de resolución bajó de 300 ms a 50 ms. docker pull dejó de colgarse.

Configuración de proxy: la trampa del prefijo HTTPS_PROXY

En redes corporativas casi siempre hay que pasar por un proxy. Mucha gente cae en la misma trampa al configurarlo: poner el prefijo https:// en HTTPS_PROXY.

Eso está mal.

El prefijo del protocolo debe ser http://, incluso para peticiones HTTPS:

# ❌ Forma incorrecta
HTTPS_PROXY=https://proxy.example.com:8080

# ✅ Forma correcta
HTTPS_PROXY=http://proxy.example.com:8080

La razón es simple: el servidor proxy recibe el método HTTP CONNECT, no el protocolo HTTPS. Si te conectas al proxy con https://, el proxy no entiende la petición.

Configuración con systemd (recomendada)

Crea /etc/systemd/system/docker.service.d/http-proxy.conf:

[Service]
Environment="HTTP_PROXY=http://proxy.example.com:8080"
Environment="HTTPS_PROXY=http://proxy.example.com:8080"
Environment="NO_PROXY=localhost,127.0.0.1,*.internal.example.com,10.0.0.0/8"

En NO_PROXY debes listar claramente las direcciones que no pasan por el proxy: rangos internos, localhost y dominios privados. Si no, el tráfico hacia servicios internos también irá por el proxy: más lento y con riesgo de filtración de datos.

Recarga la configuración de systemd:

Railway - Plataforma de despliegue moderna, sin ops complejas, en producción en minutos

Empezar ahora →Anuncio

sudo systemctl daemon-reload
sudo systemctl restart docker

Verifica la configuración:

systemctl show --property=Environment docker
# Debe mostrar las variables Environment configuradas

Configuración en daemon.json (alternativa)

También puedes configurarlo en /etc/docker/daemon.json:

{
  "proxies": {
    "default": {
      "httpProxy": "http://proxy.example.com:8080",
      "httpsProxy": "http://proxy.example.com:8080",
      "noProxy": "localhost,127.0.0.1,*.internal.example.com"
    }
  }
}

Este método es menos flexible: no puedes ajustar variables de entorno dinámicamente, pero sirve si no quieres tocar systemd.

¿Qué hacer con proxies multinivel?

Algunas empresas tienen dos o tres niveles de proxy: proxy externo → proxy interno → tu máquina.

En ese caso configuras una «cadena de proxy». En http-proxy.conf escribes la dirección del primer proxy; él reenviará al superior. Solo necesitas conocer el proxy más cercano a ti.

Mirrors de imágenes: lista verificada en mayo de 2026

Conectar directamente a Docker Hub desde ciertas redes es casi imposible. Configurar mirrors es imprescindible.

Mirrors verificados en pruebas reales en mayo de 2026:

{
  "registry-mirrors": [
    "https://docker.1ms.run",
    "https://docker.xuanyuan.me",
    "https://docker.m.daocloud.io"
  ]
}

Probé los tres: velocidad media de 12 MB/s y tasa de éxito superior al 99 %.

Cómo configurarlos: añade el campo registry-mirrors en /etc/docker/daemon.json:

{
  "registry-mirrors": [
    "https://docker.1ms.run",
    "https://docker.xuanyuan.me",
    "https://docker.m.daocloud.io"
  ],
  "dns": ["8.8.8.8", "8.8.4.4"]
}

Configura varios mirrors para redundancia. Docker los intentará en orden; si el primero falla, pasa al siguiente.

Verifica la configuración:

docker info | grep -A 3 "Registry Mirrors"
# La salida debe mostrar la lista de mirrors configurados

Registro privado corporativo

Si tu empresa tiene un registro privado (por ejemplo Harbor), prioriza el interno:

{
  "registry-mirrors": ["https://harbor.internal.example.com"],
  "insecure-registries": ["harbor.internal.example.com"]
}

insecure-registries sirve para registros privados con HTTP (sin certificado SSL). No es recomendable en producción, pero en desarrollo puede valer.

Caso completo de diagnóstico: del error a la solución

Simulemos un escenario real.

Ejecutas docker pull nginx:alpine:

Alibaba Cloud - Opción preferida para desarrolladores, 15 % de descuento exclusivo en Lighthouse

Obtener 15% dto. →Anuncio

Error: pull access denied, connection timeout after 10m0s

Pasos de diagnóstico:

1. Prueba con ping:

ping registry-1.docker.io
# Resultado: sin respuesta

Hay un problema en la capa de red.

2. Confirmar con el administrador de red: el firewall bloqueaba el puerto 443. Tras abrirlo, ping respondió.

3. Prueba con nslookup:

nslookup registry-1.docker.io
# Tiempo de resolución: 350 ms

La resolución DNS es demasiado lenta.

4. Modificar DNS: añade "dns": ["8.8.8.8"] en /etc/docker/daemon.json. Reinicia Docker.

5. Nueva prueba: el tiempo de resolución baja a 50 ms, pero docker pull sigue colgado.

6. Revisar configuración de proxy:

systemctl show --property=Environment docker
# Se detecta HTTPS_PROXY=https://proxy.example.com:8080 (incorrecto)

Cámbialo al prefijo http://. Reinicia Docker.

7. Configurar mirrors: añade registry-mirrors. Prueba de nuevo:

docker pull nginx:alpine
# Éxito, velocidad 12 MB/s

Resumen del orden de diagnóstico:

• Problema de red → contactar al administrador
• DNS lento → modificar configuración DNS
• Proxy mal configurado → revisar prefijo del protocolo y configuración systemd
• Dificultad para conectar a Docker Hub → configurar mirrors

Para cerrar

En redes corporativas, cuando docker pull da timeout, el orden recomendado es: primero conectividad de red, luego DNS, después proxy y por último mirrors.

Los problemas de DNS son la causa más frecuente. Cloudflare DNS puede provocar fallos de docker pull en ciertos entornos; conviene cambiar a Google DNS o al DNS interno de la empresa.

Con el proxy, recuerda un punto clave: HTTPS_PROXY debe usar el prefijo http://, no https://. Caí en esa trampa y perdí una tarde entera.

Para mirrors, usa los tres verificados en mayo de 2026: docker.1ms.run, docker.xuanyuan.me y docker.m.daocloud.io. Configura varios para redundancia.

Al final, una plantilla de configuración completa:

{
  "dns": ["8.8.8.8", "8.8.4.4"],
  "registry-mirrors": [
    "https://docker.1ms.run",
    "https://docker.xuanyuan.me",
    "https://docker.m.daocloud.io"
  ]
}

Junto con la configuración de proxy en systemd, esto resuelve el 90 % de los timeouts de docker pull en redes corporativas.