Home Assistant peut-il fonctionner derrière un proxy inverse sur un sous-chemin ?
Home Assistant peut fonctionner derrière un proxy inverse, mais le servir de manière fiable depuis un sous-chemin réécrit ne constitue généralement pas une limite de déploiement prise en charge.
Une page à l’adresse example.com/homeassistant peut renvoyer du HTML, tandis que les requêtes suivantes ciblent encore des ressources relatives à la racine, des routes d’authentification, des WebSockets ou des rappels d’intégration. Ne testez pas uniquement le premier écran : utilisez un navigateur vierge, connectez-vous, ouvrez un tableau de bord en direct, rechargez une route imbriquée et exécutez un rappel. Si une couche supprime le préfixe, déplacez Home Assistant vers son propre nom d’hôte plutôt que d’ajouter d’autres réécritures.
Distinguez la prise en charge du proxy inverse de celle des sous-chemins
Un proxy inverse peut terminer TLS et transmettre une requête ciblant la racine d’un nom d’hôte à Home Assistant. Un sous-chemin impose une exigence différente : chaque URL générée, ressource, appel d’API, WebSocket, redirection et rappel doit préserver systématiquement un préfixe que l’application comprend. La réussite au niveau du proxy ne suffit pas à établir ce contrat applicatif.
Les tests de la communauté Home Assistant aboutissent à une conclusion claire : l’application ne prend pas en charge un déploiement sous un préfixe d’URL. La réponse retenue concernant l’installation de Home Assistant dans un sous-chemin recommande un sous-domaine, quel que soit le choix de proxy.
La mention PASS pour la prise en charge du proxy inverse signifie que Home Assistant fonctionne à la racine d’un nom d’hôte dédié avec une transmission correcte. La mention FAIL pour le sous-chemin proposé signifie qu’une ou plusieurs routes de l’application perdent le préfixe. Ne mélangez pas ces verdicts pour conclure que les proxys inverses sont eux-mêmes incompatibles.
Utilisez les ressources frontend comme premier test à faible risque
Ouvrez le sous-chemin proposé dans un profil de navigation privé et inspectez les requêtes réseau avant de modifier Home Assistant. Si le document de base se charge, mais que JavaScript, les icônes, les manifestes ou les traductions demandent des chemins depuis la racine du nom d’hôte, la topologie a déjà échoué à son premier critère réversible.
Une tentative documentée de réécriture de chemin a renvoyé la page principale, tandis que les ressources frontend demandaient des URL préfixées par une barre oblique sans le préfixe de Home Assistant. Cet échec des ressources relatives à la racine est une incompatibilité de chemins applicatifs, et non un fichier manquant sur le proxy.
La mention PASS signifie que chaque ressource frontend est renvoyée correctement sous la route prévue. La mention FAIL signifie que des réponses 404 ou des requêtes vers le chemin racine apparaissent. Arrêtez-vous là et testez un nom d’hôte dédié ; la substitution du corps des réponses est fragile, car de futures versions du frontend peuvent introduire de nouveaux chemins que la réécriture ne couvrira pas.
Testez les WebSockets, l’authentification et les routes imbriquées
Une structure statique de tableau de bord ne constitue pas une session complète. Connectez-vous depuis un profil vierge, observez les mises à jour des entités pendant plusieurs minutes, actualisez une URL de tableau de bord imbriquée, déconnectez-vous, puis reconnectez-vous. Vérifiez ensuite si les mises à niveau HTTP, les jetons, les redirections et le rechargement des routes conservent la même origine et le même chemin publics.
Home Assistant s’appuie fortement sur les WebSockets pour les communications frontend en direct ; un proxy doit donc préserver le chemin de mise à niveau et les en-têtes. Le témoignage d’un opérateur sur la gestion des WebSockets par un proxy inverse montre pourquoi le simple chargement du HTML ne constitue pas un test de compatibilité suffisant.
La mention PASS signifie que l’authentification, les mises à jour en direct, la navigation et les rechargements directs fonctionnent tous sans erreur de traduction de chemin. Un échec limité aux sockets ou aux redirections suffit également à rejeter la conception en sous-chemin. Corriger une directive du proxy ne prouve pas que les rappels et les futures routes deviendront compatibles avec le préfixe.
Choisissez un nom d’hôte dédié comme limite stable
Publiez Home Assistant à la racine d’un nom d’hôte dédié, tel que ha.example.com, puis acheminez ce nom d’hôte via le proxy inverse vers le service interne. Vous conservez ainsi une seule origine publique sans exiger que l’application comprenne un préfixe de chemin. Un VPN privé ou un tunnel peut fournir la même limite racine propre sans exposition publique.
Lorsqu’un chemin distant existant cesse de fonctionner après des changements réseau, vérifiez séparément le DNS, l’adresse publique, le NAT, le tunnel et le routage du proxy. Le diagnostic de ZimaSpace concernant l’accès distant après un changement de routeur fournit cette vérification complémentaire.
L’alternative est validée lorsqu’un navigateur vierge peut charger les ressources, établir un WebSocket, s’authentifier, actualiser les routes imbriquées et atteindre Home Assistant après le redémarrage du proxy. Ne conservez l’ancienne route que le temps nécessaire pour annuler les changements DNS ou de proxy ; n’exploitez pas indéfiniment deux URL publiques ambiguës.
Arrêtez-vous lorsque la session complète survit à un redémarrage
Redémarrez une fois le proxy et Home Assistant, puis répétez le test complet depuis le réseau local et depuis le réseau distant prévu. Confirmez le nom du certificat, l’adresse client transmise, la limite du proxy de confiance, la connexion, l’état en direct, la déconnexion et un rappel d’intégration. Il s’agit de la charge de travail initiale, et non d’une vérification statique de page réduite.
Déclarez la réussite uniquement pour la conception avec nom d’hôte racine qui passe toutes les étapes. Un sous-chemin qui ne fonctionne qu’après une réécriture personnalisée des réponses reste une dette opérationnelle non prise en charge, car une mise à jour peut modifier le comportement des ressources ou des rappels. Documentez le nom d’hôte validé, l’adresse en amont et la configuration de restauration.
Faites remonter le problème si la conception avec nom d’hôte racine échoue encore, car la cause restante est probablement liée à la confiance du proxy, à la transmission des WebSockets, au DNS, au certificat ou au routage, plutôt qu’à la prise en charge du chemin de base. N’exposez pas directement Home Assistant sur un port non protégé dans le seul but de conserver la forme d’URL souhaitée.
Produits recommandés
Assistance et conseils
Plus à lire
Home Assistant fonctionne en Wi-Fi, mais échoue en Ethernet ou via VPN
Testez chaque chemin réseau séparément, vérifiez l’état de l’interface et du routage, distinguez l’accès direct par IP de la découverte, puis ne réparez que...
Comment mettre hors service Home Assistant sans laisser de données non protégées
Prouvez le remplacement ou l’archivage, révoquez chaque chaîne de confiance, assainissez chaque appareil contenant des données et ne conservez que les copies de récupération...
Faut-il utiliser les mises à jour automatiques de Home Assistant sur un serveur domestique ?
Choisissez des mises à jour manuelles, avec notification uniquement, ou automatiques par étapes, en fonction de l’impact sur le foyer, du risque de compatibilité,...
