O que deve verificar quando uma aplicação autoalojada abre localmente, mas não é possível aceder à respetiva API?

Eva Wong é a redatora técnica e entusiasta residente na ZimaSpace. Uma geek desde sempre, apaixonada por homelabs e software de código aberto, dedica-se a traduzir conceitos técnicos complexos em guias práticos. A Eva acredita que a auto-hospedagem deve ser divertida, não intimidante. Através dos seus tutoriais, ajuda a comunidade a desmistificar configurações de hardware, desde montar o primeiro NAS até dominar os contentores Docker.

Uma página que abre localmente não prova que o percurso da API funciona; a interface do browser e o pedido ao backend podem usar anfitriões, portas, protocolos ou credenciais diferentes.

Num servidor doméstico, o HTML e os recursos estáticos podem ser carregados através de um proxy inverso, da cache do browser ou de um contentor Web local, enquanto os pedidos à API seguem para outro serviço, subcaminho, ponto de acesso WebSocket ou URL base configurado externamente. Comece por capturar no browser um pedido que falhou, volte a executá-lo a partir do ponto relevante da rede e, em seguida, isole o encaminhamento, o TLS, a autenticação, as políticas do browser e a configuração da aplicação, em vez de tomar a página visível como prova de que toda a infraestrutura está acessível.

Confirme se a página e a API usam o mesmo percurso de rede

Abra as ferramentas de programador do browser e volte a carregar a ação que está a falhar. Registe o URL do pedido, o método, o estado, o corpo da resposta, o endereço remoto, o iniciador e se a falha corresponde a um pedido HTTP normal, WebSocket, evento enviado pelo servidor ou pedido em segundo plano.

Num caso de Baserow autoalojado, uma interface utilizável indicava repetidamente que estava a restabelecer a ligação porque o canal de eventos do browser seguia um caminho diferente através do proxy. O sintoma visível era uma ligação de eventos falhada, não uma falha total do servidor Web.

Compare, carácter a carácter, o pedido de documento bem-sucedido com o pedido à API que falhou: esquema, nome de anfitrião, porta, prefixo do caminho e cadeia de consulta. Se forem diferentes, investigue a primeira camada que mudou. Se forem idênticos, prossiga com os cabeçalhos, os cookies, o tratamento da resposta e o encaminhamento para o backend.

Volte a executar o pedido exato a partir de cada ponto relevante da rede

Copie um pedido que falhou para um comando e volte a executá-lo a partir do cliente, do anfitrião do proxy inverso e de um contentor temporário ligado à rede da aplicação. Preserve o método, o cabeçalho de autorização, o tipo de conteúdo, o corpo e o nome de anfitrião esperado.

Uma API pode estar acessível nas camadas TCP e HTTP e, ainda assim, rejeitar o pedido efetivo por falta de um token ou cabeçalho. Uma discussão sobre a API do FreshRSS concluiu que uma falha externa se devia a falta de contexto de autorização, e não a um problema geral de acessibilidade do contentor.

Identifique o primeiro ponto em que ocorre a falha. Uma falha de DNS aponta para a resolução de nomes; uma recusa de ligação aponta para o serviço à escuta, a porta ou a rede; um erro de TLS aponta para a identidade ou a confiança; as respostas 401 ou 403 apontam para a autenticação ou as políticas; uma resposta 404 aponta muitas vezes para o encaminhamento ou a reescrita do subcaminho; e uma chamada direta bem-sucedida, mas falhada no navegador, aponta o diagnóstico para o proxy ou para as regras do navegador.

Verifique o URL base, a porta e o subcaminho da API

Inspecione o URL público da aplicação, o URL da API, o URL do WebSocket, o caminho base e as variáveis definidas durante a compilação do frontend. Uma interface servida localmente pode conter um endereço absoluto da API que aponta para um domínio antigo, um IP privado, uma porta incorreta ou um caminho raiz que só existe no servidor.

As implementações em subcaminhos são particularmente sensíveis ao tratamento das barras e às regras de reescrita. Num caso de proxy inverso do Frigate, os recursos deixaram de funcionar devido ao comportamento de reescrita do subcaminho, apesar de ser possível aceder à interface principal.

Teste o endpoint da API com e sem o prefixo configurado apenas para identificar a rota correta. Em seguida, configure a aplicação e o proxy para usarem o mesmo caminho canónico. Não mantenha exceções de reescrita duplicadas que fazem alguns métodos funcionar, enquanto os carregamentos, os callbacks ou os endpoints de streaming continuam a contornar o backend previsto.

Verifique os cabeçalhos do proxy inverso, o TLS e o suporte de streaming

Compare a rota do proxy para páginas comuns com a rota para pedidos de API, WebSocket e streaming. Confirme o nome do serviço upstream, a porta interna, a versão HTTP, o comportamento de atualização da ligação, o tempo limite de leitura, a política de buffering e os cabeçalhos encaminhados do host e do protocolo.

Os utilizadores do Open WebUI relataram uma interface aparentemente funcional, enquanto a saída da API através do proxy fica bloqueada devido a diferenças no comportamento do buffering ou do streaming em relação ao acesso direto. O diagnóstico deve centrar-se no percurso de streaming através do proxy, não na página estática.

Envie o nome de anfitrião e o esquema originais para o backend através de cabeçalhos de proxy fidedigno configurados de forma restrita. Ative as atualizações para WebSocket apenas nas rotas que delas necessitam, desative o buffering inadequado nos endpoints de streaming e verifique se o proxy utiliza o listener interno da aplicação, em vez de selecionar por engano a porta pública do anfitrião.

Distinga a política do browser da acessibilidade do servidor

Quando um comando direto é bem-sucedido, mas o browser falha, inspecione a consola do browser para detetar erros de CORS, conteúdo misto, certificados, cookies e preflight. O servidor pode responder corretamente, enquanto o browser se recusa a expor ou enviar o pedido.

Uma discussão sobre o Open WebUI por trás de um proxy inverso relaciona as falhas de WebSocket e da API com o tratamento da origem e do protocolo encaminhado, mostrando por que razão a identidade da origem e do protocolo deve manter-se consistente ao longo do proxy.

Confirme que uma página HTTPS nunca chama uma API HTTP, que a API só permite a origem necessária, que os pedidos de preflight chegam à mesma rota e que os cookies de sessão usam os atributos corretos de domínio, caminho, Secure e SameSite. Evite desativar globalmente as proteções do browser; corrija antes a identidade pública e a política do servidor.

Valide o fluxo de trabalho completo da API em todas as redes necessárias

Depois de o primeiro pedido com falha funcionar, teste o início de sessão, a listagem ou pesquisa, a criação ou atualização, o carregamento, a transferência, os eventos em segundo plano e uma renovação do token, a partir da LAN e de todos os percursos remotos suportados. Um único GET bem-sucedido não prova que as operações de escrita autenticadas ou as ligações de longa duração foram corrigidas.

O fluxo de trabalho do ZimaSpace para separar a acessibilidade por IP do encaminhamento do domínio é o passo seguinte quando as chamadas diretas à API funcionam por endereço, mas falham através do nome de anfitrião público.

O problema só fica resolvido quando o browser e o cliente que não é um browser usam o endpoint canónico previsto, o proxy chega ao backend correto, a autenticação se mantém ao longo dos redirecionamentos, as políticas do browser aceitam a resposta e as sessões de streaming ou WebSocket permanecem estáveis. Guarde o pedido com falha capturado como teste de regressão para futuras atualizações.

Assistência e dicas

Mais para ler

Get More Builds Like This

Stay in the Loop

Get updates from Zima - new products, exclusive deals, and real builds from the community.

Stay in the Loop preferences

We respect your inbox. Unsubscribe anytime.