---
title: N8N en mode Queue
url: https://blog.guigpap.com/fr/infrastructure/n8n-queue-mode/
url_md: https://blog.guigpap.com/fr/infrastructure/n8n-queue-mode.md
category: infrastructure
date: '2026-01-19'
maturite: production
techno:
  - n8n
  - docker
  - redis
  - postgresql
application:
  - automation
  - infrastructure
---

# N8N en mode Queue

> Configuration de N8N avec workers séparés et Redis pour la scalabilité

## 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é) |

> **Note - 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

```mermaid
flowchart TD
  subgraph Main["N8N Main · :5678"]
    direction TB
    UI["Interface web"]
    API["API REST"]
    HOOKS["Webhooks · déclencheurs"]
    ENQ["Enqueue jobs → Redis"]
  end

  subgraph Bull["Redis · Bull Queue"]
    direction TB
    Q1["bull:jobs:active"]
    Q2["bull:jobs:waiting"]
    PS["Pub/Sub · coordination workers"]
  end

  W1["Worker 1 · replica"]
  W2["Worker 2 · replica"]
  WN["Worker N · replica"]

  Main --> Bull
  Bull --> W1
  Bull --> W2
  Bull --> WN
```

---

## 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.

> **Tip - 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

```yaml
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
```

> **Danger - 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` |

> **Note - 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](/fr/infrastructure/ai-stack/) via HTTP interne :

```javascript
// 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
  }
}
```

> **Caution - 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](/fr/workflows/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

```bash
# 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](/fr/infrastructure/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](/fr/infrastructure/architecture-vps/) — Vue d'ensemble
- [AI Stack](/fr/infrastructure/ai-stack/) — Claude Ollama + Qdrant
- [Monitoring Stack](/fr/infrastructure/monitoring-stack/) — Métriques N8N

### Workflows
- [Telegram Orchestrator](/fr/workflows/telegram-orchestrator/) — Bot de contrôle central
- [Docker Auto-Updates](/fr/workflows/docker-updates/) — Mises à jour automatiques
- [Notification Hub](/fr/workflows/notification-hub/) — Centralisation des alertes

### Référence
- [Glossaire](/fr/reference/glossary/) — Queue, Worker, Bull

## Metadonnees agent

- Cet article est issu du blog GuiGPaP Lab.
- Contexte global du blog: https://blog.guigpap.com/llms.txt
- Contact auteur: https://odoo.guigpap.com/mon-cv
- Licence: CC-BY-SA 4.0