Uma instância única do n8n consegue fazer muito — até o dia em que não consegue mais. O sinal costuma ser sutil no início: workflows que antes completavam em segundos começam a demorar, execuções se acumulam na fila, e em dias de pico o processo consome toda a memória disponível e reinicia sozinho. Não é bug do n8n. É o comportamento esperado de qualquer sistema de processos concorrentes rodando em processo único sem separação entre agendamento e execução. A solução existe, está documentada e muda completamente o perfil de capacidade da operação: o queue mode.
Resumo rápido: O n8n em modo padrão roda tudo em um processo único — o agendador, a interface web e a execução de workflows competem pelos mesmos recursos. Queue mode separa essas responsabilidades: um processo main coordena e expõe a interface, workers dedicados executam os jobs de uma fila Redis, e um banco Postgres dedicado persiste tudo. O resultado é escala horizontal real: adicionar workers aumenta a capacidade de processamento sem tocar no core.
Por que o n8n single-instance tem limite
O n8n em instalação padrão roda como processo Node.js único. Quando um webhook chega, quando um agendamento dispara ou quando você executa manualmente um workflow, o mesmo processo que serve a interface web é o que executa o workflow. Para volumes baixos a moderados, isso funciona bem. O problema aparece quando múltiplos workflows pesados rodam em paralelo.
Node.js tem um event loop single-threaded. Operações de I/O são não-bloqueantes por design, mas processamento intensivo — transformar grandes volumes de dados, fazer múltiplas chamadas HTTP em série, processar payloads grandes — ocupa o event loop e atrasa tudo mais. Em paralelo, a memória se fragmenta entre execuções concorrentes e o processo começa a ficar instável.
O segundo problema é a falta de isolamento de falhas. Em single-instance, um workflow que consome memória excessiva afeta todos os outros. Um reinício do processo por OOM (out of memory) interrompe todas as execuções em andamento sem possibilidade de retomada.
O que muda no queue mode
A separação de responsabilidades é a mudança central. Em queue mode, o n8n opera com pelo menos dois tipos de processo distintos:
Main: responsável por receber webhooks, servir a interface web, agendamento e criação de jobs na fila. Não executa workflows diretamente.
Workers: processos dedicados à execução de workflows. Consomem jobs da fila Redis, executam e reportam o resultado. Podem existir múltiplos workers rodando em paralelo, em containers separados ou em servidores diferentes.
Redis funciona como fila. O main publica jobs; os workers consomem. Redis é eficiente para esse padrão de pub/sub e oferece persistência configurável para não perder jobs em caso de reinício.
Postgres armazena o estado de execução de forma durável. Workflows versionados, histórico de execuções, credenciais criptografadas — tudo em banco relacional com transações garantidas, não em SQLite como na instalação básica.
A consequência prática: se você precisa de mais throughput, adiciona workers. Se o main precisar reiniciar para uma atualização, os workers continuam processando os jobs que já estão em execução. Um worker que falha não afeta os outros.
Tabela: n8n cloud vs self-hosted single vs self-hosted queue mode
| Dimensão | n8n Cloud | Self-Hosted Single | Self-Hosted Queue Mode |
|---|---|---|---|
| Setup inicial | Minutos | 1-2 horas | 4-8 horas |
| Custo fixo mensal | Plano pago (escala por execuções) | Custo do servidor | Custo de 2+ servidores/containers |
| Escala horizontal | Gerenciada pelo provedor | Não disponível | Sim — adicionar workers |
| Isolamento de falha | Gerenciado | Processo único — falha afeta tudo | Workers independentes |
| Controle de dados | Dados no servidor n8n | Total controle | Total controle |
| Workflows em git | Exportação manual | Possível via API | Integrado ao fluxo DevOps |
| Execuções simultâneas | Limitado pelo plano | Limitado pelo processo | Configurável por número de workers |
| RBAC por workspace | Disponível (Enterprise) | Não nativo | Configurável com Enterprise ou workarounds |
| Customização de ambiente | Não disponível | Total | Total |
| Overhead operacional | Baixo | Médio | Alto |
Quando migrar do n8n cloud ou single para queue mode
A migração faz sentido quando alguns sinais aparecem de forma consistente, não apenas em picos isolados:
Execuções que se acumulam na fila interna sem serem processadas em tempo razoável. Workflows que competem por recursos e atrasam uns aos outros. O processo n8n reiniciando por OOM ou erro não tratado durante picos. Necessidade de manter execuções de diferentes clientes ou contextos isoladas (multi-tenant básico via workspace separado). Volume de execuções mensais que torna o custo do n8n Cloud maior que o custo de infraestrutura própria.
Para operações que processam dados sensíveis — documentos de clientes, registros financeiros, dados de saúde — o self-hosted em qualquer modo elimina a dúvida sobre onde os dados transitam. Em queue mode, você tem controle total sobre o Redis e o Postgres, incluindo criptografia em repouso e isolamento de rede.
Arquitetura de referência para produção
Uma arquitetura funcional de produção usa os seguintes componentes:
Traefik ou Caddy como reverse proxy na frente do main, com SSL automático via Let's Encrypt. O main fica exposto na porta 443; Redis e Postgres ficam em rede interna sem exposição externa.
Redis em modo standalone para a maioria das operações. Se a confiabilidade da fila for crítica, Redis Sentinel ou Redis Cluster adicionam failover, mas aumentam a complexidade. Para a maior parte das operações, backup frequente do Redis é suficiente.
Postgres como banco principal do n8n. Um banco dedicado para o n8n evita que outras aplicações interfiram com as consultas do n8n. Configure backups automáticos com Restic ou pg_dump periódico para destino offsite.
Dois ou mais workers em containers separados. O número de workers define o paralelismo máximo. Cada worker processa um job por vez (configurável). Três workers = até três workflows simultâneos em execução real, sem contenção de recursos.
Em Docker Compose, a separação é declarativa: serviço n8n-main, serviço n8n-worker (com scale: 3 para três instâncias), Redis e Postgres. A variável de ambiente EXECUTIONS_MODE=queue ativa o modo. QUEUE_BULL_REDIS_HOST aponta para o Redis. Resto da configuração segue a documentação oficial.
Workflows versionados em git com RBAC
Queue mode é a base. O que eleva o nível operacional é tratar os workflows do n8n como código: versionados em git, com processo de revisão antes de ir para produção.
O n8n tem API REST que permite exportar e importar workflows como JSON. Um fluxo básico de GitOps para n8n funciona assim:
Desenvolvimento acontece em uma instância de staging separada. Quando um workflow está pronto, é exportado via API como JSON e commitado no repositório. O merge para a branch principal dispara um pipeline CI que importa o workflow via API na instância de produção.
Esse fluxo resolve dois problemas recorrentes: rastreabilidade ("quem mudou esse workflow e quando?") e recuperação ("qual era a versão anterior que funcionava?"). Em operações com múltiplos workflows críticos, um workflow quebrado sem possibilidade de rollback pode paralisar processos inteiros.
O RBAC (controle de acesso baseado em papel) do n8n Enterprise permite separar quem pode criar workflows, quem pode ativá-los em produção e quem apenas visualiza execuções. Para operações onde diferentes times operam diferentes workflows, essa separação é necessária para evitar que uma mudança em um workflow de um time afete o de outro. Quando o departamento de DevOps da MaxVision estrutura um n8n em queue mode, o controle de acesso e o versionamento em git fazem parte da entrega desde o primeiro deploy.
Para operações que não têm licença Enterprise, o workaround mais comum é ter instâncias separadas por contexto ou por time, com acesso compartilhado apenas ao que for comum.
Autoscaling: quando e como
Autoscaling real — adicionar workers automaticamente sob demanda e removê-los quando o volume cai — exige orquestração de containers: Kubernetes com HPA (Horizontal Pod Autoscaler) ou Docker Swarm com scaling baseado em métricas.
Para a maioria das operações, autoscaling não é necessário no início. Um número fixo de workers dimensionado para o pico esperado é mais simples de operar e menos sujeito a surpresas. Se os picos são previsíveis (processamento noturno, campanhas específicas), o scaling manual ou agendado — aumentar workers antes do pico e reduzir depois — é suficiente.
Quando o volume é genuinamente imprevisível e os picos têm custo operacional real em espera de execução, o autoscaling com Kubernetes faz sentido. A configuração usa KEDA (Kubernetes Event-Driven Autoscaling) com Redis como trigger: quando a fila ultrapassa N jobs pendentes, novos pods worker são criados automaticamente.
Esse nível de sofisticação raramente é o ponto de partida certo. Normalmente, a operação cresce até um ponto onde o scaling manual vira gargalo operacional, e é aí que a migração para Kubernetes e KEDA se justifica pelo esforço.
Monitoramento da fila e dos workers
Um aspecto que costuma ser negligenciado em deployments de queue mode é a visibilidade do estado da fila. Em single-instance, você vê o histórico de execuções na interface do n8n e tem uma ideia do throughput. Em queue mode, a fila do Redis pode acumular jobs sem que isso fique óbvio na interface.
O Bull Dashboard — ou o BullMQ Board, dependendo da versão — é uma interface web que mostra o estado da fila em tempo real: jobs ativos, aguardando, concluídos, falhos. Em produção, expor essa interface de forma restrita (autenticação básica ou VPN) dá visibilidade operacional sem custo adicional.
Para alertas, integrar Prometheus com redis_exporter e n8n com métricas customizadas permite criar alertas para "fila acima de N jobs por mais de X minutos" — sinal de que os workers estão sobrecarregados ou que um job está bloqueando a fila.
A migração do n8n cloud para self-hosted queue mode
A migração em si envolve: exportar todos os workflows e credenciais da instância cloud, preparar a infraestrutura self-hosted com queue mode, importar os workflows e reconfigurar credenciais (credenciais são criptografadas e não migram diretamente — precisam ser reinseridas).
O ponto de maior atenção é o período de transição: webhooks apontando para a URL do n8n cloud precisam ser atualizados para a URL self-hosted. Se houver integrações externas que chamam esses webhooks, o processo de atualização precisa ser coordenado para minimizar interrupção.
Para operações críticas, a estratégia recomendada é rodar as duas instâncias em paralelo por um período: cloud recebendo os webhooks existentes, self-hosted recebendo os novos. Quando a confiança no self-hosted estiver estabelecida, migra os webhooks restantes e encerra o cloud.
Perguntas Frequentes
Quantos workers são necessários para começar?
Para a maioria das operações que justificam queue mode, dois workers já oferecem isolamento de falha e paralelismo básico. Três a cinco workers cobrem operações com volume médio-alto. O número ideal depende do tempo médio de execução dos workflows e do paralelismo desejado. Comece com dois e monitore a profundidade da fila para calibrar.
Redis precisa de configuração especial para funcionar com n8n?
A configuração padrão do Redis funciona para a maioria dos casos. O que vale configurar é persistência (AOF ou RDB) para não perder jobs na fila em caso de reinício, e maxmemory-policy para evitar que o Redis consuma memória sem limite. Para queue mode do n8n, Redis com 512MB a 1GB é suficiente para volumes altos.
É possível usar queue mode com SQLite em vez de Postgres?
Não. O n8n em queue mode exige Postgres. O SQLite não suporta o nível de concorrência necessário para múltiplos workers acessando o banco simultaneamente. A migração de SQLite para Postgres é necessária antes de ativar o queue mode.
Queue mode resolve o problema de workflows que ficam presos infinitamente?
Parcialmente. Workers têm timeout configurável. Se um workflow ultrapassar o timeout, o job é marcado como falho e o worker fica disponível para o próximo. O que queue mode não resolve é a lógica interna do workflow — um loop infinito dentro de um workflow ainda vai consumir o worker até o timeout. Para esses casos, o monitoramento da duração de execução é necessário para detectar e interromper execuções anômalas.
Vale a pena ir direto para Kubernetes ou começar com Docker Compose?
Para a grande maioria das operações que migraram de single-instance ou cloud, Docker Compose é o ponto de partida correto. É mais simples de operar, mais fácil de debugar e cobre bem o caso de uso de dois a cinco workers em um único servidor ou conjunto pequeno de servidores. Kubernetes faz sentido quando você já tem o cluster, quando o autoscaling real é necessário ou quando a operação exige alta disponibilidade com failover automático de workers.
Conclusão
O n8n single-instance é uma ferramenta excelente para começar e para operações de volume baixo a moderado. Quando o volume cresce, a limitação não é do n8n — é da arquitetura de processo único que não foi projetada para escala horizontal. Queue mode resolve exatamente esse problema: separa responsabilidades, permite adicionar capacidade sem tocar no core e torna a operação resiliente a falha de componentes individuais.
O investimento em configuração é real — algumas horas para um ambiente funcional, mais tempo para workflows em git e monitoramento adequado. Mas é um investimento que o próprio volume justifica: quando a fila começa a travar em produção, o custo de não ter queue mode fica muito claro.
Estruturar n8n em queue mode do jeito certo — workers dimensionados, Redis com persistência, Postgres dedicado, workflows em git e fila monitorada — é o tipo de trabalho que o departamento de DevOps da MaxVision já opera em produção. Se quiser avaliar o que faz sentido para o seu volume atual e projeção de crescimento, comece por aqui.
