Qu’est-ce que Docker : les connaissances minimales nécessaires pour les débutants sur n8n

L'endroit où l'installation de n8n bloque le plus facilement n'est pas n8n lui-même, mais le Docker qui le précède. On copie les cinq lignes de commandes du tutoriel, le container démarre, on clique deux fois dans l'interface et ça marche ; le lendemain, on constate que tous les workflows ont disparu — la seule raison est qu'il manquait une chose dans ces cinq lignes -v。

Cet article ne traite que la partie de Docker nécessaire à l'installation de n8n : image, container, volume, port. Quatre mots. Quant aux modes réseau, à Compose, à la construction de ses propres images, on verra quand on en aura vraiment besoin ; apprendre trop tôt, on oublie de toute façon.

Un seul prérequis : savoir taper des commandes dans un terminal et savoir ce qu'est un « port ». Ne jamais avoir touché à Docker n'a aucun impact.

• Pourquoi n8n finit toujours dans Docker
• Quatre mots : image, container, volume, port
• Installer Docker d'abord
• Lancer un n8n, en trois étapes
• Comment savoir que c'est bien installé
• Dans quel fichier se trouvent réellement les données
• Six erreurs que l'on rencontre vraiment
• Quelques points de sécurité liés à n8n

Pourquoi n8n finit toujours dans Docker

La page d'installation officielle propose plusieurs voies : installation globale via npm, exécution directe via npx, Docker, version desktop. Les deux premières sont les plus légères, une seule npm install -g n8n suffit, le problème est qu'elles lient n8n au Node de votre machine. n8n est pointilleux sur la version de Node, la documentation indique l'intervalle 20.19 à 24.x. Le jour où vous passez Node à 26 pour un autre projet, n8n tombe en panne avec lui, et le message d'erreur n'est pas forcément explicite.

Docker change d'approche : il empaquette n8n avec le Node, les bibliothèques système et les données de fuseau horaire dont il a besoin dans un seul paquet, qui tourne de la même façon sur n'importe quelle machine. Je suis特意 allé voir dans l'image 2.43.7 : Node est en 26.7.0, l'image de base est Alpine. Tout cela n'a rien à voir avec le fait que votre hôte ait Node 18 ou 26 installé.

Le coût doit aussi être clairement énoncé. Vous avez une couche supplémentaire à maintenir : l’image occupe du disque (1,8 GB après décompression pour 2.43.7), en cas de problème il faut consulter un journal de plus, et la mise à jour passe de « npm update » à « changer l’image et relancer ». Je considère que ça vaut le coup — pour la mise à jour, changer le tag, supprimer le container, relancer, trois minutes, sans se soucier de la version de Node.

Si vous ne comptez jouer que deux jours en local, je ne recommande pas Docker, npm est plus rapide. Si vous prévoyez de l’exécuter à long terme, ou de le mettre à disposition de collègues, passez directement à Docker, n’empruntez pas de détours.

Quatre mots : image, container, volume, port

Image

Une image est un paquet en lecture seule préparé par quelqu’un d’autre, contenant un système de fichiers complet capable de faire tourner n8n.n8nio/n8n est le nom,2.43.7 est le tag. Un même nom porte une série de tags, un tag correspond à une version.

Le tag s’écrit latest, ce qui signifie « dernière version stable ». En production, je ne recommande pas de l’écrire ainsi : si un jour le container redémarre et récupère au passage une nouvelle image, le comportement change, et vous ne saurez même pas où chercher. Fixez le numéro de version, traitez la mise à jour comme une opération distincte.

Container

L’image est inerte.docker run Le processus qui démarre ensuite s’appelle un container. Un container équivaut à une image plus une couche inscriptible ; tout ce que vous modifiez à l’intérieur est écrit sur cette couche. Si le container est supprimé, cette couche disparaît avec lui — cette phrase est la source de tous les pièges qui suivent.

卷

C’est pourquoi les données de n8n ne doivent pas être placées dans le container. Un volume est un répertoire sur l’hôte, géré par Docker, monté dans un certain chemin du container. Le chemin reconnu par n8n est /home/node/.n8n, la base de données, les clés de chiffrement et les journaux d'événements sont là.

J'ai compté : un répertoire qui vient d'être créé avec un compte owner et qui a exécuté un workflow .n8n répertoire, 5,5 MB. Dont database.sqlite 1,5 MB, plus un fichier de 4 MB -wal fichier. C'est tout ce qu'il y a, et si on le perd, tout est à refaire.

port

-p 5678:5678, à gauche des deux-points c'est le port de l'hôte, à droite le port dans le container. Le n8n dans le container écoute toujours 5678 (sauf si tu modifies N8N_PORT), si tu veux changer le numéro à l'extérieur, tu ne touches qu'à gauche :-p 8080:5678。

écrire 127.0.0.1:5678:5678 cela ne lie qu'à la machine locale, l'extérieur ne peut pas se connecter. J'utilise cette écriture pendant mes tests, pour ne pas oublier de fermer.

D'abord installer Docker

Sur Ubuntu / Debian le plus simple c'est le script officiel :

curl -fsSL https://get.docker.com | sh

Il ajoute le dépôt officiel, installe docker-ce, avec le plugin compose. Si tu n'aimes pas « envoyer directement la sortie de curl à sh », passe proprement par le dépôt officiel apt, les étapes sont dans la doc Docker, c'est juste plus long.

Après l'installation, tape deux commandes pour voir la version :

docker --version
# Docker version 29.1.3, build 29.1.3-0ubuntu3~24.04.2

Ma machine 232 tourne sous Ubuntu 24.04 + Docker 29.1.3. Tu peux utiliser 24 ou 25, les commandes sont identiques.

Docker nécessite root ou sudo par défaut. Certains disent qu'ajouter l'utilisateur au docker groupe permet de se passer de sudo, c'est vrai, mais cela revient à donner à cet utilisateur les droits root, la raison est dans la section sécurité.

Lancer un n8n, trois étapes

Première étape : créer le volume

docker volume create n8n_data
# n8n_data

Le nom du volume renvoyé signifie qu'il est créé. Cette étape n'est pas obligatoire,docker run écrire dans -v n8n_data:/home/node/.n8n le créera automatiquement — mais en le créant une fois d'abord, vous pouvez confirmer qu'il existe vraiment.

Deuxième étape : le faire tourner

docker run -d 
  --name n8n 
  -p 127.0.0.1:5678:5678 
  -e TZ=Asia/Shanghai 
  -e GENERIC_TIMEZONE=Asia/Shanghai 
  -e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true 
  -v n8n_data:/home/node/.n8n 
  n8nio/n8n:2.43.7

Par rapport à la commande originale de la documentation officielle, j'ai modifié deux choses.

L'une est l'ajout de -d. La documentation donne docker run -it --rm, exécution au premier plan, dès que le terminal se ferme ou Ctrl+C, n8n s'arrête ;--rm et supprime aussi le container au passage. En débogage c'est très propre, mais pour une exécution longue durée ce n'est pas viable, ajoutez -d pour le laisser en arrière-plan.

L'autre est l'ajout devant le port de 127.0.0.1:. La documentation indique -p 5678:5678, cela équivaut à lier sur 0.0.0.0 ; tant que la machine a une IP publique, quiconque scanne le 5678 verra votre page de connexion. Sur ma machine 232, le 5678 est occupé, j'utilise donc en pratique -p 127.0.0.1:5681:5678, la correspondance est identique.

Les deux variables de fuseau horaire doivent être définies.TZ gère l'heure système du container,GENERIC_TIMEZONE gère la façon dont n8n calcule le temps lui-même, le Schedule Trigger se base sur la seconde. Si vous ne définissez que TZ, les tâches planifiées restent en UTC, votre 9h du matin devient 17h heure de Pékin. Ce genre de chose ne laisse aucune anomalie dans les logs.

Troisième étape : consulter les logs et attendre qu'il démarre

docker logs -f n8n

Le premier démarrage exécute des dizaines de migrations de base de données,Starting migration ... 和 Finished migration ... alternent, c'est normal. Attendez que ces deux lignes apparaissent :

Version: 2.43.7

Editor is now accessible via:
http://localhost:5678

Ce http://localhost:5678 est une adresse interne au container, impossible à ouvrir dans le navigateur. Ce que vous pouvez ouvrir, c'est http://服务器IP:5678, ou sur la machine locale http://127.0.0.1:5678. Cette ligne a trompé pas mal de gens, y compris moi lors du premier lancement.

La version 2.43.7 émet aussi cinq avertissements de deprecation au démarrage, à propos de N8N_RUNNERS_MODE、N8N_UNVERIFIED_PACKAGES_ENABLED Ces valeurs par défaut devront être modifiées plus tard. Cela n'affecte pas l'utilisation, c'est pour préparer les versions futures. Il y a aussi une ligne Failed to start Python task runner in internal mode. because Python 3 is missing from this system.— Python n'est pas installé dans l'image, si vous n'utilisez que le nœud Code en JS, vous pouvez l'ignorer complètement.

Une fois le compte créé, on entre. Cette étape n'a de sens que si elle est écrite dans le volume — la vérification ci-dessous expliquera comment confirmer qu'elle est réellement persistée sur disque.

Comment savoir que c'est bien installé

Quatre vérifications, toutes à faire dans le terminal.

1. docker ps Dans STATUS c'est Up, PORTS a un mapping, IMAGE est le tag que vous avez spécifié.
2. curl -s http://127.0.0.1:5678/healthz Retourne {"status":"ok"}. Cette interface indique seulement que le processus est vivant.
3. docker exec n8n n8n --version 回 2.43.7, correspond au tag que vous avez fourni.
4. docker restart n8n, attendez une dizaine de secondes puis ouvrez la page, il ne devrait plus vous demander de créer un compte.

Le point 4 est le plus facile à négliger, et le plus précieux. Il vérifie deux choses à la fois : le volume est correctement monté, et les données sont réellement en dehors du container.

Quand j'ai pris cette capture d'écran, j'ai jeté un œil dans le container .n8n, 5.5 MB, cela correspond à ce qui a été dit plus haut. Si votre du -sh affiche quelques centaines de K, les données ont probablement été écrites dans la couche inscriptible du container, le volume n'est pas monté.

Dans quel fichier se trouvent réellement les données

Une fois le volume créé, l'emplacement réel sur l'hôte est déterminé par Docker, utilisez cette commande pour vérifier :

docker volume inspect n8n_data
# [
#     {
#         "CreatedAt": "2026-11-02T09:28:41+08:00",
#         "Driver": "local",
#         "Mountpoint": "/var/lib/docker/volumes/n8n_data/_data",
#         "Name": "n8n_data",
#         "Scope": "local"
#     }
# ]

« Mountpoint » est son emplacement réel sur l'hôte. Sur ma machine, j'ai déplacé le répertoire racine des données Docker vers /data/docker, donc ce que je vois est /data/docker/volumes/n8n_data/_data; sur une machine installée par défaut, c'est le /var/lib/docker/...ci-dessus. Fiez-vous à la sortie de votre propre machine.

Vu depuis le container, voici à quoi cela ressemble pour n8n :

docker exec n8n ls -la /home/node/.n8n
# -rw-r--r-- 1 node node 1519616 Nov  2 09:29 database.sqlite
# -rw-r--r-- 1 node node   32768 Nov  2 09:38 database.sqlite-shm
# -rw-r--r-- 1 node node 4136512 Nov  2 09:37 database.sqlite-wal
# -rw-r--r-- 1 node node    7972 Nov  2 09:37 n8nEventLog-1.log
# -rw-r--r-- 1 node node     526 Nov  2 09:38 n8nEventLog.log

workflows, historiques d'exécution, identifiants chiffrés, tout est dans database.sqlite . La clé de chiffrement nécessaire pour déchiffrer les identifiants se trouve dans le même répertoire, par défaut le fichier config , généré automatiquement au premier démarrage.

Donc sauvegarder n8n revient à deux choses : ce répertoire, et le numéro de version. Si vous ne sauvegardez que le sqlite sans la clé, après restauration sur une autre machine, les identifiants seront tous illisibles.

Si vous voulez passer à un répertoire hôte que vous spécifiez vous-même (par exemple /data/n8n), remplacez le -v n8n_data:/home/node/.n8n Remplacer par -v /data/n8n:/home/node/.n8n suffit. C'est un « bind mount » : le répertoire est sous votre contrôle, la sauvegarde est plus intuitive, le prix à payer est que vous devez gérer vous-même les permissions — et c'est précisément le prochain piège.

Six erreurs que vous rencontrerez vraiment

1. Oublier -v, supprimer le container équivaut à supprimer la base de données

J'ai fait un comparatif avec deux containers, sur la même machine, avec la même image : celui avec -v n8n_data:/home/node/.n8n , après redémarrage, l'interface renvoie pour « afficher ou non la configuration initiale » false; l'autre sans -v , la même interface renvoie true— il est redevenu une instance vide.

Tout le processus ne signale aucune erreur, aucune alerte. Un beau jour, vous ouvrez et constatez que les workflows ont disparu.

Méthode de vérification :docker inspect n8n, remontez chercher "Mounts" ce passage, si "Destination": "/home/node/.n8n" y apparaît, c'est monté ; si tout le passage est vide, c'est dangereux.

2. Monter un répertoire de l'hôte, erreur EACCES

On veut utiliser un mount bind, le répertoire est créé et on monte directement, donc :

Error: Failed to load command "start"
Error: EACCES: permission denied, open '/home/node/.n8n/config'

Les logs de migration s'affichaient normalement, puis ça s'est bloqué d'un coup. Parce que le n8n dans l'image n'est pas root, c'est un utilisateur uid 1000 node（docker exec n8n id On peut voir uid=1000(node)), et votre mkdir répertoire créé appartient à root, 755, les autres ne peuvent pas y écrire.

Il suffit de changer le propriétaire :

chown -R 1000:1000 /data/n8n

Après modification, on relance, même répertoire, même commande, 200, ça démarre normalement, et les fichiers sont réellement écrits dans le répertoire de l'hôte. Peu importe qui est uid 1000 sur l'hôte, dans le container c'est 1000 qui est reconnu.

3. Port déjà occupé

docker: Error response from daemon: failed to set up container networking:
driver failed programming external connectivity on endpoint n8n
(...): failed to bind host port 0.0.0.0:5678/tcp: address already in use

Cela signifie que le port 5678 de l'hôte est déjà utilisé par quelqu'un, cela n'a rien à voir avec l'intérieur du container. Regardons d'abord qui c'est :

ss -ltnp 'sport = :5678'

Le cas courant est que votre ancien container n8n tourne encore,docker ps On peut voir. Ou l'ancien container a été supprimé mais pas complètement, le plus simple est de changer de port pour démarrer d'abord.

4. Accès via IP + http, retour à la page de login après connexion

La page s'ouvre, le compte et le mot de passe sont corrects, on clique sur login sans erreur, puis la page revient au formulaire de login. On dirait un mot de passe erroné, mais c'est en fait un problème de cookie.

Le cookie de login de n8n porte Secure le marqueur (N8N_SECURE_COOKIE Par défaut, c'est true), le navigateur n'autorise son enregistrement qu'en HTTPS. Si vous y accédez en http, le serveur renvoie quand même 200, le navigateur jette directement ce cookie, et la requête suivante n'a donc plus d'état de connexion.

Deux approches : la méthode propre consiste à placer devant une couche Nginx avec certificat ; pour un débogage temporaire en réseau interne, ajoutez -e N8N_SECURE_COOKIE=false, et pensez à supprimer cette ligne après le débogage. Ne la considérez pas comme une configuration à long terme — cela équivaut à faire circuler votre identifiant et mot de passe sur un canal en clair.

5. Fermer le terminal arrête n8n

Si vous l'avez lancé selon la commande docker run -it --rm du document, Ctrl+C suffit à l'arrêter. Ce n'est pas un service en arrière-plan, c'est un processus au premier plan dans votre terminal.

补 -d Relancez ; s'il tourne déjà,docker start n8n peut aussi le récupérer, mais si ce container a été supprimé avec --rm , il ne reste qu'à refaire docker run— les données sont dans le volume, elles sont toujours là.

6. Utiliser latest, et un jour le comportement change

Aucune erreur, aucune alerte, simplement après un redémarrage un jour, les valeurs par défaut des nœuds, l'interface, voire le nom d'un paramètre ont changé. La raison : vous avez récupéré une nouvelle version.

Fixez le numéro de version, et traitez la mise à jour comme une vraie tâche : sauvegardez d'abord le volume, changez ensuite le tag, puis après le démarrage exécutez deux workflows critiques pour vérifier les résultats. La mise à jour elle-même n'a rien de technique, toute la difficulté est dans « ne pas savoir ce qui a changé ».

Quelques points de sécurité liés à n8n

Ne mettez pas 5678 directement sur l'Internet public.n8n a une page de connexion, mais c'est une application auto-hébergée, sans protection supplémentaire au-delà de la connexion, et les scanners cherchent ce genre de port tous les jours. Le mettre sur 0.0.0.0 sans reverse proxy ni HTTPS, c'est comme suspendre la clé de la maison à la porte. La configuration que j'ai utilisée lors de mes tests -p 127.0.0.1:5678:5678 a déjà bloqué l'extérieur.

docker Le groupe équivaut à root.Celui qui peut / monter dans le container peut modifier n'importe quel fichier sur l'hôte. Réfléchissez-y avant de donner des permissions à un collègue.

Traitez les volumes comme des clés secrètes.Celui à l'intérieur database.sqlite contient le chiffrement de tous les identifiants, et le même répertoire contient la clé de déchiffrement. Quiconque copie les deux ensemble verra tous les tokens de vos comptes tiers en clair. Où placer la sauvegarde est plus important que la sauvegarde elle-même.

N'écrivez pas de mot de passe en ligne de commande.docker run -e DB_PASSWORD=xxx Cela restera dans docker inspect la sortie, et quiconque l'exécute peut le voir. Pour transmettre des valeurs sensibles, utilisez un fichier env, ou _FILE la série de variables avec suffixe.

Résumé

Quatre mots suffisent pour démarrer : l'image est le paquet, le container est le paquet en cours d'exécution, le volume est le terrain hors du paquet, le port est le numéro de rue.

Le seul vrai point où l'installation de n8n peut mal tourner : le volume n'est pas monté. Aucune erreur n'apparaît, et vous ne le remarquez pas tout de suite ; le temps de vous en rendre compte, le workflow a déjà disparu. Donc la première chose à faire après l'installation est docker restart une fois, pour vérifier que les données sont toujours là.

Le reste n'est qu'une question de maîtrise. À l'usage, vous découvrirez que le plus grand avantage de Docker n'est pas la « portabilité », mais la possibilité de « tout supprimer et recommencer en cas de problème » — les données sont dans le volume, le container peut de toute façon être jeté à tout moment.

L'article précédent estComment diagnostiquer les erreurs de démarrage de n8n et l'occupation des ports, qui traite des cas où le service ne démarre pas. Le sommaire de toute la série se trouveici, et j'ai regroupé les cas de panne à part sur la pageDépannage.

Références

• Install with Docker: les docker run commandes officielles,docker volume create、/home/node/.n8n les explications sur les volumes, ainsi que les étapes de mise à jour de l'image
• Installer avec Docker Compose: la configuration de la version compose,5678:5678 ce commentaire indique « le seul port qui doit être exposé à l'extérieur »
• Variables d'environnement Deployment：N8N_PORT par défaut 5678,N8N_LISTEN_ADDRESS par défaut ::、N8N_USER_FOLDER 与 N8N_ENCRYPTION_KEY
• Variables d'environnement Security：N8N_SECURE_COOKIE par défaut true、N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS par défaut false
• Volumes Docker: le volume réside sur l'hôte /var/lib/docker/volumes/<名字>/_data, ainsi que sa différence avec le mount de type bind
• la liste des tags de n8nio/n8n: un tag par version, permettant de consulter le digest de l'image et la taille compressée
• Installer Docker Engine sur Ubuntu: les étapes complètes avec le dépôt officiel apt, à suivre si vous ne voulez pas utiliser de script tout-en-un

Dernière mise à jour : 2 novembre 2026, avec n8n 2.43.7.