n8n 3.0 mit Docker Compose: neu installieren und von 2.x umsteigen

n8n 3.0.0 ist am 27. Oktober 2026 erschienen und räumt gründlich auf: Selbst gehostete Instanzen laufen nur noch mit Docker, zahlreiche Legacy-Nodes wie Function, Cron und Item Lists sind entfernt, mehrere Sicherheitsvorgaben werden strenger. Mit 208.808 GitHub-Sternen (Abruf 28.10.2026) gehört n8n zu den meistgenutzten Automatisierungswerkzeugen im Selfhosting. Diese Anleitung zeigt beide Wege: eine frische Installation mit Docker Compose und PostgreSQL sowie den Umstieg einer bestehenden 2.x-Instanz, inklusive Migration Report, Backup, Update und vollständigem Restore. Alle Ausgaben stammen aus einem Testlauf mit 2.46.0 und 3.0.0.

Voraussetzungen

Für eine kleine bis mittlere Instanz mit PostgreSQL und externem Task Runner reichen folgende Ressourcen:

• Linux-Server oder VM mit x86_64 oder ARM64, zum Beispiel Debian 12 oder Ubuntu 24.04
• 2 CPU-Kerne und 4 GB RAM
• 20 GB freier Speicher für Images, Datenbank, Binärdaten und Backups
• Docker Engine mit Docker Compose Plugin (Version 2), eingerichtet wie in der Grundlagen-Anleitung Docker Compose unter Linux
• Für den Zugriff von außen eine Domain und ein Reverse Proxy mit HTTPS
• Bei einem Umstieg: Shell-Zugriff auf die bestehende 2.x-Instanz und ein Wartungsfenster von etwa 30 Minuten

Schritt 1: Was sich mit n8n 3.0 ändert

Für Administratoren zählen vor allem diese Breaking Changes:

• Nur noch Docker: n8n 3.0 veröffentlicht kein lauffähiges npm-Paket mehr. Wer n8n mit npm oder npx n8n betreibt, muss vor dem Update auf Container umziehen.
• Entfernte Nodes: unter anderem Function, Function Item, Item Lists, Cron, Interval, HTML Extract, Read Binary File, Read PDF, Workflow Trigger sowie ältere OpenAI- und LangChain-Nodes. Workflows mit diesen Nodes schlagen fehl.
• Speicherordner umbenannt: Beim ersten Start benennt n8n ~/.n8n/binaryData in ~/.n8n/storage um. Existieren beide Ordner, startet n8n nicht.
• Neue Standardwerte: N8N_RUNNERS_TASK_TIMEOUT sinkt von 300 auf 60 Sekunden, N8N_UNVERIFIED_PACKAGES_ENABLED steht auf false, der Modus N8N_DEFAULT_BINARY_DATA_MODE=default entfällt, die Grenzen der Compression-Node sinken auf 256 MiB und 1.000 Einträge.
• Sicherheit: Die Schlüsselrotation ist standardmäßig aktiv, die SSRF-Sperrliste wächst unter anderem um 100.64.0.0/10, und Slack-API-Zugangsdaten brauchen ein Signing Secret.
• Abgeschaltet: Chat Hub ist standardmäßig aus (zurück per N8N_ENABLED_MODULES=chat-hub), der Workflow-Import per URL entfällt.

Wichtig für die Planung: Am 28. Oktober 2026 um 01:30 Uhr UTC zeigten die Docker-Hub-Tags latest und stable noch auf denselben Digest wie 2.45.4, während beta und next auf 2.46.0 standen. Auf GitHub sind 3.0.0 und 2.46.0 als Pre-release markiert. Tragen Sie die Version deshalb fest in die .env ein.

Verifizieren: docker compose exec n8n n8n --version zeigt die laufende Version. Läuft n8n noch per npm, beginnt Ihr Umstieg mit einer Neuinstallation nach Schritt 2.

Schritt 2: Neuinstallation mit Docker Compose und PostgreSQL

Grundlage ist das Beispiel withPostgres aus dem offiziellen Repository n8n-hosting. Es nutzt einen eingeschränkten Datenbanknutzer für n8n und einen eigenen Container für den Task Runner der Code-Nodes. Angepasst sind Zeitzone, Port nur auf 127.0.0.1 und der Wegfall von links.

mkdir -p /opt/n8n && cd /opt/n8n
curl -fsSLO https://raw.githubusercontent.com/n8n-io/n8n-hosting/main/docker-compose/withPostgres/init-data.sh

Eckdaten	Wert
Images	docker.n8n.io/n8nio/n8n:3.0.0, n8nio/runners:3.0.0, postgres:18
Port	5678 (Weboberfläche und Webhooks), intern 5679 für den Runner
Volumes	n8n_storage auf /home/node/.n8n, db_storage auf /var/lib/postgresql/data
Wichtige Env	N8N_VERSION, DB_POSTGRESDB_*, N8N_RUNNERS_AUTH_TOKEN, GENERIC_TIMEZONE

Legen Sie die compose.yaml an:

volumes:
  db_storage:
  n8n_storage:

services:
  postgres:
    image: postgres:18
    restart: always
    environment:
      - POSTGRES_USER
      - POSTGRES_PASSWORD
      - POSTGRES_DB
      - POSTGRES_NON_ROOT_USER
      - POSTGRES_NON_ROOT_PASSWORD
      - PGDATA=/var/lib/postgresql/data
    volumes:
      - db_storage:/var/lib/postgresql/data
      - ./init-data.sh:/docker-entrypoint-initdb.d/init-data.sh
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -h localhost -U ${POSTGRES_USER} -d ${POSTGRES_DB}']
      interval: 5s
      timeout: 5s
      retries: 10

  n8n:
    image: docker.n8n.io/n8nio/n8n:${N8N_VERSION}
    restart: always
    environment:
      - N8N_DEPLOYMENT_ARTIFACT=docker-compose
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_PORT=5432
      - DB_POSTGRESDB_DATABASE=${POSTGRES_DB}
      - DB_POSTGRESDB_USER=${POSTGRES_NON_ROOT_USER}
      - DB_POSTGRESDB_PASSWORD=${POSTGRES_NON_ROOT_PASSWORD}
      - N8N_RUNNERS_MODE=external
      - N8N_RUNNERS_AUTH_TOKEN=${RUNNERS_AUTH_TOKEN}
      - N8N_RUNNERS_BROKER_LISTEN_ADDRESS=0.0.0.0
      - GENERIC_TIMEZONE=Europe/Berlin
      - TZ=Europe/Berlin
    ports:
      - 127.0.0.1:5678:5678
    volumes:
      - n8n_storage:/home/node/.n8n
    depends_on:
      postgres:
        condition: service_healthy

  n8n-runner:
    image: n8nio/runners:${N8N_VERSION}
    restart: always
    environment:
      - N8N_RUNNERS_AUTH_TOKEN=${RUNNERS_AUTH_TOKEN}
      - N8N_RUNNERS_TASK_BROKER_URI=http://n8n:5679
    depends_on:
      - n8n

Die .env enthält Version und Geheimnisse. Erzeugen Sie die Passwörter zufällig, zum Beispiel mit openssl rand -hex 16, und setzen Sie die Datei auf chmod 600:

N8N_VERSION=3.0.0

POSTGRES_USER=n8nadmin
POSTGRES_PASSWORD=zufaelliges-passwort-1
POSTGRES_DB=n8n

POSTGRES_NON_ROOT_USER=n8n
POSTGRES_NON_ROOT_PASSWORD=zufaelliges-passwort-2

RUNNERS_AUTH_TOKEN=zufaelliges-token-48-zeichen

PGDATA=/var/lib/postgresql/data ist bei postgres:18 Pflicht, sonst startet die Datenbank auf einem bestehenden Volume leer. Mehr zu Healthchecks und Secrets in Compose finden Sie in der Anleitung Docker Compose absichern.

docker compose up -d --pull always
docker compose ps
curl -s http://127.0.0.1:5678/healthz

Verifizieren: Nach etwa 20 Sekunden sollten alle drei Dienste laufen und der Health-Endpunkt antworten:

SERVICE      IMAGE                           STATUS
n8n          docker.n8n.io/n8nio/n8n:3.0.0   Up 10 seconds
n8n-runner   n8nio/runners:3.0.0             Up 10 seconds
postgres     postgres:18                     Up 41 seconds (healthy)

{"status":"ok"}

Schritt 3: Owner-Konto anlegen und ersten Workflow prüfen

Öffnen Sie die Oberfläche über Ihren Reverse Proxy oder per SSH-Tunnel (ssh -L 5678:127.0.0.1:5678 server) und legen Sie das Owner-Konto mit starkem Passwort an. Für den Funktionstest genügt ein Workflow aus Webhook und Code-Node: Der Code-Node läuft im Runner-Container, ein erfolgreicher Aufruf belegt also auch dessen Anbindung.

Verifizieren: Ein veröffentlichter Workflow mit Webhook-Pfad sedv-test und einem Code-Node, der 21 * 2 zurückgibt, antwortete im Test so:

$ curl -s http://127.0.0.1:5678/webhook/sedv-test
{"ok":true,"version":"runner","summe":42}

Schritt 4: Bestehende 2.x-Instanz mit dem Migration Report prüfen

In n8n 2.46.0 finden Sie unter Settings den Punkt Migration Report. Er listet betroffene Workflows und Instanz-Einstellungen, sortiert nach Auswirkung von „Upgrade blocked“ bis „Capability removed“. Im Test mit 2.46.0 und drei Workflows meldete der Bericht „2 of 3 compatible“: Der Workflow mit Cron-Node wird unter 3.0 fehlschlagen. Im Reiter Instance issues erschienen vier Hinweise zur Konfiguration.

So arbeiten Sie die Punkte ab:

1. Workflows mit „Executions will fail“ öffnen und Legacy-Nodes ersetzen: Cron und Interval durch Schedule Trigger, Function durch den Code-Node, Item Lists durch Split Out, Aggregate, Sort, Limit, Remove Duplicates oder Summarize.
2. Für Code-Nodes, die länger als eine Minute rechnen, N8N_RUNNERS_TASK_TIMEOUT=300 setzen.
3. Nicht verifizierte Community-Nodes entweder durch verifizierte ersetzen oder N8N_UNVERIFIED_PACKAGES_ENABLED=true setzen.
4. Wer ein Volume direkt auf /home/node/.n8n/binaryData mountet, ändert das Ziel auf /home/node/.n8n/storage.

Verifizieren: Klicken Sie im Bericht auf Refresh. Ziel ist, dass die Zahl kompatibler Workflows der Gesamtzahl entspricht. Workflows, die Sie nicht mehr brauchen, markieren Sie als „Won't fix“.

Schritt 5: Backup vor dem Update

Ein Backup besteht bei n8n immer aus zwei Teilen: dem PostgreSQL-Dump mit Workflows, Zugangsdaten und Ausführungen sowie dem Volume /home/node/.n8n. In dessen Datei config steht der encryptionKey, mit dem n8n die Zugangsdaten verschlüsselt. Ein Dump ohne diesen Schlüssel ist für Zugangsdaten wertlos.

cd /opt/n8n && mkdir -p backup
docker compose exec -T postgres sh -c 'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Fc' \
  > backup/n8n-db-$(date +%F).dump
docker compose stop n8n n8n-runner
docker compose run --rm --no-deps -T --entrypoint sh n8n \
  -c 'tar czf - -C /home/node/.n8n .' > backup/n8n-data-$(date +%F).tgz
docker compose up -d
cp .env compose.yaml backup/

Kopieren Sie den Ordner backup verschlüsselt auf ein anderes System, er enthält Geheimnisse.

Verifizieren: tar tzf backup/n8n-data-*.tgz muss ./config enthalten, der Dump sollte nicht leer sein. Im Test war der Dump rund 650 KB groß:

./
./config
./nodes/
./nodes/package.json
./storage/
./n8nEventLog.log

Schritt 6: Update von 2.x auf 3.0.0

Das eigentliche Update ist ein Tag-Wechsel. Prüfen Sie den Migration Report vorher auf der aktuellen 2.x-Version, im Test war das 2.46.0.

sed -i 's/^N8N_VERSION=.*/N8N_VERSION=3.0.0/' .env
docker compose up -d --pull always
docker compose exec n8n n8n --version
docker compose logs n8n | grep -E 'version change|Version:'

Verifizieren: Im Test war die Instanz nach 15 Sekunden bereit. Das Log hält den Versionswechsel ausdrücklich fest, alle drei Workflows, der Webhook und die gespeicherten Zugangsdaten funktionierten unverändert:

3.0.0
Recorded version change: 2.46.0 -> 3.0.0
Version: 3.0.0

Der Migration Report bleibt auch unter 3.0 erreichbar. Für den Cron-Workflow bietet er die Schaltfläche Migrate: n8n ersetzt den Node durch einen Schedule Trigger mit gleicher Regel und speichert das Ergebnis als neue Version. Veröffentlichen müssen Sie diese Version anschließend selbst.

Neu in den Einstellungen ist der Punkt Data encryption keys. Weil die Schlüsselrotation jetzt standardmäßig aktiv ist, legt n8n beim ersten Start von 3.0 einen Datenschlüssel an. Ältere Daten bleiben lesbar und werden beim nächsten Speichern neu verschlüsselt. Der Menüpunkt Chat fehlt nach dem Update, weil Chat Hub abgeschaltet ist.

Schritt 7: Restore nach Totalverlust

Ein Backup ist erst etwas wert, wenn der Restore klappt. Der Test simulierte einen Totalverlust mit docker compose down -v; danach existierte kein Volume mehr. Die Wiederherstellung folgt dieser Reihenfolge:

docker compose up -d postgres
docker compose exec -T postgres sh -c 'pg_restore -U "$POSTGRES_USER" -d "$POSTGRES_DB" --exit-on-error' \
  < backup/n8n-db-2026-10-28.dump
docker compose run --rm --no-deps -T --entrypoint sh n8n \
  -c 'rm -rf /home/node/.n8n/* && tar xzf - -C /home/node/.n8n' < backup/n8n-data-2026-10-28.tgz
docker compose up -d

Das Init-Skript legt den Datenbanknutzer n8n neu an, pg_restore läuft daher fehlerfrei. Starten Sie n8n erst nach dem Volume-Restore, sonst erzeugt n8n einen neuen Schlüssel und verweigert den Start.

Verifizieren: Nach dem Restore war die Anmeldung wieder möglich, sogar eine vor dem Totalverlust gespeicherte Sitzung blieb gültig. Alle Workflows waren zurück, der Webhook lieferte erneut {"ok":true,...,"summe":42}, und der Export der Zugangsdaten mit n8n export:credentials --all --decrypted zeigte den Klartext der Test-Zugangsdaten.

Troubleshooting

Meldung	Ursache	Lösung
Both /home/node/.n8n/binaryData and /home/node/.n8n/storage exist, so n8n cannot tell which one holds your data.	Altes und neues Verzeichnis für Binärdaten existieren gleichzeitig; der Container startet in einer Schleife neu.	Inhalt von binaryData nach storage verschieben, binaryData löschen, n8n neu starten.
Deployment key 'signing.hmac' cannot be read with this instance encryption key	Datenbank wiederhergestellt, aber n8n-Volume mit der Datei config fehlt oder stammt von einer anderen Instanz.	Volume aus dem Backup zurückspielen. Die CLI meldet im gleichen Fall Credentials could not be decrypted.
Cannot use a "n8n-nodes-base.function" node ("Function"): this node type is deprecated.	Import oder Anlage eines Workflows mit Function-Node; schon 2.46.0 lehnt das per API und CLI ab.	Workflow-JSON vor dem Import auf den Code-Node umstellen.
Code-Node bricht nach 60 Sekunden ab	Neuer Standard für N8N_RUNNERS_TASK_TIMEOUT.	Variable beim Dienst n8n auf den benötigten Wert setzen.
HTTP-Request auf eine CGNAT-Adresse scheitert	Erweiterte SSRF-Sperrliste, etwa für 100.64.0.0/10.	Ziel per N8N_SSRF_ALLOWED_IP_RANGES oder N8N_SSRF_ALLOWED_HOSTNAMES freigeben, default in der Sperrliste lassen.

Kommt die Instanz nach dem Update gar nicht hoch, setzen Sie N8N_VERSION zurück, spielen das Backup aus Schritt 5 ein und starten neu. Ein bloßer Tag-Rückschritt reicht nicht, weil 3.0 die Datenbank beim Start migriert.

Häufige Fragen

Kann ich n8n 3.0 weiter mit npm betreiben?

Nein. n8n 3.0 veröffentlicht kein lauffähiges npm-Paket mehr, selbst gehostete Instanzen brauchen Docker.

Sollte ich jetzt schon auf 3.0 aktualisieren?

Für neue Instanzen spricht wenig dagegen, wenn Sie die Version pinnen. Bestehende Produktivinstanzen aktualisieren Sie besser in einem Wartungsfenster nach einem Probelauf mit Kopie, denn 3.0.0 ist auf GitHub zum Zeitpunkt dieser Anleitung als Pre-release markiert und die Tags latest und stable zeigen noch auf 2.45.4.

Wo liegt der Verschlüsselungsschlüssel?

In der Datei /home/node/.n8n/config im Volume n8n_storage, sofern Sie N8N_ENCRYPTION_KEY nicht selbst setzen. Deshalb gehört das Volume in jedes Backup, und docker compose down -v ist auf einem Produktivsystem tabu.

Wie halte ich n8n künftig aktuell?

Verfolgen Sie die Release-Notes und lassen Sie sich über neue Image-Versionen benachrichtigen, etwa mit Diun. Automatische Container-Updates sind bei n8n wegen der Datenbankmigrationen riskant; Hintergründe stehen in der Anleitung Container-Updates mit Diun und WUD.

Fazit

Der Sprung auf n8n 3.0 ist für Compose-Installationen technisch ein Tag-Wechsel; die eigentliche Arbeit steckt in alten Workflows. Der Migration Report nimmt Ihnen die Suche ab, und für einige Fälle wie den Cron-Node migriert n8n sogar selbst. Entscheidend ist ein vollständiges Backup aus Datenbank und Volume. Fehlt der Schlüssel, startet die Instanz nicht; mit beiden Teilen war die Wiederherstellung nach Totalverlust im Test in wenigen Minuten erledigt. Den Server selbst sichern Sie zusätzlich mit einer Firewall wie ufw ab, wie in Linux-Server absichern beschrieben.

Weiterführende Anleitungen und Quellen

• n8n mit Docker: KI-Automatisierung und Workflows (Hintergrund zu n8n 2.x)
• n8n CVE-2026-33696: Prototype-Pollution-Lücke führt zu Remote Code Execution
• Caddy als Reverse Proxy mit automatischem HTTPS
• n8n-Doku: v3.0 breaking changes
• n8n-Doku: n8n 3.0 migration tool
• GitHub: Release n8n@3.0.0
• n8n-hosting: Beispiel withPostgres
• Docker Hub: Tags von n8nio/n8n