Ir para o conteúdo
Promovaweb

Como a rota funciona no Traefik

Quando quatro apps dividem a mesma porta 443 da VPS, o Traefik escolhe o destino de cada requisição HTTP por um trajeto de quatro peças, numa ordem fixa. O entrypoint recebe a conexão numa porta, o router compara a requisição com a condição declarada para cada app, os middlewares ajustam a requisição no caminho e o service a repassa ao container que vai responder.

Ficha e sumário da página
Referência técnica
Traefik v3.7.19
Revisão
13 de novembro de 2026
Conteúdo
Documentação oficial consultada
  1. Quatro peças entre a porta e o app
  2. Entrypoints, as portas que o Traefik escuta
  3. A condição do router e a prioridade
  4. Services, o endereço do app
  5. Nomes e o sufixo do provider

Quatro peças entre a porta e o app

Cada peça do roteamento responde por uma parte do trajeto. O diagrama abaixo mostra a função de cada uma com o exemplo de um app publicado em n8n.seudominio.com.br:

  1. Entrypoint

    websecure :443

    A porta de rede onde o Traefik recebe a conexão.

  2. Router

    Host(`n8n.seudominio.com.br`)

    Compara a requisição com a condição do router e escolhe o service.

  3. Middleware

    redirectscheme, basicauth

    Altera a requisição ou recusa a passagem antes do service.

  4. Service

    loadbalancer.server.port=5678

    Guarda o endereço e a porta do app.

  5. App

    n8n:5678

    O container recebe a requisição e responde.

Sem middleware, que é a única peça opcional do caminho, o router repassa a requisição direto ao service.

A resposta do app volta pelas mesmas peças, na ordem inversa. Por isso um middleware consegue acrescentar cabeçalhos à resposta, como os cabeçalhos de segurança descritos na página Middlewares.

Entrypoints, as portas que o Traefik escuta

Um entrypoint é uma porta que o Traefik abre para ouvir conexões. O endereço segue o formato [host]:porta[/tcp|/udp], com TCP como padrão quando o protocolo não aparece e o sufixo /udp para o tráfego UDP. Numa VPS com apps web, a configuração usual tem dois entrypoints, web na porta 80 e websecure na 443, com nomes escolhidos por você.

O entrypoint da porta 80 costuma existir só para enviar o visitante ao HTTPS. A opção http.redirections.entryPoint.to aponta o entrypoint de destino, com o esquema https e o redirecionamento permanente como padrões. Assim, todo app atrás do Traefik recebe o redirecionamento sem nenhuma label própria.

Os entrypoints pertencem à configuração de instalação. Um router que não declara em qual entrypoint escuta usa os entrypoints marcados com asDefault. Quando nenhum entrypoint tem essa marca, o router escuta em todos os entrypoints HTTP.

A condição do router e a prioridade

O router liga uma requisição a um service pela condição escrita na label rule. Essa condição usa funções que examinam partes da requisição:

  • HostO domínio da requisição. Aceita um curinga de um nível, como *.seudominio.com.br.
  • PathPrefixO começo do caminho, como /api.
  • PathO caminho exato.
  • HeaderUm cabeçalho da requisição, pelo nome e pelo valor.
  • MethodO método HTTP, como GET ou POST.
  • ClientIPO IP da conexão de origem, sem ler o cabeçalho X-Forwarded-For.

Cada função também tem uma versão com expressão regular, como HostRegexp, PathRegexp e HeaderRegexp. A função Query compara parâmetros da URL. As funções se combinam com &&, ||, parênteses e a negação !, de modo que a condição Host(`app.seudominio.com.br`) && PathPrefix(`/api`) atende só os caminhos que começam com /api naquele domínio.

Quando duas condições servem para a mesma requisição, vence o router de maior prioridade. Sem prioridade declarada, o Traefik usa como prioridade o tamanho da condição em caracteres, por isso a condição mais longa, que costuma ser a mais específica, vence. Um router com Host(`app.seudominio.com.br`) && PathPrefix(`/api`) atende /api antes do router que declara só o Host do mesmo domínio. A label priority força outra ordem e aceita números negativos, mas o valor 0 é ignorado e devolve o router à ordem pelo tamanho.

Quando nenhum router tem uma condição para o domínio da requisição, o Traefik responde 404 page not found. Essa resposta mostra que a requisição chegou ao Traefik sem encontrar destino, o que costuma apontar para uma label rule com o domínio errado.

Services, o endereço do app

O service diz como alcançar o app que vai responder. O tipo usual é o loadBalancer, com uma lista de servidores, cada um com a URL de uma instância do app. No provider Docker, você não escreve essa URL, porque o Traefik monta o endereço com o IP do container na rede e a porta da label loadbalancer.server.port. Com mais de um container no mesmo service, o Traefik reparte as requisições entre eles.

O service também define como a entrega acontece. O passHostHeader, ligado por padrão, repassa ao app o domínio que o visitante digitou. O healthCheck tira da rotação o servidor que deixa de responder com status 2XX ou 3XX. A sessão fixa, chamada sticky, usa um cookie para manter o mesmo visitante no mesmo servidor.

A documentação descreve ainda três services que combinam outros services:

  • weighted: reparte as requisições entre services de acordo com pesos.
  • mirroring: copia as requisições para um segundo service.
  • failover: troca para um service reserva quando o principal falha.

Numa VPS com um container por app, o loadBalancer com um servidor atende cada app sem nenhuma dessas combinações.

Nomes e o sufixo do provider

Routers, services e middlewares se ligam pelo nome. Nas labels traefik.http.routers.n8n.rule e traefik.http.services.n8n.loadbalancer.server.port, o n8n é um nome escolhido por você. Esse nome precisa ser único entre os apps atrás do mesmo Traefik, porque o dashboard identifica cada rota por ele.

Cada peça pertence ao provider que a declarou. Para usar num container um middleware declarado num arquivo, você acrescenta o nome do provider depois de uma arroba, como em seguranca@file. O próprio Traefik tem peças internas nesse formato, como o service api@internal, que serve o dashboard descrito na página Dashboard, logs e métricas.

A origem dessas peças, os providers e as labels que o Traefik lê nos containers, é o assunto da página Providers e labels.

StayCloud

Uma VPS para desenvolver com agentes

Servidor da StayCloud em São Paulo, com acesso root e disco NVMe, para deixar seus agentes de IA rodando o dia todo.

Montar minha VPS

Link de parceiro da Promovaweb.