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

┌─────────────────────────────────────────────────────────┐
│                    N8N Main (port 5678)                  │
│  ├─ Interface web                                       │
│  ├─ API REST                                            │
│  ├─ Webhooks (déclencheurs)                             │
│  └─ Enqueue jobs → Redis                                │
└───────────────────────┬─────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────────┐
│                  Redis (Bull Queue)                      │
│  ├─ Queue: bull:jobs:active                             │
│  ├─ Queue: bull:jobs:waiting                            │
│  └─ Pub/Sub: coordination workers                       │
└───────────────────────┬─────────────────────────────────┘
                        │
        ┌───────────────┼───────────────┐
        ▼               ▼               ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│  Worker 1   │ │  Worker 2   │ │  Worker N   │
│  (replica)  │ │  (replica)  │ │  (replica)  │
└─────────────┘ └─────────────┘ └─────────────┘

---

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 :

Table	Usage
authorized_users	IDs Telegram autorisés
image_policies	Politique de mise à jour par image Docker
pending_updates	Queue des updates Docker à appliquer
github_project_mapping	Mapping repos GitHub ↔ projets Odoo
trigger_whitelist	Workflows autorisés via Telegram

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 Claude Ollama
{
  "url": "http://claude-ollama:11434/api/generate",
  "method": "POST",
  "body": {
    "model": "claude-sonnet-4-20250514",
    "prompt": "Analyse ce message...",
    "stream": false
  }
}

Cas d’usage IA :

• Intent detection — Le Telegram Orchestrator utilise Claude pour router les messages
• RAG — Recherche sémantique dans Qdrant pour enrichir les réponses
• Résumés — Génération automatique de résumés de logs ou alertes

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