Tutoriales de VPS
Docker pull en VPS: resolver timeout, 429 y x509 (2026)
Identifica daemon, separa rutas de red, revisa cuotas Hub y certificados fiables y valida la descarga de la imagen objetivo.

Si docker pull se atasca en Pulling fs layer y devuelve i/o timeout, TLS handshake timeout, 429 Too Many Requests o x509: certificate signed by unknown authority, diagnostica cada tipo. No pegues un espejo desconocido en /etc/docker/daemon.json: puede impedir iniciar Docker o enviar peticiones a un tercero no fiable.
La guía Ubuntu/Docker Engine distingue red del host, proxy del daemon, límites Hub, certificados y disco. Si descargar funciona y el contenedor no resuelve, consulta red de contenedores.
Consulta versiones, context, servicio y un fallo sin cambios:
docker version
docker context ls
sudo systemctl status docker --no-pager
docker pull hello-world:latest
sudo journalctl -u docker -n 100 --no-pager
Si docker version no alcanza daemon, repara servicio/acceso. Si docker context ls elige otro host, investiga esa máquina. curl funcionando en tu ordenador no prueba dockerd del VPS.
| Error | Capa probable | Revisar |
|---|---|---|
lookup registry-1.docker.io: no such host | DNS host | getent, resolvectl, DNS proveedor |
dial tcp ... i/o timeout, TLS handshake timeout | Salida 443/proxy/ruta | curl -4/-6 frente al daemon |
You have reached your pull rate limit | Cuota Hub | Cuenta, repetición y ventana |
Solo 429 Too Many Requests | Abuso Hub/intermediario | Respuesta completa y logs |
x509: certificate signed by unknown authority | CA/proxy TLS | Certificado y CA |
manifest unknown, pull access denied | Nombre/tag/permisos | Ruta e identidad |
no space left on device | Disco/inodos | Directorios reales |
Ejecuta en el 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/ sin token suele devolver 401: confirma DNS/TCP/TLS de esa prueba, no permiso del paquete. Si curl -4 funciona y curl -6 agota tiempo, investiga IPv6 con logs/proveedor, sin desactivarlo globalmente. Si ambos fallan, revisa firewall/salida, proxy, DNS y ruta.
curl hereda proxy del shell; el daemon descarga. Shell correcto puede coexistir con daemon sin proxy; daemon configurado puede funcionar mientras curl falla. Compara capas.
Para proxy HTTP fiable, sigue guía del daemon en /etc/docker/daemon.json. Respalda y conserva log-driver/registry-mirrors; combina solo 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"
}
}
Usa dirección real fiable. https-proxy comenzando con http:// puede usar CONNECT para HTTPS. Añade registries a no-proxy solo si admiten acceso directo. Restringe archivos con credenciales, fuera de repositorios/capturas/logs.
Valida antes de reinicio planificado, que afecta contenedores:
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
Si falla dockerd --validate, repara/restaura antes. systemd también admite proxy, pero prevalece daemon.json. ~/.docker/config.json configura principalmente contenedores nuevos y builds, no la descarga de dockerd. Consulta proxy CLI. Desktop/rootless necesitan procesos propios.
La página Hub lista 100 pulls anónimos por IPv4 o IPv6 /64 en seis horas, y 200 Personal autenticados. Planes pagos y uso razonable difieren; comprueba condiciones actuales. Salidas compartidas agotan cuota.
Si indica You have reached your pull rate limit, autentica con docker login y elimina pulls repetidos. 429 Too Many Requests breve puede ser abuso, distinto de la cuota. Detén bucles, revisa diagnóstico Hub y logs; reduce concurrencia/peticiones, espera o contacta. Un espejo no verificado no repara permisos ni garantiza despliegue.
Un caché Hub propio/fiable permite combinar registry-mirrors en daemon.json; consulta mirrors. No cubre todos los registries: ghcr.io se revisa aparte. Conserva TLS y verifica responsable/mantenimiento.
Ante x509, comprueba timedatectl status y si falla Hub, proxy o registry privado. Instala la CA verificada, no un certificado de servidor renombrado, en /etc/docker/certs.d/<仓库域名:端口>/ca.crt; sin puerto para 443. Linux Engine interpreta .crt como CA. Consulta certificados. Un proxy TLS también requiere confianza del host. No ocultes emisor desconocido con insecure-registries.
Para no space left on device, encuentra almacenamiento real, sin asumir /var/lib/docker. Engine reciente puede 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
Identifica disco/directorio antes de ampliar o eliminar imágenes sin uso. No uses docker system prune -a --volumes sobre volúmenes productivos. Tras reparar, prueba docker pull <镜像:固定版本>. Fija versión/digest y conserva reversión.
docker pullfunciona ydocker image inspect <镜像:版本>muestra imagen.sudo journalctl -u docker -n 50 --no-pagersin errores repetidos de proxy/TLS/límite.docker infomuestra mirror, Docker Root Dir y entorno previstos; cambios gestionados.- Contenedores sanos y
docker compose pull/actualización repetible.
curl con 401 no basta: descarga la imagen objetivo desde el daemon correcto. Para DNS/bridge posteriores, consulta la guía.
Referencias: proxy daemon, límites Hub, mirrors, certificados.