Co należy sprawdzić, gdy aplikacja hostowana samodzielnie otwiera się lokalnie, ale nie można uzyskać dostępu do jej API?

Eva Wong

IceWhale author

Eva Wong jest Technicznym pisarzem i stałym majsterkowiczem w ZimaSpace. Całe życie geek z pasją do homelabów i oprogramowania open-source, specjalizuje się w tłumaczeniu skomplikowanych koncepcji technicznych na przystępne, praktyczne przewodniki. Eva wierzy, że samodzielne hostowanie powinno być zabawą, a nie czymś onieśmielającym. Poprzez swoje samouczki umożliwia społeczności rozwiewanie tajemnic konfiguracji sprzętu, od budowy pierwszego NAS po opanowanie kontenerów Docker.

What Should You Check When a Self-Hosted App Opens Locally but Its API Cannot Be Reached?

Lokalnie otwierająca się strona nie dowodzi, że jej ścieżka API działa; interfejs przeglądarkowy i żądanie 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ć ładowane z odwrotnego proxy, pamięci podręcznej przeglądarki lub lokalnego kontenera WWW, podczas gdy wywołania API trafiają do innej usługi, podścieżki, punktu końcowego WebSocket albo zewnętrznie skonfigurowanego bazowego adresu URL. Zacznij od przechwycenia jednego nieudanego żądania w przeglądarce, odtwórz je z odpowiedniej granicy sieci, a następnie rozdziel problemy z routingiem, TLS, uwierzytelnianiem, polityką przeglądarki i konfiguracją aplikacji, zamiast uznawać widoczną stronę za dowód, że cały stos jest osiągalny.

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

Otwórz narzędzia deweloperskie przeglądarki i odśwież wadliwą funkcję. Zapisz adres URL żądania, metodę, status, treść odpowiedzi, adres zdalny, inicjator oraz informację, czy błąd dotyczy zwykłego żądania HTTP, WebSocketu, zdarzeń wysyłanych przez serwer czy żądania wykonywanego w tle.

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

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

Odtwórz dokładne żądanie z każdej istotnej granicy

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ć rzeczywiste żądanie z powodu braku tokenu lub nagłówka. Dyskusja dotycząca API FreshRSS zawęziła zewnętrzny problem do braku kontekstu autoryzacji, a nie ogólnej osiągalności kontenera.

Interpretuj najwcześniejszą granicę, na której występuje błąd. Błąd DNS wskazuje na rozwiązywanie nazw; odmowa połączenia wskazuje na nasłuchujący proces, port lub sieć; błąd TLS wskazuje na tożsamość lub zaufanie; kod 401 lub 403 wskazuje na uwierzytelnianie lub politykę; kod 404 często wskazuje na routing lub przepisywanie podścieżki, a pomyślne połączenie bezpośrednie przy nieudanym wywołaniu z przeglądarki kieruje diagnozę w stronę reguł proxy lub przeglądarki.

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

Sprawdź publiczny adres URL aplikacji, adres URL API, adres URL WebSocketu, ścieżkę bazową i zmienne frontendu ustawiane podczas budowania. Lokalnie serwowany interfejs może zawierać bezwzględny adres API wskazujący na starą domenę, prywatny adres IP, nieprawidłowy port lub ścieżkę główną, która istnieje wyłącznie na serwerze.

Wdrożenia pod podścieżką są szczególnie wrażliwe na sposób obsługi ukośników i reguł przepisywania. W przypadku Frigate za odwrotnym proxy nieudane zasoby powiązano z zachowaniem przepisywania podścieżki, mimo że główny interfejs był osiągalny.

Przetestuj punkt końcowy API zarówno z skonfigurowanym prefiksem, jak i bez niego, wyłącznie w celu ustalenia prawidłowej trasy, a następnie skonfiguruj aplikację i proxy tak, aby uzgodniły jedną kanoniczną ścieżkę. Nie utrzymuj wielu wyjątków przepisywania, przez które niektóre metody działają, podczas gdy przesyłanie plików, wywołania zwrotne lub punkty końcowe przesyłania strumieniowego nadal omijają właściwy backend.

Featured

ZimaCube 2 Osobisty domowy NAS w chmurze

ZimaCube2

Zweryfikuj nagłówki odwrotnego proxy, TLS i obsługę przesyłania strumieniowego

Porównaj trasę proxy dla zwykłych stron z trasą dla żądań API, WebSocketów i przesyłania strumieniowego. Potwierdź nazwę usługi upstream, wewnętrzny port, wersję HTTP, działanie aktualizacji połączenia, limit czasu odczytu, zasady buforowania oraz przekazywane nagłówki hosta i protokołu.

Użytkownicy Open WebUI zgłaszali interfejs, który wyglądał na sprawny, podczas gdy dane API przesyłane przez proxy zatrzymywały się z powodu różnic w buforowaniu lub obsłudze strumieniowania w porównaniu z dostępem bezpośrednim. Diagnostyka powinna koncentrować się na ścieżce przesyłania strumieniowego przez proxy, a nie na stronie statycznej.

Przekazuj backendowi oryginalną nazwę hosta i schemat za pomocą precyzyjnie skonfigurowanych, zaufanych nagłówków proxy. Włączaj aktualizacje WebSocketu tylko na trasach, które ich wymagają, wyłącz nieodpowiednie buforowanie dla punktów końcowych przesyłania strumieniowego i sprawdź, czy proxy korzysta z wewnętrznego procesu nasłuchującego aplikacji, a nie przypadkowo z opublikowanego portu hosta.

Oddziel politykę przeglądarki od osiągalności serwera

Gdy bezpośrednie polecenie działa, a przeglądarka kończy się błędem, sprawdź w konsoli przeglądarki błędy CORS, mixed content, certyfikatu, plików cookie i żądań preflight. Serwer może odpowiadać prawidłowo, podczas gdy przeglądarka odmawia udostępnienia odpowiedzi lub wysłania żądania.

Dyskusja dotycząca Open WebUI za odwrotnym proxy łączy awarie WebSocketów i API z obsługą originu oraz przekazywanego protokołu, pokazując, dlaczego tożsamość originu i protokołu musi pozostać spójna w całym proxy.

Potwierdź, że strona HTTPS nigdy nie wywołuje API przez HTTP, że API zezwala wyłącznie na wymagany origin, że żądania preflight docierają do tej samej trasy oraz że pliki cookie sesji mają prawidłowe atrybuty domeny, ścieżki, Secure i SameSite. Nie wyłączaj globalnie zabezpieczeń przeglądarki; zamiast tego napraw publiczną tożsamość i politykę serwera.

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

Po naprawieniu pierwszego nieudanego żądania 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 każdej obsługiwanej ścieżki zdalnej. Pojedyncze pomyślne żądanie GET nie dowodzi, że naprawiono uwierzytelnione operacje zapisu ani połączenia długotrwałe.

Procedura ZimaSpace dotycząca oddzielenia osiągalności po adresie IP od routingu domeny jest kolejnym krokiem, gdy bezpośrednie wywołania API działają po adresie, ale zawodzą za pośrednictwem publicznej nazwy hosta.

Problem jest rozwiązany dopiero wtedy, gdy przeglądarka i klient pozaprzeglądarkowy korzystają z zamierzonego kanonicznego punktu końcowego, proxy dociera do właściwego backendu, uwierzytelnianie zachowuje się po przekierowaniach, polityka przeglądarki akceptuje odpowiedź, a sesje przesyłania strumieniowego lub WebSocketów pozostają stabilne. Zachowaj przechwycone nieudane żądanie jako test regresji na potrzeby przyszłych aktualizacji.