tva
← Artigos

Guia completo de solução de problemas do n8n auto-hospedado em 2025: tamanho dos dados de execução e webhooks com Traefik

Última atualização: 15 de outubro de 2025

A auto-hospedagem do n8n oferece execuções ilimitadas de fluxos de trabalho, controle completo dos dados e economia significativa em comparação com planos na nuvem. Mas, na realidade, instâncias auto-hospedadas enfrentam desafios que os usuários do n8n Cloud geralmente não precisam gerenciar — especificamente em relação ao processamento de grandes volumes de dados e à configuração de webhooks com proxies reversos.

Em junho de 2025, publicamos dois guias de solução de problemas abordando essas questões separadamente. O problema é que não existe um guia abrangente para implantações do n8n em produção com o proxy reverso Traefik que aborde ambas as questões em conjunto.

Este guia combina ambas as correções originais, fornece a configuração completa do Traefik com suporte a WebSocket, inclui os novos requisitos de task runners de 2025 e apresenta arquivos docker-compose prontos para produção que você pode implantar imediatamente.

Sumário

  1. Diagnóstico rápido: qual problema você tem?
  2. Entendendo os dois principais problemas
  3. Correção #1: erro de dados de execução muito grandes
  4. Correção #2: problemas de URL de webhook
  5. Configuração completa de produção com Traefik
  6. Requisito de 2025: task runners
  7. Referência de variáveis de ambiente
  8. Exemplos de Docker Compose
  9. Testando sua configuração
  10. Solução de problemas comuns

Diagnóstico rápido: qual problema você tem?

Sintoma: “Existing execution data is too large”

Você vê este erro quando:

  • Clica em “Execute Node” durante o desenvolvimento de fluxos de trabalho
  • Testa fluxos de trabalho com grandes conjuntos de dados ou muitos itens
  • Usa o modo de execução parcial (testando nós individuais)
  • Processa transformações complexas com múltiplas ramificações

Você precisa de: Correção #1: tamanho dos dados de execução

Sintoma: webhooks mostram URLs incorretas ou não funcionam

Você vê isso quando:

  • URLs de webhook são exibidas com números de porta (ex.: :5678)
  • Serviços externos (Slack, GitHub, Stripe) não conseguem alcançar seus webhooks
  • Webhooks funcionam no modo de teste, mas falham em produção
  • Você está usando um proxy reverso (Nginx, Traefik, Caddy)

Você precisa de: Correção #2: configuração da URL de webhook

Sintoma: avisos de descontinuação sobre task runners

Você vê nos logs:

Running n8n without task runners is deprecated. Task runners will be
turned on by default in a future version.

Você precisa de: Configuração de task runners

Sintoma: você quer uma configuração completa pronta para produção

Você precisa de:

  • Ambas as correções aplicadas corretamente
  • Proxy reverso Traefik com HTTPS automático
  • Boas práticas de produção e segurança
  • Limites de recursos e monitoramento adequado

Vá para: Configuração completa de produção

Entendendo os dois principais problemas

Por que os usuários do n8n Cloud raramente lidam com esses problemas

No n8n Cloud, o n8n gerencia a configuração do servidor para você, como URLs de webhooks, armazenamento de dados binários e atualizações. Na auto-hospedagem, você é responsável por essas configurações.

As causas raiz

Problema #1: limite de tamanho dos dados de execução

O limite padrão de 16 MiB para o corpo das requisições enviadas ao backend, incluindo os dados de execução parcial provoca erros ao trabalhar com grandes conjuntos de dados, muitas ramificações de fluxos de trabalho ou transformações complexas. O desenvolvimento de fluxos de trabalho se torna frustrante — você não consegue testar nós individuais durante o desenvolvimento. A correção é direta: a variável de ambiente N8N_PAYLOAD_SIZE_MAX.

Problema #2: geração de URLs de webhook

O n8n tenta detectar automaticamente sua URL pública, mas essa detecção falha quando ele está atrás de um proxy reverso. Serviços externos recebem URLs de webhook incorretas, com portas ou nomes de host internos — as integrações falham silenciosamente. A correção: a variável de ambiente WEBHOOK_URL.

Correção #1: erro de dados de execução muito grandes

O problema em detalhe

Quando você executa apenas parte de um fluxo de trabalho (clicando em “Execute Node” no editor), o n8n precisa carregar dados de execução anteriores para fornecer contexto ao nó. Por padrão, o n8n limita essa requisição a 16 MiB (N8N_PAYLOAD_SIZE_MAX=16; o valor é expresso em MiB) para evitar problemas de memória em servidores menores. Se a requisição for maior, o n8n (ou um proxy reverso com um limite menor para o corpo da requisição) responde com HTTP 413, e o editor mostra esse erro.

A mensagem de erro

De acordo com a documentação oficial do n8n:

Please execute the whole workflow, rather than just the node.
(Existing execution data is too large.)

Este erro aparece ao processar milhares de itens em um único nó, trabalhar com grandes respostas JSON de APIs, transformar grandes conjuntos de dados com nós Code ou usar fluxos de trabalho com muitas ramificações paralelas.

A solução: N8N_PAYLOAD_SIZE_MAX

A correção é simples, mas requer entender os recursos disponíveis do seu servidor.

Configurações recomendadas por quantidade de RAM do servidor

RAM do servidorN8N_PAYLOAD_SIZE_MAXValor a definir (MiB)Percentual da RAM
2GB ou menos64MB64~3%
4GB128MB128~3%
8GB256MB256~3%
16GB+512MB512~3%

Regra geral: Use menos de 20% da sua RAM disponível para manter o sistema estável sob carga.

Implementação com Docker Compose

version: '3.8'

services:
  n8n:
    image: n8nio/n8n:latest
    container_name: n8n
    restart: unless-stopped
    ports:
      - "5678:5678"
    environment:
      - N8N_PORT=5678

      # Payload size fix (256MB for 8GB+ RAM servers; value in MiB)
      - N8N_PAYLOAD_SIZE_MAX=256

      # Binary data optimization (highly recommended)
      - N8N_DEFAULT_BINARY_DATA_MODE=filesystem
      - N8N_BINARY_DATA_TTL=1440  # 24 hours

    volumes:
      - n8n_data:/home/node/.n8n

    # Resource limits (adjust based on your server)
    deploy:
      resources:
        limits:
          memory: 2G
        reservations:
          memory: 1G

volumes:
  n8n_data:

Entendendo o modo de armazenamento de dados binários

Padrão: armazenamento em memória (não recomendado)

# This is the default - DON'T use in production
N8N_DEFAULT_BINARY_DATA_MODE=default

Problemas: Armazena arquivos (imagens, PDFs etc.) na RAM, desperdiça memória valiosa, não é adequado para cargas de trabalho de produção e limita a quantidade de arquivos que você pode processar.

Nos nossos testes, o modo padrão usou ~315 MB de RAM em repouso, contra 211 MB no modo de sistema de arquivos — ou seja, ~100 MB a menos de memória em repouso.

Recomendado: armazenamento no sistema de arquivos

N8N_DEFAULT_BINARY_DATA_MODE=filesystem
N8N_BINARY_DATA_TTL=1440  # Clean up after 24 hours (value in minutes)

Benefícios: Armazena arquivos em disco em vez de na RAM, oferece desempenho significativamente melhor com arquivos grandes, está pronto para produção e é recomendado pelo n8n. Observe que N8N_BINARY_DATA_TTL não tem efeito desde o n8n 1.9.0: o n8n exclui os dados binários ao limpar as execuções, portanto as configurações de limpeza de execuções controlam o uso do disco.

Importante: Se você usa o modo de fila (execução distribuída baseada em Redis), observe que o n8n não oferece suporte ao modo de sistema de arquivos nesse caso. Em outubro de 2026, a documentação do n8n recomenda o modo database para o modo de fila.

Impacto na prática

Nos nossos testes com Docker em outubro de 2025, com o n8n versão 1.115.2:

ConfiguraçãoUso de memóriaDiferença
Padrão (sem correções)315 MBLinha de base
Com correção do payload + modo filesystem211 MB-104 MB

Principal descoberta: Nas nossas medições em repouso, a configuração com a correção de payload e o modo binário de sistema de arquivos usou menos memória que a padrão. Não medimos a memória sob carga com payloads grandes, situação em que o uso depende dos seus fluxos de trabalho.

Correção #2: problemas de URL de webhook

O problema em detalhe

Ao gerar URLs de webhook para exibir no editor e registrar nos serviços externos, o n8n tenta detectar automaticamente sua URL pública. Atrás de um proxy reverso, essa detecção falha completamente.

O que você verá (as URLs incorretas)

http://n8n.yourdomain.com:5678/webhook/abc123

Problemas com essa URL:

  1. Número de porta incluído (:5678) — serviços externos geralmente não conseguem acessar portas não padrão
  2. Protocolo incorreto (http em vez de https) — muitos serviços exigem HTTPS
  3. Nome de host interno — pode ser o nome do contêiner Docker em vez do domínio público

Por que os serviços externos falham

Serviços como GitHub, Slack, Stripe, Zoom, Google Sheets e centenas de outros tentam enviar webhooks a essas URLs incorretas e falham silenciosamente. Você configura a integração, ela parece correta na interface, mas as notificações nunca chegam.

A solução: variável de ambiente WEBHOOK_URL

De acordo com a documentação oficial do n8n:

“A variável de ambiente WEBHOOK_URL é usada para definir manualmente a URL do webhook para que o n8n possa exibi-la na interface do editor e registrar as URLs corretas de webhook nos serviços externos. Ao executar o n8n atrás de um proxy reverso, é importante definir essa variável.”

Configuração básica

environment:
  - WEBHOOK_URL=https://n8n.yourdomain.com
  - N8N_EDITOR_BASE_URL=https://n8n.yourdomain.com
  - N8N_PROTOCOL=https
  - N8N_HOST=n8n.yourdomain.com
  - N8N_TRUST_PROXY_HEADER=true
  - N8N_PROXY_HOPS=1

O que cada variável faz

WEBHOOK_URL (A MAIS IMPORTANTE)

  • A URL pública de todos os endpoints de webhook
  • Usada ao registrar webhooks nos serviços externos
  • Deve corresponder exatamente à configuração do Traefik ou do proxy reverso
  • Nota sobre a versão: Renomeada de WEBHOOK_TUNNEL_URL na v0.227.0; o nome antigo foi removido no n8n 1.0

N8N_EDITOR_BASE_URL

  • A URL de acesso à interface web do n8n
  • Geralmente igual à WEBHOOK_URL
  • Aparece na barra de endereços do navegador e nos convites por e-mail

N8N_PROTOCOL

  • Defina como https para produção (com SSL/TLS)
  • Defina como http apenas para testes locais
  • Deve corresponder ao protocolo cuja conexão é terminada no proxy reverso

N8N_HOST

  • Apenas o nome do seu domínio público
  • Não inclua o protocolo (https://) nem a porta
  • Exemplo: n8n.yourdomain.com e não https://n8n.yourdomain.com:443

N8N_TRUST_PROXY_HEADER

  • Não é uma variável documentada do n8n: ela não aparece na referência de variáveis de ambiente do n8n, portanto defini-la não tem efeito documentado
  • A confiança nos cabeçalhos do proxy (para os endereços IP reais dos clientes) é controlada por N8N_PROXY_HOPS
  • Você pode omiti-la nos exemplos deste guia

N8N_PROXY_HOPS

  • Defina como 1 quando houver um proxy reverso
  • Defina como 2 se houver dois proxies (raro)
  • Informa ao n8n em quantas camadas de proxy confiar

Testando URLs de webhook

Antes da correção

Na interface do n8n, crie um nó Webhook e verifique a URL exibida:

http://n8n.example.com:5678/webhook/abc123  ❌ Wrong

Após a correção

O mesmo nó Webhook agora exibe:

https://n8n.example.com/webhook/abc123  ✅ Correct

Diferença crucial: Os serviços externos agora conseguem acessar essa URL porque ela usa a porta HTTPS padrão 443 (gerenciada pelo seu proxy reverso) em vez da porta interna 5678.

Configuração completa de produção com Traefik

Por que Traefik?

O Traefik é um proxy reverso moderno perfeitamente adequado para implantações Docker — HTTPS automático via Let's Encrypt sem gerenciamento manual de certificados, descoberta de serviços que detecta automaticamente contêineres por meio de rótulos do Docker, suporte nativo a WebSocket para a conexão em tempo real do editor do n8n, configuração fácil apenas com rótulos do Docker em vez de arquivos de configuração complexos e um painel integrado para monitorar o roteamento e os certificados em tempo real.

Visão geral da arquitetura

Internet
  ↓
[Traefik Reverse Proxy]
  ↓ HTTPS (Let's Encrypt)
  ↓ WebSocket Support
[Contêiner n8n]
  ↓ Rede interna
[Banco de dados PostgreSQL]

Suporte a WebSocket

O Traefik encaminha conexões WebSocket nativamente, incluindo a conexão em tempo real usada pelo editor do n8n, portanto não é necessário middleware adicional. Webhooks são requisições HTTPS comuns e não dependem de WebSocket. O exemplo de produção abaixo inclui rótulos opcionais de cabeçalhos WebSocket; você pode omiti-los.

Docker Compose completo para produção

Esta configuração combina ambas as correções, inclui o Traefik com suporte adequado a WebSocket e segue boas práticas de produção:

version: '3.8'

networks:
  traefik-net:
    external: true
  n8n-internal:
    internal: true

services:
  # PostgreSQL Database
  postgres:
    image: postgres:16-alpine
    container_name: n8n-postgres
    restart: unless-stopped
    networks:
      - n8n-internal
    environment:
      - POSTGRES_USER=n8n
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=n8n
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U n8n"]
      interval: 10s
      timeout: 5s
      retries: 5
    deploy:
      resources:
        limits:
          memory: 512M

  # n8n Application
  n8n:
    image: n8nio/n8n:latest
    container_name: n8n
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    networks:
      - traefik-net
      - n8n-internal

    # Traefik Configuration Labels
    labels:
      # Enable Traefik for this container
      - "traefik.enable=true"
      - "traefik.docker.network=traefik-net"

      # Router configuration
      - "traefik.http.routers.n8n.rule=Host(`${N8N_DOMAIN}`)"
      - "traefik.http.routers.n8n.entrypoints=websecure"
      - "traefik.http.routers.n8n.tls.certresolver=letsencrypt"

      # Service configuration
      - "traefik.http.services.n8n.loadbalancer.server.port=5678"

      # Middleware: Request size limit in bytes (256MB, matches N8N_PAYLOAD_SIZE_MAX)
      - "traefik.http.middlewares.n8n-buffering.buffering.maxRequestBodyBytes=268435456"

      # Middleware: WebSocket headers (optional; Traefik proxies WebSockets natively)
      - "traefik.http.middlewares.n8n-websocket.headers.customrequestheaders.Upgrade=websocket"
      - "traefik.http.middlewares.n8n-websocket.headers.customrequestheaders.Connection=Upgrade"

      # Middleware: Security headers
      - "traefik.http.middlewares.n8n-security.headers.customResponseHeaders.X-Robots-Tag=noindex,nofollow"
      - "traefik.http.middlewares.n8n-security.headers.sslProxyHeaders.X-Forwarded-Proto=https"

      # Apply ALL middlewares
      - "traefik.http.routers.n8n.middlewares=n8n-buffering,n8n-websocket,n8n-security"

    environment:
      # Database Configuration
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_PORT=5432
      - DB_POSTGRESDB_DATABASE=n8n
      - DB_POSTGRESDB_USER=n8n
      - DB_POSTGRESDB_PASSWORD=${DB_PASSWORD}

      # FIX #2: Webhook URL Configuration
      - WEBHOOK_URL=https://${N8N_DOMAIN}
      - N8N_EDITOR_BASE_URL=https://${N8N_DOMAIN}
      - N8N_PROTOCOL=https
      - N8N_HOST=${N8N_DOMAIN}
      - N8N_PORT=5678
      - N8N_TRUST_PROXY_HEADER=true
      - N8N_PROXY_HOPS=1

      # FIX #1: Payload Size Configuration
      - N8N_PAYLOAD_SIZE_MAX=256  # 256 MiB

      # Binary Data Management
      - N8N_DEFAULT_BINARY_DATA_MODE=filesystem
      - N8N_BINARY_DATA_TTL=1440  # 24 hours

      # 2025 Requirement: Task Runners
      - N8N_RUNNERS_ENABLED=true
      - N8N_RUNNERS_MODE=internal
      - N8N_RUNNERS_MAX_CONCURRENCY=5

      # Production Optimizations
      - NODE_ENV=production
      - EXECUTIONS_DATA_MAX_AGE=168  # 7 days
      - EXECUTIONS_DATA_PRUNE_MAX_COUNT=1000
      - N8N_LOG_LEVEL=info
      - N8N_LOG_OUTPUT=console

      # Timezone (adjust to your location)
      - GENERIC_TIMEZONE=America/New_York
      - TZ=America/New_York

      # Security
      - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}

    volumes:
      - n8n_data:/home/node/.n8n

    # Resource Limits (8GB+ RAM server)
    deploy:
      resources:
        limits:
          memory: 2G
          cpus: '2.0'
        reservations:
          memory: 1G
          cpus: '1.0'

    # Health Check
    healthcheck:
      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:5678/healthz"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

volumes:
  n8n_data:
  postgres_data:

Configuração do Traefik

Se o Traefik ainda não estiver em execução, veja a configuração completa:

Etapa 1: crie a rede do Traefik

docker network create traefik-net

Etapa 2: crie a configuração do Traefik

Crie traefik/traefik.yml:

api:
  dashboard: 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]  # CHANGE THIS
      storage: /letsencrypt/acme.json
      httpChallenge:
        entryPoint: web

log:
  level: INFO

accessLog: {}

Etapa 3: crie o Docker Compose do Traefik

Crie traefik/docker-compose.yml:

version: '3.8'

networks:
  traefik-net:
    external: true

services:
  traefik:
    image: traefik:v2.10
    container_name: traefik
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
    networks:
      - traefik-net
    ports:
      - "80:80"
      - "443:443"
      - "8080:8080"  # Dashboard (secure this in production!)
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./traefik.yml:/traefik.yml:ro
      - ./letsencrypt:/letsencrypt
    labels:
      - "traefik.enable=true"

Etapa 4: crie o arquivo de variáveis de ambiente

Crie .env no seu diretório do n8n:

# Domain Configuration
N8N_DOMAIN=n8n.yourdomain.com

# Database Password (generate secure password)
DB_PASSWORD=your_secure_db_password_here

# n8n Encryption Key (generate random string)
N8N_ENCRYPTION_KEY=your_encryption_key_here

Gere valores seguros:

# For DB_PASSWORD
openssl rand -base64 32

# For N8N_ENCRYPTION_KEY
openssl rand -hex 32

Etapa 5: inicie tudo

# Start Traefik first
cd traefik
docker compose up -d

# Wait a few seconds, then start n8n
cd ../n8n
docker compose up -d

# Watch logs to verify startup
docker compose logs -f n8n

Verificando sua configuração

Verifique o painel do Traefik

Acesse http://your-server-ip:8080. Isso só funciona se você também definir api.insecure: true em traefik.yml (apenas para testes); caso contrário, configure um roteador para o painel (api@internal) em um domínio próprio.

Deve mostrar:

  • ✅ Roteador do n8n ativo, com status verde
  • ✅ Certificado obtido do Let's Encrypt
  • ✅ Serviço marcado como íntegro

Verifique o acesso ao n8n

Acesse https://n8n.yourdomain.com

Deve mostrar:

  • ✅ HTTPS funcionando com certificado válido do Let's Encrypt
  • ✅ Nenhum aviso de segurança do navegador
  • ✅ Página de login ou configuração do n8n exibida corretamente

Verifique as URLs de webhook

  1. Entre no n8n
  2. Crie um novo fluxo de trabalho
  3. Adicione um nó Webhook
  4. Verifique a “Production URL” exibida

Esperado:

https://n8n.yourdomain.com/webhook/abc123

NÃO deve ser assim (indica configuração incorreta):

http://n8n.yourdomain.com:5678/webhook/abc123  ❌

Requisito de 2025: task runners

O que são task runners?

Os task runners executam código definido em nós Code dentro de processos isolados em vez do processo principal do n8n. Isso proporciona melhor segurança por meio de ambientes isolados (sandbox), maior estabilidade, pois erros de código não encerram o processo principal, e compatibilidade futura, pois serão obrigatórios em versões futuras do n8n.

Por que isso importa agora

Da documentação oficial do n8n:

“Executar o n8n sem task runners está obsoleto. Os task runners serão habilitados por padrão em uma versão futura. É aconselhável definir N8N_RUNNERS_ENABLED=true agora para evitar possíveis problemas no futuro.”

Dos logs dos nossos testes (outubro de 2025):

There are deprecations related to your environment variables:
 - N8N_RUNNERS_ENABLED -> Running n8n without task runners is deprecated.

Configuração

Modo interno (recomendado para um único servidor)

environment:
  - N8N_RUNNERS_ENABLED=true
  - N8N_RUNNERS_MODE=internal
  - N8N_RUNNERS_MAX_CONCURRENCY=5

O n8n inicia o task runner como um processo filho — é a configuração mais simples, não exige infraestrutura adicional, é adequada para a maioria das implantações auto-hospedadas e tem impacto mínimo no desempenho. Em outubro de 2026, a documentação do n8n descreve o modo interno como inseguro por concepção e o descontinua a partir do n8n 3.0.

Modo externo (para configurações distribuídas)

environment:
  - N8N_RUNNERS_ENABLED=true
  - N8N_RUNNERS_MODE=external
  - N8N_RUNNERS_AUTH_TOKEN=your_secure_token

Contêineres separados de task runners oferecem melhor isolamento de recursos para fluxos de trabalho de alto volume e permitem escalabilidade horizontal em múltiplos servidores, e são executados como um contêiner sidecar a partir da imagem n8nio/runners, cuja versão deve corresponder à da sua imagem do n8n. Uma configuração com Docker Compose é suficiente; Docker Swarm ou Kubernetes não são necessários.

Verificando os task runners

Verifique a lista de processos

docker exec n8n ps aux

Sem task runners (3 processos):

PID   USER     TIME  COMMAND
    1 node      0:00 tini -- /docker-entrypoint.sh
    7 node      0:12 node /usr/local/bin/n8n

Com task runners (4 processos):

PID   USER     TIME  COMMAND
    1 node      0:00 tini -- /docker-entrypoint.sh
    7 node      0:16 node /usr/local/bin/n8n
   18 node      0:10 node [...]/task-runner/dist/start.js

Evidência: processo do task runner visível com PID 18.

Verifique os logs

docker logs n8n | grep -i runner

Deve aparecer:

n8n Task Broker ready on 127.0.0.1, port 5679
Registered runner "JS Task Runner" (zCWpF0Eb_LJsqWYvLm5t1)

Impacto no uso de recursos

Nos nossos testes com Docker (outubro de 2025, n8n versão 1.115.2):

ConfiguraçãoMemóriaCPUProcessos
Sem task runners214 MB0,14%3
Com task runners289 MB0,29%4
Diferença+75 MB+0,15%+1

O consumo adicional é mínimo. Os benefícios — segurança, estabilidade e compatibilidade futura — superam em muito esse pequeno custo de recursos.

Referência de variáveis de ambiente

Lista completa de variáveis

VariávelTipoPadrãoFinalidadePrioridade
Variáveis críticas
WEBHOOK_URLString–URL pública de webhookOBRIGATÓRIA com proxy reverso
N8N_PAYLOAD_SIZE_MAXNúmero16 (MiB)Tamanho máximo do corpo das requisições em MiB, incluindo dados de execução parcialOBRIGATÓRIA para grandes volumes de dados
N8N_RUNNERS_ENABLEDBooleanofalseHabilitar task runnersRecomendado na versão 1.x (desnecessário a partir do n8n 2.0)
N8N_TRUST_PROXY_HEADER––Não consta nas variáveis documentadas do n8nDesnecessário; use N8N_PROXY_HOPS
Configuração de webhooks
N8N_EDITOR_BASE_URLString–URL da interface do editorRecomendada
N8N_PROTOCOLStringhttpProtocolo (http/https)Produção
N8N_HOSTStringlocalhostNome de host públicoProdução
N8N_PORTNúmero5678Porta internaOpcional
N8N_PROXY_HOPSNúmero0Número de proxies reversosDefinir como 1 com proxy
Desempenho
N8N_DEFAULT_BINARY_DATA_MODEStringdefaultModo de armazenamento de dados bináriosRecomendada
N8N_BINARY_DATA_TTL––Sem efeito desde o n8n 1.9.0 (dados binários são limpos junto com as execuções)Pode ser removido
Task runners
N8N_RUNNERS_MODEStringinternalModo do task runnerSe os runners estiverem habilitados
N8N_RUNNERS_MAX_CONCURRENCYNúmero10Máximo de tarefas simultâneas por runnerOpcional

Configurações predefinidas por cenário

Cenário A: desenvolvimento (máquina local)

environment:
  - N8N_PORT=5678

Use quando: Estiver testando localmente, sem proxy reverso e sem requisitos de produção

Cenário B: atrás de um proxy reverso (sem grandes volumes de dados)

environment:
  - N8N_PORT=5678
  - WEBHOOK_URL=https://n8n.yourdomain.com
  - N8N_EDITOR_BASE_URL=https://n8n.yourdomain.com
  - N8N_PROTOCOL=https
  - N8N_HOST=n8n.yourdomain.com
  - N8N_TRUST_PROXY_HEADER=true
  - N8N_PROXY_HOPS=1
  - N8N_RUNNERS_ENABLED=true

Use quando: A instância do n8n for pública, precisar de webhooks e usar fluxos de trabalho menores

Cenário C: configuração completa de produção

environment:
  # Database
  - DB_TYPE=postgresdb
  - DB_POSTGRESDB_HOST=postgres
  - DB_POSTGRESDB_PORT=5432
  - DB_POSTGRESDB_DATABASE=n8n
  - DB_POSTGRESDB_USER=n8n
  - DB_POSTGRESDB_PASSWORD=${DB_PASSWORD}

  # Webhooks
  - WEBHOOK_URL=https://n8n.yourdomain.com
  - N8N_EDITOR_BASE_URL=https://n8n.yourdomain.com
  - N8N_PROTOCOL=https
  - N8N_HOST=n8n.yourdomain.com
  - N8N_PORT=5678
  - N8N_TRUST_PROXY_HEADER=true
  - N8N_PROXY_HOPS=1

  # Performance
  - N8N_PAYLOAD_SIZE_MAX=256  # 256 MiB
  - N8N_DEFAULT_BINARY_DATA_MODE=filesystem
  - N8N_BINARY_DATA_TTL=1440

  # Task Runners
  - N8N_RUNNERS_ENABLED=true
  - N8N_RUNNERS_MODE=internal
  - N8N_RUNNERS_MAX_CONCURRENCY=5

  # Production
  - NODE_ENV=production
  - EXECUTIONS_DATA_MAX_AGE=168  # 7 days
  - EXECUTIONS_DATA_PRUNE_MAX_COUNT=1000
  - N8N_LOG_LEVEL=info

  # Security
  - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}

Use quando: A implantação em produção usar todos os recursos, grandes fluxos de trabalho e acesso público

Exemplos de Docker Compose

Todos os quatro cenários do nosso ambiente de testes estão disponíveis. Essas configurações foram validadas com o n8n versão 1.115.2 em outubro de 2025. Os exemplos usam a tag de imagem latest; fixe n8nio/n8n:1.115.2 para reproduzir a versão testada.

Comparação do uso de recursos (dos nossos testes)

CenárioMemóriaCPUProcessosDescrição
Padrão315 MB0,00%3Sem correções, linha de base
Correção do payload211 MB0,00%3Payload + modo filesystem
Correção de webhook215 MB0,14%3Apenas configuração de webhook
Produção289 MB0,29%4Todas as correções + task runners

Principal descoberta: Em repouso, a configuração de produção com todas as correções usou menos memória que a configuração padrão nos nossos testes. São medições em repouso, não resultados sob carga com payloads grandes.

Testando sua configuração

Lista de verificação antes da implantação

1. Configuração de DNS

# Verify DNS points to your server
nslookup n8n.yourdomain.com

# Should return your server's public IP

2. Disponibilidade das portas

# Check if required ports are free
sudo netstat -tlnp | grep -E '(80|443|5678)'

# Should show nothing or only Traefik on 80/443

3. Instalação do Docker

# Verify Docker
docker --version

# Verify Docker Compose
docker compose version

4. Variáveis de ambiente

# Verify .env file exists
cat .env

# Should show N8N_DOMAIN, DB_PASSWORD, N8N_ENCRYPTION_KEY

Etapas de implantação

# Step 1: Create Traefik network
docker network create traefik-net

# Step 2: Start Traefik
cd traefik
docker compose up -d

# Step 3: Wait for Traefik to be ready
sleep 10

# Step 4: Start n8n
cd ../n8n
docker compose up -d

# Step 5: Watch logs for any errors
docker compose logs -f n8n

Testes após a implantação

Teste 1: acesso por HTTPS

curl -I https://n8n.yourdomain.com

Esperado: HTTP/2 200 (ou HTTP/1.1 200)

Teste 2: redirecionamento de HTTP para HTTPS

curl -I http://n8n.yourdomain.com

Esperado: HTTP/1.1 308 Permanent Redirect com Location: https://n8n.yourdomain.com

Teste 3: integridade dos contêineres

docker ps

Esperado: Tanto n8n quanto n8n-postgres devem mostrar o status (healthy) 

Teste 4: formato da URL de webhook

  1. Entre na interface web do n8n
  2. Crie um novo fluxo de trabalho
  3. Adicione um nó Webhook
  4. Verifique a Production URL exibida

Formato esperado:

https://n8n.yourdomain.com/webhook/abc123

NÃO esperado (erro de configuração):

http://n8n.yourdomain.com:5678/webhook/abc123  ❌

Teste 5: task runners ativos

docker logs n8n | grep -i runner

Saída esperada:

Registered runner "JS Task Runner"

Teste 6: variáveis de ambiente aplicadas

docker exec n8n env | grep N8N_PAYLOAD_SIZE_MAX

Esperado: N8N_PAYLOAD_SIZE_MAX=256

Solução de problemas comuns

Problema: HTTPS não funciona

Sintomas: O navegador mostra o aviso “Não seguro”, há mensagens de erro de certificado e não é possível acessar por HTTPS

Diagnóstico:

# Check Traefik logs for errors
docker logs traefik | grep -i error

# Check certificate file exists
ls -la traefik/letsencrypt/acme.json

# Verify DNS resolution
nslookup n8n.yourdomain.com

Soluções:

  1. DNS não aponta para o servidor: Atualize seu registro DNS A para apontar para o IP público do servidor, aguarde a propagação do DNS (até 24 horas, geralmente muito mais rápida) e teste a partir de outra rede: dig n8n.yourdomain.com +short
  2. Porta 80 bloqueada: O Let's Encrypt precisa da porta 80 para o desafio HTTP. Verifique o firewall: sudo ufw status. Libere as portas se estiverem bloqueadas: sudo ufw allow 80/tcp && sudo ufw allow 443/tcp
  3. E-mail inválido na configuração do Traefik: Edite traefik/traefik.yml, atualize certificatesResolvers.letsencrypt.acme.email para um endereço válido e reinicie o Traefik: docker compose restart

Problema: webhooks retornam 404

Sintomas: Serviços externos relatam falhas de webhook, as URLs de webhook parecem corretas, mas não funcionam, e o modo de teste funciona, mas o de produção falha

Diagnóstico:

# Test webhook directly
curl -v https://n8n.yourdomain.com/webhook/test

# Check Traefik routing logs
docker logs traefik | grep webhook

# Verify n8n sees requests
docker logs n8n | grep webhook

Soluções:

  1. WEBHOOK_URL não definida corretamente: Verifique a variável de ambiente: docker exec n8n env | grep WEBHOOK_URL. Deve corresponder exatamente ao seu domínio: WEBHOOK_URL=https://n8n.yourdomain.com
  2. Configuração de rede incorreta: Verifique se o n8n está na rede traefik-net: docker inspect n8n | grep -A 5 Networks. A saída deve mostrar “traefik-net”

Problema: “Execution Data Too Large” ainda aparece

Sintomas: O erro ainda ocorre após definir N8N_PAYLOAD_SIZE_MAX e grandes fluxos de trabalho falham em “Execute Node”

Diagnóstico:

# Verify variable is set
docker exec n8n env | grep PAYLOAD

# Should show N8N_PAYLOAD_SIZE_MAX=256

Soluções:

  1. Variável não aplicada (contêiner não recriado): Recrie o contêiner para aplicar as alterações: docker compose up -d n8n (docker compose restart não aplica valores de ambiente alterados). Verifique depois: docker exec n8n env | grep PAYLOAD
  2. Seu fluxo de trabalho precisa de um limite maior: Para servidores com 16GB+ de RAM, aumente para 512MB: N8N_PAYLOAD_SIZE_MAX=512
  3. Limite de tamanho da requisição no Traefik muito baixo: Aumente também o limite do Traefik (em bytes) para corresponder: "traefik.http.middlewares.n8n-buffering.buffering.maxRequestBodyBytes=536870912"

Problema: uso elevado de memória

Sintomas: O contêiner usa >1,5GB de RAM quando ocioso, o uso de memória cresce com o tempo e ocorrem erros de falta de memória

Diagnóstico:

# Monitor memory
docker stats n8n

# Check binary data mode
docker exec n8n env | grep BINARY_DATA_MODE

Soluções:

  1. Não está usando o modo de sistema de arquivos: Adicione ao ambiente: N8N_DEFAULT_BINARY_DATA_MODE=filesystem. Impacto: ~100 MB a menos de memória em repouso nos nossos testes
  2. Execuções antigas se acumulando: Reduza o período de retenção: EXECUTIONS_DATA_MAX_AGE=168 (7 dias em vez de 14) e EXECUTIONS_DATA_PRUNE_MAX_COUNT=1000
  3. Limite do contêiner muito baixo: Aumente se o servidor tiver capacidade. Altere o limite de memória de 2G para 4G na seção de recursos de implantação

Conclusão

O que resolvemos

Este guia abrangente aborda os dois problemas mais comuns do n8n auto-hospedado:

  1. ✅ Erro de dados de execução muito grandes — Corrigido com N8N_PAYLOAD_SIZE_MAX e modo de armazenamento de dados binários filesystem
  2. ✅ Problemas de URL de webhook — Corrigidos com WEBHOOK_URL e configuração adequada de proxy reverso

Além destas adições críticas:

  1. ✅ Configuração completa do Traefik — Configuração pronta para produção com suporte a WebSocket
  2. ✅ Configuração de task runners — Requisito de 2025 para compatibilidade futura
  3. ✅ Boas práticas de produção — Limites de recursos, verificações de integridade, cabeçalhos de segurança e monitoramento
  4. ✅ Configurações validadas — Todos os arquivos docker-compose testados com n8n 1.115.2 em outubro de 2025

Principais conclusões

Para correções rápidas:

  • Defina N8N_PAYLOAD_SIZE_MAX=256 para problemas de dados de execução (256MB para servidores com 8GB+ de RAM)
  • Defina WEBHOOK_URL=https://your-domain.com para problemas de webhook
  • Defina N8N_RUNNERS_ENABLED=true para eliminar avisos de descontinuação
  • Use N8N_DEFAULT_BINARY_DATA_MODE=filesystem (cerca de 100 MB a menos de memória em repouso nos nossos testes)

Para implantação em produção:

  • Use nosso docker-compose.yml completo com a configuração do Traefik
  • Não é necessário middleware WebSocket — o Traefik encaminha WebSocket nativamente, e webhooks são requisições HTTPS comuns
  • Inclua PostgreSQL para melhorar o desempenho sob carga
  • Defina limites de recursos adequados com base na capacidade do seu servidor
  • Implemente verificações de integridade para que o monitoramento e os serviços dependentes detectem falhas (o Docker por si só marca um contêiner como não saudável, mas não o reinicia)

Para usuários do Traefik (CRÍTICO):

  • O Traefik gerencia WebSocket sem middleware adicional; os webhooks precisam de um roteador correto e de WEBHOOK_URL
  • Defina o limite de tamanho do corpo da requisição para corresponder ou superar o tamanho do payload
  • Configure cabeçalhos de segurança (X-Robots-Tag, X-Forwarded-Proto)
  • Garanta que o DNS aponte para seu servidor antes de iniciar o Traefik (requisito do Let's Encrypt)

O que há de novo em relação aos artigos de junho de 2025

RecursoArtigos de junho de 2025Este guia
Correção dos dados de execução✅ Detalhada✅ Incluída + medições de recursos
Correção de webhook✅ Detalhada✅ Incluída + integração com Traefik
Configuração do Traefik❌ Não abordada✅ Configuração completa
Suporte a WebSocket❌ Não abordado✅ Enfatizado
Task runners❌ Não abordados✅ Requisito de 2025
docker-compose combinado❌ Separados✅ Pronto para produção
Medições de recursos❌ Teóricas✅ Dados reais de testes
Variáveis de ambiente✅ Abordadas✅ Referência completa

Testes e validação

Nosso ambiente de testes (outubro de 2025):

  • ✅ n8n versão 1.115.2
  • ✅ Contêineres Docker em execução por 2+ horas
  • ✅ Todas as variáveis de ambiente verificadas nos contêineres em execução
  • ✅ Uso de recursos medido com docker stats
  • ✅ Processo do task runner confirmado na lista de processos
  • ✅ Endpoints HTTP testados e acessíveis
  • ✅ Configurações validadas como funcionais

Próximas etapas

  1. Escolha seu cenário:
    • Desenvolvimento: configuração mínima
    • Atrás de um proxy reverso: correção de webhook + task runners
    • Produção: configuração completa com Traefik (recomendado)
  2. Implante:
    • Copie o docker-compose.yml adequado
    • Crie o arquivo .env com seu domínio e senhas seguras
    • Inicie primeiro o Traefik e depois o n8n
    • Execute os testes após a implantação
  3. Valide:
    • Verifique se o HTTPS funciona com um certificado válido
    • Verifique se as URLs de webhook têm o formato correto
    • Teste com um grande conjunto de dados (se necessário)
    • Confirme que os task runners estão registrados
  4. Monitore:
    • Acompanhe o uso de recursos com docker stats
    • Configure alertas de verificação de integridade (monitoramento externo)
    • Implemente rotação de logs para evitar que o disco fique cheio
    • Planeje backups regulares dos volumes de dados

Recursos relacionados

De junho de 2025:

Documentação oficial do n8n:

Dúvidas ou problemas?

Se você encontrar problemas não abordados neste guia:

  1. Consulte nossos artigos detalhados de solução de problemas de junho de 2025 para obter orientações adicionais
  2. Consulte a documentação oficial do n8n para conhecer os recursos mais recentes
  3. Pesquise nos fóruns da comunidade n8n por problemas semelhantes
  4. Consulte a seção de solução de problemas acima para problemas comuns
  5. Entre em contato com a tva para obter suporte profissional de implementação

Testes reproduzíveis

Todas as configurações deste guia podem ser reproduzidas no seu próprio ambiente — os arquivos Docker Compose estão prontos para produção, as variáveis de ambiente estão documentadas e verificadas, os comandos de teste são fornecidos para validação e as saídas esperadas estão claramente especificadas. Você pode validar todas as afirmações deste guia implantando as configurações e executando os testes fornecidos.

Precisa de ajuda com a implementação?

Se você gostaria que a tva cuidasse da sua implantação do n8n ou precisa de assistência com a configuração de produção, entre em contato conosco. Implementamos essas configurações para organizações que buscam infraestrutura n8n confiável e pronta para produção.

Publicado: 15 de outubro de 2025
Testado com: n8n v1.115.2, Docker Compose v3.8, Traefik v2.10
Requisitos do servidor: 4GB+ de RAM, 2+ núcleos de CPU recomendados para produção
Baseado em: Documentação oficial do n8n, testes Docker validados e boas práticas da comunidade

Leitura complementar

Corrigindo problemas de webhook do n8n: guia completo para instâncias auto-hospedadas

Resolvendo o erro “Existing execution data is too large” do n8n: a correção completa para instâncias auto-hospedadas

n8n 2.x auto-hospedado: diagnostique os limites dos dados de execução e aumente o payload com segurança