Migration de n8n vers Traefik 3.3 et Postgres 16 : guide technique

# Migration sécurisée de n8n : Mise à niveau de Traefik vers 3.3 et Postgres vers 16 sans perte de données

Migrer n8n depuis des versions obsolètes de Traefik et Postgres vers une pile moderne nécessite de résoudre des problèmes de compatibilité critiques. Cet article fournit un guide technique pour préserver les données et les identifiants lors de la mise à niveau depuis Traefik 1.x et Postgres 11 vers les dernières versions.

Préparation : Sauvegarde et clé de chiffrement

L'étape clé de la migration consiste à exporter correctement les données et à préserver la clé de chiffrement. Sans elle, les identifiants deviendront inaccessibles après le transfert. Pour n8n, c'est critique : le système utilise un chiffrement symétrique pour stocker les tokens et mots de passe.

Effectuez ces deux actions obligatoires :

• Créez un dump de la base de données au format custom pour une restauration correcte :

docker exec -t postgres_db pg_dump -U root -d n8n -Fc > /tmp/n8n_backup.dump
docker cp postgres_db:/tmp/n8n_backup.dump ./n8n_backup.dump

• Extrayez la clé de chiffrement actuelle de la configuration. La source peut se trouver en deux endroits :

- Variable N8N_ENCRYPTION_KEY dans docker-compose.yml

- Paramètre encryptionKey dans le fichier ~/.n8n/config

Ignorer cette étape entraînera une erreur Needs first setup au démarrage. Le système reconnaîtra la base de données mais ne pourra pas déchiffrer les identifiants stockés.

Déploiement de la pile : Pièges de Traefik 3.3

Lors du déploiement de Traefik 3.3, un problème d'incompatibilité critique avec l'API Docker apparaît. Le routeur utilise par défaut une version obsolète de l'API (1.24), alors que les démons Docker modernes exigent la version 1.41 ou supérieure. Cela entraîne des erreurs 404 lors de la tentative de découverte des conteneurs.

Solution — forcez la version de l'API dans les variables d'environnement :

environment:
  - DOCKER_API_VERSION=1.41

Ce changement permet à Traefik d'interagir correctement avec Docker Engine. Sans cela, le routeur ne peut pas voir les conteneurs n8n et Postgres, rendant impossible la configuration automatique des routes via le Provider Docker.

Notez l'isolation réseau : tous les services doivent être dans le même réseau personnalisé (n8n_net). Cela assure une interaction stable entre les conteneurs sans conflits de routage. Exemple de configuration correcte :

networks:
  n8n_net:
    name: n8n_net

services:
  traefik:
    networks:
      - n8n_net
  n8n:
    networks:
      - n8n_net
  postgres_db:
    networks:
      - n8n_net

Restauration de la base de données dans Postgres 16 : Correction des problèmes de permissions

Postgres 16 introduit des changements dans la politique de sécurité par défaut. Le schéma public a maintenant des permissions restreintes, provoquant une erreur permission denied for schema public au démarrage de n8n.

Après restauration du dump, exécutez :

docker cp n8n_backup.dump postgres_db:/tmp/
docker exec -i postgres_db pg_restore -U root -d n8n -1 /tmp/n8n_backup.dump

Puis accordez des permissions complètes sur le schéma au propriétaire de la base de données :

docker exec -it postgres_db psql -U root -d n8n -c "GRANT ALL ON SCHEMA public TO root;"

Cela est nécessaire car n8n utilise activement le schéma public pour stocker les métadonnées. Sauter cette étape fera planter le conteneur n8n de manière répétée.

Correction des identifiants : Éviter l'erreur « Needs first setup »

Même en passant correctement N8N_ENCRYPTION_KEY via les variables d'environnement, n8n peut l'ignorer. La raison est un conflit entre la variable d'environnement et le fichier de configuration local. Au premier démarrage, le système génère un nouveau fichier ~/.n8n/config qui écrase la clé des variables.

Solution :

• Supprimez le fichier de configuration dans le conteneur :

docker exec -it n8n rm /home/node/.n8n/config

• Redémarrez le service :

docker compose restart n8n

Cela force n8n à utiliser la clé des variables d'environnement au lieu du fichier local. Assurez-vous que la variable N8N_ENCRYPTION_KEY originale est spécifiée dans docker-compose.yml.

Nuances supplémentaires : Processus en arrière-plan et SQLite

Pendant la migration, des problèmes peuvent survenir avec les tâches en arrière-plan utilisant SQLite (par ex., parseurs Telegram basés sur Telethon). Après transfert, vous verrez sqlite3.OperationalError: database is locked.

Cause — fichiers de journalisation résiduels (.session-journal, .session-wal) qui verrouillent la base de données. Solution :

• Installez l'utilitaire psmisc :

apt install psmisc -y

• Tuez de force les processus qui maintiennent le verrou :

fuser -k -v /root/parser_folder/session_name.session

• Supprimez les fichiers temporaires :

rm -f /root/parser_folder/session_name.session-journal
rm -f /root/parser_folder/session_name.session-wal

• Redémarrez le service :

systemctl restart service_name.service

Important : Supprimer les journaux n'affecte pas le fichier de session principal. L'autorisation Telegram reste intacte.

Points clés

• La clé de chiffrement est obligatoire — sans la N8N_ENCRYPTION_KEY originale, tous les identifiants deviendront inaccessibles.
• Traefik nécessite une spécification explicite de l'API — le paramètre DOCKER_API_VERSION=1.41 est critique pour la découverte des conteneurs.
• Postgres 16 restreint les permissions — émettre manuellement GRANT ALL ON SCHEMA public.
• Conflits de config locale n8n — supprimer ~/.n8n/config résout le problème de clé de chiffrement.
• Verrous SQLite nécessitent un nettoyage — supprimer les fichiers .journal et .wal restaure les processus en arrière-plan.

Après avoir complété toutes les étapes, n8n démarrera avec tous les workflows, webhooks et identifiants préservés. La migration entre versions majeures de logiciels comporte toujours des risques, mais suivre ces procédures minimise les temps d'arrêt et les pertes de données.

— Editorial Team