Home Assistant
Come configurare Cloudflare Tunnel per Home Assistant
Pubblica Home Assistant con Cloudflare Tunnel senza port forwarding, usando cloudflared, un hostname DNS, token riservato e controlli di sicurezza.
Prerequisiti & Hardware Necessario
- Hardware: server o VM Linux con Home Assistant raggiungibile sulla LAN e accesso Internet in uscita. Un host possibile è Beelink Mini S12 Pro Mini PC.
- Software: account Cloudflare, dominio con nameserver Cloudflare,
cloudflaredo container Cloudflare Tunnel e Home Assistant. Cloudflare Tunnel è il collegamento software; DNS e dominio sono servizi Cloudflare; Home Assistant resta il servizio origin. - Rete: nessuna porta inbound pubblica necessaria. Il connector crea connessioni outbound verso Cloudflare; il firewall deve consentire l’uscita TCP/UDP prevista, inclusa la porta 7844.
- Sicurezza: usa un hostname dedicato, autenticazione Home Assistant e, per utenti esterni, Cloudflare Access. Non pubblicare direttamente il pannello senza autenticazione.
Procedura passo-passo
- Metti il dominio su Cloudflare. Aggiungi il dominio al tuo account e completa il cambio dei nameserver presso il registrar. Verifica che Cloudflare gestisca la zona DNS prima di creare il tunnel.
- Crea il tunnel dal dashboard. In Cloudflare apri Networking → Tunnels, seleziona Create Tunnel, scegli Cloudflared e assegna un nome descrittivo. Non incollare il token in repository, screenshot o chat.
- Configura il published application. Nella sezione delle route aggiungi un hostname, per esempio
ha.example.it, e come servizio inserisci l’origin locale:http://IP_HOME_ASSISTANT:8123. Se cloudflared è nello stesso network Docker e il servizio si chiamahomeassistant, usa il nome risolvibile dalla rete Docker. - Installa il connector. Usa il comando generato dal dashboard. Per un host Docker, la forma documentata è:
docker run -d --name cloudflared --restart unless-stopped cloudflare/cloudflared:latest tunnel --no-autoupdate run --token TOKEN_GENERATO_DA_CLOUDFLAREIl token è una credenziale: sostituiscilo solo con quello generato per il tunnel e proteggi l’accesso al comando.
- Controlla il connector.
Il tunnel deve risultare Healthy/Connected nel dashboard e il log non deve mostrare errori DNS, TLS o connessione alla origin.docker ps --filter name=cloudflared docker logs --tail=100 cloudflared - Verifica l’origin dalla rete locale. Dal server connector prova:
Se il connector è su una VM o container separato, verifica routing, firewall e DNS interno prima di diagnosticare Cloudflare.curl -I http://IP_HOME_ASSISTANT:8123 - Apri Home Assistant dall’hostname. Visita
https://ha.example.it, completa il login e controlla che dashboard, WebSocket e aggiornamenti live funzionino. Home Assistant richiede WebSocket per molte funzioni della UI. - Gestisci proxy e intestazioni solo se richiesto. Se Home Assistant segnala una richiesta proxy non valida, configura
use_x_forwarded_foretrusted_proxiesusando esclusivamente l’IP/subnet reale del connector. Non copiare CIDR generici senza verificarli dal log e dalla topologia. - Applica Cloudflare Access. Crea una policy Zero Trust che limiti l’hostname a identità o email autorizzate. Mantieni comunque l’autenticazione interna di Home Assistant: Access è un ulteriore livello, non una sostituzione automatica dell’account HA.
- Testa assenza di port forwarding. Rimuovi eventuali regole NAT/port forwarding per 8123 dal router e verifica che l’hostname Cloudflare continui a funzionare. Dalla WAN l’IP pubblico non deve esporre Home Assistant direttamente.
Verifica del funzionamento
La configurazione è corretta quando il tunnel è connesso, il published hostname risolve al tunnel, https://ha.example.it apre Home Assistant, WebSocket e login funzionano e la porta 8123 non è pubblicata sul router. Prova anche il riavvio del connector e controlla che restart: unless-stopped lo riporti online.
Problemi comuni
| Problema | Causa | Soluzione |
|---|---|---|
| Hostname non raggiungibile | Route DNS o tunnel non connesso | Controlla tunnel, published application, DNS e log di cloudflared. |
| 502 Bad Gateway | Origin IP/porta errati o Home Assistant non raggiungibile dal connector | Prova curl dalla macchina connector e correggi servizio/route. |
| Dashboard parzialmente bloccata | WebSocket non instradato o proxy configurato male | Controlla route HTTP, log browser e configurazione proxy reale. |
| Cloudflare Tunnel connesso ma accesso non protetto | Cloudflare Access non configurato e HA esposto all’hostname | Aggiungi una policy Access e mantieni login/2FA Home Assistant. |
| Si accede ancora dall’IP pubblico | Port forwarding 8123 ancora attivo | Rimuovi la regola NAT e chiudi l’ingresso inbound sul firewall. |
FAQ essenziali
Cloudflare Tunnel sostituisce WireGuard?
No. Tunnel pubblica servizi applicativi tramite hostname; WireGuard crea una VPN di rete. Per amministrare più servizi privati e dispositivi LAN, una VPN può essere più adatta.
Posso usare un Quick Tunnel?
Solo per test. Per Home Assistant in produzione crea un tunnel nominato con dominio, token protetto e policy di accesso.
Prodotti consigliati
Hardware pertinente alla guida
I collegamenti portano alle pagine dei prodotti indicati. Il prezzo Amazon, quando disponibile, proviene dall’API ufficiale ed è aggiornato con data e ora; prezzo e disponibilità finali sono quelli della pagina Amazon.