Timeout no docker pull em rede corporativa: DNS, proxy e mirrors

Você executa docker pull nginx dentro da rede corporativa, e a barra de progresso simplesmente trava. Dez minutos depois, o terminal mostra “connection timeout”. Um colega fala para configurar proxy, o administrador de rede diz que o DNS está normal, e alguém no Stack Overflow recomenda trocar o mirror. O que você verifica primeiro?

Este artigo traz um fluxo claro de diagnóstico: conectividade de rede -> configuração de DNS -> configuração de proxy -> firewall -> mirror. Seguindo essa ordem, normalmente dá para localizar o problema em cerca de cinco minutos.

Primeiro passo do diagnóstico: verifique a conectividade de rede

Não comece alterando arquivos de configuração. Primeiro confirme se a sua máquina consegue alcançar o Docker Hub.

Abra o terminal e rode estes comandos:

# 1. Testar se a rede responde
ping -c 3 registry-1.docker.io

# 2. Verificar a resolução DNS
nslookup registry-1.docker.io

# 3. Testar se a porta 443 está acessível
curl -v https://registry-1.docker.io/v2/

O ping não responde? Então o problema está na camada de rede. Pode ser bloqueio de firewall ou rota mal configurada. Primeiro peça ao administrador de rede para confirmar se a porta 443 está liberada.

O nslookup demora mais de 200ms? Há problema na configuração de DNS; a próxima seção mostra como ajustar.

O curl retorna 401 ou 429? A rede está funcionando, mas talvez você tenha batido no rate limit do Docker Hub: usuários anônimos só podem fazer 100 pulls a cada 6 horas. Nesse caso, vale considerar mirrors.

Fluxo de diagnóstico:

Rede sem acesso -> pedir ao administrador para checar firewall/rotas
DNS lento -> ajustar a configuração de DNS (veja a próxima seção)
Conecta, mas dá timeout -> verificar a configuração de proxy (veja a terceira seção)
Rate limit -> configurar mirrors de imagem (veja a quarta seção)

Já passei por um caso assim: o ping respondia, o nslookup estava normal, mas o docker pull continuava travando. No fim, era a configuração de proxy: o HTTPS_PROXY estava com o prefixo de protocolo errado.

Configuração de DNS: o ponto mais fácil de errar

Problemas de resolução DNS são a causa mais comum e também a mais fácil de ignorar.

Rode um nslookup:

Vultr - Servidor cloud NVMe de alto desempenho, 32 locais globais, deploy Docker com um clique

Ver preços →Anúncio

nslookup registry-1.docker.io
# Tempo de resolução: 300ms-500ms -> DNS lento demais
# Falha de resolução: server can't find -> configuração de DNS errada

A armadilha do Cloudflare DNS

Algumas redes corporativas usam 1.1.1.1, o DNS da Cloudflare. Em certos ambientes, esse DNS pode fazer o Docker pull falhar: o protocolo DNS-over-HTTPS da Cloudflare e o mecanismo de resolução DNS do Docker daemon podem esbarrar em problemas de compatibilidade.

Há um issue no GitHub (#2299) dedicado a esse problema: o DNS usado pelo Docker daemon fica diferente do DNS do sistema, e a resolução falha.

Solução: troque para Google DNS (8.8.8.8) ou para o servidor DNS interno da sua empresa.

Ajustar o DNS do Docker daemon

Adicione o campo dns em /etc/docker/daemon.json:

{
  "dns": ["8.8.8.8", "8.8.4.4", "IP_DO_DNS_CORPORATIVO"]
}

Depois da alteração, reinicie o Docker:

sudo systemctl restart docker

Valide se a configuração entrou em vigor:

docker info | grep -A 5 "DNS"
# A saída deve mostrar os servidores DNS que você configurou

Fixar DNS no Docker Desktop

Se você usa Docker Desktop no Mac ou no Windows, faça pela tela de configurações:

Settings -> Docker Engine -> adicione o campo dns à configuração JSON.

Também dá para definir servidores DNS diretamente em Settings -> Resources -> Network.

Em um teste anterior na rede da empresa, trocar o DNS de Cloudflare para Google reduziu o tempo de resolução de 300ms para 50ms. Depois disso, o docker pull parou de travar.

Configuração de proxy: a armadilha no prefixo de HTTPS_PROXY

Redes corporativas geralmente precisam passar por proxy. Muita gente tropeça no mesmo detalhe: configura HTTPS_PROXY com o prefixo https://.

Isso está errado.

O prefixo do proxy precisa ser http://, mesmo quando a requisição final é HTTPS:

# Escrita errada
HTTPS_PROXY=https://proxy.example.com:8080

# Escrita correta
HTTPS_PROXY=http://proxy.example.com:8080

O motivo é simples: o servidor proxy recebe o método HTTP CONNECT, não o protocolo HTTPS. Se você tenta se conectar ao proxy usando https://, o proxy simplesmente não entende.

Configuração via systemd (recomendada)

Crie /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"

No NO_PROXY, escreva com cuidado os destinos que não devem passar pelo proxy: endereços internos, localhost e domínios privados. Caso contrário, até o acesso a serviços internos da empresa passa pelo proxy. Além de ficar lento, isso pode vazar dados.

Recarregue a configuração do systemd:

KiloClaw - OpenClaw gerenciado para empresas: orquestração de agentes IA e roteamento inteligente

Começar →Anúncio

sudo systemctl daemon-reload
sudo systemctl restart docker

Valide a configuração:

systemctl show --property=Environment docker
# Você deve ver as variáveis Environment configuradas

Configuração via daemon.json (alternativa)

Também dá para configurar em /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"
    }
  }
}

Esse método é menos flexível que o systemd: você não consegue ajustar dinamicamente por variáveis de ambiente. Mas serve bem quando você não quer lidar com systemd.

E quando há vários níveis de proxy?

Algumas empresas têm dois ou até três níveis de proxy: proxy externo -> proxy interno -> sua máquina.

Nesse caso, configure a “cadeia de proxy”. No http-proxy.conf, escreva o endereço do primeiro proxy; ele encaminha automaticamente para o proxy superior. Você só precisa saber o endereço do proxy mais próximo da sua máquina.

Mirrors de imagem: lista disponível em maio de 2026

Conectar diretamente ao Docker Hub a partir de redes na China continental é, na prática, quase impossível. Mirrors de imagem viram item obrigatório.

Mirrors testados e disponíveis em maio de 2026:

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

Testei as três fontes: velocidade média de 12MB/s e taxa de sucesso acima de 99%.

Como configurar: adicione o campo registry-mirrors em /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"]
}

Configure mais de uma fonte para tolerância a falhas. O Docker tenta em sequência; se a primeira falhar, passa automaticamente para a próxima.

Valide a configuração:

docker info | grep -A 3 "Registry Mirrors"
# A saída deve mostrar a lista de mirrors configurados

Registry privado da empresa

Se a sua empresa tem um registry privado, como Harbor, prefira o interno:

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

insecure-registries é usado para registries privados em HTTP, sem certificado SSL. Não recomendo isso em produção, mas em ambiente de desenvolvimento pode quebrar o galho.

Caso completo de diagnóstico: do erro à solução

Vamos simular um cenário real.

Você executa docker pull nginx:alpine:

Alibaba Cloud - Escolha dos desenvolvedores, 15% de desconto exclusivo em Lighthouse

Ganhar 15% off →Anúncio

Error: pull access denied, connection timeout after 10m0s

Passos de diagnóstico:

1. Teste com ping:

ping registry-1.docker.io
# Resultado: sem resposta

Há um problema na camada de rede.

2. Confirmar com o administrador de rede: o firewall estava bloqueando a porta 443. Depois da liberação, o ping passou a responder.

3. Teste com nslookup:

nslookup registry-1.docker.io
# Tempo de resolução: 350ms

A resolução DNS está lenta demais.

4. Ajustar DNS: adicione "dns": ["8.8.8.8"] em /etc/docker/daemon.json. Reinicie o Docker.

5. Testar de novo: o tempo de resolução cai para 50ms, mas o docker pull ainda trava.

6. Verificar proxy:

systemctl show --property=Environment docker
# Encontrado HTTPS_PROXY=https://proxy.example.com:8080 (errado)

Troque para o prefixo http://. Reinicie o Docker.

7. Configurar mirrors: adicione registry-mirrors. Teste novamente:

docker pull nginx:alpine
# Sucesso, velocidade de 12MB/s

Resumo da ordem de diagnóstico:

• Problema na camada de rede -> falar com o administrador de rede
• DNS lento -> ajustar a configuração de DNS
• Proxy configurado errado -> verificar o prefixo do protocolo e a configuração systemd
• Conexão direta ao Docker Hub difícil -> configurar mirrors

Fechando

Quando o Docker pull dá timeout em rede corporativa, a ordem de diagnóstico recomendada é: primeiro conectividade de rede, depois DNS, em seguida proxy e, por fim, mirrors de imagem.

DNS é a causa mais comum. Cloudflare DNS pode fazer o Docker pull falhar em alguns ambientes; troque para Google DNS ou para o DNS interno da empresa.

Na configuração de proxy, grave um ponto: HTTPS_PROXY precisa usar o prefixo http://, não https://. Eu já caí nessa e perdi uma tarde.

Para mirrors, use as três fontes testadas em maio de 2026: docker.1ms.run, docker.xuanyuan.me e docker.m.daocloud.io. Configure mais de uma para tolerância a falhas.

Um template completo de configuração:

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

Com isso e uma configuração de proxy via systemd, você resolve a maior parte dos timeouts de Docker pull em redes corporativas.