Tutoriais de VPS
Docker não conecta ao host: serviços, host-gateway e endereços de escuta
Escolha serviço ou endereço do host, configure host-gateway e confira escuta e firewall, diferenciando publicação de portas e conexões de saída.

curl http://127.0.0.1:8000 funciona no host, mas a aplicação no Docker recebe Connection refused. Confira o destino: localhost em um contêiner bridge comum é o próprio contêiner, não o VPS.
Para outro contêiner, normalmente use seu nome de serviço em rede compartilhada. Se o serviço roda diretamente no host, confira host.docker.internal e a escuta. O guia trata de Docker Engine Linux com bridge; Desktop, host e rootless exigem verificações próprias.
| Conexão | Endereço preferencial | Erro comum |
|---|---|---|
| app → backend na mesma rede | http://backend:8000 | localhost:8000 |
| app → API diretamente no VPS | Endereço acessível do host ou alias configurado | 127.0.0.1 do contêiner |
| VPS → porta publicada | Endereço vinculado e porta publicada | Confundir porta interna e externa |
| Navegador → serviço VPS | Domínio público ou entrada autorizada | Nome interno Docker |
Com context remoto, o host é onde está o daemon, não o notebook. Confira docker context show antes de alterar escuta e firewall.
Compose networking oferece descoberta por nome na rede comum. Use a porta interna e evite IPs variáveis de contêiner.
A demonstração não publica portas. Python serve para verificar conexão, não como modelo de produção:
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 entram na rede padrão do projeto. backend escuta 8000 e app usa backend:8000, sem adicionar ports.
Execute em diretório de teste separado e confira pelo 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)'
Deve mostrar status HTTP quando a demonstração funciona. Não sobrescreva produção nem use o servidor temporário de arquivos como API. Projetos diferentes têm redes padrão diferentes. Para conectá-los, associe explicitamente uma rede compartilhada adequada e evite aliases conflitantes.
Se a API está diretamente no VPS, adicione alias ao app real. É outra demonstração independente:
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"
Não inicia API no host: seu serviço precisa fornecer 8000. extra_hosts só mapeia nome para endereço. Não cria serviço, modifica escuta ou libera firewall.
A referência do daemon explica host-gateway: o padrão depende do bridge padrão e pode ser configurado. Não fixe 172.17.0.1 em todo VPS nem suponha que equivale ao gateway de uma rede personalizada.
O engine precisa suportar esse valor. Compose analisado não garante criação no engine. Confira plataforma e versão se falhar; host-gateway não é DNS público comum.
No projeto original, valide e atualize app:
docker compose config --quiet
docker compose up -d --no-deps app
Preserve serviço, -f, arquivo de ambiente e nome do projeto. Confira montagens e backup; não apague volumes. restart pode não aplicar configuração nova; veja mudanças Compose sem efeito.
No host:
sudo ss -lntp '( sport = :8000 )'
ip -brief address
Um serviço limitado a 127.0.0.1:8000 normalmente não escuta nos outros endereços alcançados pelo bridge. Um alias não encaminha automaticamente loopback para o bridge.
Use endereço acessível dentro do limite de acesso pretendido e permita só origens necessárias. Se só aceita loopback, utilize proxy controlado ou outra implantação. Não exponha banco em todas as interfaces e portas públicas para testar.
A demonstração Python separa resolução 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)'
Se a imagem real não tem Python, use ferramenta instalada. Comando ausente não indica falha de rede. São verificações HTTP; banco precisa do cliente do protocolo correspondente.
| Resultado | Investigue |
|---|---|
| Nome não resolve | Alias ausente, nome errado ou outro ambiente |
| Connection refused | Sem escuta ou rejeição ativa |
| Timeout | Rotas, filtragem e resposta do serviço |
| HTTP 401 ou rejeição do banco | Servidor respondeu; confira credenciais e aplicação |
Confira escuta, rede Docker e firewall juntos. Porta pública funcionando não comprova acesso a partir do bridge.
Para acessar backend pelo VPS, integre abaixo de backend:
services:
backend:
ports:
- "127.0.0.1:18000:8000"
Mapeia loopback do host em 18000 para contêiner 8000; veja publicação de portas. Integre à imagem backend; o trecho sozinho não é um serviço completo.
app na mesma rede continua usando backend:8000, não backend:18000. O host usa seu endereço publicado. Outro bridge não converte a vinculação loopback 18000 em uma entrada equivalente substituindo host-gateway.
app não precisa de ports para alcançar serviço do host. Separe publicação de entrada e acesso de saída.
Docker Desktop fornece host.docker.internal em sua rede host/VM. Não presuma o mesmo no Linux nem deduza sua topologia porque um Mac não tem docker0.
network_mode: host compartilha o namespace de rede do host, segundo o driver host, sem IP separado do contêiner. Muda isolamento e conflitos de portas; não é remendo universal de bridge e não mantém as regras originais de publicação.
Se Nginx Proxy Manager não alcança programa do host, confira destino, escuta e rede e veja seu guia.
Confirme que a requisição sai do contêiner pretendido para host e porta esperados e teste a operação real. Análise, resolução, TCP e autenticação são etapas distintas.
O artigo original analisou três configurações com Docker Compose 2.17.3: rede compartilhada, host-gateway e rede com publicação. A configuração combinada publicou 127.0.0.1:18000 para 8000; app manteve backend:8000. O daemon local não estava ativo. Análise estática não comprova tráfego bridge, host-gateway ou conexão de produção ao banco.