O Home Assistant pode funcionar atrás de um proxy inverso num subcaminho?

O Home Assistant pode ser executado atrás de um proxy inverso, mas disponibilizá-lo de forma fiável a partir de um subcaminho reescrito geralmente não é uma fronteira de implementação suportada.

Uma página em example.com/homeassistant pode devolver HTML, enquanto os pedidos seguintes continuam a apontar para recursos relativos à raiz, rotas de autenticação, WebSockets ou callbacks de integrações. Teste mais do que o primeiro ecrã: use um navegador novo, inicie sessão, abra um painel em tempo real, recarregue uma rota aninhada e conclua um callback. Se alguma camada remover o prefixo, mova o Home Assistant para o seu próprio hostname em vez de adicionar mais reescritas.

Separe o suporte de proxy inverso do suporte a subcaminhos

Um proxy inverso pode terminar o TLS e encaminhar um pedido à raiz do hostname para o Home Assistant. 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 estabelece 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 aceite a colocação do Home Assistant num subcaminho recomenda um subdomínio, independentemente da escolha do proxy.

PASSA no suporte a proxy inverso significa que o Home Assistant funciona na raiz de um hostname dedicado, com o encaminhamento correto. FALHA no subcaminho proposto significa que uma ou mais rotas da aplicação perdem o prefixo. Não combine essas conclusões numa afirmação de 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 privado do navegador e inspecione os pedidos de rede antes de alterar o Home Assistant. Se o documento base carregar, mas o JavaScript, os ícones, os manifestos ou as traduções solicitarem caminhos a partir da raiz do hostname, a topologia já falhou no primeiro critério reversível.

Uma tentativa documentada de reescrita de caminho devolveu a página principal, enquanto os recursos do frontend solicitaram URLs prefixados por uma barra, sem o prefixo do Home Assistant. Essa falha de recursos relativos à raiz é uma incompatibilidade de caminhos da aplicação, não um ficheiro em falta no proxy.

PASSA significa que todos os recursos do frontend são devolvidos com êxito na rota pretendida. FALHA significa que aparecem respostas 404 ou pedidos para caminhos na raiz. Pare aí e teste um hostname dedicado; a substituição do corpo das respostas é frágil, porque futuras compilações do frontend podem introduzir novos caminhos que a reescrita não abrange.

Teste WebSockets, autenticação e rotas aninhadas

Uma estrutura estática de painel não constitui uma sessão completa. Inicie sessão a partir de um perfil limpo, observe as atualizações das entidades durante vários minutos, atualize um URL de painel aninhado, termine a sessão e inicie sessão novamente. Depois, verifique se as atualizações HTTP, os tokens, os redirecionamentos e as recargas de rotas mantêm a mesma origem e o mesmo caminho públicos.

O Home Assistant depende bastante de WebSockets para a comunicação em tempo real do frontend, pelo que um proxy tem de preservar o caminho de atualização e os cabeçalhos. O relato de um operador sobre o tratamento de WebSockets pelo proxy inverso mostra por que motivo carregar apenas HTML não é um teste de compatibilidade suficiente.

PASSA significa que a autenticação, as atualizações em tempo real, a navegação e as recargas diretas funcionam sem erros de tradução de caminhos. Uma FALHA limitada aos sockets ou aos redirecionamentos continua a rejeitar o desenho com subcaminho. Corrigir uma diretiva do proxy não prova que os callbacks e as futuras rotas passarão a reconhecer o prefixo.

Featured

ZimaCube 2 NAS Pessoal Cloud para Casa

ZimaCube2

$799.00 - $2,499.00

Buy Now

Escolha um hostname dedicado como fronteira 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 origem pública única sem exigir que a aplicação compreenda um prefixo de caminho. Uma VPN privada ou um túnel podem fornecer a mesma fronteira de raiz limpa sem exposição pública.

Quando um caminho remoto existente deixa de funcionar após alterações na rede, verifique independentemente o DNS, o endereço público, o NAT, o túnel e o encaminhamento do proxy. O diagnóstico da ZimaSpace para o acesso remoto após uma alteração no router fornece essa verificação complementar do caminho.

A alternativa passa quando um navegador limpo consegue carregar recursos, estabelecer um WebSocket, autenticar, atualizar rotas aninhadas e aceder ao Home Assistant após um reinício do proxy. Mantenha a rota antiga disponível apenas durante o tempo necessário para reverter alterações de DNS ou do proxy; não opere indefinidamente dois URLs públicos ambíguos.

Pare quando a sessão completa sobreviver a um reinício

Reinicie o proxy e o Home Assistant uma vez e repita o teste completo a partir da LAN e da rede remota pretendida. Confirme o nome do certificado, o endereço do cliente encaminhado, a fronteira do proxy de confiança, o início de sessão, o estado em tempo real, o encerramento da sessão e um callback de integração. Esta é a carga de trabalho original, não uma verificação estática reduzida da página.

Declare sucesso apenas para o desenho com hostname na raiz que passe todos os passos. Um subcaminho que só funciona após uma reescrita personalizada das respostas continua a ser dívida operacional não suportada, porque uma atualização pode alterar o comportamento dos recursos ou dos callbacks. Documente o hostname validado, o endereço upstream e a configuração de reversão.

Escalone o problema quando o desenho com hostname na raiz continuar a falhar, porque a causa restante é provavelmente a confiança do proxy, o encaminhamento de WebSockets, o DNS, o certificado ou o encaminhamento, e não o suporte a um caminho base. Não exponha diretamente o Home Assistant numa porta desprotegida apenas para preservar o formato de URL pretendido.