n8n: Parte 5 — Escalado: modo de cola, workers y task runners

Cuando un proceso n8n deja de poder manejar la cantidad de ejecuciones, se escala: la ejecución de los flujos se extrae a procesos workers separados, la recepción de webhooks — a procesos separados, y el código personalizado — a task runners aislados. Cómo activar el modo de cola está descrito en la segunda parte de la serie; aquí — cómo está organizado el escalado y cómo gestionarlo.

Primero sobre los workers “ligeros” y “pesados”

En la comunidad a menudo se habla de dividir los workers en “ligeros” (flujos rápidos: webhooks, notificaciones) y “pesados” (procesamiento de archivos, llamadas largas a IA). Es importante entender: no hay colas nombradas en n8n. En la documentación no existe ni la variable QUEUES, ni una configuración de cola por flujo, ni la variable N8N_WORKER_CONCURRENCY. Todos los workers de una misma instalación toman tareas de una sola cola en Redis, y no se puede elegir qué worker ejecutará un flujo concreto.

Se puede separar la carga de otras maneras — están descritas más abajo.

De qué consta una instalación escalada

• Instancia principal (main) — interfaz, API, cron; pone las ejecuciones en la cola.
• Redis — cola de tareas.
• Workers — procesos n8n worker que toman ejecuciones de la cola y las ejecutan.
• Procesadores de webhook — procesos n8n webhook que reciben webhooks entrantes.
• PostgreSQL — base de datos compartida; el esquema distribuido con SQLite no está soportado.

Todos los procesos deben usar la misma N8N_ENCRYPTION_KEY, de lo contrario los workers no podrán descifrar las credenciales. Los datos binarios en modo de cola no se pueden almacenar en el sistema de archivos — la documentación recomienda un almacenamiento externo S3.

Workers y paralelismo

Un worker se lanza con el comando n8n worker. El número de ejecuciones simultáneas en un worker se fija con la bandera --concurrency, por defecto 10:

n8n worker --concurrency=5

La carga se escala con dos palancas: el número de workers (horizontalmente) y el --concurrency de cada uno (verticalmente). Si los flujos son intensivos en memoria — menos paralelismo por worker y más workers; si es principalmente espera de APIs externas — se puede aumentar el paralelismo.

Un tope general es la variable N8N_CONCURRENCY_PRODUCTION_LIMIT: número máximo de ejecuciones de producción que se ejecutan simultáneamente. Por defecto -1 — límite desactivado.

Las ejecuciones manuales desde el editor por defecto se ejecutan en la instancia principal. Para que también se envíen a los workers, se fija OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERS=true — la documentación recomienda esto para producción.

Procesadores de webhook

Si los flujos se lanzan por webhooks, la recepción de peticiones se extrae a procesos separados:

n8n webhook

El balanceador dirige las rutas /webhook/* a un pool de procesadores de webhook, y en la instancia principal se desactiva la recepción de webhooks de producción con la variable N8N_DISABLE_PRODUCTION_MAIN_PROCESS=true. Así un pico de peticiones entrantes no interfiere con la interfaz.

Task runners

El código del nodo Code se ejecuta en task runners — procesos separados, aislados de n8n. Cada runner por defecto ejecuta hasta 5 tareas simultáneas (N8N_RUNNERS_MAX_CONCURRENCY), una tarea se detiene después de 300 segundos (N8N_RUNNERS_TASK_TIMEOUT).

Hay dos modos:

• internal — el runner se inicia como un proceso hijo de n8n bajo el mismo usuario. Desde n8n 3.0 el modo se declaró obsoleto: el código que escapa de la sandbox obtiene acceso a todo lo que tiene n8n, incluidas las credenciales guardadas;
• external — junto a n8n corre un contenedor separado n8nio/runners (la versión de la imagen debe coincidir con la versión de n8n), la comunicación está protegida por un secreto común N8N_RUNNERS_AUTH_TOKEN.

En modo de cola cada worker necesita su propio contenedor con runners. La variable N8N_RUNNERS_ENABLED quedó obsoleta con n8n 2.0 — los task runners están siempre habilitados.

Cómo, aun así, separar “ligero” y “pesado”

Puesto que la cola es única, la separación se hace a nivel de instalaciones y flujos:

1. Instalación n8n separada para tareas pesadas. Su propia instancia principal, su propio Redis y sus propios workers — por ejemplo, para procesamiento de documentos o trabajo con IA. Los flujos ligeros llaman a los pesados vía webhook o petición HTTP.
2. Procesadores de webhook separados de los workers. La recepción de peticiones se mantiene rápida incluso cuando los workers están ocupados.
3. Paralelismo según la naturaleza de la carga. Para una instalación con flujos pesados — pequeño --concurrency y más memoria por worker.
4. Sacar el código pesado fuera de n8n. A menudo es más sencillo realizar el procesamiento largo de archivos en un servicio externo y dejar a n8n el papel de coordinador.

Conjunto mínimo de variables

EXECUTIONS_MODE=queue
QUEUE_BULL_REDIS_HOST=redis
DB_TYPE=postgresdb
N8N_ENCRYPTION_KEY=una-misma-clave-en-todos-los-procesos
OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERS=true
N8N_RUNNERS_MODE=external
N8N_RUNNERS_AUTH_TOKEN=secreto-compartido

Errores típicos

• Claves de cifrado diferentes entre la instancia principal y los workers — los flujos fallan al descifrar las credenciales.
• SQLite en modo de cola — no está soportado.
• Datos binarios en el disco de la instancia principal — los workers no los ven.
• Un solo contenedor de runners para toda la instalación — en modo de cola cada worker necesita su propio contenedor.
• Búsqueda de la configuración “cola por flujo” — no existe; separen la carga con instalaciones separadas.

Enlaces útiles

• n8n: habilitar el modo de cola
• n8n: documentación completa (secciones sobre variables de entorno y task runners)