Escalar n8n: modo de colas, workers y task runners

¿Qué problema resolvemos?

En un despliegue básico, una instancia de n8n gestiona el editor, los webhooks, la ejecución de workflows y los triggers. Al aumentar la concurrencia, esas tareas pueden competir por los recursos. El modo de colas separa la ejecución de los workflows de producción de la instancia principal; los nodos Code tienen sus propios requisitos de task runners.

La solución es separar responsabilidades:

Piensa en ello como un restaurante: el Main es el maître que recibe pedidos, Redis es la barra donde se dejan las comandas, el Worker es el cocinero, el Webhook Processor es la puerta de entrada para pedidos online y los Task Runners son los ayudantes especializados que preparan ingredientes específicos.

Arquitectura visual

Tráfico público -> proxy inverso
  Editor, API y webhooks de prueba -> Main
  Webhooks de producción y de espera -> Procesadores de webhooks

Main / procesadores de webhooks -> cola de Redis -> Workers
Main / procesadores de webhooks / workers <-> PostgreSQL

Nodo Code del worker <-> broker del worker <-> runner externo

El worker recupera el workflow de la base de datos y guarda allí los resultados de la ejecución. El runner ejecuta las tareas de los nodos Code y devuelve sus resultados a través del broker. Si la instancia principal ejecuta workflows manuales, también necesita un runner para sus nodos Code. Arquitectura de colas.

Antes de implementar

Alcance de esta guía: es una explicación de la arquitectura. El antiguo ejemplo de Compose combinaba n8n 1.71.3 con una configuración de runners auxiliares cuyo mínimo documentado es 1.111.0, y utilizaba parámetros de conexión incorrectos. Se ha retirado. Este artículo no ofrece un despliegue probado de principio a fin.

Ese mínimo marca una condición de compatibilidad, no una recomendación para desplegar una versión antigua. Para implementarlo, elige una versión con soporte, fija las imágenes de n8n y de los runners a la misma versión y sigue la configuración oficial del modo externo y la guía del modo de colas. La instancia principal, los procesadores de webhooks y los workers también deben utilizar la misma versión de n8n.

El despliegue necesita su propia gestión de secretos, almacenamiento persistente, reglas de acceso a la red, proxy HTTPS y pruebas de recuperación. Las conexiones que se explican a continuación orientan la configuración; no forman un archivo completo de Compose.

Entender cada componente

PostgreSQL

Guarda workflows, credenciales y datos de ejecución. La instancia principal, los procesadores de webhooks y los workers necesitan acceso a la base de datos. Utiliza PostgreSQL para esta arquitectura distribuida; n8n no admite un despliegue distribuido de colas basado en SQLite.

Redis

Transporta los identificadores de las ejecuciones en cola y los mensajes de coordinación. Forma parte del proceso de ejecución: tratarlo como una caché prescindible es un error. Utiliza maxmemory-policy=noeviction para almacenar los trabajos: al alcanzar el límite de memoria, Redis rechaza las escrituras que necesitan más memoria en lugar de expulsar claves existentes. Planifica la persistencia y el margen de memoria, y vigila su consumo. Esta política no evita que se agote la memoria ni garantiza que todas las tareas terminen correctamente. Comportamiento de expulsión de Redis.

Main y procesadores de webhooks

La instancia principal sirve el editor y la API y gestiona los triggers. El modo de colas envía las ejecuciones de producción a los workers. Las ejecuciones manuales se realizan en main, salvo que OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERS=true las envíe también a los workers.

Los procesadores de webhooks son opcionales: reciben el tráfico de producción y pasan el trabajo de ejecución a la cola. Separarlos puede aliviar la carga del editor; la CPU, la memoria, Redis y la base de datos compartidos pueden seguir siendo cuellos de botella.

Workers

Los workers recogen las ejecuciones de la cola y procesan los workflows. La opción n8n worker --concurrency=10 fija un límite de diez trabajos, salvo que N8N_CONCURRENCY_PRODUCTION_LIMIT lo sobrescriba. En n8n 2.0.0, un valor de entorno distinto de -1 tiene prioridad sobre esa opción. Diez es su valor predeterminado, no una recomendación de capacidad. La concurrencia de tareas del runner es un límite distinto. Implementación del worker en 2.0.0.

Task runners externos

Cada worker necesita un contenedor auxiliar de runners para las tareas de los nodos Code. Main también lo necesita cuando realiza ejecuciones manuales; un receptor dedicado a webhooks no necesita un runner por el mero hecho de recibir peticiones HTTP.

Los task runners están activados por defecto desde n8n 2.0. Python nativo requiere el modo externo. JavaScript admite el modo interno, pero n8n recomienda el modo externo y medidas adicionales de aislamiento en producción o con datos sensibles. Separar contenedores es una capa de protección: también importan los permisos, los archivos montados, los secretos expuestos y los límites de recursos. No garantiza que el código malicioso o la falta de memoria no puedan afectar a otros servicios.

Enrutar el tráfico al proceso adecuado

Con un dominio público compartido y procesadores de webhooks dedicados, las rutas predeterminadas documentadas son:

Actualiza estas reglas si personalizas los nombres de los endpoints. Los puertos del host dependen de la red y del proxy; 5680 no es un puerto obligatorio para los webhooks. Ajusta la URL pública de los webhooks y la configuración del proxy al despliegue real. Guía oficial del balanceador.

Qué verificar en un entorno separado

Que un contenedor esté en ejecución no demuestra que funcione un workflow. Prueba el acceso al editor, un workflow guardado de producción, webhooks de producción y de prueba, un webhook de espera reanudado mediante una llamada externa, la ejecución manual y los nodos Code de JavaScript o Python que utilices. Comprueba que el worker previsto ejecuta el trabajo y que se guardan los resultados.

Después, prueba los reinicios y la recuperación con datos representativos y una copia de seguridad comprobada. Si falla un runner, revisa la dirección del broker, la conectividad, el token de autenticación compartido, las versiones de las imágenes y los registros. Un runner con problemas no indica una única causa. Son pasos para validar una implementación; no se han ejecutado sobre un despliegue proporcionado por este artículo.

Responsabilidades de configuración

El runner se conecta al broker de n8n. Mantén privado el puerto 5679 del broker; no es el puerto público del editor. La clave de cifrado y el token de autenticación del runner tienen funciones distintas.

En las versiones 1.x compatibles, activa los runners expresamente con N8N_RUNNERS_ENABLED=true. Desde 2.0 están activados por defecto y ese parámetro ya no es necesario. Revisa la configuración de runners de la versión elegida, incluidos los requisitos de Python y sus dependencias, en la guía oficial.

¿Cuándo necesitas esto?

Utiliza el modo de colas cuando necesites separar la ejecución de producción del editor o repartir el trabajo entre varios workers. Añade procesadores de webhooks dedicados cuando la recepción de peticiones necesite escalar por separado.

No hay un umbral universal útil basado solo en las ejecuciones diarias. Una petición HTTP breve y un workflow que procesa archivos grandes tienen costes muy distintos. Para dimensionar, prueba workflows y picos de tráfico representativos y mide la espera en cola, la duración de las ejecuciones, la memoria, la CPU y la carga de la base de datos antes de añadir workers o aumentar la concurrencia. El antiguo mínimo de 4 GB / 2 vCPU y los tramos de volumen diario no eran límites de capacidad validados.

Recursos

• Documentación oficial de Queue Mode
• Variables de entorno de Queue Mode
• Documentación de Task Runners
• Breaking changes en n8n 2.0