Come configurare la terminazione SSL per un contenitore Collabora CODE

La terminazione SSL è particolarmente adatta a un container Collabora Online Development Edition (CODE) quando si desidera un endpoint HTTPS pubblico mantenendo la gestione dei certificati su un proxy inverso come Nginx. In questa configurazione, il browser si connette a Nginx tramite HTTPS, Nginx decifra il traffico e Collabora riceve traffico HTTP non crittografato sulla sua porta interna. L'obiettivo di qualità non è semplicemente "il caricamento della pagina". Un'implementazione di successo dovrebbe prevedere un certificato pubblico valido, un endpoint di rilevamento WOPI raggiungibile, aggiornamenti WebSocket funzionanti e una sessione di modifica documenti attiva e stabile.

La documentazione proxy di Collabora descrive questo schema di offload SSL come una connessione solo HTTP tra il proxy e Collabora, con ssl.enable=falsee ssl.termination=truesul lato Collabora. Consulta le impostazioni del reverse proxy di Collabora Online . Gli esempi seguenti utilizzano Nginx e Docker Compose, ma lo stesso risultato può essere ottenuto con altri reverse proxy purché mantengano il comportamento host e WebSocket richiesto.

Cosa dovrebbe ottenere una buona configurazione di terminazione SSL

Passaggio 1: Confermare il confine di rete prima di modificare la collaborazione

Decidi dove termina il TLS e quali host possono raggiungere la porta 9980. Se Nginx è in esecuzione sulla stessa macchina di Docker, associare la porta pubblicata a un parametro 127.0.0.1specifico è un modo semplice per impedire l'accesso diretto a Internet. La documentazione di Docker afferma che pubblicare una porta su un parametro specifico 127.0.0.1la mantiene locale all'host; consulta la documentazione di Docker sulla pubblicazione delle porte .

Se Nginx è in esecuzione in un altro container, una rete Docker privata condivisa è generalmente una soluzione più sicura rispetto alla pubblicazione della porta 9980. Il principio è lo stesso: i client devono utilizzare il nome host del reverse proxy HTTPS, non direttamente il container di Collabora.

Passaggio 2: Eseguire CODE in modalità di terminazione SSL

Per la terminazione TLS lato proxy, Collabora deve sapere che lo schema originale rivolto al client è HTTPS, anche se la sua connessione upstream immediata è HTTP. Le impostazioni documentate sono:

--o:ssl.enable=false --o:ssl.termination=true

Un esempio minimo di Compose è il seguente:

services:
  collabora:
    image: collabora/code:YOUR_TESTED_TAG
    restart: unless-stopped
    ports:
      - "127.0.0.1:9980:9980"
    environment:
      - "extra_params=--o:ssl.enable=false --o:ssl.termination=true"
      - "server_name=office.example.com"

Sostituisci YOUR_TESTED_TAGcon una versione che hai convalidato, invece di presumere automaticamente che latestsia sicura per un'implementazione simile a quella di produzione. Configura inoltre le impostazioni host o alias WOPI appropriate per la tua integrazione; questi valori dipendono dal fatto che tu stia connettendo Nextcloud, ownCloud, un altro host WOPI o un'integrazione personalizzata.

Dopo aver avviato il container, verificare che sia in esecuzione e che la mappatura delle porte corrisponda al limite di porte desiderato:

docker compose up -d
docker compose ps
docker logs --tail=100 collabora

Nota sulla versione per le distribuzioni 26.04

Non considerare i due flag SSL come unica variabile durante la risoluzione dei problemi di un'immagine 26.04 corrente. A metà del 2026, Collabora ha rilevato delle regressioni relative all'immagine Docker senza distro e alle configurazioni con SSL disabilitato. Un problema ufficiale su GitHub documenta una regressione all'avvio della versione 26.04 e un successivo riscontro della community di Collabora ha segnalato che il comportamento di terminazione SSL interessato funzionava di nuovo in un'immagine 26.04.2.4.1 successiva. Consultare il problema #16019 su CollaboraOnline/online se una configurazione di terminazione precedentemente funzionante smette di funzionare subito dopo un aggiornamento dell'immagine.

Questo è anche un motivo per bloccare e testare la versione della tua immagine. Un errore di configurazione e una regressione dell'immagine del container possono apparire simili da Nginx: entrambi possono manifestarsi come una risposta 502 o un errore di connessione upstream.

Passaggio 3: Configurare Nginx per terminare i percorsi TLS e Proxy Collabora

Nginx necessita di un certificato valido per l'hostname di Collabora e deve inoltrare gli endpoint HTTP di Collabora, oltre al traffico WebSocket. La guida al proxy di Collabora mostra le posizioni dedicate per le risorse del browser, il rilevamento, le funzionalità, le connessioni WebSocket principali, i percorsi di download/upload e il WebSocket di amministrazione. La seguente configurazione segue tale struttura, aggiungendo le intestazioni di inoltro comuni:

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;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    location ^~ /hosting/discovery {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
    }

    location ^~ /hosting/capabilities {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
    }

    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 $host;
        proxy_set_header X-Forwarded-Proto https;
        proxy_read_timeout 36000s;
    }

    location ~ ^/(c|l)ool {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
    }

    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 $host;
        proxy_set_header X-Forwarded-Proto https;
        proxy_read_timeout 36000s;
    }
}

Le intestazioni WebSocket non sono puramente estetiche. La documentazione ufficiale di Nginx spiega che Upgradee Connectionsono intestazioni hop-by-hop e devono essere passate esplicitamente per i WebSocket con proxy inverso. Vedi Proxying WebSocket di Nginx . La documentazione standard del modulo proxy copre anche proxy_set_header, proxy_pass, e proxy_read_timeout: ngx_http_proxy_module .

Passaggio 4: Convalidare Nginx prima di ricaricare

Prima di sostituire una configurazione funzionante e verificarne il corretto funzionamento, esegui un test della configurazione di Nginx:

sudo nginx -t

Ricarica il caricatore solo se il test di sintassi ha esito positivo:

sudo systemctl reload nginx

Quindi, verifica che Nginx stesso possa raggiungere il backend locale di Collabora. In una configurazione sullo stesso host, un controllo utile è il seguente:

curl -I http://127.0.0.1:9980/hosting/discovery

Le intestazioni di risposta esatte possono variare a seconda della versione di Collabora, ma il risultato fondamentale è che la connessione TCP abbia successo e l'endpoint risponda anziché andare in timeout o rifiutare la connessione. Se questa richiesta locale fallisce, la modifica delle impostazioni TLS pubbliche non risolverà il problema sottostante del container o della rete.

Passaggio 5: Verifica dell'endpoint HTTPS pubblico

Da un client che risolve l'hostname pubblico, richiedere l'endpoint di rilevamento tramite Nginx:

curl -I https://office.example.com/hosting/discovery

Una richiesta del browser https://office.example.com/hosting/discoverydovrebbe restituire XML. Questo è un controllo funzionale migliore rispetto all'affidarsi all'URL radice perché il comportamento della pagina radice non è il contratto WOPI principale e può variare a seconda della versione.

Verificate inoltre la catena di certificati con il vostro browser o con uno strumento di diagnostica TLS. Il nome host deve corrispondere al certificato, la catena deve essere considerata attendibile e non devono essere presenti avvisi di contenuto misto causati dalla pubblicità di URL HTTP non crittografati da parte di Collabora al browser.

Passaggio 6: Testare un documento reale e il WebSocket

Il successo del rilevamento è necessario ma non sufficiente. Apri un documento dal tuo host WOPI e tienilo aperto abbastanza a lungo da testare la sessione live. Negli strumenti per sviluppatori del browser, la richiesta WebSocket di Collabora dovrebbe aggiornarsi correttamente anziché riconnettersi ripetutamente o restituire un errore 400/502. Una sessione funzionante dovrebbe consentirti di digitare, salvare e riaprire il documento.

Se la shell dell'editor si carica ma il documento non viene generato subito dopo, dare priorità al percorso WebSocket, al timeout del proxy, alla lista di elementi consentiti WOPI e al comportamento dell'intestazione host. Se i log di Nginx mostrano un errore di connessione upstream prima che venga stabilita qualsiasi connessione WebSocket, controllare prima il listener e la versione dell'immagine di CODE.

Come diagnosticare le modalità di guasto più comuni

errore di connessione 502 Bad Gateway

Un errore 502 di solito significa che Nginx non è riuscito a ottenere una risposta valida dal server upstream configurato. Verifica se CODE è effettivamente in ascolto sulla porta 9980 e se stai utilizzando il protocollo upstream corretto. Nella configurazione con terminazione SSL, il passaggio dal proxy a CODE avviene tramite HTTP. Se un problema di regressione dell'immagine fa sì che CODE continui a servire HTTPS internamente nonostante le tue impostazioni, i log e un curltest diretto riveleranno l'incongruenza. Non passare definitivamente a un server upstream HTTPS solo per nascondere un problema di regressione di configurazione inspiegabile; verifica prima il comportamento dell'immagine di CODE che stai utilizzando.

La funzione di rilevamento funziona, ma i documenti non si aprono.

Questo problema spesso indica un inoltro WebSocket o un'autorizzazione WOPI piuttosto che un problema con TLS stesso. Verifica il /cool/.../wspercorso, le intestazioni di aggiornamento e l'host che hai autorizzato come sorgente WOPI. Collabora può essere perfettamente raggiungibile tramite HTTPS pur rifiutando o causando l'errore di una sessione di modifica.

URL con contenuti misti o con schema errato

Se un browser rileva una pagina HTTPS che fa riferimento a risorse HTTP, verifica ssl.termination=truel'intestazione dello schema inoltrato e il nome del server. Il lato pubblico della distribuzione deve identificarsi sempre come HTTPS, anche se il collegamento privato è HTTP.

Il contenitore segnala un problema di salute anche se la modifica funziona.

Le recenti release 26.04 hanno introdotto un comportamento di controllo dello stato di salute che è cambiato durante la transizione alle immagini senza distro. Collabora ha monitorato un caso in cui il probe non rispettava una configurazione di backend HTTP dietro la terminazione TLS. Se i test funzionali vengono superati ma lo stato di salute di Docker risulta inaspettatamente rosso, consultare la cronologia dei problemi specifici della release prima di riprogettare un proxy funzionante. Vedere il problema #16032 su CollaboraOnline/online .

Quando utilizzare un design diverso

La terminazione SSL lato proxy è appropriata quando il proxy inverso e Collabora comunicano tramite un'interfaccia locale fidata o una rete privata isolata. Se il traffico tra Nginx e CODE attraversa una rete non fidata, il semplice HTTP sul collegamento interno potrebbe non soddisfare i requisiti di sicurezza. In tal caso, utilizzare TLS anche per il backend oppure posizionare entrambi i servizi su una rete protetta in cui l'intercettazione non rappresenti una minaccia concreta.

Allo stesso modo, se si utilizza già un ingresso gestito dalla piattaforma che gestisce correttamente certificati, routing e WebSocket, aggiungere un secondo livello Nginx solo per Collabora non offre grandi vantaggi. L'architettura corretta è quella che fornisce un singolo confine TLS osservabile senza passaggi superflui.

Lista di controllo per la convalida finale

• Il nome host di Collabora si risolve nel proxy inverso.
• La porta 443 presenta un certificato attendibile per quel nome host.
• CODE non è esposto inutilmente a Internet pubblico sulla porta 9980.
• ssl.enable=falsee ssl.termination=truevengono applicati per la progettazione del backend HTTP.
• Nginx può raggiungere CODE tramite il suo indirizzo privato.
• /hosting/discoveryrisponde tramite l'URL HTTPS pubblico.
• L' /cool/.../wsaggiornamento di WebSocket è stato completato con successo.
• Un documento reale si apre, si modifica, si salva e si riapre.
• Hai salvato e testato la versione esatta dell'immagine CODE che intendi distribuire.

Se tutti questi controlli hanno esito positivo, la terminazione SSL sta svolgendo correttamente il suo compito: il traffico esterno è protetto da HTTPS, Collabora considera la connessione pubblica sicura e il percorso di modifica rimane funzionante. Se un controllo fallisce, è necessario risolvere il problema a quel livello specifico anziché modificare contemporaneamente diverse parti dello stack.