Home Assistant za reverse proxy (nginx)

Home Assistant domyślnie działa po HTTP na porcie 8123. Jeśli chcesz sięgać do niego pod ładnym adresem (np. ha.twojadomena.pl) z zielonym HTTPS, a przy okazji obsłużyć kilka innych usług na tym samym serwerze, najczystszym rozwiązaniem jest reverse proxy — najczęściej nginx. Poniżej działająca konfiguracja i najważniejsza pułapka, o którą rozbija się większość ludzi: trusted_proxies.

Krok 1: konfiguracja nginx

Serwer proxy przyjmuje ruch po HTTPS i przekazuje go do HA po HTTP w sieci lokalnej. Kluczowe są nagłówki Upgrade/Connection — bez nich WebSocket HA (czyli cały interfejs) nie zadziała:

server {
    listen 443 ssl;
    server_name ha.twojadomena.pl;

    ssl_certificate     /etc/nginx/certs/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/privkey.pem;

    location / {
        proxy_pass http://192.168.100.154: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;

        # niezbędne dla WebSocket (interfejs HA)
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Krok 2: powiedz Home Assistantowi, że stoi za proxy

To jest miejsce, w którym większość ludzi utyka: po wpięciu proxy HA pokazuje błąd „400: Bad Request" przy logowaniu. Powód — HA nie ufa nagłówkom X-Forwarded-For od nieznanego adresu. Trzeba jawnie wskazać IP proxy w configuration.yaml:

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 192.168.100.98      # IP serwera z nginx
    - 172.16.0.0/12       # jeśli nginx jest w Dockerze — sieć kontenerów

Po zapisaniu zrestartuj Home Assistant. Jeśli nginx działa w kontenerze Docker, HA widzi jako źródło adres z sieci dockerowej (np. 172.18.0.x) — dlatego dopisujemy też zakres 172.16.0.0/12. Zły trusted_proxies = dokładnie ten błąd 400.

Krok 3: certyfikat HTTPS

Masz dwie wygodne drogi:

• Let's Encrypt (np. przez certbot albo wtyczkę w panelu proxy) — darmowy, automatyczne odnawianie. Wymaga, by domena wskazywała na Twoje publiczne IP i był otwarty port 80/443.
• Cloudflare — jeśli domena jest w Cloudflare, możesz użyć trybu proxy (pomarańczowa chmurka) i certyfikatu Origin, albo tunelu Cloudflare, który w ogóle nie wymaga otwierania portów na routerze.

Najczęstsze błędy

• Interfejs się nie ładuje / kręci się kółko — brak nagłówków Upgrade/Connection (WebSocket). Dodaj je do location.
• 400: Bad Request przy logowaniu — źle ustawiony trusted_proxies. Dodaj realne IP proxy (przy Dockerze zakres sieci kontenerów).
• Przekierowanie w pętli — HA ma ustawione base_url/SSL po swojej stronie, a proxy też terminuje SSL. Wybierz jedno miejsce terminacji (proxy) i nie ustawiaj ssl_certificate w samym HA.

Podsumowanie

• nginx przyjmuje HTTPS i przekazuje do HA po HTTP — pamiętaj o nagłówkach WebSocket.
• use_x_forwarded_for + poprawny trusted_proxies to warunek, żeby logowanie działało.
• Certyfikat z Let's Encrypt albo Cloudflare; przy Cloudflare Tunnel nie musisz otwierać portów.
• Wystawiając HA do sieci — włącz 2FA i ogranicz dostęp.