Questa applicazione self-hosted funzionerà dietro un reverse proxy? Una checklist di compatibilità
Il fatto che un'applicazione Docker sia raggiungibile su una porta non dimostra che si comporterà correttamente su un dominio HTTPS pubblico. Usa questa checklist basata su evidenze per verificare URL canonici, header inoltrati, cookie, upload, connessioni in tempo reale e callback prima del lancio.
Perché la compatibilità con il reverse proxy è un criterio per la scelta dell'applicazione
Un reverse proxy si colloca tra un visitatore e un'applicazione. Può instradare un dominio pubblico verso un servizio interno e terminare TLS, quindi l'applicazione non deve necessariamente essere in ascolto direttamente su Internet. Questo schema infrastrutturale è comune, ma non garantisce che ogni applicazione self-hosted funzioni correttamente dietro di esso.
La domanda importante non è soltanto se il container si avvia o se la sua porta interna risponde a una richiesta. L'applicazione deve comprendere l'indirizzo pubblico visualizzato dagli utenti, lo schema HTTPS originale e, ove pertinente, l'indirizzo del client di origine. Deve inoltre funzionare con i limiti e il comportamento delle connessioni del proxy per le funzionalità che il tuo team intende utilizzare.
Considera la compatibilità con il reverse proxy come un criterio di selezione e accettazione. Prima di impegnarti su un'applicazione, consulta la documentazione ufficiale di distribuzione e cerca indicazioni esplicite su impostazioni dell'URL esterno, reverse proxy, proxy attendibili, header inoltrati, upload, connessioni in tempo reale e autenticazione esterna. Quando la documentazione non ne parla, registra l'incertezza e verifica il flusso di lavoro esatto di cui hai bisogno.
- Non equiparare “funziona in Docker” a “è pronta per un dominio HTTPS pubblico”.
- Preferisci un'applicazione con una configurazione documentata per l'URL esterno o canonico.
- Richiedi evidenze da una distribuzione di test, non soltanto un controllo di integrità del container riuscito.
- Per i test di accettazione usa solo il dominio pubblico e i normali percorsi utente; una porta interna diretta può nascondere difetti legati al proxy.
Mappa il percorso della richiesta prima di modificare le impostazioni
Annota il percorso completo di una richiesta normale: browser, nome DNS pubblico, reverse proxy, applicazione e qualsiasi servizio di supporto come database, servizio email, provider di identità, servizio di object storage o destinazione webhook. Questo trasforma un problema vago relativo al proxy in un insieme di confini verificabili.
Il proxy riceve la richiesta pubblica e invia una richiesta upstream all'applicazione. Durante questo processo, l'applicazione potrebbe non vedere più i dettagli della connessione originale, a meno che non sia progettata per utilizzare gli header della richiesta forniti dal proxy. Traefik, ad esempio, aggiunge automaticamente X-Forwarded-For, X-Real-Ip, X-Forwarded-Host, X-Forwarded-Port, X-Forwarded-Proto e X-Forwarded-Server quando inoltra le richieste.
Documenta inoltre quali porte sono intenzionalmente pubbliche. Docker afferma che le porte dei container non sono raggiungibili esternamente per impostazione predefinita; pubblicare una porta la rende disponibile al di fuori dell'host. Quando l'applicazione upstream e il proxy condividono un host, pubblicare solo su localhost può limitare l'accesso all'host Docker anziché esporre il servizio upstream da remoto.
- Hostname o hostname pubblici, incluso qualsiasi dominio alternativo.
- Schema esterno previsto: normalmente HTTPS per una distribuzione pubblica.
- Punti di ingresso del proxy per HTTP e HTTPS.
- Hostname e porta dell'upstream interno.
- Posizione del confine TLS.
- Qualsiasi proxy aggiuntivo, bilanciatore di carico, CDN, VPN o tunnel davanti al reverse proxy.
- Quali porte upstream devono restare private e quali devono essere raggiungibili pubblicamente.
Controllo 1: configura e verifica l'URL esterno canonico
Molte applicazioni richiedono un'impostazione esplicita per l'indirizzo dal quale gli utenti le raggiungono. La documentazione ufficiale può chiamarla URL di base, URL del sito, URL pubblico, URL esterno, URL del server, URL radice o in modo simile. Impostala sull'indirizzo HTTPS pubblico definitivo, incluso qualsiasi prefisso di percorso richiesto, anziché su un nome di container interno, un indirizzo IP privato o un URL HTTP.
Questa impostazione influenza comunemente i link nell'interfaccia, i link inviati via email, le destinazioni per la reimpostazione delle password, i payload dei webhook e la costruzione dei callback OAuth. Una discrepanza apparentemente minima può produrre reindirizzamenti verso un hostname interno, link HTTP da un sito HTTPS o un flusso di accesso che ritorna nella posizione errata.
Usa l'hostname definitivo prima di testare le integrazioni. Modificare un URL pubblico in seguito può richiedere cambiamenti nell'applicazione, nel provider di identità, nei fornitori di webhook e nei segnalibri. Se la documentazione ufficiale non spiega l'impostazione o se è supportato un sottopercorso, non presumere che sia sicuro distribuire l'applicazione sotto un percorso come example.com/app.
- Imposta l'URL canonico documentato sull'esatto URL HTTPS pubblico.
- Apri le pagine da una sessione del browser pulita e ispeziona i reindirizzamenti.
- Invia un'email di reimpostazione della password o di invito, se l'applicazione lo supporta, e verifica che il link utilizzi l'indirizzo pubblico.
- Crea un link di condivisione o una risorsa pubblica, ove applicabile, e aprilo da una sessione separata.
- Testa sia l'hostname semplice sia qualsiasi hostname alternativo previsto, quindi scegli un indirizzo canonico.
Controllo 2: definisci il confine dei proxy attendibili e degli header inoltrati
Un reverse proxy necessita di un modo per trasmettere informazioni sulla richiesta ricevuta. RFC 7239 definisce l'header standardizzato Forwarded per le informazioni modificate o perse nel passaggio attraverso i proxy, inclusi indirizzo sorgente, host e protocollo. Nella pratica, le applicazioni possono utilizzare anche gli header X-Forwarded-*. La documentazione dell'applicazione dovrebbe indicare quali header legge e come dichiarare i proxy attendibili.
La fiducia è l'aspetto critico. Un client non deve poter fornire un header che l'applicazione tratta come autorevole per identità del client, host o schema. RFC 7239 rileva che le conclusioni basate su dati inoltrati dipendono dalla fiducia nei proxy che li hanno aggiunti. Traefik può essere configurato per considerare attendibili i dati degli header inoltrati solo da indirizzi IP o CIDR specificati; la sua documentazione sconsiglia una modalità con fiducia sempre attiva in produzione.
Registra l'intervallo di indirizzi del proxy o il confine di rete che l'applicazione è configurata per considerare attendibile, se l'applicazione dispone di tale impostazione. Se esiste più di un livello proxy, determina quale livello rimuove, sovrascrive o conserva gli header inoltrati. Si tratta di una decisione di sicurezza, non solo di una comodità di instradamento.
- Trova la documentazione ufficiale dell'applicazione relativa a reverse proxy o proxy attendibili.
- Identifica se utilizza Forwarded, X-Forwarded-Proto, X-Forwarded-Host, X-Forwarded-For o altri header.
- Limita la fiducia negli header al confine proxy noto ovunque il componente pertinente lo supporti.
- Evita di esporre direttamente l'applicazione upstream insieme al proxy, salvo una necessità specifica e controllata.
- Testa una normale richiesta pubblica e conferma che l'applicazione riporti lo schema e l'host esterni previsti.
Controllo 4: verifica gli indirizzi IP client e gli eventi di audit
La gestione dell'indirizzo del client è importante quando un'applicazione mostra la cronologia degli accessi, scrive eventi di audit, applica controlli di accesso basati su IP, limita le richieste o prende decisioni di sicurezza in base a un indirizzo sorgente. Dietro un proxy, il peer immediato visibile all'applicazione può essere il proxy anziché il browser della persona.
Crea un test controllato con almeno due reti client distinte, ove pratico. Esegui un'azione che dovrebbe essere registrata, quindi esamina la visualizzazione di audit o i log dell'applicazione in base al comportamento documentato. L'obiettivo non è necessariamente esporre indirizzi IP grezzi a ogni amministratore; è assicurarsi che il contesto registrato dall'applicazione e qualsiasi controllo basato su IP si comportino come previsto dalla tua policy.
Se l'applicazione non documenta una gestione dell'indirizzo client consapevole del proxy, evita di presumere che i suoi record di attività identifichino la rete dell'utente di origine. Mantieni questa limitazione nel record di compatibilità e valuta se influisce sui requisiti di sicurezza, conformità o supporto.
- Identifica le funzionalità che dipendono dalle informazioni sull'indirizzo client.
- Verifica se i record di audit mostrano l'indirizzo del proxy o il contesto client previsto.
- Testa tramite il percorso pubblico qualsiasi funzionalità documentata di allowlist IP, blocklist, limitazione della frequenza o accesso sospetto.
- Conferma che vengano accettate solo informazioni di inoltro fornite da proxy attendibili.
- Decidi chi può accedere alle informazioni di audit e per quanto tempo devono essere conservate.
Controllo 5: testa upload, limiti delle richieste e richieste di lunga durata
Gli upload di grandi dimensioni e le richieste lente attraversano più di un confine. L'applicazione può imporre il proprio limite di dimensione, mentre il proxy può imporne un altro. Con il middleware di buffering di Traefik, una richiesta più grande di maxRequestBodyBytes non viene inoltrata al servizio e riceve HTTP 413. Un valore pari a zero significa illimitato, ma illimitato non è automaticamente la scelta operativa corretta.
Il buffering modifica il comportamento oltre ai limiti. Traefik documenta che, quando è collegato il suo middleware di buffering, legge l'intero corpo della richiesta prima di inoltrarlo e può memorizzare nel buffer su disco i corpi di grandi dimensioni in base alla soglia configurata. Valuta questo aspetto rispetto al tipo e alla dimensione dei file che gli utenti devono realmente inviare, anziché usare un piccolo file di esempio come unico test.
Le operazioni di lunga durata richiedono evidenze specifiche. Testa il flusso di lavoro visibile all'utente alla durata prevista e osserva eventuali errori a livello di browser, proxy e applicazione. Un piccolo upload riuscito non dimostra che un'importazione, un'esportazione o un'altra richiesta estesa di dimensioni rilevanti funzionerà in modo affidabile.
- Definisci il file o la richiesta normale più grande per il servizio, oltre a un caso di rifiuto leggermente più grande.
- Testa tramite il dominio pubblico un file vicino al limite previsto di accettazione.
- Conferma dove una richiesta sovradimensionata viene rifiutata, dal proxy o dall'applicazione, e se il messaggio è comprensibile.
- Esamina le implicazioni sul disco se i corpi delle richieste possono essere memorizzati nel buffer su disco.
- Testa end-to-end un'azione utente prevista di lunga durata.
- Registra insieme i limiti configurati e quelli osservati affinché modifiche future non creino regressioni accidentali.
Controllo 6: verifica end-to-end i requisiti in tempo reale e di streaming
Non presumere che ogni applicazione utilizzi WebSocket, Server-Sent Events, risposte in streaming o long polling nello stesso modo. Identifica prima la funzionalità effettiva che necessita di una connessione persistente o in streaming: notifiche live, modifica collaborativa, accesso al terminale, aggiornamenti della dashboard, chat o una risposta generata. Poi testa tale funzionalità attraverso il dominio pubblico definitivo.
Traefik documenta il supporto per WebSocket e WebSocket sicuri mediante il normale instradamento HTTP, inclusa la gestione automatica dell'upgrade e la conservazione degli header WebSocket come Origin, Sec-WebSocket-Key e Sec-WebSocket-Version. Questa capacità è utile, ma non elimina la necessità di testare i controlli di origine, l'autenticazione, la gestione della sessione e il comportamento di riconnessione propri dell'applicazione.
Per le funzioni di streaming e basate su eventi che non utilizzano WebSocket, consulta sia la documentazione dell'applicazione sia quella del proxy per il comportamento pertinente della connessione. Testa con lo stesso browser, hostname, configurazione HTTPS e autorizzazioni utente che avranno gli utenti in produzione.
- Identifica la specifica funzionalità in tempo reale richiesta dal tuo team.
- Testala dopo aver effettuato l'accesso tramite l'hostname HTTPS pubblico.
- Mantieni la funzionalità attiva abbastanza a lungo da osservare il normale comportamento di riconnessione o aggiornamento.
- Testa con più di una sessione del browser se la funzionalità implica aggiornamenti condivisi.
- Verifica che errori del browser, log dell'applicazione e log del proxy indichino lo stesso percorso di richiesta quando si verifica un errore.
- Non definire compatibile una funzionalità finché il suo effettivo flusso di lavoro utente non è stato superato.
Domande frequenti
Ogni applicazione Docker può funzionare dietro un reverse proxy?
No. La pubblicazione di una porta Docker può rendere raggiungibile un container, ma l'applicazione deve anche gestire correttamente il proprio URL pubblico, lo schema HTTPS, i dettagli delle richieste inoltrate, le sessioni e gli eventuali upload, callback o connessioni in tempo reale richiesti. Verifica questi comportamenti tramite la documentazione ufficiale dell'applicazione e una distribuzione di test sul percorso pubblico.
Perché un'applicazione reindirizza a HTTP o a un hostname interno dietro un proxy?
Questo indica comunemente che il suo URL esterno canonico è assente o errato, oppure che non utilizza correttamente le informazioni di un proxy attendibile sull'host e sullo schema HTTPS originali. Imposta l'URL pubblico documentato, configura il comportamento del proxy attendibile dove l'applicazione lo supporta e ripeti il test attraverso il dominio pubblico definitivo.
Quali header inoltrati devo controllare?
Controlla gli header documentati dall'applicazione. Traefik aggiunge automaticamente X-Forwarded-For, X-Real-Ip, X-Forwarded-Host, X-Forwarded-Port, X-Forwarded-Proto e X-Forwarded-Server quando inoltra le richieste. RFC 7239 definisce inoltre l'header standardizzato Forwarded. Considera attendibili tali informazioni solo se provengono da confini proxy noti.
Come devo testare la compatibilità degli upload?
Carica tramite l'indirizzo HTTPS pubblico un file realistico vicino al limite previsto in produzione, quindi testa un file più grande che dovrebbe essere rifiutato. Identifica se il rifiuto avviene a livello di proxy o applicazione. Se viene usato il buffering di Traefik, esamina l'impostazione della dimensione massima del corpo della richiesta e il suo comportamento di buffering su disco.
I WebSocket richiedono una configurazione speciale del proxy?
La risposta dipende dal proxy e dall'applicazione. Traefik documenta il supporto WebSocket tramite il normale instradamento HTTP con gestione automatica dell'upgrade. Tuttavia, testa l'esatta funzionalità dell'applicazione che necessita di comunicazione in tempo reale tramite il dominio definitivo, poiché autenticazione, convalida dell'origine, comportamento di riconnessione e requisiti dell'applicazione differiscono.
Perché gli URL di reindirizzamento OAuth devono essere testati dopo aver scelto il dominio definitivo?
OAuth 2.0 richiede che gli endpoint di reindirizzamento siano URI assoluti e i server di autorizzazione convalidano gli URI di reindirizzamento forniti rispetto ai valori registrati. Per i flussi con codice di autorizzazione, il redirect_uri utilizzato nella richiesta di token deve corrispondere a quello usato nella richiesta di autorizzazione, quando incluso. Registra e testa l'esatto URL di callback HTTPS pubblico.
Fonti e approfondimenti
- Port publishing and mapping — Docker
- EntryPoints Documentation — Traefik Labs
- Headers Documentation — Traefik Labs
- Buffering Documentation — Traefik Labs
- WebSocket User Guide — Traefik Labs
- Challenge Types — Internet Security Research Group / Let’s Encrypt
- RFC 7239: Forwarded HTTP Extension — RFC Editor / IETF
- RFC 6749: The OAuth 2.0 Authorization Framework — RFC Editor / IETF