Tutoriais de VPS
Docker pull no VPS: corrigir timeout, 429 e x509 (2026)
Identifique daemon, separe rotas de rede, confira quotas Hub e certificados confiáveis e valide o download da imagem alvo.

Se docker pull trava em Pulling fs layer e retorna i/o timeout, TLS handshake timeout, 429 Too Many Requests ou x509: certificate signed by unknown authority, investigue cada tipo. Não cole espelho desconhecido em /etc/docker/daemon.json: pode impedir Docker de iniciar ou enviar pedidos a serviço não confiável.
O guia Ubuntu/Docker Engine separa rede do host, proxy do daemon, limites Hub, certificados e disco. Se baixar funciona e o contêiner não resolve, veja rede de contêineres.
Veja versões, context, serviço e um erro sem alterar:
docker version
docker context ls
sudo systemctl status docker --no-pager
docker pull hello-world:latest
sudo journalctl -u docker -n 100 --no-pager
Se docker version não alcança daemon, corrija serviço/acesso. Se docker context ls seleciona outro host, investigue essa máquina. curl funcionando no computador não comprova dockerd do VPS.
| Erro | Camada provável | Conferir |
|---|---|---|
lookup registry-1.docker.io: no such host | DNS host | getent, resolvectl, DNS provedor |
dial tcp ... i/o timeout, TLS handshake timeout | Saída 443/proxy/rota | curl -4/-6 frente ao daemon |
You have reached your pull rate limit | Quota Hub | Conta, repetições e janela |
Só 429 Too Many Requests | Abuso Hub/intermediário | Resposta e logs |
x509: certificate signed by unknown authority | CA/proxy TLS | Certificado e CA |
manifest unknown, pull access denied | Nome/tag/permissões | Caminho e identidade |
no space left on device | Disco/inodes | Diretórios reais |
Execute no VPS:
getent ahosts registry-1.docker.io
getent ahosts auth.docker.io
curl -4 -sS -o /dev/null -w 'IPv4 HTTP %{http_code}, connect %{time_connect}s, TLS %{time_appconnect}s\n' --connect-timeout 10 https://registry-1.docker.io/v2/
curl -6 -sS -o /dev/null -w 'IPv6 HTTP %{http_code}, connect %{time_connect}s, TLS %{time_appconnect}s\n' --connect-timeout 10 https://registry-1.docker.io/v2/
/v2/ sem token normalmente retorna 401: confirma DNS/TCP/TLS do teste, não autorização. Se curl -4 funciona e curl -6 expira, investigue IPv6 com logs/provedor, sem desativar globalmente. Se ambos falham, confira firewall/saída, proxy, DNS e rota.
curl herda proxy do shell; daemon faz pull. Shell correto pode coexistir com daemon sem proxy; daemon configurado pode funcionar enquanto curl falha. Compare camadas.
Para proxy HTTP confiável, siga guia do daemon em /etc/docker/daemon.json. Faça backup e preserve log-driver/registry-mirrors; combine apenas proxies:
sudo install -d -m 755 /etc/docker
if [ -f /etc/docker/daemon.json ]; then sudo cp -a /etc/docker/daemon.json "/etc/docker/daemon.json.bak.$(date +%F-%H%M%S)"; fi
sudo nano /etc/docker/daemon.json
Para proxy existente proxy.example.com:3128:
{
"proxies": {
"http-proxy": "http://proxy.example.com:3128",
"https-proxy": "http://proxy.example.com:3128",
"no-proxy": "localhost,127.0.0.1,.internal.example.com"
}
}
Use endereço real confiável. https-proxy começando com http:// pode usar CONNECT para HTTPS. Inclua registries em no-proxy só com acesso direto possível. Restrinja arquivos com credenciais, fora de repositórios/logs/capturas.
Valide antes de reinício planejado, que afeta contêineres:
sudo python3 -m json.tool /etc/docker/daemon.json >/dev/null
sudo dockerd --validate --config-file=/etc/docker/daemon.json
sudo systemctl restart docker
sudo systemctl status docker --no-pager
docker pull hello-world:latest
Se dockerd --validate falha, corrija/restaure antes. systemd também admite proxy, mas daemon.json prevalece. ~/.docker/config.json configura principalmente contêineres novos e builds, não pull do dockerd. Veja proxy CLI. Desktop/rootless usam procedimentos próprios.
A página Hub lista 100 pulls anônimos por IPv4 ou IPv6 /64 em seis horas, e 200 Personal autenticados. Planos pagos/uso razoável diferem; confira termos atuais. Saída compartilhada esgota quota.
Se aparece You have reached your pull rate limit, autentique com docker login e retire pulls repetitivos. 429 Too Many Requests curto pode ser abuso, separado da quota. Pare loops, confira diagnóstico Hub e logs; reduza pedidos/concorrência, aguarde ou contate. Espelho não verificado não corrige autorização nem comprova deploy confiável.
Cache Hub próprio/confiável permite combinar registry-mirrors em daemon.json; veja mirrors. Não cobre todo registry: ghcr.io exige verificação separada. Preserve TLS e confira responsável/manutenção.
Em x509, confira timedatectl status e se falha Hub, proxy ou registry privado. Instale a CA verificada, não certificado de servidor renomeado, em /etc/docker/certs.d/<仓库域名:端口>/ca.crt; sem porta para 443. Linux Engine trata .crt como CA. Veja certificados. Proxy TLS também precisa de confiança no host. Não esconda emissor desconhecido com insecure-registries.
Para no space left on device, encontre armazenamento real sem presumir /var/lib/docker. Engine recente pode usar containerd:
docker info --format 'Docker Root Dir: {{.DockerRootDir}}'
df -h / /var/lib/docker /var/lib/containerd 2>/dev/null || true
df -i /
docker system df
Identifique disco/diretório antes de ampliar ou excluir imagens confirmadas sem uso. Evite docker system prune -a --volumes em volumes de produção. Depois teste docker pull <镜像:固定版本>. Fixe versão/digest e preserve rollback.
docker pullfunciona edocker image inspect <镜像:版本>mostra imagem.sudo journalctl -u docker -n 50 --no-pagersem erros recorrentes de proxy/TLS/limite.docker infomostra mirror, Docker Root Dir e ambiente esperados; mudanças gerenciadas.- Contêineres saudáveis e
docker compose pull/atualização repetível.
curl com 401 não basta: a imagem alvo precisa ser baixada no daemon correto. Para DNS/bridge depois, veja o guia.
Referências: proxy daemon, limites Hub, mirrors, certificados.