Was sollten Sie prüfen, wenn eine selbst gehostete App lokal geöffnet werden kann, ihre API jedoch nicht erreichbar ist?

Eva Wong

IceWhale author

Eva Wong ist die Technische Redakteurin und und leidenschaftliche Tüftlerin bei ZimaSpace. Eine lebenslange Geek mit einer Leidenschaft für Homelabs und Open-Source-Software, sie spezialisiert sich darauf, komplexe technische Konzepte in zugängliche, praktische Anleitungenzu übersetzen. Eva ist der Meinung, dass Self-Hosting Spaß machen und nicht einschüchternd sein sollte. Durch ihre Tutorials befähigt sie die Community, Hardware-Setups zu entmystifizieren, vom Bau ihres ersten NAS bis hin zur Beherrschung von Docker-Containern.

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

Dass sich eine Seite lokal öffnen lässt, beweist nicht, dass ihr API-Pfad funktioniert; Browseroberfläche und Backend-Anfrage können unterschiedliche Hosts, Ports, Protokolle oder Zugangsdaten verwenden.

Auf einem Heimserver können HTML und statische Ressourcen über einen Reverse-Proxy, den Browser-Cache oder einen lokalen Webcontainer geladen werden, während API-Aufrufe an einen anderen Dienst, Unterpfad, WebSocket-Endpunkt oder eine extern konfigurierte Basis-URL gehen. Beginnen Sie damit, eine fehlgeschlagene Anfrage im Browser zu erfassen, sie von der relevanten Netzwerkgrenze aus erneut abzusetzen und anschließend Routing, TLS, Authentifizierung, Browserrichtlinien und Anwendungskonfiguration getrennt zu untersuchen, anstatt die sichtbare Seite als Beweis dafür zu betrachten, dass der gesamte Stack erreichbar ist.

Nachweisen, ob Seite und API denselben Netzwerkpfad verwenden

Öffnen Sie die Entwicklertools des Browsers und laden Sie die fehlschlagende Aktion erneut. Notieren Sie Anfrage-URL, Methode, Status, Antworttext, Remote-Adresse, Initiator und ob es sich beim Fehler um eine gewöhnliche HTTP-Anfrage, einen WebSocket, ein Server-Sent Event oder einen Hintergrundabruf handelt.

Ein selbst gehosteter Baserow-Fall zeigte eine nutzbare Oberfläche, die wiederholt eine erneute Verbindung meldete, weil der Ereigniskanal des Browsers einem anderen Proxy-Pfad folgte. Das sichtbare Symptom war eine fehlgeschlagene Ereignisverbindung, kein vollständiger Ausfall des Webservers.

Vergleichen Sie die erfolgreiche Dokumentanfrage und die fehlgeschlagene API-Anfrage Zeichen für Zeichen: Schema, Hostname, Port, Pfadpräfix und Abfragezeichenfolge. Wenn sie sich unterscheiden, untersuchen Sie die erste abweichende Ebene. Wenn sie identisch sind, fahren Sie mit Headern, Cookies, Antwortverarbeitung und Backend-Routing fort.

Die exakte Anfrage von jeder relevanten Grenze aus erneut absetzen

Kopieren Sie eine fehlgeschlagene Anfrage als Befehl und setzen Sie sie vom Client, vom Host des Reverse-Proxys und von einem temporären Container im Anwendungsnetzwerk erneut ab. Behalten Sie Methode, Autorisierungs-Header, Inhaltstyp, Request-Body und den erwarteten Hostnamen bei.

Eine API kann auf TCP- und HTTP-Ebene erreichbar sein und die tatsächliche Anfrage dennoch ablehnen, weil ein Token oder Header fehlt. Eine FreshRSS-API-Diskussion grenzte einen externen Fehler auf fehlenden Autorisierungskontext ein, nicht auf eine allgemeine Erreichbarkeit des Containers.

Ordnen Sie die früheste fehlschlagende Grenze ein. Ein DNS-Fehler weist auf die Namensauflösung hin; eine Verbindungsverweigerung auf Listener, Port oder Netzwerk; ein TLS-Fehler auf Identität oder Vertrauen; 401 oder 403 auf Authentifizierung oder Richtlinien; 404 häufig auf Routing oder Umschreiben von Unterpfaden. Wenn ein direkter Aufruf erfolgreich ist, der Browseraufruf jedoch fehlschlägt, richtet sich die Diagnose eher auf Proxy- oder Browserregeln.

API-Basis-URL, Port und Unterpfad prüfen

Untersuchen Sie die öffentliche URL, API-URL, WebSocket-URL, den Basispfad und die Build-Zeit-Variablen des Frontends. Eine lokal bereitgestellte Oberfläche kann eine absolute API-Adresse enthalten, die auf eine alte Domain, eine private IP-Adresse, den falschen Port oder einen Root-Pfad verweist, der nur auf dem Server existiert.

Bereitstellungen unter einem Unterpfad reagieren besonders empfindlich auf die Behandlung von Schrägstrichen und Umschreibungsregeln. Ein Frigate-Fall mit Reverse-Proxy führte fehlschlagende Ressourcen auf das Umschreibungsverhalten des Unterpfads zurück, obwohl die Hauptoberfläche erreichbar war.

Testen Sie den API-Endpunkt sowohl mit als auch ohne das konfigurierte Präfix, um den korrekten Pfad zu ermitteln, und sorgen Sie anschließend dafür, dass Anwendung und Proxy sich auf einen kanonischen Pfad einigen. Behalten Sie keine doppelten Umschreibungsausnahmen bei, durch die einige Methoden funktionieren, während Uploads, Rückrufe oder Streaming-Endpunkte weiterhin am vorgesehenen Backend vorbeigeleitet werden.

Featured

ZimaCube 2 Persönliche Cloud Home NAS

ZimaCube2

Header des Reverse-Proxys, TLS und Streaming-Unterstützung prüfen

Vergleichen Sie die Proxy-Route für gewöhnliche Seiten mit den Routen für API-, WebSocket- und Streaming-Anfragen. Bestätigen Sie den Namen des Upstream-Dienstes, den internen Port, die HTTP-Version, das Verhalten beim Verbindungs-Upgrade, das Lese-Timeout, die Pufferungsrichtlinie sowie die weitergeleiteten Host- und Protokoll-Header.

Nutzer von Open WebUI haben von einer Oberfläche berichtet, die funktionsfähig wirkt, während die API-Ausgabe hinter dem Proxy ins Stocken gerät, weil sich Pufferung oder Streaming-Verhalten vom direkten Zugriff unterscheiden. Der diagnostische Schwerpunkt liegt auf dem Streaming-Pfad hinter dem Proxy, nicht auf der statischen Seite.

Übermitteln Sie den ursprünglichen Hostnamen und das ursprüngliche Schema über eng konfigurierte, vertrauenswürdige Proxy-Header an das Backend. Aktivieren Sie WebSocket-Upgrades nur für Routen, die sie benötigen, deaktivieren Sie unangemessene Pufferung für Streaming-Endpunkte und stellen Sie sicher, dass der Proxy den internen Listener der Anwendung verwendet, statt versehentlich den veröffentlichten Host-Port.

Browserrichtlinien von der Erreichbarkeit des Servers trennen

Wenn ein direkter Befehl erfolgreich ist, der Browser jedoch fehlschlägt, prüfen Sie die Browserkonsole auf CORS-, Mixed-Content-, Zertifikats-, Cookie- und Preflight-Fehler. Der Server kann korrekt antworten, während der Browser die Anfrage nicht freigibt oder nicht sendet.

Eine Diskussion zu Open WebUI hinter einem Reverse-Proxy verknüpft WebSocket- und API-Fehler mit der Behandlung von Origin und weitergeleitetem Protokoll. Sie zeigt, warum Origin- und Protokollidentität über den gesamten Proxy hinweg konsistent bleiben müssen.

Stellen Sie sicher, dass eine HTTPS-Seite niemals eine HTTP-API aufruft, dass die API nur den erforderlichen Origin erlaubt, dass Preflight-Anfragen dieselbe Route erreichen und dass Sitzungscookies die korrekten Attribute für Domain, Pfad, Secure und SameSite verwenden. Deaktivieren Sie den Browserschutz nicht global, sondern korrigieren Sie stattdessen die öffentliche Identität und Richtlinie des Servers.

Den vollständigen API-Ablauf aus jedem erforderlichen Netzwerk prüfen

Nachdem die erste fehlgeschlagene Anfrage funktioniert, testen Sie Anmeldung, Auflisten oder Suchen, Erstellen oder Aktualisieren, Upload, Download, Hintergrundereignisse und eine Token-Erneuerung aus dem LAN sowie über jeden unterstützten Fernzugriff. Ein einzelner erfolgreicher GET-Aufruf beweist nicht, dass authentifizierte Schreibvorgänge oder langlebige Verbindungen repariert sind.

Der ZimaSpace-Workflow zum Trennen von IP-Erreichbarkeit und Domain-Routing ist der nächste Schritt, wenn direkte API-Aufrufe über die Adresse funktionieren, aber über den öffentlichen Hostnamen fehlschlagen.

Das Problem ist erst gelöst, wenn Browser und Nicht-Browser-Client den vorgesehenen kanonischen Endpunkt verwenden, der Proxy das korrekte Backend erreicht, die Authentifizierung Weiterleitungen übersteht, die Browserrichtlinie die Antwort akzeptiert und Streaming- oder WebSocket-Sitzungen stabil bleiben. Bewahren Sie die erfasste fehlgeschlagene Anfrage als Regressionstest für künftige Upgrades auf.