Proxy reverso Traefik: balanceamento em múltiplos containers Docker

Proxy reverso Traefik com balanceamento em múltiplos containers Docker é uma arquitetura na qual o Traefik descobre réplicas de uma aplicação e distribui as requisições entre elas. Para configurar o balanceamento, o proxy e as réplicas devem compartilhar uma rede Docker, usar as mesmas regras de roteamento e informar corretamente a porta interna do serviço.

1. Crie uma rede Docker compartilhada para o Traefik e as aplicações.
2. Configure o provedor Docker e a porta de entrada do proxy reverso.
3. Defina o roteador, o serviço e a porta interna por meio de labels.
4. Inicie a aplicação com múltiplas réplicas sem publicar suas portas externamente.
5. Valide a descoberta dos containers e teste a distribuição das requisições.

Pré-requisitos

A descoberta de serviços Docker permite que o Traefik encontre containers por meio das labels, mas exige uma estrutura consistente de rede e roteamento. Antes de começar, confirme os seguintes requisitos:

• Acesso administrativo ao servidor e permissão para executar comandos Docker.
• Docker e o comando docker compose funcionando no host.
• Portas 80 e, caso HTTPS seja configurado depois, 443 disponíveis para o Traefik.
• Um domínio, como seudominio.com.br, apontando para o IP público do servidor.
• Uma imagem de aplicação que escute em uma porta conhecida dentro do container.
• Nenhum serviço concorrente ocupando a porta que será publicada pelo Traefik.

Se o acesso administrativo ainda não estiver pronto, consulte Acessando servidores VPS Linux da AviraHost. Para revisar o apontamento do domínio, use como referência o Guia de zona DNS: registros A, MX, CNAME e TXT do zero.

Confirme primeiro se o domínio resolve para o endereço esperado:

getent ahostsv4 seudominio.com.br

Output esperado:
203.0.113.10 STREAM seudominio.com.br
203.0.113.10 DGRAM  seudominio.com.br
203.0.113.10 RAW    seudominio.com.br

O endereço exibido deve corresponder ao servidor onde o Traefik será executado. Uma divergência no DNS não impede a inicialização dos containers, mas fará as requisições públicas chegarem a outro destino.

Proxy reverso Traefik com balanceamento em múltiplos containers Docker

Uma rede Docker compartilhada cria o caminho interno usado pelo proxy para alcançar todas as réplicas. Somente o Traefik precisa publicar a porta de entrada no host; a aplicação pode manter sua porta acessível exclusivamente dentro dessa rede. Isso evita conflitos ao escalar o mesmo serviço, pois várias réplicas não tentam vincular a mesma porta pública.

Crie uma rede dedicada chamada proxy:

docker network create proxy

Output esperado:
uma linha contendo o identificador da nova rede Docker

Confirme que a rede foi registrada:

docker network ls --filter name=proxy

Output esperado:
NETWORK ID     NAME      DRIVER    SCOPE
identificador  proxy     bridge    local

A rede será declarada como externa no arquivo do Compose. Dessa maneira, ela não será recriada junto com o projeto e poderá conectar o proxy às réplicas. O nome deve ser idêntico em todos os pontos da configuração.

Como preparar o arquivo do proxy reverso Traefik

Crie um diretório de trabalho e entre nele. Essa operação não remove arquivos existentes, mas é recomendável usar um diretório novo para não misturar configurações de outros projetos.

mkdir -p traefik-balanceamento
cd traefik-balanceamento
pwd

Output esperado:
caminho completo terminado em /traefik-balanceamento

O arquivo Compose terá dois serviços. O primeiro publica a porta 80 e observa os metadados do Docker. O segundo representa a aplicação que será replicada. A montagem do socket em modo somente leitura permite a descoberta dos containers, mas esse arquivo continua sendo um recurso sensível do host; restrinja o acesso ao servidor e ao diretório.

Configurar labels, roteador e serviço do Traefik

As labels de roteamento do Traefik relacionam o domínio de entrada ao serviço interno. O roteador seleciona requisições destinadas a seudominio.com.br, enquanto o serviço informa qual porta deve ser usada para alcançar cada réplica. Todas as instâncias criadas a partir do serviço app herdam essas labels.

Crie o arquivo compose.yaml com o conteúdo abaixo:

services:
  traefik:
    image: traefik
    command:
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--entrypoints.web.address=:80"
    ports:
      - "80:80"
    volumes:
      - "/var/run/docker.sock:/var/run/docker.sock:ro"
    networks:
      - proxy
    restart: unless-stopped

  app:
    image: traefik/whoami
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.app.rule=Host(`seudominio.com.br`)"
      - "traefik.http.routers.app.entrypoints=web"
      - "traefik.http.services.app.loadbalancer.server.port=80"
      - "traefik.docker.network=proxy"
    networks:
      - proxy
    restart: unless-stopped

networks:
  proxy:
    external: true

A aplicação de validação responde com informações do container, facilitando a identificação de qual réplica processou cada chamada. Em uma implantação real, substitua essa imagem pela imagem da sua aplicação e altere loadbalancer.server.port para a porta em que ela realmente escuta.

Não adicione ports ao serviço app apenas para que o Traefik o alcance. A conexão acontece pela rede proxy. Também não defina um nome fixo de container no serviço escalável, pois cada réplica precisa receber uma identidade própria.

Valide a sintaxe e veja os serviços reconhecidos:

docker compose config --services

Output esperado:
traefik
app

Se a validação apresentar erro, revise recuo, aspas e nomes das redes antes de iniciar. Um arquivo aceito pelo Compose ainda pode conter uma porta interna incorreta, por isso essa informação será verificada novamente durante o teste de conectividade.

Subir e escalar as réplicas da aplicação

O escalonamento horizontal com Docker Compose cria várias instâncias do mesmo serviço sem duplicar manualmente sua definição. Como a porta da aplicação não está publicada no host, as réplicas podem escutar na mesma porta interna sem conflito. O Traefik descobre cada instância conectada à rede e associada às labels do serviço.

Inicie o Traefik e crie três réplicas da aplicação:

docker compose up -d --scale app=3

Output esperado:
linhas indicando a criação e a inicialização do Traefik e de três containers do serviço app

Confira o estado dos containers:

docker compose ps

Output esperado:
NAME                         SERVICE    STATUS
traefik-balanceamento-app-1  app        Up
traefik-balanceamento-app-2  app        Up
traefik-balanceamento-app-3  app        Up
traefik-balanceamento-traefik-1 traefik Up

Os nomes podem variar conforme o nome do diretório ou do projeto, mas devem existir três linhas para app e uma para traefik. Caso uma réplica reinicie continuamente, investigue seus logs antes de testar o balanceamento.

Para aumentar ou reduzir a quantidade de instâncias, execute novamente o comando com outro valor:

docker compose up -d --scale app=4

Output esperado:
uma nova réplica do serviço app criada e iniciada

Atenção: reduzir a quantidade de réplicas encerra containers excedentes. Confirme se a aplicação mantém dados persistentes fora do sistema de arquivos efêmero do container antes de diminuir a escala.

Testar a distribuição de tráfego entre containers

O teste de balanceamento do Traefik deve comprovar duas condições: o domínio chega ao roteador correto e respostas sucessivas podem vir de containers diferentes. Para eliminar uma possível dúvida de DNS durante a validação inicial, o comando pode enviar o cabeçalho de host diretamente ao IP local do proxy.

Execute várias requisições:

for numero in 1 2 3 4 5 6
do
  curl -s -H "Host: seudominio.com.br" http://127.0.0.1 | grep Hostname
done

Output esperado:
Hostname: replica-a
Hostname: replica-b
Hostname: replica-c
Hostname: replica-a
Hostname: replica-b
Hostname: replica-c

Os identificadores reais serão diferentes e a sequência não precisa seguir exatamente essa ordem. O ponto importante é observar mais de um hostname entre as respostas. Um único resultado em uma amostra curta não comprova falha, mas resultados persistentemente iguais justificam conferir se todas as réplicas foram descobertas e estão acessíveis.

Teste também pelo domínio público:

curl -s http://seudominio.com.br | grep Hostname

Output esperado:
Hostname: identificador-de-uma-replica

Por fim, acompanhe os registros do proxy e da aplicação enquanto envia novas requisições:

docker compose logs --tail=50 traefik
docker compose logs --tail=50 app

Output esperado:
registros recentes sem falhas de conexão com a porta interna do serviço

Os logs são fundamentais quando o roteador corresponde ao domínio, mas o proxy não consegue estabelecer conexão com uma réplica. Compare o nome da rede, a porta configurada na label e a porta realmente utilizada pela aplicação.

Problemas comuns e como resolver

O diagnóstico de containers no Traefik deve separar falhas de entrada, descoberta e conectividade interna. Comece verificando o estado dos serviços e os logs, evitando alterar várias labels ao mesmo tempo.

Sintoma: o domínio retorna 404 do Traefik

Causa: a requisição chegou ao proxy, mas nenhuma regra de roteamento correspondeu ao cabeçalho de host. Isso ocorre quando o domínio da label está diferente, a label não foi aplicada ou o container não foi exposto ao provedor Docker.

Solução: confira a regra Host, confirme traefik.enable=true e recrie os serviços após salvar o arquivo.

docker compose config
docker compose up -d

Output esperado:
configuração normalizada seguida de serviços em execução sem erro

Sintoma: o Traefik retorna 502 Bad Gateway

Causa: o roteador foi encontrado, mas o proxy não alcançou a aplicação. As causas mais frequentes são rede compartilhada ausente, porta interna incorreta ou aplicação escutando em outra interface dentro do container.

Solução: confirme a associação à rede e compare a porta real da aplicação com traefik.http.services.app.loadbalancer.server.port.

docker network inspect proxy
docker compose logs --tail=100 app

Output esperado:
Traefik e réplicas listados na rede, com a aplicação iniciada sem erro

Sintoma: somente uma réplica aparece nas respostas

Causa: as demais instâncias podem não ter sido criadas, podem estar reiniciando ou podem estar fora da rede usada pelo Traefik. Também é possível que poucas requisições não tenham fornecido uma amostra suficiente para observar hosts diferentes.

Solução: verifique a quantidade de containers, o estado de cada réplica e repita o teste acompanhando os logs.

docker compose ps
docker compose logs --tail=100 app

Output esperado:
todas as réplicas do serviço app com estado Up e sem reinicializações contínuas

Sintoma: a porta 80 já está em uso

Causa: outro processo ou container já publicou a porta usada como entrada pelo Traefik.

Solução: identifique o responsável antes de interromper qualquer serviço. Não encerre processos sem saber seu impacto.

ss -ltnp | grep ":80 "

Output esperado:
uma linha identificando o processo que está escutando na porta 80, ou nenhuma linha se a porta estiver livre

Perguntas frequentes sobre proxy reverso Traefik com balanceamento

Como o Traefik balanceia requisições entre múltiplos containers Docker?

O Traefik identifica as instâncias disponíveis por meio do provedor Docker e encaminha as requisições para os containers associados ao mesmo serviço. Os containers precisam estar acessíveis pela rede usada pelo proxy e expor corretamente a porta interna da aplicação.

É necessário publicar a porta de cada container para usar o Traefik?

Não é necessário publicar externamente a porta de cada aplicação quando o Traefik e os containers compartilham uma rede Docker. A porta pode permanecer acessível apenas nessa rede, enquanto o Traefik publica as portas de entrada do proxy reverso.

Como adicionar mais réplicas ao balanceamento do Traefik?

Crie novas instâncias do mesmo serviço Docker mantendo a configuração de roteamento e a rede compartilhada com o Traefik. Depois, confirme que todas as réplicas foram descobertas e estão recebendo requisições antes de direcionar tráfego de produção.

Como testar se o Traefik está distribuindo o tráfego entre os containers?

Envie várias requisições ao domínio roteado e acompanhe os logs do Traefik e das réplicas da aplicação. Para facilitar a validação, cada container pode retornar temporariamente seu hostname, permitindo identificar qual instância respondeu.

Por que o Traefik retorna erro 502 ao acessar um container Docker?

O erro 502 normalmente indica que o Traefik encontrou a rota, mas não conseguiu alcançar o serviço de destino. Verifique se ambos estão na mesma rede Docker, se a porta interna informada está correta e se a aplicação está escutando dentro do container.

Conclusão

O balanceamento de carga em containers depende da combinação correta entre descoberta Docker, rede compartilhada, labels consistentes e porta interna válida. A configuração deve ser validada tanto pelo estado dos containers quanto por requisições repetidas e análise dos logs.

• Mantenha o Traefik e todas as réplicas conectados à mesma rede Docker.
• Escale o serviço sem publicar individualmente as portas das aplicações.
• Teste hostnames diferentes e revise os logs antes de liberar tráfego de produção.

Leia também

• Solucionar erro de Traefik ao rotear containers Docker no Debian 12
• Conexão recusada no Traefik porta 80/443: causa e como reabrir
• Passo a passo: Traefik para roteamento Docker Fedora 42

Precisa de ajuda com Traefik e containers Docker?

Uma infraestrutura com recursos adequados ajuda a executar o proxy reverso e múltiplas réplicas com isolamento e espaço para crescimento. Avalie uma opção de servidor compatível com a quantidade de containers e o perfil de tráfego da aplicação.

Conheça as opções de Servidor VPS