Cosa controllare quando un’app self-hosted si apre localmente, ma la sua API non è raggiungibile?
L’apertura locale di una pagina non dimostra che il relativo percorso API funzioni; l’interfaccia del browser e la richiesta al backend possono utilizzare host, porte, protocolli o credenziali diversi.
Su un server domestico, l’HTML e le risorse statiche possono essere caricati da un proxy inverso, dalla cache del browser o da un container web locale, mentre le chiamate API viaggiano verso un altro servizio, un sottopercorso, un endpoint WebSocket o un URL di base configurato esternamente. Inizia acquisendo una richiesta non riuscita nel browser, riproponila dal confine di rete pertinente e poi distingui routing, TLS, autenticazione, criteri del browser e configurazione dell’applicazione, invece di considerare la pagina visibile come prova che l’intero stack sia raggiungibile.
Dimostra se la pagina e l’API usano lo stesso percorso di rete
Apri gli strumenti per sviluppatori del browser e ricarica l’azione che non funziona. Registra l’URL della richiesta, il metodo, lo stato, il corpo della risposta, l’indirizzo remoto, l’iniziatore e se l’errore riguarda una normale richiesta HTTP, un WebSocket, un evento inviato dal server o un fetch in background.
Un caso di Baserow self-hosted mostrava un’interfaccia utilizzabile che segnalava ripetutamente la riconnessione perché il canale degli eventi seguiva un percorso proxy diverso. Il sintomo visibile era una connessione agli eventi non riuscita, non un guasto completo del server web.
Confronta carattere per carattere la richiesta del documento riuscita con quella API non riuscita: schema, nome host, porta, prefisso del percorso e stringa di query. Se differiscono, indaga il primo livello che cambia. Se sono identiche, prosegui con intestazioni, cookie, gestione della risposta e routing del backend.
Ripeti la richiesta esatta da ogni confine pertinente
Copia una richiesta non riuscita come comando e ripetila dal client, dall’host del proxy inverso e da un container temporaneo collegato alla rete dell’applicazione. Mantieni il metodo, l’intestazione di autorizzazione, il tipo di contenuto, il corpo e il nome host previsto.
Un’API può essere raggiungibile ai livelli TCP e HTTP, ma rifiutare la richiesta reale perché manca un token o un’intestazione. Una discussione sull’API di FreshRSS ha ricondotto un errore esterno al contesto di autorizzazione mancante, anziché a un problema generale di raggiungibilità del container.
Interpreta il primo confine in cui si verifica l’errore. Un errore DNS indica un problema di risoluzione del nome; il rifiuto della connessione indica il listener, la porta o la rete; un errore TLS indica l’identità o l’attendibilità; i codici 401 o 403 indicano autenticazione o criteri; il codice 404 spesso indica routing o riscrittura del sottopercorso; e una chiamata diretta riuscita con una chiamata dal browser non riuscita sposta la diagnosi verso le regole del proxy o del browser.
Controlla l’URL di base dell’API, la porta e il sottopercorso
Esamina l’URL pubblico dell’applicazione, l’URL dell’API, l’URL WebSocket, il percorso di base e le variabili definite durante la compilazione del frontend. Un’interfaccia servita localmente può contenere un indirizzo API assoluto che punta a un vecchio dominio, a un IP privato, alla porta sbagliata o al percorso radice esistente solo sul server.
Le distribuzioni su sottopercorso sono particolarmente sensibili alla gestione delle barre e alle regole di riscrittura. Un caso di proxy inverso per Frigate ha ricondotto le risorse non riuscite al comportamento di riscrittura del sottopercorso, anche se era possibile raggiungere l’interfaccia principale.
Prova l’endpoint API sia con il prefisso configurato sia senza, solo per identificare il percorso corretto, quindi modifica applicazione e proxy affinché concordino su un unico percorso canonico. Non mantenere eccezioni di riscrittura duplicate che fanno funzionare alcuni metodi mentre upload, callback o endpoint di streaming continuano a bypassare il backend previsto.
Verifica le intestazioni del proxy inverso, TLS e il supporto allo streaming
Confronta il percorso del proxy per le pagine normali con quello per le richieste API, WebSocket e streaming. Conferma il nome del servizio upstream, la porta interna, la versione HTTP, il comportamento dell’upgrade della connessione, il timeout di lettura, i criteri di buffering e le intestazioni inoltrate relative a host e protocollo.
Gli utenti di Open WebUI hanno segnalato un’interfaccia apparentemente funzionante mentre l’output API inoltrato dal proxy si bloccava perché il comportamento di buffering o streaming differiva da quello dell’accesso diretto. L’attenzione diagnostica deve concentrarsi sul percorso di streaming inoltrato dal proxy, non sulla pagina statica.
Invia al backend il nome host e lo schema originali tramite intestazioni di proxy fidato configurate in modo restrittivo. Abilita gli upgrade WebSocket solo sui percorsi che ne hanno bisogno, disabilita il buffering inappropriato per gli endpoint di streaming e verifica che il proxy utilizzi il listener interno dell’applicazione, invece della porta host pubblicata per errore.
Distingui i criteri del browser dalla raggiungibilità del server
Quando un comando diretto ha esito positivo ma il browser non funziona, controlla nella console del browser gli errori relativi a CORS, contenuti misti, certificati, cookie e richieste preliminari. Il server può rispondere correttamente mentre il browser rifiuta di esporre o inviare la richiesta.
Una discussione su Open WebUI tramite proxy inverso collega i problemi di WebSocket e API alla gestione dell’origine e del protocollo inoltrato, mostrando perché identità dell’origine e del protocollo debbano rimanere coerenti attraverso il proxy.
Verifica che una pagina HTTPS non chiami mai un’API HTTP, che l’API consenta solo l’origine necessaria, che le richieste preliminari raggiungano lo stesso percorso e che i cookie di sessione utilizzino dominio, percorso, attributi Secure e SameSite corretti. Evita di disabilitare globalmente le protezioni del browser; correggi invece l’identità pubblica e i criteri del server.
Convalida l’intero flusso API da ogni rete necessaria
Dopo aver fatto funzionare la prima richiesta non riuscita, testa accesso, elenco o ricerca, creazione o aggiornamento, upload, download, eventi in background e un aggiornamento del token dalla LAN e da ogni percorso remoto supportato. Una singola GET riuscita non dimostra che le scritture autenticate o le connessioni di lunga durata siano state ripristinate.
Il flusso ZimaSpace per separare la raggiungibilità tramite IP dal routing del dominio è il passaggio successivo quando le chiamate API dirette funzionano tramite indirizzo ma falliscono attraverso il nome host pubblico.
Il problema è risolto solo quando browser e client non browser utilizzano l’endpoint canonico previsto, il proxy raggiunge il backend corretto, l’autenticazione sopravvive ai reindirizzamenti, i criteri del browser accettano la risposta e le sessioni di streaming o WebSocket rimangono stabili. Conserva la richiesta non riuscita acquisita come test di regressione per i futuri aggiornamenti.
Prodotti consigliati
Supporto e consigli
Altro da leggere
Plex può condividere una GPU con un altro container Docker?
Plex e un altro container possono spesso accedere alla stessa GPU, ma è necessario testare il supporto dei driver, la mappatura dei dispositivi, il...
Come capire se un errore di Plex proviene dal client o dal server
Riproduci lo stesso elemento su un altro client, confronta il percorso della sessione, quindi raccogli le prove dal server solo dopo che l’ambito ti...
Come configurare la cache di Plex e l’archiviazione temporanea per la transcodifica
Proteggi lo stato persistente di Plex collocando i file temporanei di transcodifica su un’unità locale adatta, quindi verifica la pulizia, lo spazio libero e...
