Node-RED-Projekte mit Git-Versionsverwaltung

Node-RED-Projekte machen Ihre Flows zu einem Git-Repository, sodass jede Änderung committet, überprüfbar und umkehrbar ist. In diesem Tutorial aktivieren Sie den Projektmodus, legen ein Projekt an, committen und pushen auf ein Remote, klonen es auf einen anderen Rechner und halten, ganz wichtig, Ihre MQTT-Broker-Zugangsdaten verschlüsselt und außerhalb des Repositorys.

Warum Sie Ihre Flows versionieren sollten

Ohne Projekte speichert Node-RED alles in einer einzigen Datei flows.json im Benutzerverzeichnis. Deployt jemand eine fehlerhafte Änderung, gibt es keine Historie zum Nachsehen und keinen einfachen Weg zurück. Kopien von Flows wandern als exportiertes JSON per E-Mail oder Chat, und niemand weiß sicher, welche Version in der Produktion läuft. Gerade auf Edge-Gateways in der Fertigung, die Maschinendaten liefern, ist das ein echtes Betriebsrisiko.

Projekte lösen das mit Werkzeugen, die Entwickler bereits kennen:

• Historie. Jeder Commit hält fest, wer was wann geändert hat.
• Diffs. Der Editor zeigt vor dem Commit die Unterschiede auf Node-Ebene.
• Branches. Probieren Sie eine riskante Änderung auf einem Branch aus und mergen Sie sie, wenn sie funktioniert.
• Remotes. Pushen Sie zu GitHub, GitLab, Gitea oder Azure DevOps für Backup und Zusammenarbeit.
• Abhängigkeiten. Jedes Projekt hat eine package.json mit den benötigten Nodes, sodass ein neuer Rechner weiß, was zu installieren ist.

Voraussetzungen

Projekte setzen die Git-Kommandozeile und für SSH-Remotes ssh-keygen voraus. Prüfen Sie, ob beides auf dem Rechner mit Node-RED installiert ist:

git --version
ssh-keygen -h 2>&1 | head -1

Unter Debian, Ubuntu oder Raspberry Pi OS installieren Sie Git mit sudo apt install git. Das offizielle Docker-Image enthält Git bereits.

Node-RED-Projekte aktivieren

Der Projektmodus ist standardmäßig ausgeschaltet. Öffnen Sie settings.js in Ihrem Benutzerverzeichnis (~/.node-red/settings.js bzw. /data/settings.js in Docker), suchen Sie den Abschnitt editorTheme und aktivieren Sie ihn:

editorTheme: {
    projects: {
        enabled: true,
        workflow: {
            // "manual": Sie committen explizit
            // "auto": Node-RED committet bei jedem Deployment
            mode: "manual"
        }
    }
},

Starten Sie Node-RED neu. Beim ersten Öffnen des Editors bietet ein Willkommensbildschirm an, ein Projekt anzulegen, ein Repository zu klonen oder den Schritt zu überspringen. Der manuelle Modus ist für Teams der bessere Standard: Sie deployen beim Testen so oft Sie möchten und committen erst, wenn eine Änderung fertig ist, mit einer aussagekräftigen Nachricht.

Ihr erstes Projekt anlegen

1. Wählen Sie im Willkommensbildschirm Create Project oder später im Hauptmenü Projects → New.
2. Geben Sie bei Nachfrage Ihren Git-Benutzernamen und Ihre E-Mail-Adresse ein; sie erscheinen in der Commit-Historie.
3. Benennen Sie das Projekt, zum Beispiel plant-telemetry.
4. Wählen Sie einen Namen für die Flow-Datei. Der Standard flow.json ist in Ordnung.
5. Verschlüsselung der Zugangsdaten einrichten. Wählen Sie "Enable encryption" und geben Sie einen starken Schlüssel ein. Speichern Sie ihn in Ihrem Passwort-Manager.
6. Klicken Sie auf Create Project.

Node-RED legt im Benutzerverzeichnis unter projects/ einen Ordner mit dieser Struktur an:

~/.node-red/projects/plant-telemetry/
  .git/
  .gitignore
  README.md
  package.json
  flow.json
  flow_cred.json

Die Zugangsdatendatei ist mit dem Schlüssel aus Schritt 5 verschlüsselt, und dieser Schlüssel liegt in Ihren lokalen Node-RED-Laufzeiteinstellungen, nicht im Repository. Genau dieses Design hält Broker-Passwörter aus Git heraus: Das Repository enthält nur Chiffretext, und nur Rechner, denen Sie den Schlüssel geben, können ihn entschlüsseln.

Einen Flow bauen und committen

Fügen Sie einen einfachen MQTT-Flow hinzu, damit es etwas zu versionieren gibt. Konfigurieren Sie einen Broker-Node für den kostenlosen öffentlichen MQTT-Broker mit Server broker.connectmq.com, Port 1883 und einer eindeutigen Client-ID wie nr-proj-a19e. Lassen Sie einen mqtt in-Node connectmq/demo/a19e/# abonnieren und verbinden Sie ihn mit einem Debug-Node. Deployen Sie.

Öffnen Sie in der Seitenleiste den Tab Project history (das Git-Symbol). Unter Local Changes sehen Sie die Flow-Datei als geändert aufgeführt. Klicken Sie darauf, um einen visuellen Diff der hinzugefügten Nodes zu sehen. Stagen Sie die Datei, schreiben Sie eine Commit-Nachricht wie "Add telemetry subscriber" und committen Sie.

Nehmen Sie nun eine Änderung vor, etwa die Umbenennung des Debug-Nodes, und deployen Sie erneut. Der History-Tab zeigt einen neuen Diff genau dieser Änderung. Hier zahlen sich Node-RED-Projekte aus: Im Review sehen Sie, dass sich eine Property geändert hat, statt eines unlesbaren JSON-Blocks.

Auf ein Remote-Repository pushen

Legen Sie bei Ihrem Git-Hoster ein leeres Repository an. Öffnen Sie in Node-RED Projects → Project Settings → Settings → Git remotes und fügen Sie die Remote-URL hinzu.

Für SSH-Remotes erzeugen Sie einen Schlüssel direkt in Node-RED über User Settings → Git config → SSH Keys → Add key. Node-RED zeigt den öffentlichen Schlüssel an; hinterlegen Sie ihn bei Ihrem Git-Hoster als Deploy Key mit Schreibrecht. HTTPS-Remotes mit einem Personal Access Token funktionieren ebenfalls, und Node-RED fragt beim ersten Push nach den Zugangsdaten.

Zurück im History-Tab zeigt der Abschnitt Commit History nun Pfeile für Push und Pull. Pushen Sie Ihre Commits. Im Terminal können Sie den Inhalt des Repositorys prüfen:

git clone git@github.com:your-org/plant-telemetry.git
cd plant-telemetry
cat flow_cred.json   # gibt Chiffretext aus, etwa {"$":"8f2c..."}

Broker-Zugangsdaten aus Git heraushalten

Zugangsdaten brauchen eine bewusste Strategie. Sie haben drei sinnvolle Optionen:

Für die zweite Option fügen Sie flow_cred.json zur .gitignore hinzu und geben MQTT-Benutzernamen und Passwort nach dem Klonen in jeder Instanz neu ein. Für die dritte definieren Sie Werte wie den Broker-Host oder das Präfix der Client-ID als Umgebungsvariablen und lesen sie in Node-Properties mit ${MQTT_HOST} oder in Function-Nodes mit env.get().

Was Sie auch wählen, befolgen Sie zwei Regeln. Fügen Sie niemals ein Passwort in einen Function- oder Inject-Node ein, denn diese werden im Klartext in der Flow-Datei gespeichert. Und verwenden Sie pro Umgebung eigene Broker-Zugangsdaten, damit eine Entwicklungsinstanz niemals in Produktions-Topics publizieren kann; mit ConnectMQ kann das so einfach sein wie ein eigener Broker pro Umgebung. Unsere Checkliste zum Absichern von Node-RED behandelt die übrigen Härtungsschritte.

Ein Projekt auf einem anderen Rechner klonen

Wählen Sie auf einer zweiten Node-RED-Instanz mit aktivierten Projekten Projects → New → Clone Repository, geben Sie die Remote-URL und, falls die Zugangsdatendatei verschlüsselt ist, den Schlüssel ein. Node-RED klont das Repository, liest die package.json und zeigt an, welche Nodes fehlen. Installieren Sie sie über die Abfrage oder mit npm im Projektordner und deployen Sie dann.

Klonen Sie bei Docker in den eingebundenen Ordner /data/projects, damit das Projekt eine Neuerstellung des Containers übersteht; die Volume-Einrichtung zeigt unser Leitfaden zu Node-RED mit Docker.

Checkliste für den Workflow mit Node-RED-Projekten

1. Projekte im manuellen Modus aktivieren und Node-RED neu starten.
2. Ein Projekt pro deploybarer Anwendung anlegen, nicht eines pro Tab.
3. Verschlüsselung der Zugangsdaten aktivieren und den Schlüssel im Passwort-Manager ablegen.
4. Jeden zusätzlichen Node mit Versionsbereich in der package.json aufführen.
5. Kleine, beschriebene Änderungen committen; Diffs vor dem Commit prüfen.
6. Branches für Experimente nutzen und nach dem Test mergen.
7. Nach jedem relevanten Commit auf ein Remote pushen.
8. Umgebungsspezifische Werte in Umgebungsvariablen halten, nicht im Flow.
9. Getrennte MQTT-Zugangsdaten für Entwicklungs- und Produktions-Broker verwenden.

Wiederverwendbare Logik lässt sich leichter versionieren, wenn sie in Node-RED-Subflows liegt, denn eine Änderung an einer Vorlage erscheint als ein klarer Diff. Die offizielle Dokumentation zu Projekten behandelt erweiterte Einstellungen und die vollständige Editor-Oberfläche. Wenn Sie gerade erst mit MQTT in Node-RED beginnen, starten Sie mit dem Node-RED-MQTT-Tutorial.

Flows versionieren, den Broker ConnectMQ überlassen

Projekte geben Ihren Flows eine Historie und reproduzierbare Deployments; der Broker, mit dem sie sich verbinden, sollte genauso verlässlich sein. ConnectMQ ist ein verwalteter MQTT-Broker mit MQTT 3.1.1 und 5.0, TLS auf 8883 und Zugangsdaten pro Broker; so ist es einfach, getrennte Broker für Entwicklung und Produktion anzulegen und die Zugangsdaten jeder Umgebung auseinanderzuhalten. Starten Sie mit dem kostenlosen Serverless-Plan unter app.connectmq.com, ohne Kreditkarte. Einen Vergleich der Hosting-Ansätze bietet unsere Übersicht zum Betrieb eines MQTT-Brokers in der Cloud.

Häufig gestellte Fragen

Wie aktiviere ich Projekte in Node-RED?

Setzen Sie editorTheme.projects.enabled in settings.js auf true, stellen Sie sicher, dass Git installiert ist, und starten Sie Node-RED neu. Der Editor bietet dann an, ein Projekt anzulegen oder zu klonen.

Werden MQTT-Passwörter bei Node-RED-Projekten in Git gespeichert?

Nur in verschlüsselter Form, wenn Sie die Verschlüsselung der Zugangsdaten aktivieren. Die Zugangsdatendatei enthält Chiffretext, und der Schlüssel bleibt auf dem jeweiligen Rechner. Sie können die Zugangsdatendatei auch zur .gitignore hinzufügen.

Kann ich GitHub mit Node-RED-Projekten verwenden?

Ja. Fügen Sie das Repository als Remote hinzu, per SSH mit einem in Node-RED erzeugten Schlüssel oder per HTTPS mit einem Token, und pushen und pullen Sie dann über die Seitenleiste Project history.

Was ist der Unterschied zwischen manuellem und automatischem Workflow-Modus?

Im manuellen Modus committen Sie explizit, wenn eine Änderung fertig ist. Im automatischen Modus erstellt Node-RED bei jedem Deployment einen Commit, was einfacher ist, aber eine unübersichtlichere Historie erzeugt.