Wichtige Änderungen in n8n v2.0

Die Veröffentlichung von n8n v2.0 steht bevor. Dieses Dokument hebt die wichtigsten Breaking Changes hervor und beschreibt, wie du dich auf den Übergang vorbereiten kannst. Diese Aktualisierungen verbessern die Sicherheit, vereinfachen die Konfiguration und entfernen veraltete Funktionen.

Die Veröffentlichung von n8n 2.0 setzt das Engagement von n8n fort, eine sichere, zuverlässige und produktionsreife Automatisierungsplattform bereitzustellen. Diese Hauptversion enthält wichtige Sicherheitsverbesserungen sowie die Bereinigung veralteter Funktionen.

Verhaltensänderungen

Rückgabe erwarteter Daten beim Fortsetzen von Sub-Workflows aus dem Wartezustand

Bisher erhielt die übergeordnete Ausführung (Parent) ein falsches Ergebnis, wenn sie einen Sub-Workflow (Child) aufrief, der einen Knoten enthielt, der den Sub-Workflow in einen Wartezustand versetzte – und die übergeordnete Ausführung darauf wartete, dass der Sub-Workflow abgeschlossen wird.

Beispiele für solche Wartezustände sind: Wait-Knoten mit einer Wartezeit über 65 Sekunden, Webhook-Aufrufe, Formularübermittlungen oder Knoten für manuelle Genehmigungen (z. B. ein Slack-Knoten zur Bestätigung).

Übergeordneter Workflow:

Sub-Workflow:

v1: Die übergeordnete Ausführung gab die Eingabe des Sub-Workflows als Ausgabe wieder:

v2: Die übergeordnete Ausführung erhält das Ergebnis des Sub-Workflows:

Dies ermöglicht es, Knoten für manuelle Genehmigungen im Sub-Workflow zu verwenden und deren Ergebnisse (z. B. Genehmigung oder Ablehnung einer Aktion) im übergeordneten Workflow weiterzuverarbeiten.

Migrationspfad: Überprüfe alle Workflows, die Sub-Workflows aufrufen und bisher die Eingabedaten des Sub-Workflows erwarteten. Passe diese Workflows an das neue Verhalten an: Der übergeordnete Workflow erhält nun die Ausgabedaten am Ende des Sub-Workflows, nicht dessen Eingabedaten.

Entfernung des Start-Knotens

Der Start-Knoten wird nicht mehr unterstützt. Er war die ursprüngliche Methode zum Starten eines Workflows und wurde durch spezifischere Trigger-Knoten ersetzt.

Migrationspfad: Ersetze den Start-Knoten je nach Verwendungszweck deines Workflows:

• Manuelle Ausführung: Ersetze den Start-Knoten durch einen Manual Trigger-Knoten.
• Sub-Workflow: Wenn ein anderer Workflow diesen Workflow als Sub-Workflow aufruft, ersetze den Start-Knoten durch einen Execute Workflow Trigger-Knoten und veröffentliche den Workflow.
• Deaktivierter Start-Knoten: Wenn der Start-Knoten bereits deaktiviert war, entferne ihn vollständig aus dem Workflow.

Speichern und Veröffentlichen von Workflows

Das neue Workflow-Veröffentlichungssystem ersetzt den alten „Aktivieren/Deaktivieren“-Schalter. Der frühere Umschalter wird nun zu einer „Veröffentlichen/Veröffentlichung aufheben“-Schaltfläche. Diese Änderung ermöglicht eine bessere Kontrolle darüber, wann Änderungen live gehen, und reduziert das Risiko, unbeabsichtigt unfertige Änderungen in die Produktion zu bringen. Weitere Informationen findest du in der [Dokumentation zum Speichern und Veröffentlichen von Workflows].

Entfernung von Knoten für eingestellte Dienste

Folgende Knoten wurden entfernt, da die externen Dienste, mit denen sie verbunden waren, nicht mehr verfügbar sind:

• Spontit-Knoten
• crowd.dev-Knoten
• Kitemaker-Knoten
• Automizy-Knoten

Migrationspfad: Falls deine Workflows einen dieser Knoten verwenden, aktualisiere oder lösche diese Workflows, um Fehler zu vermeiden.

Sicherheit

Standardmäßige Blockierung des Zugriffs auf Umgebungsvariablen im Code-Knoten

Zur Verbesserung der Sicherheit blockiert n8n standardmäßig den Zugriff auf Umgebungsvariablen im Code-Knoten. Der Standardwert von N8N_BLOCK_ENV_ACCESS_IN_NODE wird nun auf true gesetzt.

Migrationspfad: Falls deine Workflows im Code-Knoten auf Umgebungsvariablen zugreifen müssen, setze in deiner Umgebungskonfiguration N8N_BLOCK_ENV_ACCESS_IN_NODE=false. Für sensible Daten empfehlen wir stattdessen die Verwendung von Anmeldedaten oder anderen sicheren Methoden statt Umgebungsvariablen.

Erzwingung strenger Dateiberechtigungen

n8n erfordert nun strikte Dateiberechtigungen für Konfigurationsdateien, um die Sicherheit zu erhöhen. Standardmäßig müssen Konfigurationsdateien die Berechtigung 0600 haben – d. h., nur der Dateieigentümer darf lesen und schreiben. Dies entspricht dem Ansatz, den SSH zur Sicherung privater Schlüssel verwendet.

Migrationspfad: Um dieses Verhalten bereits vor v2.0 zu testen, setze N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true. Falls dein System keine Dateiberechtigungen unterstützt (z. B. Windows), deaktiviere diese Anforderung mit N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=false.

Task Runner standardmäßig aktiviert

n8n aktiviert standardmäßig den Task Runner, um Sicherheit und Isolation zu verbessern. Alle Ausführungen von Code-Knoten laufen nun über den Task Runner.

Migrationspfad: Setze vor dem Upgrade auf v2.0 N8N_RUNNERS_ENABLED=true, um dieses Verhalten zu testen. Stelle sicher, dass deine Infrastruktur die Anforderungen für den Betrieb des Task Runners erfüllt. Für zusätzliche Sicherheit solltest du den externen Modus in Betracht ziehen.

Entfernung des Task Runners aus dem n8nio/n8n Docker-Image

Ab v2.0 enthält das primäre Docker-Image n8nio/n8n nicht mehr den Task Runner für den externen Modus. Du musst stattdessen das separate Docker-Image n8nio/runners verwenden, um den Task Runner im externen Modus zu betreiben.

Migrationspfad: Falls du den Task Runner im externen Modus mit Docker verwendest, aktualisiere deine Konfiguration, sodass du das Image n8nio/runners statt n8nio/n8n verwendest.

Entfernung des Pyodide-basierten Python Code-Knotens und zugehöriger Tools

n8n entfernt den auf Pyodide basierenden Python Code-Knoten und die zugehörigen Tools und ersetzt sie durch eine Implementierung auf Basis des Task Runners mit nativem Python, die bessere Sicherheit und Leistung bietet. Ab v2.0 kannst du den Python Code-Knoten nur noch im externen Modus mit dem Task Runner und nativem Python verwenden.

Der native Python Code-Knoten unterstützt nicht die in der Pyodide-Version verfügbaren integrierten Variablen (wie _input) oder die Punktnotation. Weitere Details findest du in der [Code-Knoten-Dokumentation].

Native Python-Tools unterstützen _query, also die Eingabezeichenfolge, die beim Aufruf durch einen AI-Agent übergeben wird.

Migrationspfad: Um Python weiterhin im Code-Knoten zu verwenden, richte den Task Runner im externen Modus ein und prüfe, ob deine bestehenden Python Code-Knoten und -Tools kompatibel sind.

Standardmäßige Deaktivierung der Knoten ExecuteCommand und LocalFileTrigger

Aus Sicherheitsgründen deaktiviert n8n standardmäßig die Knoten ExecuteCommand und LocalFileTrigger, da sie beliebige Befehle ausführen und auf das Dateisystem zugreifen können.

Migrationspfad: Falls du diese Knoten benötigst, entferne sie aus der Liste der deaktivierten Knoten in deiner n8n-Konfiguration, indem du die Umgebungsvariable NODES_EXCLUDE anpasst. Beispiel: Setze NODES_EXCLUDE="[]", um alle Knoten zu aktivieren, oder entferne nur die spezifischen Knoten, die du benötigst.

Standardmäßige Authentifizierung für OAuth-Callback-URLs

n8n erfordert standardmäßig eine Authentifizierung am OAuth-Callback-Endpunkt. Der Standardwert von N8N_SKIP_AUTH_ON_OAUTH_CALLBACK ändert sich von true (keine Authentifizierung) auf false (Authentifizierung erforderlich).

Migrationspfad: Setze vor dem Upgrade auf v2.0 N8N_SKIP_AUTH_ON_OAUTH_CALLBACK=false und teste deine OAuth-Integrationen, um sicherzustellen, dass sie mit aktivierter Authentifizierung korrekt funktionieren.

Standardwert für N8N_RESTRICT_FILE_ACCESS_TO festgelegt

n8n legt einen Standardwert für N8N_RESTRICT_FILE_ACCESS_TO fest, um zu steuern, wo Dateioperationen durchgeführt werden dürfen. Dies betrifft die Knoten ReadWriteFile und ReadBinaryFiles. Standardmäßig können diese Knoten nur auf Dateien im Verzeichnis ~/.n8n-files zugreifen.

Migrationspfad: Überprüfe Workflows, die Dateiknoten verwenden, und stelle sicher, dass sie nur auf Dateien in zulässigen Verzeichnissen zugreifen. Falls du Zugriff auf andere Verzeichnisse benötigst, setze die Umgebungsvariable N8N_RESTRICT_FILE_ACCESS_TO auf den gewünschten Pfad.

Standardwert von N8N_GIT_NODE_DISABLE_BARE_REPOS auf true geändert

Aus Sicherheitsgründen blockiert der Git-Knoten ab sofort standardmäßig Bare Repositories. Der Standardwert von N8N_GIT_NODE_DISABLE_BARE_REPOS ist nun true, d. h., Bare Repositories sind standardmäßig deaktiviert.

Migrationspfad: Falls deine Workflows Bare Repositories benötigen, aktiviere sie in deiner Umgebungskonfiguration mit N8N_GIT_NODE_DISABLE_BARE_REPOS=false.

Daten

Einstellung der Unterstützung für MySQL/MariaDB

n8n unterstützt MySQL und MariaDB als Speicher-Backends nicht mehr; diese Unterstützung wurde bereits in v1.0 als veraltet markiert. Für beste Kompatibilität und langfristige Unterstützung verwende PostgreSQL. Der MySQL-Knoten bleibt weiterhin wie bisher unterstützt.

Migrationspfad: Migriere deine Daten vor dem Upgrade auf v2.0 mithilfe von Datenbank-Migrationstools von MySQL oder MariaDB zu PostgreSQL oder SQLite.

Entfernung des Legacy SQLite-Treibers

Aufgrund von Zuverlässigkeitsproblemen entfernt n8n den Legacy SQLite-Treiber. Der Connection-Pool-Treiber wird der einzige verfügbare SQLite-Treiber sein. Dieser verwendet den WAL-Modus, eine einzelne Schreibverbindung und einen Pool für Leseverbindungen. Unsere Benchmarks zeigen, dass er bis zu 10-mal schneller sein kann.

Migrationspfad: Der sqlite-pooled-Treiber wird automatisch zum Standardtreiber. Du kannst den Connection Pool sofort aktivieren, indem du DB_SQLITE_POOL_SIZE auf einen Wert größer 0 setzt. Die Standard-Poolgröße wird auf 2 gesetzt.

Entfernung des In-Memory-Binärdatenmodus

n8n entfernt den Modus default für N8N_DEFAULT_BINARY_DATA_MODE, bei dem Binärdaten während der Ausführung im Arbeitsspeicher (RAM) gehalten wurden. Ab v2 stehen folgende Optionen für bessere Leistung und Stabilität zur Verfügung:

• filesystem: Binärdaten werden im Dateisystem gespeichert (Standard im regulären Modus).
• database: Binärdaten werden in der Datenbank gespeichert (Standard im Queue-Modus).
• s3: Binärdaten werden in S3-kompatiblem Speicher abgelegt.

Die Einstellung N8N_AVAILABLE_BINARY_DATA_MODES wird ebenfalls entfernt, sodass der Modus nun ausschließlich über N8N_DEFAULT_BINARY_DATA_MODE bestimmt wird.

Migrationspfad: Je nach Konfiguration wird automatisch der Dateisystem- oder Datenbankmodus verwendet. Stelle sicher, dass deine n8n-Instanz über ausreichend Speicherplatz verfügt, um Binärdaten zu speichern. Weitere Details findest du in der [Dokumentation zur Binärdaten-Konfiguration].

Konfiguration und Umgebung

Aktualisierung von dotenv

n8n verwendet die dotenv-Bibliothek, um Umgebungskonfigurationen aus .env-Dateien zu laden. Diese Bibliothek wird von Version 8.6.0 auf die neueste Version aktualisiert, was die Art der .env-Dateiverarbeitung beeinflussen kann. Wichtige Breaking Changes umfassen:

• Unterstützung für Backticks (#615): Werte mit Backticks müssen nun in einfache oder doppelte Anführungszeichen eingeschlossen werden.
• Mehrzeilige Werte: Mehrzeilige Werte werden nun unterstützt.
• Kommentare mit #: Zeilen, die mit # beginnen, werden als Kommentare behandelt.

Migrationspfad: Prüfe das dotenv-Changelog und passe deine .env-Dateien an, um Kompatibilität mit der neuen Version sicherzustellen.

Entfernung der CLI-Option n8n --tunnel

Die Kommandozeilenoption n8n --tunnel wird in v2.0 entfernt.

Migrationspfad: Falls du aktuell --tunnel für Entwicklung oder Tests verwendest, wechsle zu alternativen Tunnel-Lösungen wie ngrok, localtunnel oder Cloudflare Tunnel. Aktualisiere deine Workflows und Dokumentation entsprechend.

Entfernung von QUEUE_WORKER_MAX_STALLED_COUNT

Die Umgebungsvariable QUEUE_WORKER_MAX_STALLED_COUNT und der Bull-Mechanismus zum erneuten Versuch gestörter Aufgaben werden entfernt, da sie oft zu Verwirrung führten und unzuverlässig arbeiteten.

Migrationspfad: Entferne diese Umgebungsvariable aus deiner Konfiguration. Nach dem Upgrade wird n8n gestörte Aufgaben nicht mehr automatisch erneut versuchen. Falls du solche Fälle behandeln musst, implementiere eigene Retry-Logik oder Monitoring.

Entfernung von N8N_CONFIG_FILES

Die Umgebungsvariable N8N_CONFIG_FILES wurde entfernt.

Migrationspfad: Entferne diese Variable aus deiner Konfiguration. Migriere deine Konfiguration zu Umgebungsvariablen, .env-Dateien oder _FILE-basierten Konfigurationen.

CLI und Workflows

Ersetzung des CLI-Befehls update:workflow

Der CLI-Befehl update:workflow wird abgekündigt und durch zwei neue Befehle ersetzt, die ähnliche Funktionalität mit klarerer Semantik bieten:

• publish:workflow mit Parametern id und optional versionId
• Der Parameter --all wird entfernt, um versehentliche Veröffentlichungen in der Produktion zu verhindern
• unpublish:workflow mit Parametern id und all

Migrationspfad: Verwende den neuen Befehl publish:workflow, um Workflows einzeln nach ID (optional mit Versions-ID) zu veröffentlichen. Zum Aufheben der Veröffentlichung verwende unpublish:workflow. Dies bietet bessere Kontrolle und Transparenz über den Veröffentlichungsstatus von Workflows.

Externe Hooks (External Hooks)

Abkündigung von Frontend-Workflow-Hooks

Die Hook-Funktionen workflow.activeChange und workflow.activeChangeCurrent werden abgekündigt und durch den neuen Hook workflow.published ersetzt. Dieser wird ausgelöst, sobald eine beliebige Version eines Workflows veröffentlicht wird.

Migrationspfad: Aktualisiere deinen Code, um den neuen Hook workflow.published statt der alten Hooks zu verwenden. Dieser bietet ein konsistenteres Verhalten und wird beim Veröffentlichen einer Workflow-Version ausgelöst.

Veröffentlichungskanäle

n8n hat die Veröffentlichungskanäle von latest und next in stable und beta umbenannt.

Das stable-Tag bezeichnet die neueste stabile Version, das beta-Tag die neueste experimentelle Version. Diese Tags sind sowohl auf npm als auch auf Docker Hub verfügbar. Derzeit setzt n8n weiterhin die latest- und next-Tags für Veröffentlichungen. Diese werden in einer zukünftigen Hauptversion entfernt.

Empfehlung: Fixiere deine n8n-Version auf eine spezifische Versionsnummer, z. B. 2.0.0.

Feedback und Probleme

Falls du beim Update auf n8n 2.0 auf Probleme stößt, besuche unser Community-Forum, um Hilfe und Unterstützung zu erhalten.