So aktualisierst du Homebridge Core, Homebridge UI, Node.js LTS und Plugins sicher: Schritt-für-Schritt-Anleitung für Homemanager, Webinterface und Terminal.

System und Software sicher aktualisieren

Eine Homebridge-Installation setzt sich aus mehreren eigenständigen Software-Komponenten zusammen:

Homebridge (Core): Der Kernprozess, der die HomeKit-Kommunikation (HAP) abwickelt und deine Plugins ausführt.
Homebridge UI (inklusive API): Die Weboberfläche und Schnittstelle (homebridge-config-ui-x), über die Webbrowser und Apps wie Homemanager mit dem Server kommunizieren.
Node.js: Die JavaScript-Laufzeitumgebung, auf der Homebridge und alle Erweiterungen laufen.
Plugins: Die individuellen Erweiterungen für deine Geräte und Dienste.
Host-Betriebssystem: Das zugrundeliegende Betriebssystem (etwa Raspberry Pi OS, Debian oder macOS).

Regelmäßige Updates schließen Sicherheitslücken, beheben Fehler und erhalten die Kompatibilität mit aktuellen iOS-Versionen.

Hinweis für HOOBS: Bei HOOBS ist kein manueller Eingriff in Node.js oder das Betriebssystem möglich oder erforderlich. HOOBS bündelt alle Systemkomponenten in einem geschlossenen System und verteilt Aktualisierungen gesammelt über zentrale HOOBS Core Updates.

Vorab: Backup anlegen

Vor größeren Versionssprüngen empfiehlt sich eine Sicherungskopie der Konfiguration:

In Homemanager (Bald verfügbar): Öffne den Reiter Backup und sichere deinen Serverstand direkt in iCloud Drive oder lokal auf dem iPhone oder iPad.
In der Weboberfläche: Klicke oben rechts auf das Drei-Punkte-Menü, wähle Backup / Wiederherstellen und lade das Archiv auf deinen Computer herunter.

Tritt nach einer Aktualisierung ein Problem auf, lässt sich der funktionierende Stand so jederzeit wieder einspielen.

1. Updates verwalten und einspielen

In Homebridge werden der Core-Server, die Weboberfläche, Node.js und deine Plugins unabhängig voneinander gepflegt.

Aktualisierung in Homemanager

In Homemanager verwaltest du Systemkomponenten und Plugins direkt auf dem iPhone oder iPad. Vor jeder Aktualisierung prüft die App automatisch die Kompatibilität mit deinen installierten Erweiterungen:

Software-Übersicht in Homemanager mit getrenntem Homebridge Core, UI und Node.js — Software-Übersicht mit Update- und Versionsoptionen

Automatische Kompatibilitätsprüfung vor Updates in Homemanager — Automatische Prüfung der Abhängigkeiten vor jedem Update

Systemkomponenten: Öffne den Reiter System und wähle Software. Hier listet Homemanager Homebridge (Core), Homebridge UI und Node.js getrennt mit den aktuellen Versionsnummern auf.
Direkt aktualisieren: Steht für eine Komponente ein Update bereit, tippst du auf Update to v.... Das gilt für Homebridge und die Weboberfläche genauso wie für Node.js.
Automatische Kompatibilitätsprüfung: Vor jedem Update gleicht Homemanager die Zielversion mit den installierten Plugins und Abhängigkeiten ab. Du siehst sofort, ob alle Erweiterungen mit der neuen Version getestet sind.
Versionswechsel & Changelogs: Über Changelogs prüfst du vorab die Änderungen der Entwickler. Mit Change version kannst du gezielt auf eine frühere oder spätere Version wechseln.
Plugins verwalten: Deine Erweiterungen und Plugins verwaltest du im Reiter Integrations (oder Updates). Dort siehst du alle anstehenden Plugin-Aktualisierungen und startest die Installation direkt dort.

Aktualisierung über die Weboberfläche

Öffne die Homebridge-Weboberfläche im Browser (Standardport 8581).
Verfügbare Updates für Core, UI oder Plugins erkennst du an gelben Hinweisen in der oberen Statusleiste und im Reiter Plugins.
Klicke auf Aktualisieren und prüfe die Versionshinweise.
Bestätige die Installation. Nach dem Download startet Homebridge den Dienst neu. (Hinweis: Für Node.js-Updates kannst du das integrierte Terminal in der Weboberfläche nutzen.)

Aktualisierung per Terminal

Verbinde dich per SSH oder über das Terminal der Weboberfläche mit deinem Server und aktualisiere die Pakete bei Bedarf manuell:

Homebridge Core aktualisieren

sudo npm install -g --unsafe-perm homebridge

Homebridge Weboberfläche & API aktualisieren

sudo npm install -g --unsafe-perm homebridge-config-ui-x

Starte den Dienst anschließend neu:

sudo hb-service restart

2. Node.js sicher aktualisieren (LTS)

Homebridge basiert auf der JavaScript-Laufzeitumgebung Node.js. Für einen stabilen Betrieb sollten ausschließlich offizielle LTS (Long Term Support)-Versionen wie Node.js 20 oder 22 genutzt werden. Ungerade Versionsnummern (wie 21 oder 23) sind kurzlebige Testversionen und werden von vielen Plugins nicht unterstützt.

Node.js in Homemanager aktualisieren

In Homemanager kannst du Node.js direkt auf dem iPhone oder iPad aktualisieren:

Öffne im Reiter System den Bereich Software.
Neben der installierten Version siehst du bei Bedarf den Button Update to v....
Nach der automatischen Kompatibilitätsprüfung führt Homemanager den Installationsbefehl im Hintergrund auf dem Server aus. Falls deine Serverumgebung manuelle Zwischenschritte verlangt, zeigt die App die nötigen Befehle an.

Manueller Weg über das Terminal (ohne App)

Für Linux-Installationen und den Raspberry Pi empfiehlt sich das offizielle Werkzeug sudo hb-service update-node. Die Standard-Paketverwaltung (apt) liefert auf Debian oft veraltete Node.js-Stände aus oder überschreibt von Homebridge genutzte Pfade:

# Automatisch auf die neueste empfohlene LTS-Version aktualisieren
sudo hb-service update-node

# Oder gezielt eine bestimmte LTS-Hauptversion vorgeben
sudo hb-service update-node 22

Dieser Befehl ermittelt die empfohlene LTS-Version, richtet die Dateien ein und baut benötigte native Module automatisch neu. Du kannst den Befehl per SSH oder direkt im integrierten Terminal der Homebridge-Weboberfläche ausführen.

Docker-Installationen: In Docker-Umgebungen (wie auf Synology NAS oder Unraid) wird Node.js nicht separat im Container aktualisiert. Ziehe stattdessen das aktuelle Container-Image:

docker compose pull && docker compose up -d

3. Host-System aktuell halten

Auch das zugrundeliegende Betriebssystem benötigt regelmäßige Sicherheitsupdates und Treiberaktualisierungen.

Auf einem Raspberry Pi führst du die Aktualisierung im Terminal per SSH aus:

sudo apt update && sudo apt upgrade -y

Wurde bei diesem Vorgang ein neuer Linux-Kernel installiert, empfiehlt sich ein anschließender Neustart (sudo reboot).

Detaillierte Anleitungen und systembezogene Besonderheiten für andere Umgebungen findest du in den Installationsleitfäden:

Fehlerbehebung nach Updates

Bleibt Homebridge nach einer Aktualisierung in einer Fehlerschleife hängen, wirf einen Blick in die Server-Logs zur Fehlersuche:

Modulkonflikte reparieren (`NODE_MODULE_VERSION`)

Erscheint im Protokoll der Fehler NODE_MODULE_VERSION mismatch, greift ein Plugin auf ein hardwarenahes C++-Modul zu, das noch für eine frühere Node.js-Version kompiliert ist. Der Rebuild-Befehl kompiliert diese Bibliotheken neu:

sudo hb-service rebuild

Version zurücksetzen (Rollback)

Wenn eine neue Plugin-, UI- oder Homebridge-Version Fehler verursacht:

In Homemanager: Öffne System > Software und tippe bei der betroffenen Komponente (Homebridge oder Homebridge UI) auf Change version, um auf die vorherige Versionsnummer zurückzukehren.
Per Terminal: Installiere eine bestimmte Version gezielt über die Versionsangabe:
```
sudo npm install -g --unsafe-perm homebridge@2.1.0
```
Alternativ stellst du das zuvor erstellte Backup wieder her.

Child Bridges nutzen

Isoliere Plugins in eigene Prozesse, damit Updates einzelner Erweiterungen nie den gesamten Server stoppen.

Server startet nicht?

Schritt-für-Schritt-Hilfe bei Boot-Loops, Portkonflikten und wie du Fehler im Log schnell findest.

System & Software aktualisieren