n8n com Docker: Fila Redis para Escalabilidade de Workflows

Introdução: Por que Escalar o n8n Self-Hosted?

O n8n tem se consolidado como uma das ferramentas líderes em automação de workflows no ecossistema self-hosted. Sua natureza "fair-code" e sua flexibilidade permitem que equipes de TI, desenvolvedores e até usuários finais criem integrações complexas entre dezenas de serviços sem depender exclusivamente de plataformas SaaS custosas. No entanto, à medida que o número de workflows cresce e a frequência das execuções aumenta, a arquitetura padrão do n8n pode se tornar um gargalo.

Pela configuração padrão, o n8n executa workflows em modo "single-process". Isso significa que ele processa as tarefas sequencialmente. Se você tem um workflow longo ou múltiplos workflows sendo acionados simultaneamente, eles entram em fila na memória do processo principal. Isso pode levar a atrasos, timeouts e, em casos extremos, ao travamento do container Docker devido ao esgotamento de memória (OOM - Out of Memory).

A solução para esse problema é habilitar o modo de execução paralelo utilizando uma fila Redis. Ao configurar o n8n para usar o Redis como backend de fila, desacoplam-se a geração de jobs da sua execução. Isso permite que você escale horizontalmente os workers do n8n, processando múltiplos workflows simultaneamente, melhorando drasticamente a performance e a confiabilidade da sua infraestrutura de automação.

Neste tutorial, vamos guiar você passo a passo na configuração de um ambiente robusto para o n8n utilizando Docker Compose. Integraremos o banco de dados PostgreSQL para persistência de dados (já que o SQLite embutido não escala bem) e o Redis para gerenciar as filas de execução, garantindo que sua automação esteja pronta para produção.

Pré-requisitos e Preparação do Ambiente

Antes de iniciarmos a configuração dos containers, é essencial garantir que seu ambiente atenda aos requisitos mínimos para uma operação estável em produção. A escalabilidade depende diretamente da estabilidade da infraestrutura subjacente.

• Servidor Linux: Recomendamos Ubuntu 22.04 LTS ou Debian 12. O servidor deve ter acesso root ou privilégios de sudo.
• Docker e Docker Compose: Certifique-se de que o Docker Engine está instalado e atualizado. Verifique a versão do Docker Compose (v2 é recomendado).
• Recursos de Hardware: Para começar com escalabilidade, recomendamos um servidor com pelo menos 4 vCPUs e 8GB de RAM. O Redis e o PostgreSQL são intensivos em memória se houver muitos dados.
• Banco de Dados: Utilizaremos o PostgreSQL via Docker para este tutorial, pois ele oferece melhor concorrência e suporte a transações comparado ao SQLite nativo do n8n.

Crie um diretório dedicado para sua configuração. Isso facilita backups e atualizações futuras.

mkdir ~/n8n-scalability
cd ~/n8n-scalability

Etapa 1: Configurando o Docker Compose

O coração da nossa solução será um arquivo docker-compose.yml. Este arquivo definirá os serviços necessários: o próprio n8n, o Redis para a fila e o PostgreSQL para o banco de dados. Vamos configurar tudo isso com variáveis de ambiente seguras e redes isoladas.

Crie o arquivo docker-compose.yml no diretório criado e adicione o seguinte conteúdo. Preste atenção especial às variáveis de ambiente que habilitam a execução paralela.

version: '3.8'

services:
  n8n:
    image: docker.n8n.io/n8nio/n8n
    container_name: n8n-core
    restart: unless-stopped
    ports:
      - "5678:5678"
    environment:
      # Habilita a execução paralela via Redis
      - EXECUTIONS_MODE=queue
      - QUEUE_BULL_REDIS_HOST=redis
      - QUEUE_BULL_REDIS_PORT=6379
      # Configurações de Banco de Dados (PostgreSQL)
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_DATABASE=n8n
      - DB_POSTGRESDB_HOST=db
      - DB_POSTGRESDB_PORT=5432
      - DB_POSTGRESDB_USER=n8n_user
      - DB_POSTGRESDB_PASSWORD=seu_senha_forte_aqui
      # Segurança e Interface
      - N8N_ENCRYPTION_KEY=sua_chave_de_criptografia_aleatoria
      - GENERIC_TIMEZONE=America/Sao_Paulo
    volumes:
      - n8n_data:/home/node/.n8n
    depends_on:
      - redis
      - db
    networks:
      - n8n-network

  redis:
    image: redis:7-alpine
    container_name: n8n-redis
    restart: unless-stopped
    command: redis-server --appendonly yes --requirepass sua_senha_redis_aqui
    volumes:
      - redis_data:/data
    networks:
      - n8n-network

  db:
    image: postgres:15-alpine
    container_name: n8n-db
    restart: unless-stopped
    environment:
      - POSTGRES_DB=n8n
      - POSTGRES_USER=n8n_user
      - POSTGRES_PASSWORD=seu_senha_forte_aqui
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - n8n-network

volumes:
  n8n_data:
  redis_data:
  postgres_data:

networks:
  n8n-network:
    driver: bridge

Análise Crítica da Configuração:

1. Execução em Fila (Queue Mode): As variáveis EXECUTIONS_MODE=queue, QUEUE_BULL_REDIS_HOST e QUEUE_BULL_REDIS_PORT são as responsáveis pela mudança de paradigma. Elas instruem o n8n a não executar workflows localmente, mas sim a enviar jobs para o Redis.
2. Persistência de Dados: Utilizamos volumes nomeados (n8n_data, redis_data, postgres_data) para garantir que seus workflows e credenciais não sejam perdidos ao reiniciar os containers.
3. Segurança: Definimos senhas para o Redis e o PostgreSQL. É vital substituir seu_senha_forte_aqui e sua_chave_de_criptografia_aleatoria por strings complexas geradas aleatoriamente. A chave de criptografia (N8N_ENCRYPTION_KEY) é usada para criptografar credenciais salvas nos workflows; não a perca, pois ela é necessária para descriptografar seus dados.

Etapa 2: Iniciando os Serviços

Agora que a configuração está pronta, podemos iniciar o ambiente. Execute o comando abaixo no terminal dentro do diretório n8n-scalability.

docker compose up -d

O Docker baixará as imagens necessárias (n8n, Redis e PostgreSQL) e iniciará os containers. Você pode verificar o status dos serviços com:

docker compose ps

Todos os três serviços devem aparecer como "Up". Se algum serviço falhar ao iniciar, verifique os logs para identificar erros de conexão ou permissão:

docker compose logs -f n8n

Etapa 3: Escalando os Workers do n8n

Este é o momento em que a escalabilidade se torna tangível. Por padrão, o Docker Compose inicia apenas um container do n8n. No entanto, como configuramos o modo de fila, podemos adicionar quantos workers forem necessários sem alterar o código, apenas aumentando a contagem de réplicas.

Para adicionar dois workers adicionais (totalizando 3 instâncias processando filas simultaneamente), execute:

docker compose up -d --scale n8n=3

O Docker iniciará dois novos containers chamados n8n-core-1 e n8n-core-2. Todos eles estão conectados à mesma fila Redis e ao mesmo banco de dados PostgreSQL. Isso significa que:

• Se você disparar 5 workflows, o Redis distribuirá essas tarefas entre os 3 workers disponíveis.
• Se um worker ficar sobrecarregado ou cair, o Redis redistribuirá as tarefas pendentes para os outros workers ativos.
• Você pode escalar horizontalmente conforme a carga aumenta, simplesmente ajustando o número de réplicas.

Para verificar se os workers estão comunicando corretamente com o Redis, insira em um dos containers e verifique o estado da fila:

docker exec -it n8n-core redis-cli -a sua_senha_redis_aqui

Dentro do CLI do Redis, você pode usar comandos como INFO KEYSPACE ou inspecionar as filas Bull específicas do n8n. No entanto, a melhor maneira de verificar o funcionamento é observar os logs do n8n.

docker compose logs -f | grep "Queue"

Você verá mensagens indicando que o n8n está conectado ao backend de fila e aguardando jobs.

Etapa 4: Testando a Configuração

Agora que a infraestrutura está pronta, vamos validar se os workflows estão sendo processados corretamente. Acesse a interface web do n8n em http://seu-ip-do-servidor:5678.

1. Criação de Workflow: Crie um workflow simples. Use o nó "Interval" para acionar o workflow a cada 1 minuto e conecte-o a um nó "HTTP Request" ou "Debug".
2. Ativação: Salve e ative o workflow.
3. Monitoramento: Vá para a aba "Executions" (Execuções) na interface do n8n. Você verá as execuções sendo registradas.

Para testar a concorrência, crie 5 workflows idênticos e ative-os todos simultaneamente. Observe o painel de execução. Em uma configuração single-process, eles ficariam um atrás do outro. Com o Redis em fila, você deve ver as execuções sendo processadas em paralelo.

Além disso, verifique a integridade dos dados no PostgreSQL. Você pode conectar ao banco de dados para garantir que os workflows e credenciais estão sendo persistidos corretamente:

docker exec -it n8n-db psql -U n8n_user -d n8n

Dentro do psql, execute:

\dt

Você verá as tabelas padrão do n8n, confirmando que a comunicação entre o serviço n8n e o PostgreSQL está estabelecida.

Etapa 5: Otimizações e Boas Práticas de Produção

Agora que seu n8n está escalável, existem algumas considerações adicionais para garantir estabilidade em longo prazo e segurança máxima.

Gerenciamento de Memória dos Workers

Cada worker do n8n consome memória RAM. Ao escalar muitos workers, você pode esgotar a memória do servidor. Você pode limitar a memória consumida por cada container n8n usando as opções deploy no docker-compose ou flags de restrição do Docker. Por exemplo:

# Dentro do serviço n8n no docker-compose
deploy:
  resources:
    limits:
      memory: 1G

Isso garante que um único worker não consuma todos os recursos da máquina, permitindo um isolamento mais previsível.

Backup Automatizado

Em um ambiente escalado, o backup do banco de dados é crítico. O Redis armazena apenas a fila temporária (que pode ser reconstruída), mas o PostgreSQL contém todos os seus workflows e credenciais. Implemente um script de backup rotativo para o volume postgres_data.

# Exemplo de comando de backup do PostgreSQL
docker exec n8n-db pg_dump -U n8n_user n8n > backup_n8n_$(date +%F).sql

Segurança da Fila Redis

O Redis, por padrão, não precisa de senha se estiver em uma rede local segura. No entanto, como expomos o serviço via Docker Compose e ele é acessível pelos workers, a senha é obrigatória. Certifique-se de que a variável QUEUE_BULL_REDIS_HOST aponte para o nome interno do serviço (redis) e não para um endereço externo, mantendo o tráfego da fila dentro da rede Docker privada.

Hibernação de Workflows Inativos

Se você possui muitos workflows que raramente são executados, considere desativá-los. No modo de fila, mesmo workflows inativos podem consumir recursos se houver um bug ou loop infinito em um workflow ativo. Monitore o painel de execuções regularmente para identificar gargalos.

Conclusão

A configuração do n8n com Redis e PostgreSQL transforma uma ferramenta de automação local em uma plataforma robusta e escalável, capaz de suportar cargas de trabalho corporativas. Ao desacoplar a execução dos workflows da instância principal do servidor, você ganha resiliência contra falhas e capacidade de expandir o processamento conforme a demanda cresce.

Lembre-se que a escalabilidade não é apenas sobre adicionar mais servidores, mas sobre arquitetar o sistema para lidar com concorrência de forma eficiente. Com esta configuração em Docker Compose, você estabeleceu uma base sólida para suas automações self-hosted, pronta para crescer junto com as necessidades da sua empresa.

Para dúvidas ou ajustes específicos na sua infraestrutura, consulte a documentação oficial do n8n sobre "Queue Mode" e verifique os logs dos containers em tempo real para monitorar a saúde do seu ambiente de automação.