N8N en mode Queue

1. Quoi ? — Définition et contexte

Le mode Queue de N8N est une architecture d’exécution distribuée où les workflows sont délégués à des processus séparés (workers) via une file d’attente Redis. Cette architecture remplace le mode par défaut où tout s’exécute dans un seul processus.

Composants du mode Queue

Composant	Rôle	Instance
Main	Interface web, API, déclenchement des workflows	1 (singleton)
Workers	Exécution effective des workflows	N (scalable)
Redis	File d’attente Bull + coordination Pub/Sub	1 (partagé)
PostgreSQL	Stockage des workflows, credentials, historique	1 (partagé)

Bull Queue

Bull est une bibliothèque Node.js qui utilise Redis pour gérer des files d’attente de jobs. Chaque workflow déclenché devient un “job” que les workers récupèrent et exécutent de manière asynchrone.

Architecture visuelle

---

2. Pourquoi ? — Enjeux et motivations

Problème du mode par défaut

Par défaut, N8N exécute les workflows dans le même processus que l’interface web. Conséquences :

Symptôme	Cause	Impact
Interface lente	CPU monopolisé par un workflow	UX dégradée
Timeouts webhooks	Workflow long bloque la réponse	Intégrations cassées
Pas de parallélisme	Un seul thread d’exécution	Goulot d’étranglement
Propagation des crashs	Erreur mémoire = tout tombe	Perte de service

Cas d’usage justifiant le mode Queue

Cette configuration répond à quatre besoins concrets :

1. Appels API longs — Les workflows utilisant Claude/IA peuvent prendre 5-30 secondes par appel. Sans Queue, l’interface serait bloquée.

2. Parallélisme — Plusieurs webhooks peuvent arriver simultanément (commits GitHub, messages Telegram). Chaque worker traite un job indépendamment.

3. Tâches batch — Les imports de données ou synchronisations massives (Odoo ↔ N8N) sont exécutés en arrière-plan sans impacter l’UI.

4. Fiabilité — Les jobs échoués sont automatiquement re-tentés. Un worker qui crash n’affecte pas les autres.

Quand activer le mode Queue ?

Le mode Queue est recommandé dès que vous avez : des workflows qui durent plus de 10 secondes, plusieurs webhooks actifs, ou un besoin de haute disponibilité.

---

3. Comment ? — Mise en œuvre technique

Configuration Docker Compose

services:
  n8n:
    image: n8n-custom:latest  # Image avec nodes custom
    environment:
      - EXECUTIONS_MODE=queue
      - QUEUE_BULL_REDIS_HOST=n8n-redis
      - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}
    depends_on:
      - n8n-postgres
      - n8n-redis

  n8n-worker:
    image: n8n-custom:latest
    command: worker
    environment:
      - EXECUTIONS_MODE=queue
      - QUEUE_BULL_REDIS_HOST=n8n-redis
      - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}
    deploy:
      replicas: 5

  n8n-redis:
    image: redis:7-alpine
    volumes:
      - n8n-redis-data:/data

  n8n-postgres:
    image: postgres:15
    environment:
      - POSTGRES_DB=n8n

N8N_ENCRYPTION_KEY critique

La variable N8N_ENCRYPTION_KEY doit être identique sur le main et tous les workers. Cette clé chiffre les credentials stockés en base. Si elle diffère, les workers ne pourront pas déchiffrer les identifiants et les workflows échoueront silencieusement.

Dimensionnement des workers

Le nombre de workers (5 dans cette configuration) est déterminé par deux contraintes :

Contrainte	Calcul	Résultat
Règle empirique	1 worker par vCPU + 1 marge	4 + 1 = 5 workers
RAM disponible	~400 MB par worker	5 × 400 = 2 GB (budget n8n-stack)

Data Tables intégrées

N8N propose des Data Tables pour stocker des données structurées directement dans l’instance. La base actuelle en compte une vingtaine, organisées par domaine :

Domaine	Tables principales
Telegram	Telegram Authorized users, Telegram Banned Users, Telegram Pending Approvals
Docker	Docker_image_policies, Docker_pending_updates, Docker_pending_upd_approvals
Notifications	notification_routing, notification_history, pending_notifications, pending_deferred, escalation_tracking
Erreurs	error_dead_letter_queue, error_handling_config
Telemetry	claude_code_active_sessions, claude_code_sessions_v2
Sync externe	Odoo_github_project_mapping, timetrackr_user_mapping, content_pipeline
Workflows	n8n_trigger_whitelist, n8n_pending_actions, n8n_datatable_metadata

Data Tables vs Base de données

Les Data Tables sont pratiques pour des configurations simples ou des données temporaires. Pour des volumes importants ou des requêtes complexes, préférez PostgreSQL ou Qdrant.

Intégration AI Stack

N8N communique avec l’AI Stack via HTTP interne :

// HTTP Request vers CLI Ollama (Codex par défaut)
{
  "url": "http://cli-ollama:11434/api/generate",
  "method": "POST",
  "body": {
    "model": "codex-yolo",
    "prompt": "Analyse ce message...",
    "stream": false
  }
}

Modèle -yolo obligatoire depuis N8N

Les workflows N8N qui n’ont pas d’humain dans la boucle doivent utiliser un modèle -yolo (ex: codex-yolo, gemini-flash-yolo). Un modèle non-yolo bascule en plan mode interactif et fait timeout côté webhook (120 s).

Cas d’usage IA :

• Intent detection — Le Telegram Orchestrator utilise CLI Ollama pour router les messages
• MCP via gateway — Workflows admin via les outils MCP whitelistés (n8n_get_workflow, n8n_executions, etc.)
• RAG — Recherche sémantique dans Qdrant pour enrichir les réponses
• Analyse d’erreurs — Profile error-analyst consommé par le workflow GEH AI Auto-Fix

Commandes d’exploitation

# Voir les workers actifs
docker compose -f n8n-stack/docker-compose.yaml ps

# Logs d'un worker spécifique
docker logs n8n-stack-n8n-worker-3 --tail 100

# Scaler les workers dynamiquement
docker compose -f n8n-stack/docker-compose.yaml up -d --scale n8n-worker=8

# Vérifier la queue Redis
docker exec n8n-redis redis-cli LLEN bull:jobs:waiting

---

4. Et si ? — Perspectives et limites

Limites actuelles

Limite	Impact	Mitigation
Redis single-instance	SPOF pour la queue	Snapshots réguliers, reconstruction rapide
Pas de priorités	Jobs traités FIFO	Workflows critiques pas privilégiés
Scaling manuel	Pas d’auto-scaling	Monitoring + ajustement périodique

Scénarios d’évolution

Si la charge augmente significativement :

• Augmenter les workers jusqu’à la limite RAM
• Passer à un VPS plus puissant (scaling vertical)
• Séparer Redis/PostgreSQL sur leur propre instance

Si un workflow monopolise les ressources :

• Créer une queue dédiée pour les workflows longs
• Configurer des concurrency limits par workflow
• Utiliser des sub-workflows pour découper les traitements

Si la fiabilité devient critique :

• Déployer Redis en mode Sentinel (HA)
• Ajouter un second instance N8N main en standby
• Externaliser vers Redis Cloud ou AWS ElastiCache

Métriques à surveiller

Pour anticiper les problèmes, surveiller via Monitoring Stack :

Métrique	Seuil d’alerte	Action
bull:jobs:waiting	> 50 jobs	Ajouter workers
Worker CPU	> 80% soutenu	Optimiser workflows ou scaler
Exécutions échouées	> 5%	Investiguer les erreurs

---

Pages liées

Infrastructure

• Architecture VPS — Vue d’ensemble
• AI Stack — Claude Ollama + Qdrant
• Monitoring Stack — Métriques N8N

Workflows

• Telegram Orchestrator — Bot de contrôle central
• Docker Auto-Updates — Mises à jour automatiques
• Notification Hub — Centralisation des alertes

Référence

• Glossaire — Queue, Worker, Bull