Queue mode n8n: como escalar com workers e Redis

Veja como funciona o queue mode do n8n: principal, fila no Redis, workers, banco PostgreSQL, chave de criptografia, webhook processors e o limite do multi-main.

Por Redação Eleven Host · @robson.direitodigital · 31 de outubro de 2026 · 8 min de leitura

O queue mode n8n é o modo em que a instância principal recebe os gatilhos e coloca as execuções numa fila no Redis. Workers separados pegam essas execuções e as executam, o que divide a carga. Este guia mostra como configurar cada peça.

O caminho é: entender quando faz sentido, reunir Redis, PostgreSQL e a chave de criptografia, configurar a principal, subir os workers e conhecer os extras, como os webhook processors. Os nomes de host e as chaves dos exemplos são fictícios, e tudo vale para o n8n 2.x.

Quando o queue mode vale a pena

Segundo a documentação, a instância principal recebe os gatilhos e os webhooks e gera as execuções, mas não as roda. Ela manda o ID de cada execução para o Redis. Os workers pegam o ID, leem o fluxo no banco de dados, executam e gravam o resultado. Cada worker é uma instância Node.js própria, rodando em modo main.

Em resumo, o modo fila separa quem recebe os gatilhos de quem executa os fluxos. A documentação não traz requisito de memória ou de processador, nem um número ideal de workers.

Se a sua instância ainda não passou por uma configuração básica, comece pelo guia de variáveis de ambiente do n8n, que mostra como configurar variáveis no Docker.

O que você precisa antes de começar

O modo fila pede estas peças.

Redis

O Redis é a fila. Se você ainda não tem um, o guia Instalar Redis no Ubuntu: passo a passo na VPS mostra a instalação. Por padrão, o Redis não exige senha, e o n8n tem uma variável para informar uma, que aparece mais abaixo.

PostgreSQL

Sobre o SQLite, a documentação é direta: rodar o n8n em modo queue com SQLite não é recomendado, e um sistema distribuído com essa configuração não é suportado. Use o PostgreSQL. Segundo a página de bancos suportados, são as duas últimas versões principais com manutenção ativa, a 17 e a 18 (em julho de 2026), mais a 16 por compatibilidade.

O n8n 2.x também não aceita mais MySQL nem MariaDB para guardar os dados do próprio n8n. Isso trata do armazenamento do próprio n8n. Para conectar um fluxo a um banco MySQL, veja n8n com MySQL: como conectar e gravar dados no banco.

A mesma chave de criptografia

A chave de criptografia da instância principal precisa ser compartilhada com todos os workers e com os webhook processors. Na prática, todos usam o mesmo N8N_ENCRYPTION_KEY.

A mesma versão

Mantenha principal e workers na mesma versão do n8n. A documentação exige isso explicitamente no multi-main, que aparece mais adiante, e é uma boa prática geral.

Configurar a instância principal

A principal e os workers usam o modo fila ligado por variável de ambiente. A documentação mostra o comando export:

export EXECUTIONS_MODE=queue

Essa variável vale na principal e em cada worker. Com Docker, é o mesmo valor passado com -e, como no guia de variáveis. Para a conexão com o Redis, a documentação tem estas variáveis, com os padrões entre parênteses:

• QUEUE_BULL_REDIS_HOST (localhost) e QUEUE_BULL_REDIS_PORT (6379).
• QUEUE_BULL_REDIS_PASSWORD e QUEUE_BULL_REDIS_USERNAME, sem padrão.
• QUEUE_BULL_REDIS_DB (0) e QUEUE_BULL_REDIS_TLS (false).
• QUEUE_BULL_REDIS_TIMEOUT_THRESHOLD (10000) e QUEUE_BULL_PREFIX.

Para o PostgreSQL, a página de bancos suportados traz estas variáveis, também com o padrão entre parênteses:

• DB_TYPE=postgresdb
• DB_POSTGRESDB_HOST (localhost) e DB_POSTGRESDB_PORT (5432)
• DB_POSTGRESDB_DATABASE (n8n), DB_POSTGRESDB_USER (postgres) e DB_POSTGRESDB_PASSWORD (vazio)
• DB_POSTGRESDB_SCHEMA (public)

Por fim, defina o N8N_ENCRYPTION_KEY e use o mesmo valor em todos os processos. Para organizar tantas variáveis, veja o guia de Docker Compose na VPS.

Existe ainda a QUEUE_HEALTH_CHECK_ACTIVE, que fica em false por padrão. Ligada, o worker responde em /healthz, na porta da QUEUE_HEALTH_CHECK_PORT (padrão 5678). Outras duas aparecem na tabela da documentação: a QUEUE_WORKER_LOCK_DURATION (padrão 60000) e a OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERS (padrão false). Esta última existe, mas a página de queue mode não explica o que ela faz, então este guia não vai além disso.

A QUEUE_WORKER_MAX_STALLED_COUNT foi marcada para remoção no n8n 2.0. Se você a vê em tutoriais antigos, não a use.

Quer conhecer o n8n da Eleven Host? n8n Essencial a partir de R$ 19,90/mês; confira na loja o que cada plano inclui. Ver planos de n8n

Subir os workers

Cada worker é um processo do n8n iniciado com o comando worker. Na documentação, o comando aparece com o caminho do código-fonte (./packages/cli/bin/n8n worker). O Docker usa só o argumento worker, como abaixo.

Com Docker, o comando da documentação é este:

docker run --name n8n-queue -p 5679:5678 n8nio/n8n worker

Esse comando, sozinho, não passa variável nenhuma. Na prática, o worker precisa das variáveis da seção anterior. Este exemplo foi montado com as opções documentadas, e o meu-redis e o meu-postgres são nomes fictícios dos hosts:

docker run --name n8n-queue -p 5679:5678 \

-e EXECUTIONS_MODE=queue \

-e QUEUE_BULL_REDIS_HOST=meu-redis \

-e DB_TYPE=postgresdb \

-e DB_POSTGRESDB_HOST=meu-postgres \

-e N8N_ENCRYPTION_KEY=<a mesma chave da principal> \

n8nio/n8n worker

Faltam ali a senha do banco e a do Redis, se você as usa. Acrescente as variáveis correspondentes, no mesmo formato.

Concorrência de cada worker

A opção --concurrency define quantas execuções um worker processa ao mesmo tempo. O padrão é 10. A documentação recomenda configurar a concorrência em 5 ou mais para os workers, e avisa que valores baixos com muitos workers podem esgotar o pool de conexões do banco de dados.

Todos os workers precisam de acesso ao Redis e ao banco do n8n.

Webhook processors

Além dos workers, a documentação descreve os webhook processors, que são processos dedicados a receber os webhooks. Na documentação, o comando é ./packages/cli/bin/n8n webhook. Eles ouvem na mesma porta, a 5678 por padrão.

Com os processors, você coloca um balanceador de carga na frente e divide as rotas assim:

• /webhook/* e /webhook-waiting/* vão para os webhook processors.
• O restante vai para a instância principal.
• /webhook-test/*, das execuções manuais, precisa ir para a principal.

Para tirar os webhooks de produção da principal, a variável é N8N_DISABLE_PRODUCTION_MAIN_PROCESS=true. A documentação não recomenda colocar a instância principal no pool do balanceador.

Sobre a URL pública dos webhooks, a variável N8N_WEBHOOK_URL está disponível a partir do n8n 2.30.0. Em versões anteriores, use a WEBHOOK_URL.

Arquivos binários no modo fila

Aqui há uma limitação. A documentação diz que o n8n não suporta o modo fila com armazenamento de dados binários no sistema de arquivos. Para guardar arquivos binários no modo fila, ela recomenda um armazenamento externo S3.

Na versão 2.x, a página de mudanças informa que a opção database, em que o dado binário fica no banco, é o padrão no modo fila. Se o seu fluxo trabalha com arquivos grandes, planeje essa parte antes de ligar o modo fila.

Multi-main exige Enterprise

O multi-main é a configuração com várias instâncias principais. Segundo a documentação, ele está disponível no self-hosted Enterprise e não está disponível no n8n Cloud. Só o multi-main exige licença Enterprise, e o queue mode em si não.

Os requisitos incluem todas as principais em queue mode com PostgreSQL e Redis, a mesma versão em principais e workers, a variável N8N_MULTI_MAIN_SETUP_ENABLED=true e um balanceador com sticky sessions. Se a sua licença não é Enterprise, fique com uma principal e quantos workers precisar.

Procurando um lugar para os seus fluxos? n8n Essencial a partir de R$ 19,90/mês; confira na loja o que cada plano inclui. Conhecer o n8n Essencial

Perguntas frequentes

O que é o queue mode do n8n?

É o modo em que a instância principal recebe os gatilhos e enfileira as execuções no Redis, e workers separados as executam.

Posso usar SQLite no queue mode?

Não é recomendado, e a documentação diz que um sistema distribuído com SQLite não é suportado. Use PostgreSQL.

Todos os workers precisam do mesmo N8N_ENCRYPTION_KEY?

Sim. A chave da instância principal precisa ser compartilhada com todos os workers e com os webhook processors.

Qual é o padrão de concorrência de um worker?

Dez. A documentação recomenda configurar 5 ou mais.

O queue mode exige licença Enterprise?

Não. Apenas o multi-main, com várias instâncias principais, está disponível no self-hosted Enterprise.