# System und Software sicher aktualisieren (https://docs.homemanager-app.de/de/guide/updating-system-software)





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.

<Callout type="info">
  **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**.
</Callout>

***

## Vorab: Backup anlegen [#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 [#1-updates-verwalten-und-einspielen]

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

<Tabs items="[&#x22;Homemanager (iOS & iPadOS)&#x22;, &#x22;Homebridge Weboberfläche&#x22;, &#x22;Terminal (Kommandozeile)&#x22;]">
  <Tab>
    ### Aktualisierung in Homemanager [#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:

    <div className="grid grid-cols-1 sm:grid-cols-2 gap-4 my-6 items-start max-w-lg mx-auto">
      <div className="flex flex-col items-center">
        <ImageZoom src="/images/homebridge/updates/homemanager-system-software.png" alt="Software-Übersicht in Homemanager mit getrenntem Homebridge Core, UI und Node.js" className="max-w-[210px] rounded-2xl border border-fd-border shadow-md" figureClassName="flex flex-col items-center !my-0 max-w-[210px] w-full" caption="Software-Übersicht mit Update- und Versionsoptionen" />
      </div>

      <div className="flex flex-col items-center">
        <ImageZoom src="/images/homebridge/updates/homemanager-update-compatibility-check.png" alt="Automatische Kompatibilitätsprüfung vor Updates in Homemanager" className="max-w-[210px] rounded-2xl border border-fd-border shadow-md" figureClassName="flex flex-col items-center !my-0 max-w-[210px] w-full" caption="Automatische Prüfung der Abhängigkeiten vor jedem Update" />
      </div>
    </div>

    1. **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.
    2. **Direkt aktualisieren:** Steht für eine Komponente ein Update bereit, tippst du auf &#x2A;*Update to v...**. Das gilt für Homebridge und die Weboberfläche genauso wie für Node.js.
    3. **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.
    4. **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.
    5. **Plugins verwalten:** Deine [Erweiterungen und Plugins](/de/guide/finding-plugins) verwaltest du im Reiter **Integrations** (oder **Updates**). Dort siehst du alle anstehenden Plugin-Aktualisierungen und startest die Installation direkt dort.
  </Tab>

  <Tab>
    ### Aktualisierung über die Weboberfläche [#aktualisierung-über-die-weboberfläche]

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

  <Tab>
    ### Aktualisierung per Terminal [#aktualisierung-per-terminal]

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

    ```bash title="Homebridge Core aktualisieren"
    sudo npm install -g --unsafe-perm homebridge
    ```

    ```bash title="Homebridge Weboberfläche & API aktualisieren"
    sudo npm install -g --unsafe-perm homebridge-config-ui-x
    ```

    Starte den Dienst anschließend neu:

    ```bash
    sudo hb-service restart
    ```
  </Tab>
</Tabs>

***

## 2. Node.js sicher aktualisieren (LTS) [#2-nodejs-sicher-aktualisieren-lts]

Homebridge basiert auf der JavaScript-Laufzeitumgebung Node.js. Für einen stabilen Betrieb sollten ausschließlich offizielle &#x2A;*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 [#nodejs-in-homemanager-aktualisieren]

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

1. Öffne im Reiter **System** den Bereich **Software**.
2. Neben der installierten Version siehst du bei Bedarf den Button &#x2A;*Update to v...**.
3. 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) [#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:

```bash
# 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.

<Callout type="warn">
  **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:

  ```bash
  docker compose pull && docker compose up -d
  ```
</Callout>

***

## 3. Host-System aktuell halten [#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:

```bash
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:

* [Raspberry Pi einrichten & warten](/de/guide/install-raspberry-pi#nützliche-befehle-im-terminal)
* [Docker & Container-Images aktualisieren](/de/guide/install-docker)
* [Synology NAS einrichten](/de/guide/install-synology)
* [macOS Installation](/de/guide/install-macos)
* [Windows Installation](/de/guide/install-windows)

***

## Fehlerbehebung nach Updates [#fehlerbehebung-nach-updates]

Bleibt Homebridge nach einer Aktualisierung in einer Fehlerschleife hängen, wirf einen Blick in die [Server-Logs zur Fehlersuche](/de/guide/troubleshooting-startup-errors#log-meldungen-richtig-deuten):

### Modulkonflikte reparieren (`NODE_MODULE_VERSION`) [#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:

```bash
sudo hb-service rebuild
```

### Version zurücksetzen (Rollback) [#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:
  ```bash
  sudo npm install -g --unsafe-perm homebridge@2.1.0
  ```
* Alternativ stellst du das zuvor erstellte Backup wieder her.

<Cards>
  <Card icon="<ShieldCheck />" title="Child Bridges nutzen" description="Isoliere Plugins in eigene Prozesse, damit Updates einzelner Erweiterungen nie den gesamten Server stoppen." href="/de/guide/child-bridges" />

  <Card icon="<TriangleAlert />" title="Server startet nicht?" description="Schritt-für-Schritt-Hilfe bei Boot-Loops, Portkonflikten und wie du Fehler im Log schnell findest." href="/de/guide/troubleshooting-startup-errors" />
</Cards>