Il fatto che una pagina si apra in locale non dimostra che il relativo percorso API funzioni; l'interfaccia del browser e la richiesta al backend potrebbero usare host, porte, protocolli o credenziali diversi.
Su un home server, l'HTML e le risorse statiche possono essere caricati da un reverse proxy, dalla cache del browser o da un container web locale, mentre le chiamate API passano da un altro servizio, un sottopercorso, un endpoint WebSocket o un URL di base configurato esternamente. Inizia acquisendo nel browser una richiesta non riuscita, inviala di nuovo dal punto di rete pertinente, quindi analizza separatamente l'instradamento, TLS, l'autenticazione, le policy del browser e la configurazione dell'applicazione, senza considerare la pagina visibile come prova della raggiungibilità dell'intero stack.
Verifica 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 riesce. Registra l'URL della richiesta, il metodo, lo stato, il corpo della risposta, l'indirizzo remoto, l'iniziatore e se si tratta di una normale richiesta HTTP, di un WebSocket, di un evento inviato dal server o di un recupero in background.
Un caso di Baserow self-hosted ha mostrato un'interfaccia utilizzabile che segnalava ripetutamente la riconnessione perché il canale eventi del browser seguiva un percorso del proxy diverso. Il sintomo visibile era una connessione agli eventi non riuscita, non un'interruzione completa del server web.
Confronta carattere per carattere la richiesta del documento che riesce con la richiesta API non riuscita: schema, nome host, porta, prefisso del percorso e stringa di query. Se differiscono, esamina il primo livello in cui rilevi una modifica. Se sono identiche, passa alle intestazioni, ai cookie, alla gestione della risposta e all'instradamento del backend.
Invia di nuovo la richiesta esatta da ogni punto di rete rilevante
Copia una richiesta non riuscita sotto forma di comando e inviala di nuovo dal client, dall'host del reverse proxy e da un container temporaneo collegato alla rete dell'applicazione. Mantieni invariati il metodo, l'intestazione di autorizzazione, il tipo di contenuto, il corpo e il nome host previsto.
Un'API può essere raggiungibile a livello TCP e HTTP, ma rifiutare la richiesta effettiva perché manca un token o un'intestazione. Una discussione sull'API di FreshRSS ha ricondotto un problema esterno a un contesto di autorizzazione mancante, anziché a un problema generale di raggiungibilità del container.
Individua il primo punto in cui si verifica il problema. Un errore DNS indica un problema di risoluzione dei nomi; il rifiuto della connessione indica un problema di listener, porta o rete; un errore TLS indica un problema di identità o attendibilità; un errore 401 o 403 indica un problema di autenticazione o policy; un errore 404 indica spesso un problema di instradamento o riscrittura del sottopercorso; una chiamata diretta riuscita ma una chiamata dal browser non riuscita sposta l’analisi verso le regole del proxy o del browser.
Controlla l’URL di base, la porta e il sottopercorso dell’API
Esamina l’URL pubblico dell’applicazione, l’URL API, l’URL WebSocket, il percorso base e le variabili di compilazione del frontend. Un’interfaccia servita localmente potrebbe contenere un indirizzo API assoluto che punta a un vecchio dominio, a un IP privato, a una porta errata o a un percorso radice disponibile solo sul server.
Le installazioni su sottopercorso sono particolarmente sensibili alla gestione delle barre e alle regole di riscrittura. Un caso di reverse proxy di Frigate ha ricondotto il mancato caricamento delle risorse al comportamento delle riscritture del sottopercorso, anche se era possibile raggiungere l’interfaccia principale.
Prova l’endpoint API sia con sia senza il prefisso configurato, solo per identificare il percorso corretto, poi fai in modo che applicazione e proxy concordino su un unico percorso canonico. Non mantenere eccezioni di riscrittura duplicate che consentono il funzionamento di alcuni metodi mentre upload, callback o endpoint di streaming continuano a ignorare il backend previsto.
Verifica le intestazioni del reverse proxy, TLS e il supporto allo streaming
Confronta il percorso del proxy per le pagine ordinarie con quello per le richieste API, WebSocket e di streaming. Verifica il nome del servizio upstream, la porta interna, la versione HTTP, il comportamento di upgrade della connessione, il timeout di lettura, la policy di buffering e le intestazioni inoltrate relative all’host e al protocollo.
Gli utenti di Open WebUI hanno segnalato un’interfaccia apparentemente funzionante, mentre le risposte API si bloccavano dietro il proxy a causa di differenze nel buffering o nello streaming rispetto all’accesso diretto. L’analisi diagnostica si concentra sul percorso di streaming tramite proxy, non sulla pagina statica.
Inoltra al backend il nome host e lo schema originali tramite intestazioni proxy attendibili configurate in modo restrittivo. Abilita gli upgrade WebSocket solo sui percorsi che ne hanno bisogno, disattiva il buffering non appropriato per gli endpoint di streaming e verifica che il proxy usi il listener interno dell’applicazione, anziché la porta host pubblicata per errore.
Distingui le policy del browser dalla raggiungibilità del server
Quando un comando diretto riesce ma il browser non funziona, controlla nella console del browser gli errori CORS, di contenuto misto, del certificato, dei cookie e di preflight. Il server potrebbe rispondere correttamente, mentre il browser rifiuta di esporre o inviare la richiesta.
Una discussione su Open WebUI con reverse proxy collega i problemi di WebSocket e API alla gestione dell’origine e del protocollo inoltrato, mostrando perché l’identità dell’origine e del protocollo deve rimanere coerente attraverso il proxy.
Verifica che una pagina HTTPS non chiami mai un’API HTTP, che l’API consenta solo l’origine richiesta, che le richieste di preflight raggiungano lo stesso percorso e che i cookie di sessione usino gli attributi Domain, Path, Secure e SameSite corretti. Evita di disattivare globalmente le protezioni del browser; correggi invece l’identità pubblica e la policy del server.
Convalida l’intero flusso di lavoro API da ogni rete richiesta
Dopo aver risolto il primo errore di richiesta, prova l’accesso, gli elenchi o la ricerca, la creazione o l’aggiornamento, il caricamento, il download, gli eventi in background e un aggiornamento del token dalla LAN e da ogni percorso remoto supportato. Un singolo GET riuscito non dimostra che le richieste di scrittura autenticate o le connessioni di lunga durata funzionino correttamente.
Quando le chiamate API dirette funzionano tramite indirizzo ma non tramite il nome host pubblico, il passaggio successivo è il flusso di lavoro di ZimaSpace per distinguere la raggiungibilità dell’IP dall’instradamento del dominio.
Il problema si risolve solo quando il browser e il client non-browser usano l’endpoint canonico previsto, il proxy raggiunge il backend corretto, l’autenticazione viene mantenuta durante i reindirizzamenti, le policy del browser accettano la risposta e le sessioni in streaming o WebSocket restano stabili. Conserva la richiesta acquisita che ha generato l’errore come test di regressione per gli aggiornamenti futuri.
Assistenza e consigli
Altre letture

Come tenere nascosti i video per adulti sul tuo NAS ai tuoi familiari
Tieni privati i video per adulti su un NAS familiare. Controlla le autorizzazioni delle cartelle, l’accesso alle librerie di Plex e Jellyfin, le miniature,...

Cosa controllare prima di caricare un modello della community in Transformers
Usa l’aggiornamento della sandbox Jinja di Transformers per esaminare la provenienza dei modelli, i template di chat, il codice remoto, i pesi serializzati e...

Esegui Mirage in locale: OCR e rilevamento degli oggetti da una sola immagine
Prova il piccolo modello di visione locale di Cactus Compute, verifica l’OCR e l’estrazione degli oggetti con input reali e comprendi i limiti di...



