tva
← Insights

Guia Completo de Solução de Problemas do n8n Auto-Hospedado 2025: Corrigindo Tamanho de Dados de Execução e Problemas de Webhook com Traefik

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

Auto-hospedar o n8n oferece execuções ilimitadas de workflows, controle completo dos dados e economia significativa em comparação com planos na nuvem. Mas, na realidade, instâncias auto-hospedadas enfrentam desafios únicos que usuários da nuvem nunca encontram – especificamente em relação ao manuseio de grandes 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 existia nenhum guia abrangente para implantações de produção do n8n com proxy reverso Traefik que abordasse ambas as questões em conjunto.

Este guia combina ambas as correções originais, fornece configuração completa do Traefik com suporte a WebSocket, inclui os novos requisitos de task runners de 2025 e entrega 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 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 workflows
  • Testa workflows 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 da: Correção #1: Tamanho de Dados de Execução

Sintoma: Webhooks mostram URLs incorretas ou falham ao funcionar

Você vê isso quando:

  • URLs de webhook exibem 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 da: Correção #2: Configuração de URL de Webhook

Sintoma: Avisos de depreciaçã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 da: 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
  • Melhores 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 o n8n Cloud Não Tem Esses Problemas

O n8n Cloud lida automaticamente com limites de memória mais altos para execução parcial, URLs de webhook corretas, armazenamento otimizado de dados binários e atualizações automáticas incluindo todos os novos requisitos. Quando você auto-hospeda, você é responsável por essas configurações.

As Causas Raiz

Problema #1: Limite de Tamanho de Dados de Execução

O limite padrão de 16MB para dados de execução parcial enviados ao backend dispara erros ao trabalhar com grandes conjuntos de dados, muitas ramificações de workflow ou transformações complexas. O problema é que o desenvolvimento de workflows 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 URL de Webhook

O n8n tenta auto-detectar sua URL pública, mas essa auto-detecção falha quando atrás de um proxy reverso. Serviços externos recebem URLs de webhook incorretas com portas ou nomes de host internos – integrações quebram 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 workflow (clicando "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 transferência de dados a 16MB para evitar problemas de memória em servidores menores.

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 workflows 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 RAM do Servidor

RAM do ServidorN8N_PAYLOAD_SIZE_MAXValor em BytesPercentual da RAM
2GB ou menos64MB67108864~3%
4GB128MB134217728~3%
8GB256MB268435456~3%
16GB+512MB536870912~3%

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

Descoberta Principal: A combinação de tamanho de payload aumentado e modo binário filesystem na verdade reduz o uso de memória porque os dados são manuseados mais eficientemente em disco em vez de na RAM.

Correção #2: Problemas de URL de Webhook

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 com serviços externos. Ao executar o n8n atrás de um proxy reverso, é importante definir essa variável."

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 containers via labels do Docker, suporte a WebSocket crítico para funcionalidade de webhooks do n8n, configuração fácil apenas com labels Docker em vez de arquivos de configuração complexos, e um dashboard integrado para monitorar roteamento e certificados em tempo real.

Configuração Crítica: Suporte a WebSocket

Esta é a configuração mais comumente esquecida e causa falhas de webhook:

labels:
  # WebSocket middleware (ABSOLUTELY REQUIRED)
  - "traefik.http.middlewares.n8n-websocket.headers.customrequestheaders.Upgrade=websocket"
  - "traefik.http.middlewares.n8n-websocket.headers.customrequestheaders.Connection=Upgrade"

  # Apply middleware to router
  - "traefik.http.routers.n8n.middlewares=n8n-websocket"

Requisito 2025: Task Runners

O Que São Task Runners?

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 através de ambientes sandboxed, estabilidade aprimorada onde erros de código não derrubam 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 n8n sem task runners está depreciado. Task runners serão habilitados por padrão em uma versão futura. É aconselhável definir N8N_RUNNERS_ENABLED=true agora para evitar potenciais problemas no futuro."

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 binário filesystem
  2. Problemas de URL de Webhook – Corrigido com WEBHOOK_URL e configuração adequada de proxy reverso

Além dessas 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. Melhores Práticas de Produção – Limites de recursos, healthchecks, cabeçalhos de segurança, 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=268435456 para problemas de dados de execução (256MB para servidores com 8GB+ RAM)
  • Defina WEBHOOK_URL=https://your-domain.com para problemas de webhook
  • Defina N8N_RUNNERS_ENABLED=true para eliminar avisos de depreciação
  • Use N8N_DEFAULT_BINARY_DATA_MODE=filesystem para economizar ~100MB de RAM

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+ RAM, 2+ núcleos de CPU recomendados para produção
Baseado Em: Documentação oficial do n8n, testes Docker validados e melhores práticas da comunidade