Home Assistant può funzionare dietro un reverse proxy su un sottopercorso?

Eva Wong

IceWhale author

Eva Wong è la Technical Writer e smanettatrice residente di ZimaSpace. Una geek da sempre con una passione per homelab e software open-source, si specializza nel tradurre concetti tecnici complessi in guide accessibili e pratiche. Eva crede che l'auto-ospitare debba essere divertente, non intimidatorio. Attraverso i suoi tutorial, dà potere alla comunità di demistificare le configurazioni hardware, dalla costruzione del loro primo NAS al dominio dei container Docker.

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

Home Assistant può funzionare dietro un reverse proxy, ma servirlo in modo affidabile da un sottopercorso riscritto non è generalmente un confine di distribuzione supportato.

Una pagina su example.com/homeassistant può restituire HTML mentre le richieste successive continuano a puntare ad asset relativi alla radice, route di autenticazione, WebSocket o callback delle integrazioni. Testate più della prima schermata: usate un browser appena aperto, accedete, aprite una dashboard live, ricaricate una route annidata e completate una callback. Se un qualsiasi livello perde il prefisso, spostate Home Assistant su un hostname dedicato invece di aggiungere altre riscritture.

Separate il supporto del reverse proxy da quello dei sottopercorsi

Un reverse proxy può terminare TLS e inoltrare una richiesta alla radice dell'hostname verso Home Assistant. Un sottopercorso aggiunge un requisito diverso: ogni URL generato, asset, chiamata API, WebSocket, reindirizzamento e callback deve conservare coerentemente un prefisso che l'applicazione sappia interpretare. Il successo a livello di proxy non dimostra l'esistenza di questo contratto applicativo.

I test della community di Home Assistant portano a una conclusione diretta: l'applicazione non supporta la distribuzione sotto un prefisso URL. La risposta risolta su inserire Home Assistant in un sottopercorso raccomanda un sottodominio indipendentemente dalla scelta del proxy.

PASS per il supporto del reverse proxy significa che Home Assistant funziona alla radice di un hostname dedicato con un inoltro corretto. FAIL per il sottopercorso proposto significa che una o più route dell'applicazione perdono il prefisso. Non combinate questi verdetti sostenendo che i reverse proxy siano incompatibili in sé.

Usate gli asset del frontend come primo test a basso rischio

Aprite il sottopercorso proposto in un profilo browser privato e ispezionate le richieste di rete prima di modificare Home Assistant. Se il documento di base viene caricato ma JavaScript, icone, manifest o traduzioni richiedono percorsi dalla radice dell'hostname, la topologia ha già fallito il primo discriminatore reversibile.

Un tentativo documentato di riscrittura del percorso restituiva la pagina principale mentre le risorse del frontend richiedevano URL preceduti da una barra senza il prefisso di Home Assistant. Questo problema degli asset relativi alla radice è un'incompatibilità del percorso applicativo, non un file mancante sul proxy.

PASS significa che ogni risorsa del frontend viene restituita correttamente nel percorso previsto. FAIL significa che compaiono risposte 404 o richieste verso il percorso radice. Fermatevi e testate un hostname dedicato; la sostituzione del corpo delle risposte è fragile perché future build del frontend possono introdurre nuovi percorsi non coperti dalla riscrittura.

Testate WebSocket, autenticazione e route annidate

Una shell dashboard statica non costituisce una sessione completa. Accedete da un profilo pulito, osservate gli aggiornamenti delle entità per diversi minuti, aggiornate l'URL di una dashboard annidata, uscite e accedete di nuovo. Verificate poi se gli upgrade HTTP, i token, i reindirizzamenti e i ricaricamenti delle route mantengono la stessa origine e lo stesso percorso pubblici.

Home Assistant dipende fortemente dai WebSocket per la comunicazione live del frontend, quindi un proxy deve preservare il percorso di upgrade e le intestazioni. L'esperienza di un operatore sulla gestione dei WebSocket tramite reverse proxy mostra perché il solo caricamento dell'HTML non sia un test sufficiente di compatibilità.

PASS significa che autenticazione, aggiornamenti live, navigazione e ricaricamenti diretti funzionano senza errori di traduzione del percorso. Un FAIL limitato ai socket o ai reindirizzamenti respinge comunque il progetto del sottopercorso. Correggere una direttiva del proxy non dimostra che callback e route future diventeranno consapevoli del prefisso.

Featured

ZimaCube 2 NAS personale cloud domestico

ZimaCube2

Scegliete un hostname dedicato come confine stabile

Pubblicate Home Assistant alla radice di un hostname dedicato, ad esempio ha.example.com, quindi instradate quell'hostname tramite il reverse proxy verso il servizio interno. In questo modo mantenete una sola origine pubblica senza richiedere all'applicazione di comprendere un prefisso di percorso. Una VPN privata o un tunnel possono fornire lo stesso confine pulito alla radice senza esposizione pubblica.

Quando un percorso remoto esistente smette di funzionare dopo modifiche alla rete, verificate separatamente DNS, indirizzo pubblico, NAT, tunnel e instradamento del proxy. La guida diagnostica di ZimaSpace sull'accesso remoto dopo una modifica al router fornisce questa verifica del percorso adiacente.

L'alternativa supera il test quando un browser pulito riesce a caricare gli asset, stabilire un WebSocket, autenticarsi, aggiornare le route annidate e raggiungere Home Assistant dopo un riavvio del proxy. Mantenete il vecchio percorso disponibile solo per il tempo necessario a ripristinare le modifiche DNS o del proxy; non gestite indefinitamente due URL pubblici ambigui.

Fermatevi quando l'intera sessione sopravvive a un riavvio

Riavviate una volta il proxy e Home Assistant, quindi ripetete il test completo dalla LAN e dalla rete remota prevista. Confermate il nome del certificato, l'indirizzo client inoltrato, il confine dei proxy attendibili, l'accesso, lo stato live, la disconnessione e una callback di integrazione. Questo è il carico di lavoro originale, non un controllo ridotto a una pagina statica.

Dichiarate il successo solo per il progetto con hostname alla radice che supera ogni passaggio. Un sottopercorso che funziona soltanto dopo una riscrittura personalizzata delle risposte rimane debito operativo non supportato, perché un aggiornamento può modificare il comportamento degli asset o delle callback. Documentate l'hostname verificato, l'indirizzo upstream e la configurazione di rollback.

Escalate il problema se il progetto con hostname alla radice continua a non funzionare, perché la causa residua è probabilmente la fiducia del proxy, l'inoltro dei WebSocket, il DNS, il certificato o l'instradamento, non il supporto del percorso di base. Non esponete direttamente Home Assistant su una porta non protetta solo per conservare la forma URL desiderata.