TL;DR — Resumo Rápido

Guia completo de middlewares do Traefik: roteamento HTTP, limite de taxa, cabeçalhos de segurança, autenticação e circuit breakers para produção.

Middlewares do Traefik: Roteamento HTTP, Limite de Taxa e Segurança

Os middlewares do Traefik são o mecanismo central para transformar requisições e respostas HTTP entre o edge e seus serviços upstream. Seja para aplicar limites de taxa, injetar cabeçalhos de segurança, remover prefixos de caminho ou delegar a autenticação a um serviço externo, cada comportamento é um objeto middleware discreto que você anexa a um roteador. Este guia cobre todas as categorias principais de middleware com exemplos de configuração, uma comparação com alternativas e um exemplo completo de Docker Compose para produção.

Pré-requisitos

• Traefik v2.x ou v3.x executando como contêiner Docker ou em um host
• Familiaridade básica com labels do Docker Compose
• Um domínio registrado com DNS apontando para seu servidor
• Opcional: Authelia ou OAuth2-Proxy para fluxos ForwardAuth

Arquitetura do Traefik: O Pipeline de Requisições

O Traefik organiza o tráfego por meio de quatro primitivas:

• Entrypoints — portas de rede onde o tráfego chega (:80, :443)
• Roteadores — fazem correspondência das requisições por host, caminho ou cabeçalhos e as direcionam a um serviço
• Middlewares — transformam a requisição ou resposta (ou a rejeitam) antes de chegar ao serviço
• Serviços — os contêineres ou servidores upstream que recebem a requisição final

O Traefik descobre esses objetos automaticamente a partir de labels Docker, provedores de arquivo ou CRDs do Kubernetes.

Provedores de Configuração de Middleware

Labels Docker

labels:
  - "traefik.http.middlewares.meus-headers.headers.stsSeconds=31536000"
  - "traefik.http.routers.minhaapp.middlewares=meus-headers"

Provedor de Arquivo (YAML dinâmico)

# dynamic/middlewares.yml
http:
  middlewares:
    meus-headers:
      headers:
        stsSeconds: 31536000
        stsIncludeSubdomains: true

Middleware de Cabeçalhos de Segurança

O middleware Headers injeta ou modifica cabeçalhos HTTP em ambas as direções.

http:
  middlewares:
    headers-seguros:
      headers:
        customRequestHeaders:
          X-Forwarded-Proto: "https"
        customResponseHeaders:
          X-Powered-By: ""
        stsSeconds: 31536000
        stsIncludeSubdomains: true
        stsPreload: true
        forceSTSHeader: true
        frameDeny: true
        contentTypeNosniff: true
        browserXssFilter: true
        referrerPolicy: "strict-origin-when-cross-origin"
        permissionsPolicy: "camera=(), microphone=(), geolocation=()"
        contentSecurityPolicy: "default-src 'self'; script-src 'self' 'unsafe-inline'"

Definir um cabeçalho com valor vazio o remove da resposta.

Limite de Taxa

O middleware RateLimit limita a frequência com que um cliente pode fazer requisições.

http:
  middlewares:
    limite-api:
      rateLimit:
        average: 100
        burst: 50
        period: 1m
        sourceCriterion:
          requestHeaderName: "X-API-Key"

• average — requisições sustentadas permitidas por period
• burst — pico máximo acima da média
• period — janela deslizante (padrão 1s; suporta 1m, 1h)
• sourceCriterion — identifica o “cliente” por cabeçalho, host ou estratégia de IP

Para implantações atrás de uma CDN, use ipStrategy.depth: 1 para que o Traefik utilize o IP real do cliente.

BasicAuth e DigestAuth

Proteja rotas com autenticação HTTP quando SSO não está disponível.

http:
  middlewares:
    auth-basica:
      basicAuth:
        users:
          - "admin:$apr1$xyz$hashedpassword"
        usersFile: "/etc/traefik/.htpasswd"
        realm: "Área Administrativa"
        removeHeader: true

Gere hashes de senha com:

htpasswd -nb admin minhasenha

removeHeader: true remove o cabeçalho Authorization antes do encaminhamento, evitando vazamento de credenciais.

ForwardAuth: Integração SSO e OAuth2

ForwardAuth delega a decisão de autenticação a um serviço externo como Authelia ou OAuth2-Proxy.

http:
  middlewares:
    auth-sso:
      forwardAuth:
        address: "http://authelia:9091/api/verify"
        trustForwardHeader: true
        authResponseHeaders:
          - "Remote-User"
          - "Remote-Groups"
          - "Remote-Email"

O Traefik envia cada requisição para address primeiro. Se retornar 2xx, a requisição original prossegue.

Middlewares de Manipulação de Caminhos

StripPrefix

Remove um prefixo antes de encaminhar, útil quando o upstream espera um caminho raiz.

http:
  middlewares:
    strip-api:
      stripPrefix:
        prefixes:
          - "/api/v1"
        forceSlash: true

AddPrefix

Adiciona um prefixo. Útil quando várias rotas apontam para o mesmo serviço.

http:
  middlewares:
    adicionar-v2:
      addPrefix:
        prefix: "/v2"

ReplacePathRegex

http:
  middlewares:
    redirect-legado:
      replacePathRegex:
        regex: "^/antigo/(.*)"
        replacement: "/novo/$1"

Compressão

http:
  middlewares:
    comprimir:
      compress:
        excludedContentTypes:
          - "image/jpeg"
          - "image/png"
        minResponseBodyBytes: 1024

O Traefik suporta gzip e brotli. O brotli é usado quando o cliente envia Accept-Encoding: br.

Retry e CircuitBreaker

Retry

http:
  middlewares:
    tentar-novamente:
      retry:
        attempts: 3
        initialInterval: "100ms"

CircuitBreaker

http:
  middlewares:
    circuit-breaker:
      circuitBreaker:
        expression: "ResponseCodeRatio(500, 600, 0, 600) > 0.30"
        checkPeriod: "10s"
        fallbackDuration: "30s"
        recoveryDuration: "10s"

IPAllowList

Restringe o acesso a intervalos de IP permitidos.

http:
  middlewares:
    somente-interno:
      ipAllowList:
        sourceRange:
          - "10.0.0.0/8"
          - "172.16.0.0/12"
          - "192.168.0.0/16"
        ipStrategy:
          depth: 2

Middlewares de Redirecionamento

RedirectScheme (HTTP → HTTPS)

http:
  middlewares:
    redirect-https:
      redirectScheme:
        scheme: "https"
        permanent: true

RedirectRegex (www → sem www)

http:
  middlewares:
    redirect-www:
      redirectRegex:
        regex: "^https://www\\.(.+)"
        replacement: "https://${1}"
        permanent: true

Cadeias de Middlewares

As cadeias permitem compor múltiplos middlewares em um único pipeline nomeado.

http:
  middlewares:
    stack-seguro:
      chain:
        middlewares:
          - headers-seguros
          - redirect-https
          - limite-api
          - auth-sso

Anexe a cadeia a um roteador com uma única label:

labels:
  - "traefik.http.routers.minhaapp.middlewares=stack-seguro"

---

Comparação: Traefik vs Alternativas

Funcionalidade	Traefik	Nginx (módulos)	Envoy (filtros)	Kong (plugins)	Caddy (handlers)
Limite de taxa	Integrado	limit_req	ratelimit filter	Plugin oficial	rate_limit
Delegação de auth	ForwardAuth	auth_request	ext_authz	Plugin OIDC	forward_auth
Circuit breaker	Integrado	Não nativo	Integrado	Requer plugin	Não nativo
Reescrita de caminho	Integrado	rewrite	rewrite filter	Integrado	rewrite
Compressão	Integrado	módulo gzip	compressor	Não nativo	Integrado
Config dinâmica	Auto (labels/CRD)	Requer reload	xDS API	Admin API	Auto (Caddyfile)

---

Exemplo Completo de Docker Compose para Produção

Você tem um serviço de API em produção que precisa de HTTPS, limite de taxa, cabeçalhos de segurança e BasicAuth no caminho de administração.

services:
  traefik:
    image: traefik:v3.1
    restart: unless-stopped
    command:
      - --providers.docker=true
      - --providers.docker.exposedbydefault=false
      - --entrypoints.web.address=:80
      - --entrypoints.web.http.redirections.entryPoint.to=websecure
      - --entrypoints.web.http.redirections.entryPoint.scheme=https
      - --entrypoints.websecure.address=:443
      - --certificatesresolvers.le.acme.email=ops@exemplo.com
      - --certificatesresolvers.le.acme.storage=/letsencrypt/acme.json
      - --certificatesresolvers.le.acme.tlschallenge=true
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./letsencrypt:/letsencrypt
    networks:
      - edge

  api:
    image: ghcr.io/exemplo/api:latest
    restart: unless-stopped
    networks:
      - edge
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.api.rule=Host(`api.exemplo.com`)"
      - "traefik.http.routers.api.entrypoints=websecure"
      - "traefik.http.routers.api.tls.certresolver=le"
      - "traefik.http.routers.api.middlewares=stack-seguro"
      - "traefik.http.services.api.loadbalancer.server.port=8080"
      - "traefik.http.middlewares.hdrs.headers.stsSeconds=31536000"
      - "traefik.http.middlewares.hdrs.headers.frameDeny=true"
      - "traefik.http.middlewares.rl.rateLimit.average=120"
      - "traefik.http.middlewares.rl.rateLimit.burst=40"
      - "traefik.http.middlewares.rl.rateLimit.period=1m"
      - "traefik.http.middlewares.compress.compress=true"
      - "traefik.http.middlewares.stack-seguro.chain.middlewares=hdrs,rl,compress"

networks:
  edge:
    external: true

Armadilhas e Casos Especiais

• Cifrões em hashes de BasicAuth devem ser duplicados ($$) em labels Docker porque o Docker Compose interpola $ como variável.
• A ordem dos middlewares em uma cadeia importa. Aplique redirecionamentos antes da autenticação; aplique compressão por último.
• A latência do ForwardAuth adiciona um round-trip extra por requisição. Use cache de decisões no Authelia ou OAuth2-Proxy.
• Os contadores de RateLimit são por réplica. Com três réplicas do Traefik a taxa permitida é multiplicada por três.
• O CircuitBreaker usa sua própria linguagem de expressões, não PromQL. Consulte a documentação oficial.

Resumo

• Os middlewares do Traefik se anexam a roteadores e transformam requisições antes de chegarem aos serviços upstream
• Use Headers para HSTS, CSP e CORS; sempre remova cabeçalhos sensíveis em direção ao upstream
• RateLimit com sourceCriterion gerencia throttling de APIs; configure ipStrategy.depth atrás de CDNs
• ForwardAuth integra Authelia e OAuth2-Proxy para SSO sem modificar o código da aplicação
• As cadeias Chain compõem pipelines de segurança reutilizáveis anexáveis a qualquer roteador com uma label

Artigos Relacionados

• Traefik Reverse Proxy para Serviços Docker
• Guia Completo do Nginx como Proxy Reverso
• Docker Compose: Guia Prático para Administradores de Sistemas
• Let’s Encrypt SSL Wildcard com Nginx e Certbot
• UFW Firewall: Regras Essenciais para Servidores Linux