Kann Home Assistant hinter einem Reverse-Proxy in einem Unterpfad betrieben werden?

Eva Wong

IceWhale author

Eva Wong ist die Technische Redakteurin und und leidenschaftliche Tüftlerin bei ZimaSpace. Eine lebenslange Geek mit einer Leidenschaft für Homelabs und Open-Source-Software, sie spezialisiert sich darauf, komplexe technische Konzepte in zugängliche, praktische Anleitungenzu übersetzen. Eva ist der Meinung, dass Self-Hosting Spaß machen und nicht einschüchternd sein sollte. Durch ihre Tutorials befähigt sie die Community, Hardware-Setups zu entmystifizieren, vom Bau ihres ersten NAS bis hin zur Beherrschung von Docker-Containern.

Can Home Assistant Work Behind a Reverse Proxy on a Subpath? - Zima Store Online

Home Assistant kann hinter einem Reverse-Proxy betrieben werden, aber eine zuverlässige Bereitstellung über einen umgeschriebenen Unterpfad stellt im Allgemeinen keine unterstützte Bereitstellungsgrenze dar.

Eine Seite unter example.com/homeassistant kann HTML zurückgeben, während spätere Anfragen weiterhin auf root-relative Assets, Authentifizierungsrouten, WebSockets oder Integrations-Callbacks abzielen. Testen Sie mehr als nur den ersten Bildschirm: Verwenden Sie einen frischen Browser, melden Sie sich an, öffnen Sie ein Live-Dashboard, laden Sie eine verschachtelte Route neu und führen Sie einen Callback vollständig aus. Wenn irgendeine Ebene das Präfix verliert, verschieben Sie Home Assistant auf einen eigenen Hostnamen, statt weitere Umschreibungen hinzuzufügen.

Unterstützung für Reverse-Proxys von Unterstützung für Unterpfade trennen

Ein Reverse-Proxy kann TLS beenden und eine Anfrage an der Hostname-Wurzel an Home Assistant weiterleiten. Ein Unterpfad stellt eine andere Anforderung: Jede generierte URL, jedes Asset, jeder API-Aufruf, jeder WebSocket, jede Weiterleitung und jeder Callback muss ein Präfix konsistent beibehalten, das die Anwendung versteht. Der Erfolg auf Proxy-Ebene stellt diesen Anwendungsvertrag nicht her.

Tests der Home-Assistant-Community kommen zu einem eindeutigen Ergebnis: Die Anwendung unterstützt keine Bereitstellung unter einem URL-Präfix. Die geklärte Antwort auf Home Assistant in einem Unterpfad einzurichten empfiehlt unabhängig von der Proxy-Wahl eine Subdomain.

PASS bei der Reverse-Proxy-Unterstützung bedeutet, dass Home Assistant am Stammverzeichnis eines eigenen Hostnamens mit korrekter Weiterleitung funktioniert. FAIL beim vorgeschlagenen Unterpfad bedeutet, dass eine oder mehrere Anwendungsrouten das Präfix verlieren. Vermischen Sie diese Ergebnisse nicht zu der Aussage, Reverse-Proxys selbst seien inkompatibel.

Frontend-Assets als ersten risikoarmen Test verwenden

Öffnen Sie den vorgeschlagenen Unterpfad in einem privaten Browserprofil und überprüfen Sie die Netzwerkanfragen, bevor Sie Home Assistant ändern. Wenn das Basisdokument geladen wird, JavaScript, Symbole, Manifeste oder Übersetzungen jedoch Pfade von der Hostname-Wurzel anfordern, ist die Topologie bereits an ihrem ersten reversiblen Prüfkriterium gescheitert.

Ein dokumentierter Versuch mit einer Pfadumschreibung gab die Hauptseite zurück, während Frontend-Ressourcen URLs mit führendem Schrägstrich ohne das Home-Assistant-Präfix anforderten. Dieser Fehler bei root-relativen Assets ist eine Diskrepanz zwischen Anwendungspfad und Proxy, keine fehlende Datei auf dem Proxy.

PASS bedeutet, dass jede Frontend-Ressource unter der vorgesehenen Route erfolgreich zurückgegeben wird. FAIL bedeutet, dass 404-Antworten oder Anfragen an den Root-Pfad auftreten. Halten Sie dort an und testen Sie einen eigenen Hostnamen. Das Ersetzen von Inhalten im Antworttext ist fragil, da künftige Frontend-Builds neue Pfade einführen können, die von der Umschreibung nicht abgedeckt werden.

WebSockets, Authentifizierung und verschachtelte Routen testen

Eine statische Dashboard-Hülle stellt keine vollständige Sitzung dar. Melden Sie sich in einem sauberen Profil an, beobachten Sie die Entitätsaktualisierungen mehrere Minuten lang, aktualisieren Sie eine verschachtelte Dashboard-URL, melden Sie sich ab und anschließend wieder an. Prüfen Sie dann, ob HTTP-Upgrades, Token, Weiterleitungen und das Neuladen von Routen denselben öffentlichen Ursprung und Pfad beibehalten.

Home Assistant verwendet WebSockets intensiv für die Live-Kommunikation des Frontends, daher muss ein Proxy den Upgrade-Pfad und die Header beibehalten. Der Bericht eines Betreibers über die WebSocket-Verarbeitung eines Reverse-Proxys zeigt, warum das Laden von HTML allein kein ausreichender Kompatibilitätstest ist.

PASS bedeutet, dass Authentifizierung, Live-Aktualisierungen, Navigation und direktes Neuladen ohne Fehler bei der Pfadübersetzung funktionieren. Ein FAIL, das auf Sockets oder Weiterleitungen beschränkt ist, verwirft das Unterpfad-Design weiterhin. Die Behebung einer einzelnen Proxy-Direktive beweist nicht, dass Callbacks und künftige Routen präfixfähig werden.

Featured

ZimaCube 2 Persönliche Cloud Home NAS

ZimaCube2

Einen eigenen Hostnamen als stabile Grenze wählen

Veröffentlichen Sie Home Assistant am Stammverzeichnis eines eigenen Hostnamens wie ha.example.com und leiten Sie diesen Hostnamen anschließend über den Reverse-Proxy an den internen Dienst weiter. Dadurch bleibt ein einziger öffentlicher Ursprung erhalten, ohne dass die Anwendung ein Pfadpräfix verstehen muss. Ein privates VPN oder ein Tunnel kann dieselbe saubere Stammgrenze bereitstellen, ohne den Dienst öffentlich zugänglich zu machen.

Wenn ein bestehender Fernzugriffspfad nach Netzwerkänderungen ausfällt, überprüfen Sie DNS, öffentliche Adresse, NAT, Tunnel und Proxy-Routing unabhängig voneinander. Die ZimaSpace-Diagnose für Fernzugriff nach einer Routeränderung bietet diese angrenzende Pfadprüfung.

Die Alternative ist erfolgreich, wenn ein sauberer Browser Assets laden, einen WebSocket aufbauen, sich authentifizieren, verschachtelte Routen aktualisieren und Home Assistant nach einem Proxy-Neustart erreichen kann. Halten Sie die alte Route nur so lange verfügbar, wie für das Zurücksetzen von DNS- oder Proxy-Änderungen nötig ist. Betreiben Sie nicht auf unbestimmte Zeit zwei mehrdeutige öffentliche URLs.

Beenden, wenn die vollständige Sitzung einen Neustart übersteht

Starten Sie den Proxy und Home Assistant jeweils einmal neu und wiederholen Sie anschließend den vollständigen Test aus dem LAN und dem vorgesehenen entfernten Netzwerk. Bestätigen Sie den Zertifikatsnamen, die weitergeleitete Client-Adresse, die Vertrauensgrenze des Proxys, die Anmeldung, den Live-Status, die Abmeldung und einen Integrations-Callback. Dies ist der ursprüngliche Arbeitsablauf und keine verkürzte Prüfung einer statischen Seite.

Erklären Sie den Erfolg nur für das Root-Hostname-Design, das jeden Schritt besteht. Ein Unterpfad, der nur nach einer benutzerdefinierten Umschreibung von Antwortinhalten funktioniert, bleibt nicht unterstützte Betriebsschuld, da ein Update das Verhalten von Assets oder Callbacks ändern kann. Dokumentieren Sie den bewährten Hostnamen, die Upstream-Adresse und die Rollback-Konfiguration.

Leiten Sie den Fall weiter, wenn das Root-Hostname-Design weiterhin fehlschlägt, denn die verbleibende Ursache liegt wahrscheinlich bei Proxy-Vertrauen, WebSocket-Weiterleitung, DNS, Zertifikat oder Routing und nicht bei der Unterstützung von Basispfaden. Setzen Sie Home Assistant nicht direkt einem ungeschützten Port aus, nur um die gewünschte URL-Struktur beizubehalten.