Solucionar erro de Traefik ao rotear containers Docker no Debian 12

17 min de leitura  ·  Guia técnico

Erro de roteamento do Traefik com containers Docker ocorre quando o proxy reverso não consegue criar rotas para os serviços, resultando em respostas 404, 502 ou ausência total de tráfego. As causas mais comuns são: container fora da rede Docker do Traefik, labels ausentes ou incorretas, e socket Docker não montado. Veja abaixo como diagnosticar e corrigir cada cenário no Debian 12.

Pré-requisitos para solucionar o erro de Traefik no Debian 12

• Acesso root ou sudo ao servidor com Debian 12 (Bookworm)
• Docker Engine instalado (versão 24.x ou superior recomendada)
• Docker Compose v2 instalado (docker compose version deve retornar v2.x)
• Traefik v2.x ou v3.x rodando como container
• Acesso SSH ao servidor — veja como acessar servidores VPS Linux da AviraHost
• Portas 80 e 443 liberadas no firewall do servidor
• Domínio apontando para o IP do servidor (para testes com TLS)

Como o Traefik roteia containers Docker: entendendo o mecanismo

O Traefik como proxy reverso para containers Docker funciona por meio de um provider que monitora o daemon Docker em tempo real via socket Unix. Quando um container sobe com as labels corretas e está conectado à rede compartilhada, o Traefik cria automaticamente rotas HTTP/HTTPS sem necessidade de recarregar configuração. Esse modelo dinâmico é o principal diferencial do Traefik em relação ao Nginx configurado manualmente.

O fluxo de descoberta segue esta sequência:

1. O Traefik lê o socket /var/run/docker.sock montado como volume
2. Detecta containers com a label traefik.enable=true
3. Lê as labels de roteamento (traefik.http.routers.*) para criar regras
4. Associa o roteador a um serviço que aponta para a porta do container
5. Aplica middlewares e certificados TLS conforme configurado

Se qualquer etapa dessa cadeia falhar, o Traefik simplesmente ignora o container ou retorna erro. Por isso, o diagnóstico deve seguir essa mesma ordem.

Diagnóstico inicial: verificando logs e estado do Traefik

Antes de alterar qualquer configuração, colete informações do ambiente. O diagnóstico de erros no Traefik começa sempre pelos logs do container e pelo estado das redes Docker.

Verifique se o container do Traefik está rodando:

docker ps --filter name=traefik

CONTAINER ID   IMAGE           COMMAND                  CREATED        STATUS        PORTS
a1b2c3d4e5f6   traefik:v3.0   "/entrypoint.sh trae…"   2 hours ago    Up 2 hours    0.0.0.0:80->80/tcp, 0.0.0.0:443->443/tcp, 0.0.0.0:8080->8080/tcp

Leia os logs em busca de erros de configuração:

docker logs traefik 2>&1 | grep -iE "error|warn|level=error"

Verifique quais redes Docker existem e quais containers estão conectados:

docker network ls
docker network inspect traefik-net

Inspecione as labels de um container específico para confirmar se estão definidas:

docker inspect nome-do-container | grep -A 30 '"Labels"'

Se o dashboard estiver habilitado, acesse http://IP-DO-SERVIDOR:8080/dashboard/ e verifique as abas Routers e Services. Um roteador ausente nessa tela confirma que o Traefik não detectou o container.

Causa 1: container não conectado à rede Docker do Traefik

A causa mais frequente de containers Docker invisíveis para o Traefik é a ausência de uma rede compartilhada. O Traefik só consegue rotear tráfego para containers que estejam na mesma rede Docker que ele. Containers em redes isoladas ou usando apenas a rede padrão bridge não são alcançados.

Crie uma rede externa dedicada para o Traefik:

docker network create traefik-net

No docker-compose.yml do Traefik, declare a rede como externa:

version: "3.8"

services:
  traefik:
    image: traefik:v3.0
    container_name: traefik
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
      - "8080:8080"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./traefik.yml:/etc/traefik/traefik.yml:ro
      - ./acme.json:/acme.json
    networks:
      - traefik-net

networks:
  traefik-net:
    external: true

No docker-compose.yml de cada aplicação, conecte o container à mesma rede:

version: "3.8"

services:
  minha-app:
    image: nginx:alpine
    container_name: minha-app
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.minha-app.rule=Host(`app.exemplo.com.br`)"
      - "traefik.http.routers.minha-app.entrypoints=websecure"
      - "traefik.http.routers.minha-app.tls=true"
      - "traefik.http.routers.minha-app.tls.certresolver=letsencrypt"
      - "traefik.http.services.minha-app.loadbalancer.server.port=80"
    networks:
      - traefik-net

networks:
  traefik-net:
    external: true

Após salvar, suba os serviços:

docker compose up -d

Confirme que ambos os containers estão na mesma rede:

docker network inspect traefik-net --format '{{range .Containers}}{{.Name}} {{end}}'

traefik minha-app

Causa 2: arquivo traefik.yml com provider Docker ausente ou incorreto

O provider Docker do Traefik precisa estar explicitamente habilitado no arquivo de configuração estática. Sem ele, o Traefik ignora completamente o socket Docker, mesmo que esteja montado como volume.

Crie ou revise o arquivo traefik.yml:

api:
  dashboard: true
  insecure: true

entryPoints:
  web:
    address: ":80"
    http:
      redirections:
        entryPoint:
          to: websecure
          scheme: https
  websecure:
    address: ":443"

providers:
  docker:
    endpoint: "unix:///var/run/docker.sock"
    exposedByDefault: false
    network: traefik-net

certificatesResolvers:
  letsencrypt:
    acme:
      email: [email protected]
      storage: /acme.json
      httpChallenge:
        entryPoint: web

Atenção: o parâmetro exposedByDefault: false é recomendado por segurança — ele exige que cada container declare explicitamente traefik.enable=true. Se você definir exposedByDefault: true, todos os containers serão expostos automaticamente, o que pode ser um risco em ambientes de produção.

Após editar o arquivo, reinicie o Traefik para aplicar:

docker compose restart traefik

Verifique nos logs se o provider foi carregado sem erros:

docker logs traefik 2>&1 | grep -i "provider"

time="..." level=info msg="Starting provider aggregator providers.ProvidersAggregator"
time="..." level=info msg="Starting provider *docker.Provider"

Causa 3: labels incorretas ou com nome de roteador duplicado

Labels mal formatadas são a terceira causa mais comum de erro 404 no Traefik ao rotear containers. Um erro de digitação no nome do roteador, uma porta errada ou a ausência da regra de host fazem o Traefik criar um roteador inválido ou simplesmente descartá-lo.

Regras de validação para as labels:

• Nome do roteador deve ser único entre todos os containers — dois containers com o mesmo nome de roteador causam conflito silencioso
• A label rule é obrigatória — sem ela, o roteador não é criado
• A porta do serviço deve corresponder à porta que o processo dentro do container escuta, não à porta mapeada no host
• Aspas no shell — ao usar docker run, use aspas simples externas e escape correto; no Compose, use aspas duplas normalmente

Exemplo de labels corretas para uma aplicação Node.js rodando na porta 3000:

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.nodeapp.rule=Host(`nodeapp.exemplo.com.br`)"
  - "traefik.http.routers.nodeapp.entrypoints=websecure"
  - "traefik.http.routers.nodeapp.tls=true"
  - "traefik.http.routers.nodeapp.tls.certresolver=letsencrypt"
  - "traefik.http.services.nodeapp.loadbalancer.server.port=3000"

Para verificar se o Traefik carregou o roteador, consulte a API REST:

curl -s http://localhost:8080/api/rawdata | python3 -m json.tool | grep -A 5 "nodeapp"

Se o roteador aparecer na saída, o Traefik o reconheceu. Se não aparecer, revise as labels e os logs.

Configurando o arquivo acme.json para certificados TLS

A emissão de certificados Let's Encrypt pelo Traefik depende de um arquivo acme.json com permissão restrita. Sem a permissão correta, o Traefik falha ao gravar o certificado e pode retornar erros TLS ou simplesmente não renovar certificados expirados.

Crie o arquivo com a permissão correta antes de subir o Traefik:

touch acme.json
chmod 600 acme.json

Atenção: se o arquivo acme.json já existir com dados corrompidos ou de um domínio diferente, apague-o e recrie antes de reiniciar o Traefik. O Traefik solicitará novos certificados automaticamente.

rm acme.json
touch acme.json
chmod 600 acme.json
docker compose restart traefik

Acompanhe a emissão do certificado nos logs:

docker logs -f traefik 2>&1 | grep -iE "acme|certificate|tls"

time="..." level=info msg="Obtaining certificate for domains [app.exemplo.com.br]"
time="..." level=info msg="Certificate obtained successfully"

Para ambientes com múltiplos domínios e containers, considere também ler sobre configuração de servidor Linux para hospedagem de sites para entender como organizar a infraestrutura de rede.

Problemas comuns e como resolver

Sintoma: Traefik retorna 502 Bad Gateway para o container

Causa: O Traefik encontrou o container e criou a rota, mas não consegue se comunicar com ele. Isso ocorre quando a porta declarada na label não corresponde à porta real do processo, quando o container está em estado de erro, ou quando há um problema de rede entre os containers.
Solução: Verifique a porta que o processo escuta dentro do container com docker exec nome-do-container ss -tlnp. Confirme que a label traefik.http.services.nome.loadbalancer.server.port usa exatamente essa porta. Verifique também se o container está saudável com docker ps e se ambos estão na mesma rede com docker network inspect traefik-net.

Sintoma: dashboard do Traefik mostra roteador com status "red" ou "degraded"

Causa: O roteador foi criado mas o serviço associado está inacessível. Causas comuns incluem container parado, porta errada ou healthcheck falhando.
Solução: Acesse o dashboard em http://IP:8080/dashboard/, clique no roteador com problema e leia a mensagem de erro detalhada. Execute docker logs nome-do-container para verificar se a aplicação iniciou corretamente. Se o container usa healthcheck, aguarde ele passar para healthy antes de testar o roteamento.

Sintoma: erro "bind: address already in use" ao iniciar o Traefik

Causa: Outro processo (Nginx, Apache ou outra instância do Traefik) já está usando as portas 80 ou 443 no host.
Solução: Identifique o processo com ss -tlnp | grep -E ':80|:443' e pare-o antes de iniciar o Traefik. Se for o Nginx ou Apache instalado diretamente no host, execute systemctl stop nginx ou systemctl stop apache2 e desabilite-os com systemctl disable nginx para evitar conflito na próxima reinicialização.

Sintoma: certificado TLS expirado e não renovado automaticamente

Causa: O arquivo acme.json não tem permissão 600, o volume não está montado corretamente, ou a porta 80 está bloqueada por firewall impedindo o desafio HTTP-01.
Solução: Execute ls -la acme.json e confirme que a permissão é -rw-------. Verifique se o volume está montado com docker inspect traefik | grep acme. Teste se a porta 80 está acessível externamente com curl -I http://seudominio.com.br a partir de outra máquina. Se o firewall UFW estiver ativo, libere a porta com ufw allow 80/tcp.

Sintoma: múltiplos containers com o mesmo domínio causam comportamento imprevisível

Causa: Dois roteadores com a mesma regra Host() criam conflito. O Traefik pode rotear para qualquer um dos dois de forma não determinística.
Solução: Cada container deve ter um nome de roteador único e, se precisar compartilhar o mesmo domínio, use prefixos de path diferentes: Host(`app.exemplo.com.br`) && PathPrefix(`/api`) para um e Host(`app.exemplo.com.br`) && PathPrefix(`/web`) para outro. Verifique conflitos no dashboard na aba Routers.

Perguntas frequentes sobre Traefik e roteamento de containers Docker

Por que o Traefik não detecta meus containers Docker automaticamente?

O Traefik só detecta containers que estão na mesma rede Docker que ele e que possuem a label traefik.enable=true. Se o container estiver em uma rede diferente ou sem essa label, o Traefik simplesmente o ignora. Verifique com docker network inspect se ambos compartilham a mesma rede e confirme as labels no docker inspect do container. Lembre-se também de que, com exposedByDefault: false no traefik.yml, a label traefik.enable=true é obrigatória em cada container.

Como verificar se o Traefik está recebendo a configuração correta dos containers?

Acesse o dashboard do Traefik em http://localhost:8080/dashboard (se habilitado) e verifique a aba Routers e Services. Alternativamente, execute docker logs traefik 2>&1 | grep -i error para ver erros de configuração em tempo real. O Traefik também expõe uma API REST em /api/rawdata que retorna toda a configuração carregada — use curl -s http://localhost:8080/api/rawdata | python3 -m json.tool para inspecionar o JSON completo com todos os roteadores e serviços ativos.

O Traefik retorna erro 404 para todos os containers. O que verificar?

Um erro 404 generalizado indica que nenhuma rota foi criada. As causas mais comuns são: ausência da label traefik.http.routers.nome.rule, container não conectado à rede do Traefik, ou o provider Docker não estar habilitado no traefik.yml. Confirme que o arquivo de configuração monta o socket Docker /var/run/docker.sock:/var/run/docker.sock:ro e que a seção providers.docker existe no traefik.yml. Verifique também se o parâmetro network no provider aponta para a rede correta.

Como forçar HTTPS com redirecionamento automático no Traefik?

Adicione um entrypoint web na porta 80 com middleware de redirecionamento para o entrypoint websecure na porta 443. No traefik.yml, configure entryPoints.web.http.redirections.entryPoint.to: websecure e scheme: https. Nos containers, use a label traefik.http.routers.nome.tls=true e aponte para o resolver Let's Encrypt configurado. Com essa configuração, qualquer requisição HTTP é automaticamente redirecionada para HTTPS sem necessidade de configuração adicional nos containers.

O certificado TLS do Traefik não renova automaticamente. Como corrigir?

A renovação automática depende do arquivo acme.json ter permissão 600 e pertencer ao usuário que executa o Traefik. Execute chmod 600 acme.json e verifique se o volume está montado corretamente no docker-compose.yml. Além disso, confirme que a porta 80 está acessível externamente, pois o desafio HTTP-01 do Let's Encrypt exige isso para validar o domínio. Se o servidor estiver atrás de um firewall ou NAT, certifique-se de que o redirecionamento de porta 80 está configurado corretamente no roteador ou nas regras de firewall do servidor.

Conclusão

Resolver erros de roteamento do Traefik com containers Docker no Debian 12 exige seguir uma sequência lógica de diagnóstico: verificar logs, confirmar redes compartilhadas, validar labels e revisar o arquivo de configuração estática. A maioria dos problemas se concentra em três pontos críticos.

• Rede compartilhada: sempre crie uma rede externa dedicada (traefik-net) e conecte todos os containers a ela — nunca dependa da rede bridge padrão do Docker
• Labels obrigatórias: confirme que cada container tem traefik.enable=true, uma regra Host() válida e a porta correta do serviço declarada — um único campo ausente impede o roteamento
• Arquivo acme.json: crie-o com chmod 600 antes de subir o Traefik e garanta que a porta 80 está acessível externamente para que a renovação automática de certificados funcione sem intervenção manual

Leia também

• Entenda o Checklist de Segurança do Docker antes de ir ao ar
• configurar rede Docker para isolar serviços no VPS
• Tutorial: como monitorar Docker com Prometheus no Ubuntu 24.04

Precisa de ajuda com Traefik e containers Docker?

Configurar proxy reverso com Traefik em ambiente de produção envolve detalhes de rede, segurança e certificados que podem ser desafiadores. Um VPS com recursos adequados e suporte especializado facilita muito esse processo.

Conheça os planos de VPS da AviraHost e hospede seus containers com performance e estabilidade