Esegui Collabora CODE dietro Nginx con terminazione TLS

I documenti potrebbero bloccarsi dopo aver messo Collabora CODE dietro HTTPS perché il proxy e CODE non concordano su dove termina TLS oppure il proxy blocca il traffico WebSocket. Configura Nginx per presentare il certificato pubblico, inoltrare a un listener privato di CODE e passare le route WebSocket. Le impostazioni di CODE sono ssl.enable=falsee ssl.termination=true.

Questo esempio utilizza Nginx sull'host Docker. Per un proxy in un altro container, utilizzare invece la rete privata di Docker. Consultare le impostazioni del proxy di Collabora e la guida all'immagine Docker di CODE per le opzioni specifiche della versione.

Comprendere cosa comporta la terminazione SSL

La terminazione TLS significa che Nginx gestisce la connessione HTTPS e il certificato del browser, mentre CODE utilizza HTTP sulla porta 9980. Mantieni privato questo listener: associalo all'interfaccia di loopback su un singolo host oppure utilizza una rete Docker privata. Se il traffico dal proxy a CODE attraversa una rete non attendibile, proteggi tale collegamento con TLS o un tunnel.

Preparare il contenitore e il certificato

1. Scegli il nome host pubblico. Crea un record DNS che office.example.compunti al proxy Nginx. Ottieni un certificato per quel nome host specifico e installa la relativa catena di certificati e la chiave privata sul proxy.
2. Mantieni privata la porta di CODE. Per Nginx installato direttamente sull'host Docker, pubblica la porta del container solo sull'interfaccia di loopback. In Compose, la mappatura pertinente è 127.0.0.1:9980:9980. Non pubblicare 9980:9980su ogni interfaccia dell'host a meno che un firewall e la configurazione di rete non lo impediscano esplicitamente.
3. Imposta la modalità TLS di CODE. Nel servizio Compose, aggiungi le due opzioni alla configurazione di CODE. L'esempio seguente utilizza una variabile immagine in modo da poter aggiungere ai preferiti il ​​tag esatto che hai esaminato e testato.

services:
  collabora:
    image: ${COLLABORA_CODE_IMAGE}
    restart: unless-stopped
    ports:
      - "127.0.0.1:9980:9980"
    environment:
      extra_params: "--o:ssl.enable=false --o:ssl.termination=true"

Imposta COLLABORA_CODE_IMAGEun tag immagine testato e bloccato. Mantieni la lista host consentita WOPI e le impostazioni di autenticazione; la terminazione TLS non le sostituisce. Se Nginx è un altro servizio Docker, ometti la mappatura della porta host e configura il proxy http://collabora:9980sulla rete privata condivisa.

Configura Nginx per terminare il traffico TLS e instradare il traffico CODE tramite proxy.

4. Aggiungi l'host virtuale HTTPS. Inserisci i seguenti percorsi all'interno del blocco server Nginx per l'hostname pubblico di Collabora. Sostituisci l'hostname di esempio e i percorsi del certificato. Questa configurazione è per un URL di Collabora a livello radice, non per un URL montato al di sotto di un percorso come /office/.

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 $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
    location ^~ /hosting/discovery {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
    location ^~ /hosting/capabilities {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    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 "Upgrade";
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 36000s;
    }
    location ^~ /cool/adminws {
        proxy_pass http://127.0.0.1:9980;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 36000s;
    }
    location ~ ^/(c|l)ool {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Inoltra le route relative alle risorse, al rilevamento e alle funzionalità dell'editor. Le posizioni /cool/.../wse /cool/adminwsrichiedono le intestazioni HTTP/1.1 e Upgrade affinché Nginx possa incapsulare i WebSocket; un timeout di lettura lungo mantiene aperte le sessioni di modifica. Consulta la documentazione di Nginx sul proxying WebSocket .

Applica la modifica e verifica il comportamento dipendente dalla versione.

5. Convalida Nginx prima di ricaricarlo. Esegui nginx -t. Continua solo se Nginx segnala che il test di configurazione è andato a buon fine; quindi ricarica Nginx con il normale comando di servizio del tuo sistema.
6. Ricrea il container CODE. Applica la modifica Compose con docker compose up -d collabora. Controlla i log del container per eventuali errori di avvio e verifica che la configurazione attiva includa entrambe le opzioni SSL.

Per contestualizzare la versione, il repository di Collabora ha registrato una segnalazione il 22 luglio 2026 secondo cui il controllo di integrità integrato coolwsd --probein CODE 26.04.2.2 e versioni successive potrebbe verificare HTTPS sulla porta 9980 anche quando TLS termina al proxy. Questo può contrassegnare un container come non integro mentre l'endpoint pubblico risponde. Esamina la segnalazione del problema per il tuo tag immagine ; testa l'endpoint pubblico e una sessione di modifica prima di considerare il solo stato di integrità come prova di un errore TLS. Mantieni i controlli di integrità a meno che non vengano sostituiti da un altro sistema di monitoraggio.

Verifica il rilevamento HTTPS e una sessione di modifica effettiva.

Effettua la richiesta https://office.example.com/hosting/discoverytramite browser o con curl. Dovrebbe restituire un XML di rilevamento WOPI su HTTPS, con URL che utilizzano il nome host HTTPS pubblico. Un avviso relativo al certificato suggerisce un problema con il nome host o il certificato; gli URL HTTP suggeriscono una mancata corrispondenza tra la modalità TLS o lo schema di inoltro; un errore 502 suggerisce che il proxy non può raggiungere CODE.

Successivamente, apri un documento di prova dall'host WOPI connesso e verifica che la modifica funzioni. Negli strumenti per sviluppatori del browser, la /cool/.../wsrichiesta dovrebbe stabilire una connessione WebSocket. Se il rilevamento funziona ma la modifica si blocca, controlla le posizioni e le intestazioni WebSocket. Verifica che l'integrazione consenta l'host WOPI e punti a https://office.example.com.

Configurazione riuscita: il certificato è considerato attendibile, il rilevamento utilizza HTTPS, la porta 9980 rimane privata e un documento di prova si apre e può essere modificato tramite WebSocket.