Come configurare Collabora Online dietro Nginx

Cosa dovrebbe fare un proxy inverso funzionante

Una corretta implementazione di Collabora Online dietro Nginx fornisce agli utenti un indirizzo HTTPS pubblico per l'editor, mantenendo al contempo il servizio Collabora su una rete privata. L'editor dovrebbe caricare le risorse del browser, rilevare le funzionalità di Office, aprire un documento tramite la piattaforma di archiviazione connessa e mantenere attiva la connessione WebSocket durante la modifica. Un semplice controllo della sintassi di Nginx non garantisce il corretto funzionamento di questi percorsi.

Questo esempio presuppone che un server Collabora o un container CODE autonomo sia in ascolto sulla porta 9980, che Nginx gestisca office.example.come che la connessione TLS termini su Nginx. Sostituisci il nome host e i percorsi del certificato con i tuoi. L'indirizzo del backend 127.0.0.1:9980si applica solo quando Nginx e Collabora condividono un host e il servizio è associato all'interfaccia di loopback. Per container separati, utilizza il nome del servizio Collabora su una rete Docker privata, ad esempio http://collabora:9980.

Prima di modificare Nginx

Verifica che il nome DNS pubblico si risolva nel proxy, che il certificato TLS copra esattamente quel nome e che Nginx possa raggiungere Collabora sul suo indirizzo interno. Se utilizzi Docker, collega entrambi i servizi a una rete definita dall'utente e non pubblicare la porta di Collabora. Se Nginx è in esecuzione sull'host, associa la porta del container all'interfaccia di loopback, ad esempio 127.0.0.1:9980:9980. Il tuo firewall dovrebbe esporre le porte web pubbliche che intendi servire, non la porta del backend di Collabora.

Scegliete una configurazione TLS. La configurazione seguente utilizza TLS dal browser a Nginx e HTTP semplice su un hop privato affidabile verso Collabora. Questa è la terminazione TLS. Se la policy richiede la crittografia anche tra il proxy e Collabora, utilizzate HTTPS per il flusso in entrata e configurate Nginx in modo che consideri attendibile il certificato del backend. Non cambiate solo lo proxy_passschema: le impostazioni TLS lato server devono corrispondere a quelle del listener Collabora. Collabora documenta entrambe le configurazioni proxy nella sua guida per il reverse proxy Nginx e nel manuale dell'SDK 25.04 .

Imposta le opzioni TLS di Collabora che tengono conto del proxy.

Per la terminazione TLS, configura il servizio di Collabora coolwsdcon ssl.enable=falsee ssl.termination=true. Il modo in cui imposti questi valori dipende da come è stato installato Collabora: modifica la coolwsd.xmlconfigurazione supportata o utilizza le opzioni documentate per il tuo pacchetto o container. Con l'immagine Docker CODE, le distribuzioni in genere passano le opzioni come extra_params; controlla la documentazione dell'immagine per la tua versione e racchiudi correttamente gli argomenti tra virgolette in Compose. Riavvia o ricrea il servizio Collabora dopo averne modificato la configurazione.

Queste impostazioni indicano a Collabora che la connessione esterna è protetta dal proxy, anche se il passaggio dal proxy al backend utilizza HTTP. Non installano un certificato pubblico, non configurano il DNS né autorizzano un server di archiviazione a utilizzare Collabora. Configurare separatamente l'elenco degli host consentiti WOPI o le impostazioni di integrazione in base alla piattaforma di archiviazione in uso.

Configura Nginx per inoltrare le route dell'editor

Nginx deve passare le risorse di discovery e del browser e preservare l'aggiornamento WebSocket utilizzato dalla modifica interattiva. Di seguito è riportato un esempio a server singolo. Definire nel contesto mapNginx http, ad esempio nel file principale nginx.conf, non all'interno dell'host virtuale:

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

Inserisci il blocco server nella configurazione del sito inclusa da Nginx. Questo presuppone che i certificati TLS siano già installati e che la connessione dal proxy a Collabora sia HTTP:

server {
    listen 443 ssl;
    server_name office.example.com;

    ssl_certificate     /etc/letsencrypt/live/office.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/office.example.com/privkey.pem;

    location ^~ /browser {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
    }

    location ^~ /hosting/discovery {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
    }

    location ^~ /hosting/capabilities {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
    }

    location ~ ^/cool/(.*)/ws$ {
        proxy_pass http://127.0.0.1:9980;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;
        proxy_read_timeout 36000s;
        proxy_buffering off;
    }

    location ~ ^/(c|l)ool {
        proxy_pass http://127.0.0.1:9980;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;
        proxy_read_timeout 36000s;
    }
}

I percorsi che iniziano con /cooltrasportano le richieste WebSocket e dell'editor principali; il modello include anche /loolpercorsi legacy per compatibilità. Il proxy WebSocket di Nginx richiede le intestazioni di aggiornamento HTTP/1.1 perché Upgradee Connectionsono intestazioni hop-by-hop. Il timeout di lettura lungo aiuta a evitare di chiudere una connessione di modifica altrimenti attiva a causa di un normale timeout proxy breve. Consultare la documentazione del proxy WebSocket di Nginx e il riferimento al modulo proxy .

Per HTTPS sul server upstream, modificare gli URL del backend https://e configurare di conseguenza la verifica del certificato upstream di Nginx e la catena di certificati attendibili. Evitare di disabilitare la verifica del certificato come soluzione temporanea permanente. Se Nginx si trova in un altro container, sostituire l'indirizzo di loopback con il nome del servizio Collabora; 127.0.0.1all'interno del container proxy punta a tale container proxy.

Quando si utilizza un prefisso URI, ad esempio, /collabora/anziché un nome host dedicato, la configurazione e gli URL di rilevamento generati da Collabora richiedono una gestione aggiuntiva del percorso. Iniziate con un nome host dedicato, a meno che la vostra piattaforma non supporti esplicitamente una distribuzione con sottopercorsi. Un blocco server che inoltra le richieste alla radice non fa funzionare automaticamente gli URL generati dal rilevamento con un prefisso.

Ricarica e verifica ogni livello

Prima di applicare la configurazione di Nginx, verificala e poi riavvia il servizio:

sudo nginx -t
sudo systemctl reload nginx

Se il controllo della sintassi fallisce, correggi prima il file e la riga segnalati. Un ricaricamento riuscito conferma che Nginx ha accettato la configurazione, non che il backend, il certificato o il percorso WebSocket funzionino. Verifica separatamente la validità del DNS e del certificato, quindi richiedi i due endpoint di Collabora tramite l'hostname pubblico:

curl -fsS https://office.example.com/hosting/discovery | head
curl -fsS https://office.example.com/hosting/capabilities

L'endpoint di rilevamento dovrebbe restituire un file XML anziché una pagina 404 di Nginx o una pagina di login; le funzionalità dovrebbero restituire una risposta da Collabora. Esamina gli URL dell'editor XML di rilevamento: dovrebbero utilizzare il nome host HTTPS pubblico e i percorsi raggiungibili, non il nome di un container o un indirizzo interno. L'immagine di esempio qui sotto mostra i tipi di risposte da cercare; i valori visualizzati sono a scopo illustrativo e non rappresentano l'output di un server reale.

Infine, configura la tua piattaforma di documenti in modo che venga utilizzata https://office.example.comcome server Collabora e apri un documento di prova. Un utile indicatore di successo è che l'editor si carichi e rimanga reattivo durante la digitazione, il salvataggio e la riapertura del documento. Negli strumenti per sviluppatori del browser, la richiesta WebSocket /cool/dovrebbe aggiornarsi correttamente; lo stato HTTP 101 Switching Protocolsè il risultato previsto dell'handshake WebSocket. Non considerare lo stato di esempio mostrato come prova che il tuo server abbia superato questo controllo.

Analizzare i fallimenti in base ai loro sintomi.

• 502 Bad Gateway: Nginx non riesce a raggiungere il server upstream. Verificare il nome del servizio, la porta, la rete del container, il listener e i log. Se i container sono separati, non utilizzare l'indirizzo di loopback del container proxy.
• Errore 404 durante la fase di discovery o per le risorse del browser: verificare che la richiesta raggiunga l'host virtuale corretto e che la posizione inoltri il percorso senza una riscrittura URI involontaria. Testare l'URL pubblico, non solo l'URL di backend.
• L'editor si carica ma si blocca o si disconnette: esaminare la /cool/.../wsrichiesta. La mancanza di intestazioni di aggiornamento, una connessione upstream HTTP/1.0, un timeout breve o un proxy che memorizza temporaneamente la connessione possono interrompere la modifica. Verificare che la richiesta venga aggiornata e che rimanga aperta mentre il documento è attivo.
• Host WOPI non autorizzato: il proxy potrebbe funzionare correttamente, ma Collabora potrebbe rifiutare la piattaforma di archiviazione. Verifica il nome host WOPI effettivo confrontandolo con l'elenco degli host consentiti di Collabora e con la configurazione del connettore della piattaforma. Non risolvere il problema aprendo il backend a Internet.
• Avviso relativo a contenuti misti o certificati: assicurati che l'URL dell'editor pubblico e gli URL di discovery utilizzino HTTPS e che il certificato corrisponda al nome host. Se termini TLS su Nginx, verifica anche l'impostazione di terminazione di Collabora.

Una volta superati questi controlli, mantieni privato il backend di Collabora e monitora i log di Nginx e Collabora durante l'aggiornamento di uno dei due componenti. Questo esempio con un singolo upstream non configura l'alta disponibilità, il bilanciamento del carico o l'affinità di sessione per documento. Per più repliche di Collabora, segui le istruzioni di implementazione per il controller o il bilanciatore di carico di Collabora pertinente e verifica l'affinità dei documenti prima di instradare il traffico di produzione.

Fonti e note di versione

I dettagli di configurazione sono stati verificati il ​​6 ottobre 2026 confrontandoli con la documentazione proxy di Collabora, il manuale dell'SDK 25.04 e i riferimenti ai moduli WebSocket e proxy di Nginx. Le opzioni relative a pacchetti e container possono variare a seconda della versione di Collabora; prima di applicarle, verificare i nomi delle impostazioni per la versione in uso. L'articolo non presuppone una piattaforma di archiviazione specifica né dimostra un'implementazione in ambiente di produzione.