Wat moet je controleren wanneer een self-hosted app lokaal opent, maar de API niet bereikbaar is?

Eva Wong

IceWhale author

Eva Wong is de Technisch Schrijver en en vaste knutselaar bij ZimaSpace. Een levenslange geek met een passie voor homelabs en open-source software, zij is gespecialiseerd in het vertalen van complexe technische concepten naar toegankelijke, praktische handleidingen. Eva gelooft dat zelf-hosting leuk moet zijn, niet intimiderend. Met haar tutorials stelt ze de community in staat om hardware-setup te ontrafelen, van het bouwen van hun eerste NAS tot het beheersen van Docker-containers.

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

Dat een pagina lokaal opent, bewijst niet dat het API-pad werkt; de browserinterface en het backendverzoek kunnen verschillende hosts, poorten, protocollen of inloggegevens gebruiken.

Op een thuisserver kunnen de HTML en statische assets worden geladen via een reverse proxy, browsercache of lokale webcontainer, terwijl API-aanroepen naar een andere service, subpad, WebSocket-eindpunt of extern geconfigureerde basis-URL gaan. Begin met het vastleggen van één mislukt verzoek in de browser, voer het opnieuw uit vanaf de relevante netwerkgrens en onderscheid vervolgens routering, TLS, authenticatie, browserbeleid en applicatieconfiguratie, in plaats van de zichtbare pagina te beschouwen als bewijs dat de hele stack bereikbaar is.

Bewijs of de pagina en API hetzelfde netwerkpad gebruiken

Open de ontwikkelaarstools van de browser en laad de mislukte actie opnieuw. Noteer de verzoek-URL, methode, status, antwoordtekst, externe adres, initiator en of de fout een normaal HTTP-verzoek, WebSocket, server-sent event of achtergrondophaalactie betreft.

In een zelfgehoste Baserow-situatie bleek de interface bruikbaar, maar meldde deze voortdurend dat de verbinding opnieuw werd gemaakt omdat het eventkanaal een ander proxypad volgde. Het zichtbare symptoom was een mislukte eventverbinding, niet een volledige storing van de webserver.

Vergelijk het geslaagde documentverzoek met het mislukte API-verzoek teken voor teken: schema, hostnaam, poort, padvoorvoegsel en querystring. Als ze verschillen, onderzoek dan de eerste laag waar de wijziging optreedt. Als ze identiek zijn, ga dan verder met headers, cookies, antwoordverwerking en backendroutering.

Voer het exacte verzoek opnieuw uit vanaf elke relevante grens

Kopieer één mislukt verzoek als opdracht en voer het opnieuw uit vanaf de client, de host van de reverse proxy en een tijdelijke container die met het applicatienetwerk is verbonden. Behoud de methode, autorisatieheader, inhoudstype, body en verwachte hostnaam.

Een API kan op TCP- en HTTP-niveau bereikbaar zijn, maar het echte verzoek toch weigeren omdat een token of header ontbreekt. Een FreshRSS API-discussie bracht een externe fout terug tot ontbrekende autorisatiecontext in plaats van algemene bereikbaarheid van de container.

Interpreteer de eerste grens waar het misgaat. Een DNS-fout wijst op naamresolutie; een geweigerde verbinding op de listener, poort of het netwerk; een TLS-fout op identiteit of vertrouwen; 401 of 403 op authenticatie of beleid; 404 wijst vaak op routering of herschrijven van subpaden; en een geslaagde directe aanroep met een mislukte browseraanroep verschuift de diagnose richting proxy- of browserregels.

Controleer de basis-URL, poort en het subpad van de API

Controleer de openbare URL, API-URL, WebSocket-URL, het basispad en de build-timevariabelen van de frontend van de applicatie. Een lokaal aangeboden interface kan een absoluut API-adres bevatten dat naar een oud domein, privé-IP, verkeerde poort of rootpad verwijst dat alleen op de server bestaat.

Implementaties onder een subpad zijn bijzonder gevoelig voor slashverwerking en herschrijfregels. In een Frigate-situatie met een reverse proxy werden mislukte resources herleid tot gedrag bij het herschrijven van subpaden, hoewel de hoofdinterface bereikbaar was.

Test het API-eindpunt zowel met als zonder het geconfigureerde voorvoegsel, uitsluitend om de juiste route vast te stellen, en zorg er daarna voor dat de applicatie en proxy één canoniek pad gebruiken. Houd geen dubbele uitzonderingen voor herschrijven in stand waardoor sommige methoden werken, terwijl uploads, callbacks of streaming-eindpunten de bedoelde backend blijven omzeilen.

Featured

ZimaCube 2 Persoonlijke Cloud Home NAS

ZimaCube2

Controleer reverse-proxyheaders, TLS en ondersteuning voor streaming

Vergelijk de proxyroutes voor gewone pagina’s met de routes voor API-, WebSocket- en streamingverzoeken. Controleer de upstream-servicenaam, interne poort, HTTP-versie, gedrag bij het upgraden van verbindingen, time-out voor lezen, bufferbeleid en doorgestuurde host- en protocolheaders.

Gebruikers van Open WebUI hebben gemeld dat een interface functioneel lijkt, terwijl de geproxiede API-uitvoer blijft hangen omdat buffering of streaminggedrag verschilt van directe toegang. De diagnostische focus ligt op het geproxiede streamingpad, niet op de statische pagina.

Stuur de oorspronkelijke hostnaam en het schema via beperkt geconfigureerde, vertrouwde proxyheaders naar de backend. Schakel WebSocket-upgrades alleen in op routes die ze nodig hebben, schakel ongepaste buffering uit voor streaming-eindpunten en controleer of de proxy de interne listener van de applicatie gebruikt, in plaats van per ongeluk de gepubliceerde hostpoort.

Scheid browserbeleid van bereikbaarheid van de server

Wanneer een directe opdracht slaagt maar de browser faalt, controleer dan de browserconsole op CORS-, mixed-content-, certificaat-, cookie- en preflightfouten. De server kan correct antwoorden terwijl de browser weigert het verzoek te verzenden of het antwoord beschikbaar te stellen.

Een discussie over Open WebUI achter een reverse proxy koppelt WebSocket- en API-fouten aan de verwerking van origin- en doorgestuurde protocollen, wat laat zien waarom origin- en protocolidentiteit consistent moet blijven via de proxy.

Controleer of een HTTPS-pagina nooit een HTTP-API aanroept, of de API alleen de vereiste origin toestaat, of preflightverzoeken dezelfde route bereiken en of sessiecookies het juiste domein, pad en de juiste Secure- en SameSite-attributen gebruiken. Schakel browserbeveiligingen niet globaal uit; herstel in plaats daarvan de openbare identiteit en het beleid van de server.

Valideer de volledige API-workflow vanaf elk vereist netwerk

Test, nadat het eerste mislukte verzoek werkt, het inloggen, weergeven of zoeken, aanmaken of bijwerken, uploaden, downloaden, achtergrondgebeurtenissen en één tokenvernieuwing vanaf het LAN en elk ondersteund extern pad. Eén geslaagde GET bewijst niet dat geauthenticeerde schrijfacties of langdurige verbindingen zijn hersteld.

De ZimaSpace-workflow voor het scheiden van IP-bereikbaarheid en domeinroutering is de volgende stap wanneer directe API-aanroepen via het adres werken, maar via de openbare hostnaam mislukken.

Het probleem is pas opgelost wanneer de browser en niet-browserclient het bedoelde canonieke eindpunt gebruiken, de proxy de juiste backend bereikt, authenticatie redirects overleeft, het browserbeleid het antwoord accepteert en streaming- of WebSocket-sessies stabiel blijven. Bewaar het vastgelegde mislukte verzoek als regressietest voor toekomstige upgrades.