O queue mode é um modo de implantação do n8n que separa o recebimento do trabalho da execução dos workflows. A instância principal recebe o gatilho, grava a execução e coloca um identificador numa fila do Redis. Os workers retiram esse identificador, buscam o workflow no banco, executam e gravam o resultado.
A separação permite distribuir a carga entre vários processos. Em vez de uma máquina executar tudo, a principal cuida da entrada e os workers cuidam do processamento. O Redis funciona como a fila que liga as duas partes.
As peças da arquitetura
O modo exige quatro componentes:
- a instância principal, que recebe webhooks e execuções manuais
- os workers, que executam os workflows
- o Redis, que guarda a fila de trabalhos
- o banco, que guarda workflows, credenciais e históricos de execução
As instâncias precisam compartilhar a mesma chave de criptografia. Sem ela, um worker não consegue ler a credencial gravada pela principal. O banco também precisa ser o mesmo, e cada worker deve alcançá-lo antes de começar a processar.
O caminho de uma execução
O webhook chega à principal. Ela registra a execução e envia o identificador para o Redis. Um worker disponível recebe o identificador, consulta o banco e executa o fluxo. Ao terminar, grava o resultado e libera a vaga para o próximo trabalho.
Cada worker tem um limite de execuções simultâneas, com padrão de 10. Um workflow longo ocupa uma vaga enquanto roda. Quando todas as vagas estão ocupadas, o trabalho espera na fila. O tempo de espera aparece no histórico e não no tempo de execução do workflow.
Binários e storage compartilhado
Um nó que recebe um arquivo precisa gravá-lo em algum lugar. No modo filesystem, o arquivo fica no disco local da instância. No queue mode, a execução pode começar num worker e continuar em outro, que não tem o mesmo arquivo.
A documentação indica database, S3 ou Azure como opções compartilhadas. O banco funciona, mas carrega o banco principal e tem limite de tamanho por arquivo. S3 e Azure são as opções recomendadas para volume. A escolha vale para todos os workers e para a principal.
O que a versão 3.0 mudou
A versão 3.0 do n8n alterou o comportamento das execuções manuais. A variável OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERS foi removida, e o teste iniciado no editor agora roda no worker. O dimensionamento precisa considerar esse teste como trabalho de produção.
O timeout do task runner caiu de 300 para 60 segundos, e os limites de descompressão passaram de 2 GiB para 256 MiB. A lista completa de mudanças está no artigo sobre a versão 3.0. A revisão antes da atualização inclui memória, storage e a lista de proteção contra SSRF.
Quando usar
O queue mode faz sentido quando a carga de execução passa do que uma instância atende ou quando você precisa isolar o recebimento de webhooks do processamento. Para poucos workflows e pouco volume, uma instância única com banco e storage locais custa menos e tem menos peças para operar.
A escolha acompanha o volume e o tempo de cada workflow. Um fluxo que espera uma API lenta ocupa uma vaga por mais tempo, e o número de workers precisa cobrir essa espera. A escala horizontal descreve o mesmo princípio fora do n8n: acrescentar instâncias e distribuir o trabalho.
Dúvidas frequentes
Perguntas frequentes sobre Queue mode
- Queue mode é só aumentar o número de workers?
- Não. O modo exige Redis, banco compartilhado, storage de binários comum e a mesma chave de criptografia em todas as instâncias. Sem esses elementos, uma execução pode falhar ao buscar o workflow ou ao ler a credencial.
- Por que o armazenamento em filesystem não serve no queue mode?
- Porque cada worker grava e lê o binário do próprio disco. A execução pode cair em outro worker, que não encontra o arquivo. A documentação indica banco, S3 ou Azure como alternativas compartilhadas.
- O que acontece com as execuções iniciadas pelo editor?
- Na versão 3.0, as execuções manuais também rodam nos workers. Um teste no editor ocupa uma vaga de concorrência e compete com o trabalho de produção.
Para continuar
Recursos relacionados
Documentação
n8n: queue mode
Descreve a arquitetura com main, workers e Redis, as variáveis de ambiente e os requisitos de armazenamento compartilhado.
Abrir recursoDocumentação
n8n: visão geral de escala
Compara a instância única com o queue mode e explica quando a separação entre recebimento e execução faz sentido.
Abrir recursoArtigo
Promovaweb: n8n 3.0 em queue mode
Detalha as mudanças da versão 3.0 em execução manual, binários, timeout e rede numa instância com workers.
Abrir recursoAplicação na formação
n8n Experts
Ao preparar uma instância com muitos workflows, você dimensiona main, workers, Redis e storage compartilhado antes de ativar o queue mode.
Conhecer a formação
Fontes consultadas
Referências deste verbete
Este verbete ajudou você?
Obrigado pela resposta. Ela fica salva apenas neste navegador.