Skip to content
Sistema

O endereço IP do Docker está inacessível a partir do host

Avatar illustré de Julien Macé 7 min read
Chemin réseau d’un hôte Linux vers un service de conteneur bloqué au niveau de son écoute
Illustration conceptuelle générée : diagnostic de l’écoute d’un service Docker. Ce visuel ne représente pas un test réel.

Você já tem o endereço IP do contêiner e a porta do serviço, mas a conexão a partir do servidor Linux falha. Antes de mexer no firewall ou reiniciar o Docker, verifique onde o caminho para: serviço, namespace de rede, bridge, rota ou filtragem local.

O procedimento abaixo se aplica ao Docker Engine rootful instalado diretamente no mesmo host Linux a partir do qual você executa os comandos. Docker Desktop, modo rootless e um daemon remoto não seguem exatamente esse caminho.

Chemin réseau d’un hôte Linux vers un service de conteneur bloqué au niveau de son écoute
Ilustração conceitual gerada: o bridge está presente, mas ainda é preciso verificar se o serviço está escutando. Ela não representa um teste real.

Se você ainda não identificou o endereço, comece pelo guia para identificar o IP e a rede do contêiner. Aqui, partimos de um IP já conhecido. Além disso, um endereço de bridge não é necessariamente acessível a partir do computador físico com Docker Desktop ou a partir do host externo ao namespace RootlessKit.

Confirmar que você está no host do mecanismo

Um cliente Docker pode controlar um daemon remoto. Nesse caso, o IP interno do contêiner pertence à máquina do daemon, não necessariamente à máquina em que você digita curl.

docker context show
docker version --format '{{.Server.Version}}'
docker info --format '{{json .SecurityOptions}}'

Esses comandos mostram o contexto atual, a versão do servidor e as opções de segurança. Eles não revelam necessariamente todo o destino efetivo quando há variáveis de ambiente do Docker envolvidas. Confirme que o daemon é realmente local sem copiar para um chamado as variáveis ou URLs de endpoint que possam conter credenciais. Não troque de contexto para “experimentar”: você pode acabar inspecionando outro mecanismo.

O Docker Desktop executa o Engine em uma máquina virtual Linux leve. No Linux Desktop, o endereço de um bridge nessa VM não é automaticamente um destino acessível a partir do sistema host. Nesse caso, examine as portas já publicadas com docker port e teste o destino publicado existente, em vez de procurar docker0 no computador físico.

No modo rootless, o IP exibido por docker inspect está no namespace de rede do RootlessKit. A documentação do Docker informa que esse endereço não é diretamente acessível a partir do host externo a esse namespace. Não tente contornar esse isolamento com as etapas para Engine rootful abaixo.

Verificar o estado e a escuta do serviço

Substitua CONTENEUR pelo nome ou identificador já conhecido. O comando a seguir não altera nada:

docker inspect --type=container --format '{{.Name}} etat={{.State.Status}} running={{.State.Running}} pid={{.State.Pid}} mode={{.HostConfig.NetworkMode}}' CONTENEUR

Se o contêiner estiver parado ou reiniciando, a rota ainda não será útil. Consulte um intervalo limitado dos logs:

docker logs --timestamps --since 10m --tail 50 CONTENEUR

Às vezes, os logs não contêm nada, especialmente se o driver não os expõe ou se o programa não escreve em stdout/stderr. Também podem conter dados confidenciais. Para um serviço gerenciado pelo Compose, o guia específico explica como ler os logs do serviço Docker Compose.

Um contêiner com estado running não garante que a aplicação esteja escutando. No Engine rootful local, obtenha o PID e verifique-o antes de entrar no namespace de rede do contêiner:

PID=$(docker inspect --type=container --format '{{.State.Pid}}' CONTENEUR)
printf 'PID=%s\n' "$PID"

Prossiga somente se o resultado for um número inteiro estritamente maior que zero e se o contêiner ainda estiver em execução. Se o contêiner tiver sido recriado nesse meio-tempo, consulte novamente o estado e o PID. Nunca use nsenter com PID 0.

sudo nsenter --target "$PID" --net ss -lnt

nsenter --net executa ss no namespace de rede do processo, sem abrir um shell nem alterar a configuração. O PID é o do processo principal do contêiner; seu namespace de rede dá acesso à visão dos sockets desse contêiner. O ss executado simplesmente no host mostra os sockets do host, não os desse namespace.

Procure a porta TCP interna que você já conhece. Uma escuta em 127.0.0.1:PORT ou [::1]:PORT está limitada ao loopback do contêiner. Uma escuta no endereço do contêiner ou em 0.0.0.0:PORT pode aceitar uma conexão para esse endereço IPv4. [::]:PORT não prova, por si só, que a aplicação também aceita IPv4: isso depende da configuração dual-stack. A ausência de um socket na porta esperada aponta para o processo, a porta ou o protocolo. Esta verificação se aplica a TCP, não a UDP. Se ss não estiver disponível ou se o acesso for negado, registre essa limitação; não instale nada no contêiner durante o diagnóstico.

Testar separadamente o IP interno e a porta publicada

Use uma URL de leitura conhecida, em um endpoint que não acione nenhuma ação. Não teste um webhook nem uma URL de comando. A solicitação abaixo ignora o proxy apenas para esta chamada e usa tempos limite curtos:

curl --noproxy '*' --connect-timeout 3 --max-time 5 --silent --show-error --output /dev/null --write-out 'HTTP %{http_code}\n' 'http://IP_CONTENEUR:PORT_INTERNE/ENDPOINT_LECTURE'

Substitua os valores pelo IP e pela porta já identificados e, em seguida, por um caminho de leitura realmente documentado para o seu serviço. Não use 0.0.0.0 nem :: como endereço de destino. Para HTTPS, mantenha o nome de host necessário para o certificado; -k não corrige um problema de rede.

Um código HTTP, inclusive 401, 403 ou 404, indica que um serviço ou intermediário respondeu. 000 é o valor do curl quando ele não recebeu um código HTTP; não é um status do servidor. Uma recusa imediata pode corresponder à ausência de uma escuta ou a uma rejeição ativa. Um tempo limite excedido pode ser causado por uma rota, uma filtragem ou um serviço que não responde. Nenhum desses resultados, isoladamente, identifica a causa.

Se já houver uma publicação, compare-a separadamente:

docker port CONTENEUR
curl --noproxy '*' --connect-timeout 3 --max-time 5 --silent --show-error --output /dev/null --write-out 'HTTP %{http_code}\n' 'http://ADRESSE_HOTE:PORT_PUBLIE/ENDPOINT_LECTURE'

Use um endereço real do host e a porta publicada exibida. Essa comparação não exige criar uma publicação. Uma resposta pela porta publicada e uma falha no IP interno não provam automaticamente qual regra está em ação; apenas reduzem o escopo a investigar.

Analisar o bridge e a rota escolhida

Identifique a rede à qual o contêiner está conectado e consulte sua configuração:

docker network inspect --format 'nom={{.Name}} pilote={{.Driver}} interne={{.Internal}} ipam={{json .IPAM.Config}} options={{json .Options}}' RESEAU
ip -br link
ip -br addr
ip route get IP_CONTENEUR

O procedimento destina-se a uma rede cujo driver seja bridge. O bridge personalizado não é necessariamente docker0; identifique a interface realmente presente e confira os endereços e a rota. Não invente um nome de interface com base no identificador da rede.

ip route get indica a decisão de roteamento local, incluindo a interface e o endereço de origem escolhidos. Uma saída por uma VPN ou por uma interface inesperada é uma informação a documentar, não uma instrução para alterar as rotas. Se necessário, você pode complementar a observação com ip rule show e ip route show table all. Para entender a saída desse comando, consulte o guia que explica como verificar a rota realmente escolhida pelo Linux.

Uma rota que aponta para o bridge não prova que o serviço aceita a conexão. Um estado de vizinhança incompleto pode ajudar a localizar o problema, mas é possível que a tabela esteja vazia quando não houve tráfego recente. O fluxo criado localmente por um programa no host não passa automaticamente pela cadeia FORWARD, como ocorre com um pacote encaminhado da LAN.

Examinar a filtragem sem desativá-la

O Docker instala suas próprias regras de filtragem e isolamento para suas redes. Consulte o estado disponível sem alterá-lo:

sudo nft list ruleset
sudo iptables -S
sudo iptables -t nat -S

Se você usa um firewall, consulte também a ferramenta efetivamente presente: sudo ufw status verbose ou firewall-cmd --get-active-zones. Um comando negado, uma cadeia ausente ou uma saída vazia não provam que a filtragem esteja ausente. iptables pode ser uma interface para nftables; portanto, duas saídas não significam necessariamente que haja dois firewalls independentes.

Acompanhe o trajeto local e o retorno. Não tire conclusões apenas com base em DOCKER-USER ou FORWARD: essas cadeias não descrevem automaticamente uma conexão iniciada pelo host para o endereço do bridge. O valor de sysctl net.ipv4.ip_forward não diagnostica, por si só, esse fluxo local nem justifica alterá-lo. A documentação do Docker descreve as regras de filtragem e alerta para não alterar as que ele gerencia.

Não use nft flush ruleset, iptables -F, uma política global ACCEPT, ufw disable, nem reinicie o firewall ou o Docker para testar. Não adicione regras nem altere rotas ou VPN durante esse diagnóstico. Uma alteração pode interromper outros acessos, inclusive SSH, sem resolver a causa.

Decidir onde parar

  • Contêiner parado ou em ciclo de reinicialização: limite-se ao estado e aos logs.
  • Nenhum socket na porta interna: verifique o processo, a porta e o endereço de escuta da aplicação.
  • Docker Desktop ou rootless: não aplique o caminho do Engine rootful; observe as publicações existentes e as limitações do modo de rede.
  • Rota escolhida fora do bridge esperado: guarde a saída e trate o roteamento em uma operação separada.
  • Escuta e rota coerentes, mas tempo limite excedido: ainda é preciso examinar a filtragem e o caminho de retorno; não declare uma causa certa apenas com base no timeout.
  • Resposta HTTP: o transporte alcança um serviço ou intermediário; prossiga então no nível HTTP ou da aplicação.

O guia não altera nenhuma configuração nem cria nenhum contêiner. Uma correção de rota, firewall ou configuração da aplicação deve ser tratada em uma intervenção separada, com seu escopo e suas precauções.

Fontes técnicas: Docker Engine: driver de rede bridge; Docker Engine: filtragem de pacotes e firewalls; Docker Desktop: rede; Docker Engine: solução de problemas no modo rootless. Para distinguir o código HTTP de um erro de transporte, consulte também o guia LinuxEnCaja para interpretar o resultado do curl.

Share Facebook X WhatsApp LinkedIn Pinterest Reddit Email