Home Assistant: Ingress-Addons hinter Reverse Proxy reparieren

Erreichst du dein Home Assistant über einen Reverse Proxy, verweigern manche Add-ons über Ingress den Dienst: Die Seite bleibt weiß oder meldet Verbindungsprobleme, während lokal über die IP-Adresse alles funktioniert. Damit der Zugriff über externe Adressen klappt, müssen Header und Weiterleitungen im Proxy passend konfiguriert sein.

Das brauchst du

• Eine Home-Assistant-Installation mit Add-ons
• Einen vorgeschalteten Reverse Proxy (wie Nginx oder Caddy)
• Zugriff auf die Konfigurationsdateien deines Proxys und von Home Assistant

1. Trusted Proxies in Home Assistant prüfen

Hat sich beispielsweise die IP-Adresse eines Reverse-Proxy-Containers geändert oder können Add-ons remote nicht geladen werden, kann eine Anpassung des http-Blocks in der Konfiguration von Home Assistant helfen:

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 172.17.0.0/24
    - 172.30.33.0/24
    - 192.168.1.0/24
    - 192.168.0.0/24

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 172.17.0.0/24
    - 172.30.33.0/24
    - 192.168.1.0/24
    - 192.168.0.0/24

Passe die IP-Adressen bzw. Subnetze an deine Netzwerkumgebung an.

2. Proxy-Konfiguration für WebSockets und Pfade anpassen

Kommt es bei Add-ons zu Verbindungsproblemen, kann eine Nginx-Konfiguration mit Weiterleitungen für / und /api/websocket genutzt werden:

server {
    listen 443 ssl;
    server_name ha.example.com;
    proxy_buffering off;

    location / {
        proxy_pass http://192.168.0.19:8123;
        proxy_set_header Host $host;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

    location /api/websocket {
        proxy_pass http://192.168.0.19:8123/api/websocket;
        proxy_set_header Host $host;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

server {
    listen 443 ssl;
    server_name ha.example.com;
    proxy_buffering off;

    location / {
        proxy_pass http://192.168.0.19:8123;
        proxy_set_header Host $host;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

    location /api/websocket {
        proxy_pass http://192.168.0.19:8123/api/websocket;
        proxy_set_header Host $host;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Ersetze ha.example.com durch deine Domain und passe die Ziel-IP deines Home Assistant an.

3. Frame-Header im Reverse Proxy setzen

Damit Ingress-Frames im Browser über den Proxy geladen werden, hilft das Setzen des Content-Security-Policy-Headers im Reverse Proxy:

add_header Content-Security-Policy "frame-ancestors ha.example.com";

add_header Content-Security-Policy "frame-ancestors ha.example.com";

Bei manchen Proxy-Lösungen wie Caddy wird alternativ der Header X-Frame-Options "SAMEORIGIN" verwendet, damit sich der Ingress-Frame öffnet.

Funktioniert es?

Rufe Home Assistant über deine Domain im Browser auf und öffne ein Add-on mit Ingress (beispielsweise den Log Viewer). Lädt die Oberfläche ohne Verbindungsabbruch, greift die Konfiguration wie gewünscht.

Wenn es nicht klappt

• Firefox blockiert die Anzeige: Wenn du Firefox nutzt, kann der Tracking-Schutz („Enhanced Protection Tracker“) Probleme beim Aufruf von Add-ons über Ingress verursachen. Deaktiviere die Funktion testweise für die Home-Assistant-Webseite.
• Add-ons öffnen sich nach IP-Änderung nicht: Wenn der Reverse Proxy in einem Docker-Container betrieben wird und sich dessen IP-Adresse geändert hat, prüfe die Netzwerkadresse und passe trusted_proxies entsprechend an.
• Verbindungsprobleme: Prüfe, ob die Weiterleitungsregeln für /api/websocket sowie die Header für Upgrades in der Proxy-Konfiguration hinterlegt sind.

Quellen: Forum: Home Assistant Community, community.home-assistant.io, community.home-assistant.io