n8n-Backup: Workflows, Credentials und der Encryption Key

Ein n8n-Backup ist erst dann vollständig, wenn es Workflows, Credentials und den Encryption Key gemeinsam sichert. Fehlt der Schlüssel, bleiben alle gespeicherten Zugangsdaten dauerhaft unlesbar.

Dieser Artikel zeigt, wo n8n den Schlüssel ablegt, wie Sie ihn fest vorgeben und wie Sie Workflows und Credentials über die Kommandozeile sichern und zurückspielen.

Was macht der Encryption Key in n8n?

Der Encryption Key verschlüsselt alle Credentials, bevor n8n sie in der Datenbank ablegt. Ohne den passenden Schlüssel sind diese Daten nicht mehr lesbar.

n8n erzeugt beim ersten Start automatisch einen zufälligen Schlüssel und speichert ihn im Ordner ~/.n8n. Steht dort noch kein Schlüssel, können Sie einen eigenen Wert über die Umgebungsvariable N8N_ENCRYPTION_KEY vorgeben.

Im Queue-Modus müssen Sie diese Variable laut Dokumentation auf allen Workern setzen (Set a custom encryption key).

Setzen Sie den Schlüssel deshalb schon beim Aufsetzen der Instanz, nicht erst beim ersten Backup. Ein Docker-Compose-Ausschnitt sieht so aus:

1services:
2  n8n:
3    image: docker.n8n.io/n8nio/n8n:2.36.9
4    restart: unless-stopped
5    ports:
6      - "127.0.0.1:5678:5678"
7    environment:
8      - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}
9      - N8N_HOST=n8n.beispiel.de
10      - WEBHOOK_URL=https://n8n.beispiel.de/
11      - GENERIC_TIMEZONE=Europe/Berlin
12    volumes:
13      - n8n_data:/home/node/.n8n
14
15volumes:
16  n8n_data:
Copy

Den Wert selbst legen Sie in einer .env-Datei neben der Compose-Datei ab. Einen geeigneten Zufallswert erzeugen Sie mit openssl rand -base64 32. Diese Datei gehört nicht in die Versionsverwaltung.

Was passiert, wenn der Encryption Key verloren geht?

Geht der Encryption Key verloren, meldet n8n beim Öffnen der Credentials, dass diese nicht entschlüsselt werden konnten. Die Workflow-Logik bleibt erhalten, jede hinterlegte Verbindung müssen Sie neu authentifizieren.

Die folgende Übersicht zeigt, was ein Datenbank-Backup ohne den Schlüssel noch hergibt.

Bestandteil | Ohne passenden Encryption Key

Bestandteil: Workflow-Struktur mit Nodes und Verbindungen · Ohne passenden Encryption Key: bleibt vollständig lesbar

Bestandteil: Node-Parameter ohne Zugangsdaten · Ohne passenden Encryption Key: bleiben vollständig lesbar

Bestandteil: Credential-Namen und Credential-IDs · Ohne passenden Encryption Key: bleiben erhalten

Bestandteil: Credential-Inhalte wie API-Keys, OAuth-Token, SMTP-Passwörter · Ohne passenden Encryption Key: dauerhaft unlesbar

Bei drei Automatisierungen ist das ärgerlich. Bei vierzig gewachsenen Workflows bedeutet es, jede Verbindung zu CRM, Postfach, Buchhaltung und Warenwirtschaft von Hand neu zu verbinden.

Der Encryption Key gehört deshalb in jede Backup-Routine. Sichern Sie ihn getrennt von der Datenbank, aber genauso zuverlässig.

Wie sichern Sie Workflows und Credentials per CLI?

Die Kommandozeile sichert und importiert mit vier Befehlen: export:workflow, export:credentials, import:workflow und import:credentials. Für regelmäßige Backups ist sie zuverlässiger als der Download über die Oberfläche.

Das Flag --backup setzt laut Dokumentation intern --all, --pretty und --separate. Sie erhalten also eine lesbar formatierte Datei je Workflow, was sich gut versionieren lässt.

1# 1. Workflows und Credentials als je eine Datei sichern
2n8n export:workflow --backup --output=backups/latest/
3n8n export:credentials --backup --output=backups/latest/
4
5# 2. Einstellungsordner sichern, dort liegt der Encryption Key
6tar czf backups/latest/n8n-settings.tar.gz -C "$HOME" .n8n
7
8# 3. Auf einer Instanz mit demselben Encryption Key zurückspielen
9n8n import:workflow --separate --input=backups/latest/
10n8n import:credentials --separate --input=backups/latest/
Copy

Läuft n8n im Container, stellen Sie den Befehlen docker exec -u node <containername> voran. Die Zielpfade müssen dann im gemounteten Volume liegen.

Zwei Punkte aus der Dokumentation sind wichtig. Der Export enthält die IDs, gleiche IDs im Ziel werden beim Import überschrieben. Und import:workflow deaktiviert importierte Workflows standardmäßig (n8n-CLI-Befehle).

In der Oberfläche stehen zusätzlich „Download", „Import from File" und „Import from URL" bereit (Export und Import).

Verschlüsselt oder entschlüsselt exportieren: Was passt wann?

Der verschlüsselte Export eignet sich für das tägliche Backup, der entschlüsselte Export nur für den einmaligen Umzug auf eine Instanz mit anderem Schlüssel. Die Dokumentation weist ausdrücklich darauf hin, dass im entschlüsselten Export alle sensiblen Daten sichtbar sind.

Kriterium | `export:credentials --backup` | `export:credentials --all --decrypted`

Kriterium: Inhalt der Datei · export:credentials --backup: verschlüsselte Werte · export:credentials --all --decrypted: Zugangsdaten im Klartext

Kriterium: Import bei gleichem Encryption Key · export:credentials --backup: funktioniert · export:credentials --all --decrypted: funktioniert

Kriterium: Import bei abweichendem Encryption Key · export:credentials --backup: schlägt fehl · export:credentials --all --decrypted: funktioniert

Kriterium: Geeignet für regelmäßige Backups · export:credentials --backup: ja · export:credentials --all --decrypted: nein

Kriterium: Umgang mit der Datei · export:credentials --backup: wie das Datenbank-Backup behandeln · export:credentials --all --decrypted: direkt nach dem Import sicher löschen

Für den Umzug gilt daher: entschlüsselt exportieren, importieren, Datei löschen. Die Zielinstanz verschlüsselt die Daten beim Import mit ihrem eigenen Schlüssel.

Beim Weitergeben von Workflow-JSON ist zusätzlich Vorsicht geboten. Die Dateien enthalten Credential-Namen und IDs, und aus cURL importierte HTTP-Request-Nodes können Authentifizierungs-Header enthalten.

Wie rotieren Sie den Data Encryption Key?

n8n trennt zwei Schlüssel: Der Instance Encryption Key aus N8N_ENCRYPTION_KEY bleibt unverändert, der darunterliegende Data Encryption Key lässt sich rotieren. Die Rotation aktivieren Sie über ein Feature-Flag.

Merkmal | Instance Encryption Key | Data Encryption Key

Merkmal: Gesetzt über · Instance Encryption Key: N8N_ENCRYPTION_KEY · Data Encryption Key: von n8n erzeugt, verschlüsselt in der Datenbank

Merkmal: Aufgabe · Instance Encryption Key: schützt die Data Encryption Keys · Data Encryption Key: verschlüsselt die Credential-Daten

Merkmal: Wechselbar · Instance Encryption Key: nein, bleibt dauerhaft gleich · Data Encryption Key: ja, über die Rotationsfunktion

Merkmal: Verfügbarkeit · Instance Encryption Key: jede Installation · Data Encryption Key: Self-hosted, alle Editionen, nicht in n8n Cloud

Zum Aktivieren setzen Sie N8N_ENV_FEAT_ENCRYPTION_KEY_ROTATION=true auf allen Instanzen, also auf Main und allen Workern, und starten neu. Danach rotieren Sie unter Settings > Data Encryption Keys oder per POST auf /encryption/keys.

1# Feature-Flag auf Main und allen Workern setzen
2N8N_ENV_FEAT_ENCRYPTION_KEY_ROTATION=true
Copy

Das Aktivieren ist laut Dokumentation eine Einbahnstraße ohne Rückweg. Wird das Flag später entfernt oder n8n herabgestuft, sind alle seither geschriebenen Daten dauerhaft unzugänglich.

Nehmen Sie deshalb vorher ein vollständiges Datenbank-Backup und testen Sie zuerst auf einer Nicht-Produktivumgebung (Rotate encryption keys).

Wer eine eigene n8n-Instanz betreibt und beim Aufsetzen von Backup-Routinen oder beim Umzug zwischen Servern Unterstützung sucht, findet Begleitung im n8n-Angebot von NordFlux.

Typische Fehler und Ursachen

Fünf Fehlerbilder treten rund um Encryption Key, Export und Import besonders häufig auf.

Nach dem Umzug meldet n8n, dass Credentials nicht entschlüsselt werden konnten.

Ursache: Die Zielinstanz nutzt einen anderen Encryption Key als die Quelle. Lösung: Denselben Wert über N8N_ENCRYPTION_KEY setzen oder die Credentials mit --decrypted exportieren. Quelle: Set a custom encryption key.

Nach dem nachträglichen Setzen von `N8N_ENCRYPTION_KEY` sind alle Credentials unlesbar.

Ursache: n8n hatte beim ersten Start bereits einen eigenen Schlüssel erzeugt und die Daten damit verschlüsselt. Lösung: Den ursprünglichen Schlüssel aus dem gesicherten Ordner ~/.n8n wieder verwenden. Quelle: Set a custom encryption key.

Nur die Worker scheitern an Credentials, die Hauptinstanz läuft.

Ursache: Der Encryption Key ist im Queue-Modus nicht auf allen Workern gesetzt. Lösung: Denselben Wert auf Main und jedem Worker hinterlegen und alle Prozesse neu starten. Quelle: Set a custom encryption key.

Nach dem Import fehlen Workflows oder tragen fremde Inhalte.

Ursache: Der Export enthält die IDs, und gleiche IDs im Ziel werden überschrieben. Lösung: In eine leere Instanz importieren oder die IDs vorher in den JSON-Dateien ändern. Quelle: n8n-CLI-Befehle.

Die importierten Workflows laufen nach dem Restore nicht wieder an.

Ursache: import:workflow deaktiviert importierte Workflows standardmäßig. Lösung: Nach dem Import aktivieren oder im Multi-Main- und Queue-Modus --activeState=fromJson setzen. Quelle: n8n-CLI-Befehle.

Häufige Fragen zu n8n-Backup und Encryption Key

Reicht ein Datenbank-Backup allein aus, um n8n vollständig zu sichern?

Nein. Ein Datenbank-Backup sichert Workflows und verschlüsselte Credentials, aber ohne den zugehörigen Encryption Key bleiben die Credentials unlesbar. Der Schlüssel liegt im Ordner ~/.n8n und muss bewusst mitgesichert werden, idealerweise an einem getrennten, zugriffsgeschützten Ort.

Kann ich Workflows ohne die zugehörigen Credentials exportieren?

Ja. Der Export über die Oberfläche oder per n8n export:workflow enthält nur die Workflow-Struktur mit Verweisen auf Credential-Namen und IDs. Für die Zugangsdaten selbst brauchen Sie einen zweiten Export mit n8n export:credentials.

Wie migriere ich Credentials auf eine Instanz mit einem anderen Encryption Key?

Exportieren Sie auf der Quellinstanz mit n8n export:credentials --all --decrypted --output=backups/decrypted.json und importieren Sie regulär auf dem Ziel. Die Zielinstanz verschlüsselt die Daten mit ihrem eigenen Schlüssel. Löschen Sie die Klartextdatei direkt nach dem Import.

Was mache ich, wenn der Encryption Key tatsächlich verloren gegangen ist?

Ohne den ursprünglichen Schlüssel lassen sich verschlüsselte Credentials nicht wiederherstellen. Jede betroffene Verbindung müssen Sie in den Workflows neu authentifizieren. Die Workflow-Logik bleibt dabei erhalten, der Aufwand beschränkt sich auf das erneute Hinterlegen der Zugangsdaten.