Co należy sprawdzić, gdy samodzielnie hostowana aplikacja otwiera się lokalnie, ale nie można połączyć się z jej API?

Eva Wong jest redaktorką techniczną i rezydentką majsterkowania w ZimaSpace. Jest geekiem od zawsze, z pasją do domowych laboratoriów i oprogramowania open source, a jej specjalnością jest przekładanie złożonych zagadnień technicznych na przystępne, praktyczne poradniki. Eva wierzy, że samodzielne hostowanie powinno sprawiać radość, a nie onieśmielać. Dzięki swoim samouczkom pomaga społeczności oswoić konfigurację sprzętu, od budowy pierwszego serwera NAS po opanowanie kontenerów Docker.

To, że strona otwiera się lokalnie, nie dowodzi, że jej ścieżka API działa; interfejs przeglądarkowy i żądanie do backendu mogą korzystać z różnych hostów, portów, protokołów lub danych uwierzytelniających.

Na serwerze domowym kod HTML i zasoby statyczne mogą być dostarczane przez odwrotne proxy, pamięć podręczną przeglądarki lub lokalny kontener WWW, podczas gdy wywołania API trafiają do innej usługi, podścieżki, punktu końcowego WebSocket albo skonfigurowanego zewnętrznego adresu bazowego. Najpierw przechwyć w przeglądarce jedno nieudane żądanie, odtwórz je z odpowiedniego punktu sieciowego, a następnie sprawdź osobno routing, TLS, uwierzytelnianie, zasady przeglądarki i konfigurację aplikacji, zamiast traktować widoczną stronę jako dowód dostępności całego stosu.

Sprawdź, czy strona i API korzystają z tej samej ścieżki sieciowej

Otwórz narzędzia deweloperskie przeglądarki i ponownie wykonaj czynność, która kończy się niepowodzeniem. Zapisz adres URL żądania, metodę, kod statusu, treść odpowiedzi, adres zdalny, inicjator oraz informację, czy jest to zwykłe żądanie HTTP, WebSocket, zdarzenie wysyłane przez serwer czy pobieranie w tle.

W przypadku samodzielnie hostowanego Baserow interfejs działał, ale stale zgłaszał ponowne łączenie, ponieważ kanał zdarzeń przeglądarki korzystał z innej ścieżki przez proxy. Widocznym objawem było nieudane połączenie z kanałem zdarzeń, a nie całkowita awaria serwera WWW.

Porównaj znak po znaku udane żądanie dokumentu z nieudanym żądaniem API: schemat, nazwę hosta, port, prefiks ścieżki i ciąg zapytania. Jeśli się różnią, sprawdź pierwszą warstwę, w której nastąpiła zmiana. Jeśli są identyczne, przejdź do nagłówków, plików cookie, obsługi odpowiedzi i routingu do backendu.

Odtwórz dokładne żądanie z każdego istotnego punktu sieci

Skopiuj jedno nieudane żądanie jako polecenie i odtwórz je z klienta, hosta odwrotnego proxy oraz tymczasowego kontenera podłączonego do sieci aplikacji. Zachowaj jego metodę, nagłówek autoryzacji, typ zawartości, treść i oczekiwaną nazwę hosta.

API może być osiągalne na poziomie TCP i HTTP, a mimo to odrzucać właściwe żądanie z powodu braku tokena lub nagłówka. W dyskusji o API FreshRSS ustalono, że przyczyną problemu z dostępem z zewnątrz był brak kontekstu autoryzacji, a nie ogólna niedostępność kontenera.

Ustal, na którym etapie pojawia się pierwszy błąd. Błąd DNS wskazuje na problem z rozpoznawaniem nazw; odmowa połączenia — na nasłuchującą usługę, port lub sieć; błąd TLS — na tożsamość lub zaufanie; kod 401 lub 403 — na uwierzytelnianie lub zasady dostępu; kod 404 często wskazuje na trasowanie lub przepisywanie podścieżki; a jeśli bezpośrednie wywołanie kończy się powodzeniem, a wywołanie z przeglądarki nie, należy skupić diagnostykę na regułach proxy lub przeglądarki.

Sprawdź bazowy adres URL API, port i podścieżkę

Sprawdź publiczny adres URL aplikacji, adres URL API, adres URL WebSocket, ścieżkę bazową oraz zmienne ustawiane podczas kompilacji frontendu. Interfejs serwowany lokalnie może zawierać bezwzględny adres API wskazujący starą domenę, prywatny adres IP, niewłaściwy port lub ścieżkę główną dostępną tylko na serwerze.

Wdrożenia w podścieżce są szczególnie wrażliwe na obsługę ukośników i reguły przepisywania. W przypadku reverse proxy Frigate przyczyną błędów zasobów okazała się zmiana reguł przepisywania podścieżki, mimo że główny interfejs był dostępny.

Przetestuj punkt końcowy API zarówno z skonfigurowanym prefiksem, jak i bez niego, wyłącznie po to, by ustalić właściwą trasę, a następnie dostosuj aplikację i proxy tak, aby korzystały z jednej kanonicznej ścieżki. Nie pozostawiaj zduplikowanych wyjątków w regułach przepisywania, przez które niektóre metody działają, a przesyłanie plików, wywołania zwrotne lub punkty końcowe strumieniowania nadal omijają docelowy backend.

Sprawdź nagłówki reverse proxy, TLS i obsługę strumieniowania

Porównaj trasę proxy dla zwykłych stron z trasą dla żądań API, WebSocket i strumieniowania. Sprawdź nazwę usługi upstream, port wewnętrzny, wersję HTTP, obsługę przełączania połączenia, limit czasu odczytu, politykę buforowania oraz przekazywane nagłówki hosta i protokołu.

Użytkownicy Open WebUI zgłaszali, że interfejs pozornie działa, ale odpowiedź proxowanego API zatrzymuje się z powodu różnic w buforowaniu lub strumieniowaniu w porównaniu z dostępem bezpośrednim. Diagnostyka koncentruje się na proxowanej ścieżce strumieniowania, a nie na statycznej stronie.

Przekazuj do backendu oryginalną nazwę hosta i schemat za pomocą ściśle skonfigurowanych nagłówków zaufanego proxy. Włączaj obsługę aktualizacji połączenia do WebSocket tylko na trasach, które jej wymagają, wyłącz nieodpowiednie buforowanie punktów końcowych strumieniowych i sprawdź, czy proxy korzysta z wewnętrznego portu nasłuchu aplikacji, zamiast przypadkowo używać opublikowanego portu hosta.

Oddziel zasady przeglądarki od dostępności serwera

Gdy polecenie wykonane bezpośrednio działa, ale przeglądarka zawodzi, sprawdź w konsoli przeglądarki błędy CORS, mixed content, certyfikatu, plików cookie i preflight. Serwer może odpowiadać prawidłowo, a mimo to przeglądarka może odmawiać udostępnienia odpowiedzi lub wysłania żądania.

Dyskusja o Open WebUI za reverse proxy łączy problemy z WebSocketami i API z obsługą origin oraz przekazywanego protokołu, pokazując, dlaczego tożsamość origin i protokołu musi być spójna na całej trasie przez proxy.

Upewnij się, że strona HTTPS nigdy nie wywołuje API przez HTTP, API zezwala tylko na wymagane źródło, żądania preflight trafiają na tę samą trasę, a pliki cookie sesji mają prawidłowe atrybuty Domain, Path, Secure i SameSite. Nie wyłączaj globalnie zabezpieczeń przeglądarki — zamiast tego popraw publiczną tożsamość i zasady serwera.

Sprawdź pełny przepływ API z każdej wymaganej sieci

Gdy pierwsze nieudane żądanie zacznie działać, przetestuj logowanie, wyświetlanie listy lub wyszukiwanie, tworzenie lub aktualizowanie, przesyłanie i pobieranie plików, zdarzenia w tle oraz jedno odświeżenie tokenu — z sieci LAN i z każdej obsługiwanej sieci zdalnej. Pojedyncze udane żądanie GET nie dowodzi, że naprawiono uwierzytelnione operacje zapisu ani połączenia długotrwałe.

Procedura ZimaSpace dotycząca odróżniania dostępności IP od routingu domen to kolejny krok, gdy bezpośrednie wywołania API działają przez adres, ale zawodzą przez publiczną nazwę hosta.

Problem zostaje rozwiązany dopiero wtedy, gdy klient przeglądarkowy i nieprzeglądarkowy korzystają z właściwego, kanonicznego punktu końcowego, proxy łączy się z prawidłowym backendem, uwierzytelnianie działa również po przekierowaniach, zasady przeglądarki dopuszczają odpowiedź, a sesje strumieniowe lub WebSocket pozostają stabilne. Zachowaj przechwycone nieudane żądanie jako test regresyjny na potrzeby przyszłych aktualizacji.

Wsparcie i porady

Więcej do przeczytania

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.