Integra Collabora con Nginx senza compromettere i WebSocket.

Posiziona Collabora su un hostname HTTPS dedicato su Nginx, inoltra i percorsi dell'editor e del discovery a coolwsde passa esplicitamente le intestazioni di aggiornamento WebSocket sulle route del socket attivo. Per un singolo host, Nginx può terminare il TLS pubblico e inviare HTTP a Collabora su un'interfaccia privata; se Nginx e Collabora sono in esecuzione in container diversi, usa il nome del servizio Collabora sulla loro rete condivisa invece di 127.0.0.1.

Questo esempio presuppone che gli utenti aprano https://office.example.comil certificato e che Nginx lo gestisca. La porta di ascolto predefinita di Collabora è la 9980; utilizzare la porta raggiungibile nella propria implementazione. Un prefisso URL come https://example.com/collabora/richiede impostazioni coordinate di percorso e root del servizio, quindi questa configurazione di root-host non verrà applicata senza modifiche.

1. Definire la mappatura delle connessioni upstream e WebSocket

Nel httpcontesto di Nginx, aggiungi un nome upstream per Collabora e una mappa che imposti l'intestazione di connessione solo upgradequando un client richiede un WebSocket. Posiziona questo blocco al di fuori di qualsiasi altro serverblocco. Sostituisci l'indirizzo se Nginx raggiunge Collabora in un altro modo.

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

upstream coolwsd {
    server 127.0.0.1:9980;
}

Se Nginx è esso stesso un container, 127.0.0.1si riferisce a quel container Nginx, non al container Collabora. Su una rete Docker condivisa, l'upstream può invece essere server collabora:9980;, utilizzando il nome del servizio che si risolve in quella rete.

2. Aggiungere l'host virtuale HTTPS e le route di Collabora

All'interno del serverblocco HTTPS per office.example.com, inoltra le risorse del browser, gli endpoint di rilevamento, le connessioni WebSocket e i percorsi Collabora rimanenti. Le posizioni seguono le linee guida proxy di Collabora. Mantieni le posizioni socket specifiche al di sopra del percorso cool/ più ampio loolin modo che Nginx applichi correttamente le intestazioni WebSocket.

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

    ssl_certificate     /path/to/fullchain.pem;
    ssl_certificate_key /path/to/private-key.pem;

    location ^~ /browser {
        proxy_pass http://coolwsd;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $http_host;
    }

    location ^~ /hosting/discovery {
        proxy_pass http://coolwsd;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $http_host;
    }

    location ^~ /hosting/capabilities {
        proxy_pass http://coolwsd;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $http_host;
    }

    location ~ ^/cool/(.*)/ws$ {
        proxy_pass http://coolwsd;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 3600s;
    }

    location ^~ /cool/adminws {
        proxy_pass http://coolwsd;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 3600s;
    }

    location ~ ^/(c|l)ool {
        proxy_pass http://coolwsd;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Sostituisci i percorsi dei certificati con i file del tuo host. Se la tua installazione non utilizza la console di amministrazione, la /cool/adminwsposizione potrebbe non essere necessaria per la modifica dei documenti; il /cool/.../wspercorso principale è essenziale. Il proxy_read_timeoutvalore di un'ora è solo un esempio, non un requisito universale. Il timeout di lettura predefinito del proxy di Nginx è di 60 secondi tra letture successive. Scegli un valore superiore ai periodi di inattività necessari per le tue sessioni oppure affidati al traffico ping WebSocket appropriato, ove supportato.

3. Adattare la modalità TLS di Collabora al passaggio del proxy

Gli utenti devono poter accedere a Collabora tramite HTTPS, anche quando il collegamento privato tra Nginx e Collabora utilizza HTTP. In tale configurazione di terminazione TLS, è necessario coolwsdimpostare il proxy in modo che funga da terminatore TLS: SSL deve essere disabilitato sul listener interno e la terminazione SSL abilitata. Applicare queste impostazioni utilizzando il metodo supportato dal pacchetto o dall'immagine del container in uso, quindi riavviare/ricaricare Collabora come indicato nella relativa documentazione.

Utilizzare un upstream HTTP solo su una rete privata fidata e bloccare l'accesso pubblico alla porta 9980. Se la policy richiede la crittografia tra Nginx e Collabora, utilizzare un upstream HTTPS e configurare correttamente la verifica del certificato; non disabilitare la verifica per nascondere una mancata corrispondenza del certificato. La documentazione delle impostazioni proxy di Collabora distingue tra SSL sul proxy e SSL tra il proxy e Collabora coolwsd.

Imposta inoltre l'URL di Collabora nell'integrazione di archiviazione sul nome host HTTPS pubblico. Per Nextcloud, il relativo manuale di amministrazione richiede che il browser e entrambi i server siano in grado di comunicare tra loro tramite HTTP(S), con protocolli esterni corrispondenti. Limita la lista di indirizzi consentiti WOPI all'host di archiviazione e all'indirizzo di Collabora previsti; non allentarla eccessivamente per risolvere un errore di routing del proxy.

4. Testare la configurazione da entrambi i lati

Verifica la sintassi di Nginx prima di ricaricarlo:

sudo nginx -t
sudo systemctl reload nginx

Se Nginx è in esecuzione in un container, utilizzare la procedura di convalida e ricaricamento di tale container. Dall'host Nextcloud, testare gli endpoint pubblici di Collabora con il nome host effettivo:

curl -fsS https://office.example.com/hosting/discovery -o /dev/null
curl -fsS https://office.example.com/hosting/capabilities -o /dev/null

Apri anche quegli URL HTTPS da un browser utente. Questi verificano la raggiungibilità, ma una risposta di rilevamento positiva da sola non dimostra che la modifica del documento funzioni. Apri un documento e usa il pannello Rete del browser per verificare che le risorse vengano caricate e che la /cool/.../wsconnessione rimanga aperta. Un WebSocket HTTP/1.1 funzionante in genere mostra 101 Switching Protocols; la visualizzazione esatta può dipendere dal browser e dal protocollo di trasporto. Se questa configurazione standard funziona in Firefox ma non in Chromium, controlla il metodo e il protocollo della richiesta. Una segnalazione di bug di Collabora per la versione 25.04 documenta un WebSocket di Chromium su HTTP/2 che utilizza CONNECTe riceve un errore 405; risulta ancora aperto, come verificato il 9 ottobre 2026. Si tratta di una segnalazione specifica per la versione, non di un comportamento universale. Confronta le versioni di Collabora, Nginx e del browser prima di modificare le impostazioni HTTP/2. Vedi il problema 12155 di Collabora .

Se il rilevamento fallisce, controlla il registro degli errori di Nginx e verifica l'hostname, la porta e il protocollo del server upstream. Se il rilevamento funziona ma la modifica non riesce a connettersi, controlla il percorso WebSocket, le intestazioni, il timeout e i log di Collabora. Un errore di autorizzazione WOPI indica un problema con la lista di elementi consentiti dell'host di archiviazione. La guida alla risoluzione dei problemi di Nextcloud Office consiglia di verificare la raggiungibilità dal browser, da Nextcloud e da Collabora, quindi di esaminare i log di entrambi i server.

La guida al proxying di Nginx WebSocket spiega perché Upgradee Connectiondevono essere passati esplicitamente e perché il comportamento del timeout di inattività è importante. Consultare la documentazione del modulo proxy di Nginx per il comportamento della direttiva. Una volta superati i controlli, aprire, modificare, salvare e riaprire un documento di prova prima di invitare gli utenti a utilizzare il nuovo percorso.