Vad bör du kontrollera när en självhuserad app öppnas lokalt men dess API inte kan nås?
Att en sida öppnas lokalt bevisar inte att dess API-sökväg fungerar; webbläsargränssnittet och backendförfrågan kan använda olika värdar, portar, protokoll eller autentiseringsuppgifter.
På en hemmaserver kan HTML och statiska resurser laddas från en reverse proxy, webbläsarens cache eller en lokal webbcontainer, medan API-anrop går till en annan tjänst, undersökväg, WebSocket-slutpunkt eller en externt konfigurerad bas-URL. Börja med att fånga en misslyckad begäran i webbläsaren, spela upp den från den relevanta nätverksgränsen och separera sedan routing, TLS, autentisering, webbläsarpolicy och applikationskonfiguration i stället för att behandla den synliga sidan som bevis på att hela stacken är nåbar.
Bevisa om sidan och API:et använder samma nätverkssökväg
Öppna webbläsarens utvecklarverktyg och ladda om den åtgärd som misslyckas. Notera begärans URL, metod, status, svarstext, fjärradress, initierare och om felet gäller en vanlig HTTP-begäran, WebSocket, server-sända händelser eller en bakgrundsbegäran.
Ett självhostat Baserow-fall visade ett användbart gränssnitt som upprepade gånger rapporterade återanslutning eftersom webbläsarens händelsekanal följde en annan proxysökväg. Det synliga symptomet var en misslyckad händelseanslutning, inte ett fullständigt avbrott i webbservern.
Jämför den lyckade dokumentbegäran med den misslyckade API-begäran tecken för tecken: schema, värdnamn, port, sökvägsprefix och frågesträng. Om de skiljer sig åt ska du undersöka det första lager där skillnaden uppstår. Om de är identiska fortsätter du med headers, cookies, svarshantering och backend-routing.
Spela upp den exakta begäran från varje relevant gräns
Kopiera en misslyckad begäran som ett kommando och spela upp den från klienten, reverse-proxyvärden och en tillfällig container ansluten till applikationens nätverk. Bevara dess metod, auktoriseringsheader, innehållstyp, brödtext och förväntade värdnamn.
Ett API kan vara nåbart på TCP- och HTTP-nivåerna men ändå avvisa den riktiga begäran eftersom en token eller header saknas. En API-diskussion om FreshRSS begränsade ett externt fel till saknat autentiseringssammanhang snarare än generell nåbarhet för containern.
Tolka den tidigaste felande gränsen. DNS-fel pekar på namnupplösning; anslutningsvägran pekar på lyssnaren, porten eller nätverket; ett TLS-fel pekar på identitet eller förtroende; 401 eller 403 pekar på autentisering eller policy; 404 pekar ofta på routing eller omskrivning av undersökvägar; och ett lyckat direktanrop tillsammans med ett misslyckat webbläsaranrop flyttar fokus mot proxy- eller webbläsarregler.
Kontrollera API:ets bas-URL, port och undersökväg
Granska applikationens offentliga URL, API-URL, WebSocket-URL, bassökväg och frontendvariabler som anges vid byggtid. Ett lokalt levererat gränssnitt kan innehålla en absolut API-adress som pekar på en gammal domän, privat IP-adress, fel port eller rotsökväg som bara finns på servern.
Distributioner via undersökvägar är särskilt känsliga för snedstreck och omskrivningsregler. Ett Frigate-fall med reverse proxy spårade misslyckade resurser till beteendet vid omskrivning av undersökvägar, trots att huvudgränssnittet gick att nå.
Testa API-slutpunkten både med och utan det konfigurerade prefixet endast för att identifiera rätt route, och ändra sedan applikationen och proxyn så att de använder en gemensam kanonisk sökväg. Behåll inte dubbla omskrivningsundantag som gör att vissa metoder fungerar medan uppladdningar, callback-anrop eller strömmande slutpunkter fortsätter att kringgå den avsedda backend-tjänsten.
Verifiera reverse-proxyheaders, TLS och stöd för strömning
Jämför proxyrouten för vanliga sidor med routen för API-, WebSocket- och strömmande begäranden. Bekräfta upstream-tjänstens namn, interna port, HTTP-version, beteende för anslutningsuppgradering, lästimeout, buffringspolicy samt vidarebefordrade värd- och protokollheaders.
Open WebUI-användare har rapporterat ett gränssnitt som verkar fungera medan proxade API-svar stannar upp eftersom buffring eller strömningsbeteende skiljer sig från direktåtkomst. Fokusera diagnostiken på den proxade strömningsvägen, inte den statiska sidan.
Skicka det ursprungliga värdnamnet och schemat till backend via snävt konfigurerade headers för betrodda proxyservrar. Aktivera WebSocket-uppgraderingar endast på rutter som behöver dem, inaktivera olämplig buffring för strömmande slutpunkter och kontrollera att proxyn använder applikationens interna lyssnare i stället för den publicerade värdporten av misstag.
Separera webbläsarpolicy från serverns nåbarhet
När ett direktkommando lyckas men webbläsaren misslyckas ska du kontrollera webbläsarkonsolen efter CORS-, mixed content-, certifikat-, cookie- och preflight-fel. Servern kan svara korrekt medan webbläsaren vägrar att exponera eller skicka begäran.
En diskussion om Open WebUI bakom reverse proxy kopplar WebSocket- och API-fel till hantering av ursprung och vidarebefordrat protokoll, vilket visar varför ursprungs- och protokollidentitet måste förbli konsekvent genom proxyn.
Bekräfta att en HTTPS-sida aldrig anropar ett HTTP-API, att API:et endast tillåter det nödvändiga ursprunget, att preflight-begäranden når samma route och att sessionscookies använder korrekt domän, sökväg samt attributen Secure och SameSite. Undvik att inaktivera webbläsarskydd globalt; korrigera i stället serverns offentliga identitet och policy.
Validera hela API-arbetsflödet från alla nödvändiga nätverk
När den första misslyckade begäran fungerar ska du testa inloggning, listning eller sökning, skapande eller uppdatering, uppladdning, nedladdning, bakgrundshändelser och en tokenförnyelse från det lokala nätverket och alla fjärrvägar som stöds. Ett enda lyckat GET-anrop bevisar inte att autentiserade skrivningar eller långvariga anslutningar är reparerade.
ZimaSpace-arbetsflödet för att skilja IP-nåbarhet från domänrouting är nästa steg när direkta API-anrop fungerar via adressen men misslyckas via det offentliga värdnamnet.
Problemet är löst först när webbläsaren och den klient som inte använder webbläsare använder den avsedda kanoniska slutpunkten, proxyn når rätt backend, autentiseringen överlever omdirigeringar, webbläsarpolicyn godkänner svaret och strömmande eller WebSocket-sessioner förblir stabila. Spara den fångade misslyckade begäran som ett regressionstest inför framtida uppgraderingar.
Rekommenderade produkter
Support och tips
Mer att läsa
Kan Plex dela ett GPU-kort med en annan Docker-container?
Plex och en annan container kan ofta använda samma GPU, men du måste testa drivrutinsstöd, enhetsmappning, belastningen på videoenheten, minne och återställningsbeteende.
Så avgör du om ett Plex-fel kommer från klienten eller servern
Återskapa samma objekt på en annan klient, jämför sessionsvägen och samla sedan in serverbevis först efter att scope har visat var felet faktiskt finns.
Så konfigurerar du Plex-cache och tillfällig lagring för omkodning
Skydda beständigt Plex-tillstånd genom att placera temporära transkodningsfiler på lämplig lokal lagring och verifiera rensning, ledigt utrymme samt omstartsfunktionssätt.
