Tutoriales de VPS
Docker no conecta al host: servicios, host-gateway y direcciones de escucha
Elige nombre de servicio o dirección del host, configura host-gateway y revisa escucha y firewall, distinguiendo publicación de puertos y conexiones salientes.

curl http://127.0.0.1:8000 funciona en el host, pero la aplicación en Docker recibe Connection refused. Comprueba el destino: localhost de un contenedor bridge normal es ese contenedor, no el VPS.
Para otro contenedor, utiliza normalmente su nombre de servicio en una red compartida. Si el servicio se ejecuta realmente en el host, revisa host.docker.internal y su dirección de escucha. La guía trata de Docker Engine Linux con bridge; Desktop, host y rootless requieren comprobaciones propias.
| Conexión | Dirección preferente | Error habitual |
|---|---|---|
| app → backend en la misma red | http://backend:8000 | localhost:8000 |
| app → API directamente en VPS | Dirección del host accesible o alias configurado | 127.0.0.1 del contenedor |
| VPS → puerto publicado | Dirección enlazada y puerto publicado | Confundir puerto interno y externo |
| Navegador → servicio VPS | Dominio público o entrada autorizada | Nombre interno Docker |
Con Docker context remoto, el host es donde está el daemon, no el portátil. Revisa docker context show antes de editar escucha y firewall.
Compose networking permite descubrir servicios por nombre en una red común. Usa su puerto interno y evita IPs de contenedor cambiantes.
La demostración no publica puertos. Python es para comprobar conexión, no una plantilla de producción:
services:
app:
image: python:3.14-alpine
command: ["python", "-c", "import time; time.sleep(3600)"]
environment:
BACKEND_URL: "http://backend:8000"
backend:
image: python:3.14-alpine
command: ["python", "-m", "http.server", "8000", "--bind", "0.0.0.0"]
Ambos servicios entran en la red predeterminada del proyecto. backend escucha en 8000 y app utiliza backend:8000, sin añadir ports.
Ejecuta en un directorio de prueba separado y comprueba desde app:
docker compose up -d
docker compose exec app python -c 'import os,urllib.request; print(urllib.request.urlopen(os.environ["BACKEND_URL"], timeout=5).status)'
Debería mostrar estado HTTP cuando la demo funciona. No sobrescribas producción ni uses el servidor temporal de archivos como API. Proyectos diferentes tienen redes predeterminadas distintas. Para comunicar proyectos, incorpora explícitamente una red compartida adecuada y evita alias conflictivos.
Si la API está directamente en el VPS, añade alias al servicio app real. Esta es otra demostración independiente:
services:
app:
image: python:3.14-alpine
command: ["python", "-c", "import time; time.sleep(3600)"]
extra_hosts:
- "host.docker.internal:host-gateway"
environment:
BACKEND_URL: "http://host.docker.internal:8000"
No inicia una API en el host: tu servicio debe proporcionar 8000. extra_hosts solo mapea nombre a dirección; no crea servicio, cambia escucha ni abre firewall.
La referencia del daemon explica host-gateway: el valor predeterminado depende del bridge predeterminado y puede configurarse. No fijes 172.17.0.1 para todos los VPS ni supongas que equivale siempre al gateway de una red personalizada.
El engine debe admitirlo. Compose analizado correctamente no garantiza que el engine cree ese mapeo. Comprueba plataforma y versión si falla; host-gateway no es DNS público ordinario.
En el proyecto original, valida y actualiza app:
docker compose config --quiet
docker compose up -d --no-deps app
Conserva servicio, -f, archivo de entorno y nombre de proyecto. Comprueba datos montados y respaldo; no borres volúmenes. restart puede no aplicar la configuración; consulta Compose sin cambios efectivos.
En el host:
sudo ss -lntp '( sport = :8000 )'
ip -brief address
Un servicio limitado a 127.0.0.1:8000 normalmente no escucha en las otras direcciones accesibles desde bridge. Un alias no redirige automáticamente loopback al bridge.
Usa una dirección alcanzable dentro de tu límite de acceso y permite solo fuentes necesarias. Si solo admite loopback, utiliza un proxy controlado u otra disposición. No expongas la base de datos en todas las interfaces y puertos públicos para probar.
La demo Python separa resolución de HTTP:
docker compose exec app python -c 'import socket; print(socket.gethostbyname("host.docker.internal"))'
docker compose exec app python -c 'import os,urllib.request; print(urllib.request.urlopen(os.environ["BACKEND_URL"], timeout=5).status)'
Si la imagen real carece de Python, utiliza otra herramienta instalada. Un comando ausente no es un fallo de red. Son pruebas HTTP; una base de datos requiere su cliente de protocolo.
| Resultado | Investiga |
|---|---|
| No resuelve nombre | Alias ausente, nombre incorrecto o entorno distinto |
| Connection refused | No hay escucha o rechazo activo |
| Timeout | Rutas, filtrado y respuesta del servicio |
| HTTP 401 o rechazo de autenticación de la base de datos | El servidor respondió; revisa credenciales y aplicación |
Revisa escucha, red Docker y firewall juntos. Que un puerto público funcione no demuestra permiso desde bridge.
Para acceder al backend desde el VPS, integra bajo backend:
services:
backend:
ports:
- "127.0.0.1:18000:8000"
Mapea loopback del host en 18000 a contenedor 8000; consulta publicación de puertos. Integra con la imagen backend; el fragmento solo no es un servicio completo.
app en la misma red sigue usando backend:8000, no backend:18000. El host usa su dirección publicada. Otro bridge no convierte el enlace loopback 18000 en una entrada equivalente sustituyendo host-gateway.
app no necesita ports para conectar a un servicio del host. Separa publicación entrante de acceso saliente.
Docker Desktop proporciona host.docker.internal en su red host/VM. No supongas igual comportamiento en Linux ni deduzcas su topología porque un Mac no tiene docker0.
network_mode: host comparte namespace de red del host, según el driver host, sin IP separada del contenedor. Cambia aislamiento y conflictos de puertos. No es un parche universal de bridge y no conserva las reglas originales de publicación.
Para Nginx Proxy Manager que no alcanza un programa del host, comprueba destino, escucha y red, y consulta su guía de configuración.
Confirma origen dentro del contenedor, host y puerto esperados y operación real. Análisis, resolución, TCP y autenticación son etapas diferentes.
El artículo original analizó tres configuraciones con Docker Compose 2.17.3: red compartida, host-gateway y red con publicación. La configuración combinada publicó 127.0.0.1:18000 hacia 8000; app mantuvo backend:8000. El daemon local no estaba activo. El análisis estático no demuestra tráfico bridge, host-gateway ni conexión de producción a una base de datos.