Pular para o conteúdo principal

N8N

O que é?​

N8N é uma ferramenta opensource de automação workflow (similar ao Zapier, mas self-hosted). Permite criar workflows visuais conectando diferentes serviços via APIs.

Website oficial: https://n8n.io Documentação: https://docs.n8n.io

Função no Sistema​

  • Backend principal: Toda a lógica de negócio fica em workflows N8N
  • Orquestração: Conecta Chatwoot ↔ Dify ↔ APIs externas
  • Processamento de webhooks: Recebe eventos do Chatwoot
  • Automações: Regras de negócio, integrações, notificações

Arquitetura: Queue Mode​

O N8N está configurado em queue mode, que separa a aplicação em diferentes tipos de serviços para melhor escalabilidade:

Componentes​

  1. Editor (1 réplica):

    • Interface web para criar/editar workflows
    • Não processa execuções em produção
    • Apenas para desenvolvimento/configuração

  2. Webhook (10 réplicas):

    • Recebem requisições HTTP dos webhooks
    • Colocam jobs na fila Redis
    • Respondem rapidamente sem processar

  3. Worker (25 réplicas, concurrency: 250):

    • Consomem jobs da fila Redis
    • Executam os workflows
    • Cada worker processa até 250 jobs simultâneos
    • Total teórico: 25 × 250 = 6.250 execuções simultâneas

Por que Queue Mode?​

  • Escalabilidade: Adicionar mais workers aumenta capacidade
  • Resiliência: Se um worker cai, outros continuam processando
  • Performance: Webhooks respondem instantaneamente

URL Editor: https://n8n-queue.incibrasil.com.br

Fluxo de Dados Típico​

1. Chatwoot recebe mensagem do usuário
   ↓
2. Chatwoot dispara webhook para N8N
   ↓
3. N8N Webhook recebe e enfileira no Redis
   ↓
4. N8N Worker pega job da fila
   ↓
5. Worker processa lógica:
   - Verifica se é mensagem de bot ou humano
   - Se for bot, envia para Dify
   - Aguarda resposta do Dify
   - Envia resposta de volta ao Chatwoot
   ↓
6. Chatwoot entrega mensagem ao usuário

Workflows Principais​

1. Processamento de Mensagens​

  • Trigger: Webhook do Chatwoot (novo mensagem)
  • Função: Roteia mensagem para Dify ou processa regras de negócio
  • Output: Resposta enviada de volta ao Chatwoot

2. Transferência para Humano​

  • Trigger: Function call transfer_to_human do Dify
  • Função: Marca conversa como "aberta" e atribui a um agente
  • Output: Notificação ao agente humano

3. Encerramento de Conversa​

  • Trigger: Function call end_conversation do Dify
  • Função: Marca conversa como "resolvida" no Chatwoot
  • Output: Conversa encerrada

4. Busca na Base de Conhecimento​

  • Trigger: Function call search_knowledge_base do Dify
  • Função: Consulta documentos no Dify
  • Output: Contexto retornado para o LLM

Configuração no EasyPanel​

O N8N é instalado via Docker Compose no EasyPanel com 3 serviços separados:

1. N8N Editor​

image: n8nio/n8n:latest
environment:
  - N8N_BASIC_AUTH_ACTIVE=true
  - N8N_BASIC_AUTH_USER=<USER>
  - N8N_BASIC_AUTH_PASSWORD=<PASSWORD>
  - EXECUTIONS_MODE=queue
  - QUEUE_BULL_REDIS_HOST=redis
replicas: 1

2. N8N Webhook​

image: n8nio/n8n:latest
environment:
  - EXECUTIONS_MODE=queue
  - QUEUE_BULL_REDIS_HOST=redis
  - N8N_DISABLE_UI=true
command: webhook
replicas: 10

3. N8N Worker​

image: n8nio/n8n:latest
environment:
  - EXECUTIONS_MODE=queue
  - QUEUE_BULL_REDIS_HOST=redis
  - N8N_DISABLE_UI=true
  - EXECUTIONS_PROCESS=main
command: worker --concurrency=250
replicas: 25

4. Redis (para filas)​

image: redis:alpine

Boas Práticas​

Desenvolvimento​

  • Sempre desenvolva no Editor: Nunca edite workflows diretamente em produção
  • Use variáveis de ambiente: Para API keys e credenciais
  • Teste workflows: Antes de ativar em produção

Monitoramento​

  • Acompanhe a fila Redis: Ver se há backlog
  • Monitore workers: CPU e memória
  • Log de execuções: Verificar erros e falhas

Escalabilidade​

  • Aumente workers primeiro: Mais barato que aumentar webhooks
  • Use concurrency alto: Workers podem processar muitos jobs
  • Otimize workflows: Remova passos desnecessários

Troubleshooting​

Webhook não responde​

  • Causa: Fila Redis cheia ou workers sobrecarregados
  • Solução: Aumentar número de workers ou concurrency

Workflow trava​

  • Causa: Timeout em chamadas externas (Dify, APIs)
  • Solução: Adicionar timeout nos nós HTTP Request

Jobs ficam pending​

  • Causa: Workers não conseguem processar (erro no workflow)
  • Solução: Ver logs dos workers e corrigir erro

Próximos Passos​

  • Consulte Chatwoot para entender como os webhooks são disparados
  • Veja Dify para configurar os agentes de IA
  • Explore Arquitetura Geral para ver como tudo se conecta