O Home Assistant pode funcionar atrás de um proxy inverso, mas servi-lo de forma fiável a partir de um subcaminho reescrito geralmente não é um cenário de implementação suportado.
Uma página em example.com/homeassistant pode devolver HTML, enquanto os pedidos seguintes continuam a visar recursos com caminhos relativos à raiz, rotas de autenticação, WebSockets ou callbacks de integrações. Teste mais do que o ecrã inicial: use um navegador novo, inicie sessão, abra um painel em tempo real, volte a carregar uma rota aninhada e conclua um callback. Se alguma camada eliminar o prefixo, transfira o Home Assistant para o seu próprio nome de anfitrião em vez de acrescentar mais reescritas.
Distinga o suporte de proxy inverso do suporte de subcaminhos
Um proxy inverso pode terminar o TLS e encaminhar para o Home Assistant um pedido à raiz de um nome de anfitrião. Um subcaminho acrescenta um requisito diferente: todos os URLs gerados, recursos, chamadas à API, WebSockets, redirecionamentos e callbacks têm de preservar consistentemente um prefixo que a aplicação compreenda. O sucesso na camada do proxy não confirma esse contrato da aplicação.
Os testes da comunidade do Home Assistant chegam a uma conclusão direta: a aplicação não suporta a implementação sob um prefixo de URL. A resposta definitiva sobre colocar o Home Assistant num subcaminho recomenda um subdomínio, independentemente da escolha de proxy.
PASS para o suporte de proxy inverso significa que o Home Assistant funciona na raiz de um nome de anfitrião dedicado, com o encaminhamento correto. FAIL para o subcaminho proposto significa que uma ou mais rotas da aplicação perdem o prefixo. Não combine estes veredictos para concluir que os próprios proxies inversos são incompatíveis.
Use os recursos do frontend como primeiro teste de baixo risco
Abra o subcaminho proposto num perfil de navegação privado e inspecione os pedidos de rede antes de alterar o Home Assistant. Se o documento base for carregado, mas JavaScript, ícones, manifestos ou traduções pedirem caminhos a partir da raiz do nome de anfitrião, a topologia já falhou no primeiro teste discriminador reversível.
Uma tentativa documentada de reescrita de caminhos devolveu a página principal, enquanto os recursos do frontend pediam URLs com barra inicial, sem o prefixo do Home Assistant. Essa falha de recursos com caminhos relativos à raiz é uma incompatibilidade no caminho da aplicação, não um ficheiro em falta no proxy.
PASS significa que todos os recursos do frontend são carregados com êxito na rota prevista. FAIL significa que surgem respostas 404 ou pedidos ao caminho raiz. Pare por aí e teste um nome de anfitrião dedicado; a substituição do corpo da resposta é frágil, pois futuras versões do frontend podem introduzir novos caminhos que a reescrita não abrange.
Testar WebSockets, autenticação e rotas aninhadas
Uma estrutura estática de painel não constitui uma sessão completa. Inicie sessão com um perfil limpo, acompanhe as atualizações das entidades durante vários minutos, atualize um URL de painel aninhado, termine sessão e volte a iniciá-la. Em seguida, verifique se as atualizações HTTP, os tokens, os redirecionamentos e as recargas de rotas mantêm a mesma origem pública e o mesmo caminho.
O Home Assistant depende muito de WebSockets para a comunicação em tempo real da interface, por isso o proxy tem de preservar o processo de atualização da ligação e os cabeçalhos. O relato de um operador sobre o tratamento de WebSockets pelo proxy inverso mostra por que motivo carregar apenas o HTML não é um teste de compatibilidade suficiente.
PASS significa que a autenticação, as atualizações em tempo real, a navegação e os recarregamentos diretos funcionam sem erros de tradução de caminhos. Uma falha limitada a sockets ou redirecionamentos continua a reprovar a configuração com subcaminho. Corrigir uma diretiva do proxy não prova que os callbacks e as rotas futuras passarão a reconhecer o prefixo.
Escolha um hostname dedicado como limite estável
Publique o Home Assistant na raiz de um hostname dedicado, como ha.example.com, e encaminhe esse hostname através do proxy inverso para o serviço interno. Isto preserva uma única origem pública sem exigir que a aplicação compreenda um prefixo de caminho. Uma VPN privada ou um túnel pode proporcionar o mesmo limite de raiz simples, sem exposição pública.
Quando um caminho remoto existente deixa de funcionar após alterações de rede, verifique o DNS, o endereço público, o NAT, o túnel e o encaminhamento do proxy de forma independente. O diagnóstico da ZimaSpace para o acesso remoto após uma alteração no router fornece uma verificação complementar desse percurso.
A alternativa é aprovada quando um navegador sem sessão iniciada consegue carregar os recursos, estabelecer um WebSocket, autenticar-se, atualizar rotas aninhadas e aceder ao Home Assistant após o reinício do proxy. Mantenha a rota antiga disponível apenas durante o tempo necessário para reverter alterações ao DNS ou ao proxy; não mantenha indefinidamente duas URLs públicas ambíguas.
Pare quando a sessão completa sobreviver a um reinício
Reinicie o proxy e o Home Assistant uma vez e, em seguida, repita o teste completo a partir da LAN e da rede remota pretendida. Confirme o nome do certificado, o endereço do cliente encaminhado, os limites de confiança do proxy, o início de sessão, o estado em tempo real, o fim de sessão e um callback de integração. Este é o teste original, não uma verificação reduzida de página estática.
Declare sucesso apenas para a configuração com hostname de raiz que passe todos os passos. Um subcaminho que só funciona após reescritas personalizadas das respostas continua a ser uma dívida técnica sem suporte, pois uma atualização pode alterar o comportamento dos recursos ou dos callbacks. Documente o hostname comprovadamente funcional, o endereço upstream e a configuração de reversão.
Escale quando a configuração com hostname de raiz continuar a falhar, pois a causa restante é provavelmente a confiança no proxy, o encaminhamento de WebSockets, o DNS, o certificado ou o encaminhamento, e não o suporte de caminhos base. Não exponha o Home Assistant diretamente numa porta desprotegida apenas para preservar o formato de URL pretendido.
Assistência e dicas
Mais para ler

Como manter vídeos para adultos no seu NAS ocultos dos membros da família
Mantenha os vídeos para adultos privados num NAS familiar. Verifique as permissões das pastas, o acesso às bibliotecas do Plex e do Jellyfin, as...

O que verificar antes de carregar um modelo da comunidade em Transformers
Utilize a atualização da sandbox Jinja do Transformers para rever a proveniência dos modelos, os modelos de chat, o código remoto, os pesos serializados...

Execute o Mirage localmente: OCR e deteção de objetos a partir de uma imagem
Experimente o pequeno modelo de visão local da Cactus Compute, valide o OCR e a extração de objetos com dados reais e compreenda os...



