O que deve verificar quando uma aplicação autoalojada abre localmente, mas a respetiva API não pode ser acedida?
Uma página que abre localmente não prova que o respetivo caminho da API funciona; a interface do navegador e o pedido ao backend podem usar hosts, portas, protocolos ou credenciais diferentes.
Num servidor doméstico, o HTML e os recursos estáticos podem ser carregados a partir de um proxy inverso, da cache do navegador ou de um contentor Web local, enquanto os pedidos à API seguem para outro serviço, subcaminho, endpoint WebSocket ou URL base configurado externamente. Comece por capturar um pedido que falhou no navegador, repita-o a partir do limite de rede relevante e, em seguida, distinga encaminhamento, TLS, autenticação, política do navegador e configuração da aplicação, em vez de tratar a página visível como prova de que toda a infraestrutura está acessível.
Comprove se a Página e a API Usam o Mesmo Caminho de Rede
Abra as ferramentas de desenvolvimento do navegador e recarregue 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 obtenção em segundo plano.
Um caso de Baserow autoalojado mostrou uma interface utilizável a indicar repetidamente que estava a restabelecer a ligação, porque o canal de eventos do navegador seguia um caminho de proxy diferente. O sintoma visível era uma ligação de eventos falhada, não uma indisponibilidade completa do servidor Web.
Compare, carácter a carácter, o pedido de documento bem-sucedido com o pedido à API que falhou: esquema, nome do host, porta, prefixo do caminho e cadeia de consulta. Se forem diferentes, investigue a primeira camada que mudou. Se forem idênticos, prossiga para os cabeçalhos, cookies, tratamento da resposta e encaminhamento no backend.
Repita o Pedido Exato a Partir de Cada Limite Relevante
Copie um pedido que falhou como comando e repita-o 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 host esperado.
Uma API pode estar acessível nas camadas TCP e HTTP e, ainda assim, rejeitar o pedido real porque falta um token ou cabeçalho. Uma discussão sobre a API do FreshRSS restringiu uma falha externa à ausência de contexto de autorização, e não a uma falta geral de acessibilidade do contentor.
Interprete o primeiro limite onde ocorre a falha. Uma falha de DNS aponta para a resolução de nomes; uma recusa de ligação aponta para o listener, a porta ou a rede; um erro de TLS aponta para a identidade ou a confiança; os estados 401 ou 403 apontam para autenticação ou política; o estado 404 aponta frequentemente para encaminhamento ou reescrita de subcaminho; e uma chamada direta bem-sucedida com uma chamada do navegador falhada direciona o diagnóstico para as regras do proxy ou 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 no processo de 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 errada ou um caminho raiz que só existe no servidor.
As implementações em subcaminhos são especialmente sensíveis ao tratamento das barras e às regras de reescrita. Um caso do proxy inverso do Frigate atribuiu os recursos falhados ao comportamento da reescrita do subcaminho, embora a interface principal estivesse acessível.
Teste o endpoint da API com e sem o prefixo configurado apenas para identificar a rota correta e, depois, corrija a aplicação e o proxy para concordarem num único caminho canónico. Não mantenha exceções de reescrita duplicadas que façam alguns métodos funcionar enquanto os carregamentos, callbacks ou endpoints de transmissão continuam a ignorar o backend pretendido.
Verifique os Cabeçalhos do Proxy Inverso, o TLS e o Suporte de Transmissão
Compare a rota do proxy para as páginas normais com as rotas para pedidos à API, WebSocket e de transmissão. 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 armazenamento em buffer e os cabeçalhos de host e protocolo encaminhados.
Utilizadores do Open WebUI relataram uma interface que parecia funcional enquanto a saída da API através do proxy ficava bloqueada, porque o comportamento de armazenamento em buffer ou de transmissão diferia do acesso direto. O foco do diagnóstico é o caminho de transmissão através do proxy, não a página estática.
Envie o nome de host e o esquema originais para o backend através de cabeçalhos de proxy confiáveis configurados de forma restrita. Ative as atualizações WebSocket apenas nas rotas que delas necessitam, desative o armazenamento em buffer inadequado nos endpoints de transmissão e confirme que o proxy utiliza o listener interno da aplicação, em vez de usar acidentalmente a porta do host publicada.
Separe a Política do Navegador da Acessibilidade do Servidor
Quando um comando direto funciona, mas o navegador falha, inspecione a consola do navegador à procura de erros de CORS, conteúdo misto, certificado, cookies e preflight. O servidor pode responder corretamente enquanto o navegador recusa expor ou enviar o pedido.
Uma discussão sobre o Open WebUI através de proxy inverso relaciona falhas de WebSocket e da API com o tratamento da origem e do protocolo encaminhado, mostrando por que motivo a identidade da origem e do protocolo deve permanecer consistente através do proxy.
Confirme que uma página HTTPS nunca chama uma API HTTP, que a API permite apenas a origem necessária, que os pedidos preflight chegam à mesma rota e que os cookies de sessão usam o domínio, o caminho e os atributos Secure e SameSite corretos. Evite desativar globalmente as proteções do navegador; corrija antes a identidade pública e a política do servidor.
Valide o Fluxo Completo da API a Partir de Todas as Redes Necessárias
Depois de o primeiro pedido falhado 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 atualização de token a partir da LAN e de todos os caminhos remotos suportados. Um único GET bem-sucedido não prova que as operações autenticadas de escrita ou as ligações de longa duração foram reparadas.
O fluxo do ZimaSpace para separar a acessibilidade por IP do encaminhamento por domínio é o passo seguinte quando as chamadas diretas à API funcionam por endereço, mas falham através do nome de host público.
O problema só está resolvido quando o navegador e o cliente sem navegador utilizam o endpoint canónico pretendido, o proxy chega ao backend correto, a autenticação sobrevive aos redirecionamentos, a política do navegador aceita a resposta e as sessões de transmissão ou WebSocket permanecem estáveis. Preserve o pedido falhado capturado como teste de regressão para futuras atualizações.
Produtos recomendados
Suporte e Dicas
Mais para Ler
O Plex pode partilhar uma GPU com outro contentor Docker?
O Plex e outro contentor conseguem frequentemente aceder à mesma GPU, mas é necessário testar o suporte dos controladores, o mapeamento de dispositivos, a...
Como saber se um erro do Plex vem do cliente ou do servidor
Reproduza o mesmo item noutro cliente, compare o percurso da sessão e, em seguida, recolha provas do servidor apenas depois de o âmbito lhe...
Como configurar a cache do Plex e o armazenamento temporário de transcodificação
Proteja o estado persistente do Plex enquanto coloca os ficheiros temporários de transcodificação num armazenamento local adequado e, em seguida, verifique a limpeza, o...
