Ejercicio de n8n Queue Mode con Docker Compose: demuestra que un worker ejecutó el trabajo
Ejercicio práctico de n8n en modo queue con Docker Compose: servicios, variables de entorno y el log que confirman que un worker ejecutó el trabajo.
Comprobado con las fuentes citadas el .
Ejercicio editorial: enunciado de la tarea y objetivo
Este es un ejercicio editorial: una tarea para probar en tu propio entorno, no un informe de que nosotros la hayamos ejecutado. El objetivo es levantar n8n en modo queue con Docker Compose, conectando un proceso principal, una cola Redis y al menos un worker, y luego demostrar que un worker, y no el proceso principal, ejecutó realmente un trabajo. La propia publicación de n8n sobre pruebas de rendimiento, que cubre una ejecución de prueba de septiembre de 2025 y se publicó en el blog de n8n en enero de 2026, presenta el modo queue como el primer paso obligatorio para escalar una instancia autogestionada, no como un extra opcional, por lo que este ejercicio construye específicamente el modo queue en lugar de quedarse con un solo contenedor.
En la arquitectura documentada de n8n para el modo queue, la instancia principal recibe los triggers, como los webhooks, mientras que las instancias worker independientes realizan las ejecuciones reales de los workflows; tu archivo de Compose tiene que reproducir fielmente esa separación, o en realidad no habrás probado el modo queue en absoluto. Creemos que esta separación es la idea más importante que hay que internalizar antes de tocar Docker Compose, porque cada variable de entorno y cada paso de resolución de problemas de más adelante existen para servir a esa idea.
Sources: The n8n Scalability Benchmark – n8n Blog, Enable queue mode | Deploy | n8n Docs
Requisitos previos y datos de entrada para n8n queue mode
Antes de abrir un archivo compose, la documentación de instalación de Docker de n8n enumera dos requisitos previos: Docker Desktop, que incluye Docker Compose, y conocimientos prácticos de configuración y protección de servidores y contenedores. La propia n8n marca actualmente esa página como desactualizada, así que trata solo esos requisitos generales como vigentes, no los números de versión ni los comandos que allí se indican.
Ejecutar n8n en modo queue con Docker Compose necesita cuatro entradas de servicio: Redis para la cola de trabajos, una base de datos, un proceso n8n principal y un proceso worker. Recomendaríamos decidirse por Postgres desde el principio en lugar de incorporarlo después, ya que cambiar la base de datos debajo de una configuración en modo queue ya en funcionamiento es mucho más disruptivo que elegirla de antemano.
| Servicio | Función | Ajuste clave |
|---|---|---|
| Redis | Mantiene la cola de trabajos entre el principal y los workers | Puerto predeterminado, accesible por nombre de host desde otros servicios |
| Base de datos | Almacena workflows, credenciales y datos de ejecución | Se recomienda Postgres desde el principio, según nuestra propia recomendación |
| Principal | Recibe los triggers y encola los trabajos | EXECUTIONS_MODE=queue, clave de cifrado compartida |
| Worker | Toma los trabajos de la cola y los ejecuta | EXECUTIONS_MODE=queue, misma clave de cifrado, flag --concurrency opcional |
Dos ajustes deben coincidir en todos los servicios. La documentación de n8n indica establecer EXECUTIONS_MODE en queue tanto en la instancia principal como en cada worker, y señala que la clave de cifrado de la instancia principal debe compartirse con todos los nodos worker, ya que estos la necesitan para descifrar las credenciales almacenadas.
Sources: Install with Docker | Deploy | n8n Docs, Enable queue mode | Deploy | n8n Docs, Executions | Deploy | n8n Docs, Control concurrency | Deploy | n8n Docs
Pasos de construcción: configurando n8n queue mode con Docker Compose
Aquí tienes n8n en modo queue con Docker Compose, dividido en los servicios que añades en este orden.
- Añade un servicio Redis sin variables de entorno especiales, accesible internamente por los demás servicios.
- Añade un servicio de base de datos, con sus credenciales y un volumen persistente.
- Añade un servicio principal con EXECUTIONS_MODE=queue, la conexión a la base de datos, el host y puerto de Redis, la clave de cifrado compartida, y un puerto publicado para el editor y los webhooks.
- Añade un servicio worker con el mismo EXECUTIONS_MODE, clave de cifrado, base de datos y ajustes de Redis, iniciado con el comando worker y sin puerto publicado.
La documentación de n8n describe la concurrencia por worker, es decir, cuántos trabajos ejecuta un worker en paralelo, como un mecanismo distinto de la concurrencia del modo normal, controlado con el flag --concurrency, mientras que la protección de concurrencia de ejecución en producción, más amplia, está desactivada de forma predeterminada en las instancias autogestionadas. Para una primera aproximación a n8n queue mode docker, deja ambos en sus valores predeterminados y empieza con un solo worker; ajusta la concurrencia solo una vez que el flujo básico principal-Redis-worker esté confirmado y funcionando.
Sources: Enable queue mode | Deploy | n8n Docs, Control concurrency | Deploy | n8n Docs, Executions | Deploy | n8n Docs
Criterios de finalización: demostrar que un worker ejecutó el trabajo
Completar este ejercicio significa más que «no dio error». Tienes que disparar un workflow con webhook y demostrar que la entrada de esa ejecución concreta aparece en el log del worker, no solo en el log del proceso principal. La documentación de n8n facilitada no ofrece un ejemplo resuelto para esto; el método siguiente combina editorialmente dos funciones documentadas por separado, así que trátalo como una combinación nuestra y no como un procedimiento oficial.
La documentación de n8n recomienda dar a cada worker una ruta de log de eventos única cuando los workers comparten un sistema de archivos con permisos de escritura, y describe por separado debug como el nivel de log más detallado, con la salida que puede enviarse a la consola, a un archivo, o a ambos. Configura el nivel de log del worker en debug y apúntalo a su propio archivo, dispara el webhook, y luego abre ese archivo y confirma que la ejecución aparece ahí.
Vale la pena dejar claro un matiz: n8n documenta una página de Settings > Workers para observar los workers en ejecución, pero solo en los planes self-hosted Enterprise y n8n Cloud Enterprise, así que los lectores de la edición Community que sigan este ejercicio no pueden depender de esa interfaz y necesitan la comprobación basada en logs descrita arriba.
Sources: Enable queue mode | Deploy | n8n Docs, Set up logging | Deploy | n8n Docs
Resolución de problemas y reflexión
Según nuestra experiencia, una buena primera comprobación es si el worker puede descifrar las credenciales, ya que esto a menudo se debe a una clave de cifrado que no coincide entre el principal y el worker. A partir de ahí, comprueba si el worker puede alcanzar Redis en absoluto, ya que un desajuste de red en Compose es una causa frecuente de trabajos que se encolan pero nunca se vacían, especialmente cuando solo hay un worker en ejecución con su concurrencia configurada demasiado baja.
- Confirma que N8N_ENCRYPTION_KEY coincide exactamente entre el principal y el worker
- Confirma que el worker puede alcanzar Redis en el host y puerto configurados
- Confirma que los datos de conexión a la base de datos coinciden en el principal y el worker
- Confirma que el contenedor worker ejecuta el comando worker, no el comando principal predeterminado
Vale la pena tener presente la motivación mientras depuras. Ese mismo análisis comparativo midió 72 solicitudes por segundo, con una latencia que se mantuvo por debajo de tres segundos en una prueba de carga de un solo webhook en modo queue. Se trata de una cifra autodeclarada por n8n en un hardware de prueba específico, no una garantía para tu configuración, así que trátala como contexto de por qué importa la arquitectura, no como un objetivo a reproducir.
Seríamos cautos con perseguir esas cifras de rendimiento en un ejercicio de aprendizaje: el objetivo aquí es una configuración principal-worker-Redis correctamente conectada que puedas explicar, no un número copiado de la instancia de AWS de otra persona.
Como solución sugerida, espera que un ejercicio terminado acabe con los contenedores principal, worker, Redis y base de datos en ejecución, un webhook que responde correctamente, y un archivo de log del worker que contiene la entrada de esa ejecución mientras el log del proceso principal solo muestra que fue recibida y encolada. Esa es toda la forma de n8n queue mode con Docker Compose para un solo worker: si falta alguna de esas tres piezas, la configuración todavía no está terminada, sea cual sea el aspecto de la respuesta del webhook.
Sources: Enable queue mode | Deploy | n8n Docs, Control concurrency | Deploy | n8n Docs
