Home Assistant Nginx Reverse Proxy - So klappt das Setup!

Ein sauberer Reverse Proxy macht Home Assistant im Alltag deutlich angenehmer: nur ein externer Einstiegspunkt, saubere HTTPS-Terminierung und weniger direkte Angriffsfläche auf Port 8123. Mit Nginx lässt sich das zuverlässig umsetzen, wenn Weiterleitung, WebSockets und die Home-Assistant-Konfiguration zusammenpassen. Ich zeige hier die Architektur, eine praxistaugliche Nginx-Konfiguration, die nötigen Einträge in der Konfiguration und die Fehler, die in solchen Setups am häufigsten auftauchen.

Warum ein Reverse Proxy für Home Assistant sinnvoll ist

Ich setze Nginx vor Home Assistant vor allem dann ein, wenn der Dienst nicht mehr als einzelnes Bastelprojekt läuft, sondern Teil einer kleinen internen Plattform ist. Der Vorteil liegt nicht nur bei HTTPS. Ein Reverse Proxy bündelt Zugriffe, trennt die Außenwelt vom internen Port 8123 und gibt dir eine klare Stelle für Zertifikate, Weiterleitungen und spätere Zusatzdienste.

Praktisch heißt das: Du erreichst Home Assistant über eine saubere Domain auf Port 443, während die Anwendung selbst intern bleiben kann. Das ist besonders hilfreich, wenn du später weitere Services wie eine Dokumentation, einen Passwortmanager oder ein internes Dashboard ergänzen willst. Dann muss nicht jeder Dienst selbst TLS sprechen oder separat öffentlich erreichbar sein.

So sieht die Architektur in der Praxis aus

Das Standardbild ist einfach: Nginx nimmt externe HTTPS-Verbindungen an und leitet sie intern an Home Assistant weiter, meistens per HTTP auf Port 8123. Der Browser spricht also nur mit Nginx, während Home Assistant im Heimnetz oder in einem Docker-Netz bleibt. Das ist die Variante, die ich in den meisten Fällen bevorzuge, weil sie gut verständlich und leicht zu warten ist.

Aus meiner Sicht ist die einfache Faustregel: Je mehr Dienste du ohnehin auf einem Server oder in einem Docker-Stack betreibst, desto eher lohnt sich ein eigenständiger Nginx. Je kleiner dein Setup und je weniger du selbst pflegen willst, desto eher sprechen die Komfortlösungen für sich. Der nächste Schritt ist die eigentliche Konfiguration, denn dort entscheiden sich die meisten Fehlermeldungen.

Die Nginx-Konfiguration, die in der Praxis funktioniert

Ich halte die Nginx-Seite bewusst schlank. Home Assistant braucht keine exotischen Rewrite-Regeln, sondern vor allem korrekte Header und WebSocket-Unterstützung. Genau dort entstehen die meisten Probleme, wenn etwas zwar auf den ersten Blick erreichbar ist, die Oberfläche aber beim Login oder beim Live-Update aussteigt.

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 80;
    server_name ha.example.tld;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name ha.example.tld;

    ssl_certificate     /etc/letsencrypt/live/ha.example.tld/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/ha.example.tld/privkey.pem;

    location / {
        proxy_pass http://192.168.1.50:8123;
        proxy_http_version 1.1;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;

        proxy_read_timeout 86400;
    }
}

Worauf ich hier achte: Host sorgt dafür, dass Home Assistant die ursprüngliche Domain sieht, X-Forwarded-For transportiert die echte Client-IP, und X-Forwarded-Proto verhindert falsche Annahmen über HTTP oder HTTPS. Die Upgrade-Header sind für WebSockets entscheidend, weil die Oberfläche von Home Assistant dauerhaft mit dem Backend kommuniziert. Fehlen sie, lädt die Seite manchmal noch, bricht aber später ohne saubere Erklärung weg.

Wenn du Zertifikate über Let’s Encrypt ausstellst, ist Port 80 nur dann wichtig, wenn du HTTP-01 nutzt. Mit DNS-Challenge kannst du dir diesen Port sparen, was in Netzen mit strenger Firewall oder bereits genutztem Port 80 oft die angenehmere Lösung ist. Von hier aus ist der Schritt zur Home-Assistant-Seite kurz, aber genau dort wird das Setup erst wirklich vollständig.

Home Assistant korrekt auf den Proxy vorbereiten

Die Home-Assistant-Dokumentation empfiehlt für Reverse Proxies vor allem zwei Dinge: use_x_forwarded_for aktivieren und den Proxy in trusted_proxies eintragen. Ohne diese Freigabe blockiert Home Assistant Anfragen, weil die Anwendung den Proxy nicht als vertrauenswürdige Zwischeninstanz akzeptiert. Das ist kein Bug, sondern ein Sicherheitsmechanismus.

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 192.168.1.10
    - 172.30.33.0/24

Ich trage hier möglichst die kleinste passende Adresse oder das kleinste passende Subnetz ein. Wenn Nginx auf derselben Maschine läuft, kann 127.0.0.1 sinnvoll sein. Läuft der Proxy in Docker oder auf einem anderen Host, nimmst du besser die echte Proxy-IP oder das Docker-Subnetz, das Home Assistant tatsächlich sieht. Zu breite Freigaben wie ein ganzes Heimnetz oder gar ein offenes Netz sind zwar bequem, machen das Setup aber unnötig unsauber.

Typisch ist auch, dass sich die Proxy-IP in Docker-Umgebungen verschiebt, wenn Container neu erstellt werden oder ein Netz neu aufgebaut wird. Genau deshalb bevorzuge ich stabile Netze und dokumentiere die Adresse des Proxys sofort mit. Nach einer Änderung an configuration.yaml brauchst du außerdem einen Neustart oder zumindest einen sauberen Reload von Home Assistant, sonst testest du gegen eine alte Konfiguration. Wenn hier alles sitzt, bleiben am Ende nur noch die klassischen Fehlersituationen übrig.

Typische Fehler, die ich immer wieder sehe

Die meisten Probleme sehen dramatischer aus, als sie sind. In der Praxis lassen sich die Ursachen oft auf drei Ebenen eingrenzen: Nginx, Home Assistant oder DNS und Zertifikate. Ich starte bei Fehlermeldungen deshalb immer mit dem Symptom, nicht mit einer Vermutung.

Was ich in solchen Fällen nie überspringe: die Logs. Nginx meldet normalerweise sehr klar, ob der Upstream fehlt oder ein Zertifikat nicht passt, und Home Assistant sagt ebenfalls deutlich, wenn ein Proxy nicht vertraut wird. Erst wenn diese beiden Ebenen sauber aussehen, prüfe ich Router, Firewall und DNS. Das spart Zeit, weil man nicht sofort an der falschen Stelle sucht.

Ein weiterer Klassiker ist die Annahme, dass ein funktionierender Browser-Zugriff automatisch auch für die App, WebSockets und interne Weiterleitungen reicht. Das ist nicht so. Genau deshalb teste ich nach jeder Änderung mindestens drei Dinge: Weboberfläche im Browser, App-Zugriff von außen und einen kompletten Neustart des Stacks. Wenn diese drei Tests stabil sind, ist das Setup in der Regel belastbar.

Wann ich eine Alternative vorziehen würde

Ich würde Nginx nicht blind überall vorschalten, nur weil es technisch elegant wirkt. Wenn das eigentliche Ziel ausschließlich sicherer Fernzugriff ist, ist ein VPN oft die schlichtere Lösung. Dann bleibt Home Assistant komplett intern, und du musst keinen Webdienst öffentlich präsentieren. Das ist häufig die sauberste Antwort, wenn die Nutzerzahl klein ist und keine externen Domains gebraucht werden.

Wenn du zwar einen Reverse Proxy willst, aber keine Lust auf manuelle Nginx-Konfiguration hast, ist Nginx Proxy Manager eine vernünftige Abkürzung. Das lohnt sich vor allem dann, wenn mehrere Domains, Weiterleitungen und Zertifikate verwaltet werden müssen und eine Weboberfläche den Betrieb spürbar einfacher macht. Der Preis dafür ist ein zusätzlicher Layer, den du mitdenken und aktualisieren musst.

Die Home-Assistant-eigenen Add-ons oder ein integrierter Proxy sind dagegen dann interessant, wenn du bewusst innerhalb des Home-Assistant-Ökosystems bleiben willst. Für kleine Installationen ist das bequem, für größere Infrastrukturen bevorzuge ich aber meist eine klare Trennung zwischen Applikation und Edge-Proxys. Aus Sicherheits- und Wartungssicht ist diese Trennung später leichter zu erklären und zu prüfen. Der letzte Punkt ist deshalb weniger technisch als operativ: Wie bleibt das Ganze auf Dauer stabil?

Damit das Setup auch nach Updates ruhig bleibt

Ein gutes Reverse-Proxy-Setup lebt nicht nur von der Erstkonfiguration, sondern von klarer Pflege. Ich dokumentiere die Proxy-IP, die verwendeten Subnetze und den Ort der Zertifikate sofort mit, weil genau diese Details nach einigen Monaten sonst unnötig Zeit kosten. Dazu gehört auch, dass Nginx- und Home-Assistant-Updates gemeinsam getestet werden, statt sie ungeprüft nacheinander einzuspielen.

• Proxy-IP und Subnetze festhalten, damit trusted_proxies später nicht geraten werden muss.
• Zertifikatsablauf überwachen, besonders wenn Let’s Encrypt automatisiert erneuert werden soll.
• Logs regelmäßig prüfen, damit 400er- und WebSocket-Fehler nicht erst bei Nutzern auffallen.
• Externe und interne URL konsistent halten, damit App, Browser und Automationen dieselbe Adresse verwenden.
• Firewall-Regeln knapp halten, damit nur der Proxy öffentlich erreichbar ist und nicht der Backend-Port 8123.

Wenn du dieses Setup sauber aufziehst, ist es nicht kompliziert, sondern robust. Genau das ist für Home Assistant die bessere Lösung: nicht die technisch spektakulärste, sondern die, die nach sechs Monaten noch genauso funktioniert wie am ersten Tag.