n8n em queue mode com Redis e workers no Docker Compose

Resposta curta: no queue mode, a instância principal do n8n recebe os gatilhos e webhooks e coloca cada execução numa fila no Redis; processos worker pegam as execuções da fila e rodam. Você ativa com EXECUTIONS_MODE=queue na instância principal e nos workers, todos ligados ao mesmo Redis e ao mesmo PostgreSQL.

Quando vale a pena

• Muitas execuções ao mesmo tempo, ou workflows pesados que travam a interface.
• Você quer escalar adicionando workers, inclusive em outras máquinas.

Para uso pessoal, uma instância comum resolve, e o queue mode só acrescenta peças para manter. A documentação ressalta que queue mode com SQLite não é recomendado e que ele não suporta dados binários no sistema de arquivos: para isso, use armazenamento S3 (docs).

O compose.yaml

Crie o .env com usuário, senha e banco do PostgreSQL e a N8N_ENCRYPTION_KEY, como no guia de n8n com PostgreSQL. A chave precisa ser a mesma em todas as instâncias, senão os workers não conseguem ler as credenciais.

x-n8n: &n8n
  image: n8nio/n8n:stable
  restart: always
  environment:
    DB_TYPE: postgresdb
    DB_POSTGRESDB_HOST: postgres
    DB_POSTGRESDB_DATABASE: ${POSTGRES_DB}
    DB_POSTGRESDB_USER: ${POSTGRES_USER}
    DB_POSTGRESDB_PASSWORD: ${POSTGRES_PASSWORD}
    N8N_ENCRYPTION_KEY: ${N8N_ENCRYPTION_KEY}
    EXECUTIONS_MODE: queue
    QUEUE_BULL_REDIS_HOST: redis
    QUEUE_HEALTH_CHECK_ACTIVE: "true"
    GENERIC_TIMEZONE: America/Sao_Paulo
    TZ: America/Sao_Paulo
  depends_on:
    postgres:
      condition: service_healthy
    redis:
      condition: service_healthy

services:
  postgres:
    image: postgres:18
    restart: always
    environment:
      - POSTGRES_USER
      - POSTGRES_PASSWORD
      - POSTGRES_DB
      - PGDATA=/var/lib/postgresql/data
    volumes:
      - db_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 5s
      timeout: 5s
      retries: 10

  redis:
    image: redis:8-alpine
    restart: always
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 5s
      retries: 10

  n8n:
    <<: *n8n
    ports:
      - "127.0.0.1:5678:5678"
    volumes:
      - n8n_data:/home/node/.n8n

  n8n-worker:
    <<: *n8n
    command: worker --concurrency=5

volumes:
  db_data:
  redis_data:
  n8n_data:

• O bloco x-n8n evita repetir a configuração: a instância principal e o worker usam a mesma imagem, o mesmo banco, o mesmo Redis e a mesma chave.
• O worker é a mesma imagem do n8n com o comando worker. O --concurrency=5 define quantas execuções cada worker roda em paralelo (o padrão é 10). A documentação recomenda 5 ou mais, porque muitos workers com concorrência baixa esgotam as conexões do banco.
• O Redis não publica porta: fica só na rede interna do Compose, sem senha. Se ele estiver em outra máquina, configure QUEUE_BULL_REDIS_PASSWORD e restrinja o acesso.
• Para HTTPS, coloque um proxy reverso na frente da instância principal, como no guia com Traefik.

Suba e confira que os workers estão trabalhando

docker compose up -d
docker compose logs -f n8n-worker

Ao disparar um workflow de produção (um webhook publicado, por exemplo), o log do worker mostra:

Worker started execution 1 (job 1)
Worker finished execution 1 (job 1)

Com QUEUE_HEALTH_CHECK_ACTIVE, cada worker responde a um teste de prontidão, que confere a conexão com o banco e o Redis:

docker compose exec n8n-worker wget -qO- http://localhost:5678/healthz/readiness
# {"status":"ok"}

Escalar: mais workers

docker compose up -d --scale n8n-worker=2

Com dois workers, a fila distribui as execuções entre eles: 20 chamadas simultâneas a um webhook são divididas entre os dois, sem configuração extra. Se as execuções ficam esperando na fila, adicione workers. Se o banco reclama de conexões, reduza o número de workers e aumente a concorrência de cada um.

A tela Settings > Workers, que mostra os workers na interface, só existe no plano Enterprise. Na versão Community, acompanhe pelos logs e pelo docker stats.

Quanto de memória reservar

Consumo medido com dois workers, logo depois de uma rajada de 20 chamadas:

Com um worker, o conjunto fica perto de 700 MiB com carga leve. Uma VPS de 2 GB comporta principal e um worker com folga para workflows simples; para cada worker extra, conte mais 0,5 a 1 GB, e bem mais se os workflows usam IA, arquivos grandes ou o nó Code. Compare planos na tabela de preços em reais ou estime na calculadora.

Perguntas frequentes

O que é o queue mode do n8n?

É o modo em que a instância principal recebe gatilhos e webhooks e coloca as execuções numa fila no Redis, e processos worker pegam e rodam essas execuções.

Posso usar queue mode com SQLite?

A documentação não recomenda. Use PostgreSQL junto com o Redis.

Quantas execuções um worker roda ao mesmo tempo?

O padrão é 10, ajustável com n8n worker --concurrency. A documentação recomenda 5 ou mais.

Como adicionar mais workers?

No Docker Compose, rode docker compose up -d --scale n8n-worker=2 (ou o número desejado). Todos precisam do mesmo Redis, do mesmo banco e da mesma chave de criptografia.