Cum se configurează terminarea SSL pentru un container CODE Collabora

Terminarea SSL este o alegere excelentă pentru un container Collabora Online Development Edition (CODE) atunci când doriți un punct final HTTPS public, menținând în același timp gestionarea certificatelor la un proxy invers, cum ar fi Nginx. În acest design, browserul se conectează la Nginx prin HTTPS, Nginx decriptează traficul, iar Collabora primește HTTP simplu pe portul său intern. Obiectivul de calitate nu este doar „încărcarea paginii”. O implementare reușită ar trebui să aibă un certificat public valid, un punct final de descoperire WOPI accesibil, actualizări WebSocket funcționale și o sesiune reală de editare a documentelor care rămâne conectată.

Documentația proprie a proxy-ului Collabora descrie acest model de descărcare SSL ca o conexiune HTTP-only între proxy și Collabora, cu ssl.enable=falseși ssl.termination=truepe partea Collabora. Consultați setările proxy-ului invers Collabora Online . Exemplele de mai jos utilizează Nginx și Docker Compose, dar același rezultat poate fi obținut cu alte proxy-uri inverse dacă acestea păstrează comportamentul necesar al gazdei și WebSocket-ului.

Ce ar trebui să realizeze o configurație bună de terminare SSL

Pasul 1: Confirmați limita rețelei înainte de a schimba colaborarea

Decideți unde se termină TLS și ce gazde pot ajunge la portul 9980. Dacă Nginx rulează pe aceeași mașină ca Docker, legarea portului publicat la 127.0.0.1este o modalitate simplă de a preveni accesul direct la internet. Docker documentează faptul că publicarea unui port la 127.0.0.1îl menține local față de gazdă; consultați documentația Docker despre publicarea porturilor .

Dacă Nginx rulează într-un alt container, o rețea Docker privată partajată este de obicei mai curată decât publicarea publică a 9980. Principiul este același: clienții ar trebui să utilizeze numele de gazdă HTTPS reverse-proxy, nu direct containerul Collabora.

Pasul 2: Executați CODE în modul de terminare SSL

Pentru terminarea TLS pe ​​partea proxy, Collabora ar trebui să știe că schema originală orientată către client este HTTPS, chiar dacă conexiunea sa imediată în amonte este HTTP. Setările documentate sunt:

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

Un exemplu minimal de Compose arată astfel:

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"

Înlocuiți YOUR_TESTED_TAGcu o versiune pe care ați validat-o, în loc să presupuneți automat că latesteste sigură pentru o implementare de tip producție. De asemenea, configurați setările corespunzătoare pentru gazda sau aliasul WOPI pentru integrarea dvs.; aceste valori depind de conectarea la Nextcloud, ownCloud, o altă gazdă WOPI sau o integrare personalizată.

După pornirea containerului, confirmați că acesta rulează și că maparea porturilor se potrivește cu limita dorită:

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

Notă de versiune pentru implementările versiunii 26.04

Nu tratați cele două semnalizatoare SSL ca singura variabilă atunci când depanați o imagine 26.04 curentă. La mijlocul anului 2026, Collabora a urmărit regresiile legate de imaginea Docker fără distribuție și configurațiile cu SSL dezactivat. O problemă oficială de pe GitHub documentează o regresie la pornire la versiunea 26.04, iar o urmărire a comunității Collabora a raportat că comportamentul de terminare SSL afectat funcționează din nou într-o imagine ulterioară, versiunea 26.04.2.4.1. Consultați problema CollaboraOnline/online #16019 dacă o configurație de terminare funcțională anterior se defectează imediat după o actualizare a imaginii.

Acesta este, de asemenea, un motiv pentru a fixa și testa versiunea imaginii. O eroare de configurare și o regresie container-imagine pot arăta similar din Nginx: ambele pot apărea ca un răspuns 502 sau o conexiune upstream eșuată.

Pasul 3: Configurați Nginx pentru a termina căile de colaborare TLS și proxy

Nginx are nevoie de un certificat valid pentru numele de gazdă Collabora și trebuie să redirecționeze punctele finale HTTP ale Collabora, plus traficul WebSocket. Ghidul proxy al Collabora prezintă locații dedicate pentru resursele browserului, descoperire, capabilități, conexiunile WebSocket principale, căile de descărcare/încărcare și WebSocket-ul de administrare. Următoarea configurație respectă această structură, adăugând în același timp anteturi comune redirecționate:

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;
    }
}

Anteturile WebSocket nu sunt cosmetice. Documentația oficială Nginx explică faptul că Upgradeși Connectionsunt anteturi hop-by-hop și trebuie transmise explicit pentru WebSocket-uri cu proxy invers. Consultați proxy-ul Nginx WebSocket . Documentația standard a modulului proxy acoperă, de asemenea proxy_set_header, proxy_pass, și proxy_read_timeout: ngx_http_proxy_module .

Pasul 4: Validați Nginx înainte de reîncărcare

Testați configurația Nginx înainte de a înlocui o configurație despre care se știe că funcționează corect:

sudo nginx -t

Reîncărcați doar dacă testul de sintaxă reușește:

sudo systemctl reload nginx

Apoi confirmați că Nginx în sine poate accesa backend-ul Collabora local. Într-o configurație pe aceeași gazdă, o verificare utilă este:

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

Anteturile exacte de răspuns pot varia în funcție de versiunea Collabora, dar rezultatul cheie este că conexiunea TCP reușește și endpoint-ul răspunde, în loc să expire sau să refuze conexiunea. Dacă această solicitare locală eșuează, modificarea setărilor TLS publice nu va rezolva problema containerului sau a rețelei subiacente.

Pasul 5: Verificați endpoint-ul HTTPS public

De la un client care rezolvă numele public de gazdă, solicitați endpoint-ul de descoperire prin Nginx:

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

O solicitare a browserului https://office.example.com/hosting/discoveryar trebui să returneze XML. Aceasta este o verificare funcțională mai bună decât bazarea pe URL-ul rădăcină, deoarece comportamentul paginii rădăcină nu este contractul WOPI principal și poate diferi în funcție de versiune.

De asemenea, verificați lanțul de certificate cu browserul dvs. sau cu un instrument de diagnosticare TLS. Numele de gazdă ar trebui să corespundă certificatului, lanțul ar trebui să fie de încredere și nu ar trebui să existe avertismente privind conținutul mixt cauzate de Collabora care promovează adrese URL HTTP simple către browser.

Pasul 6: Testați un document real și WebSocket-ul

Succesul descoperirii este necesar, dar nu suficient. Deschideți un document de pe gazda WOPI reală și mențineți-l deschis suficient de mult timp pentru a putea activa sesiunea live. În instrumentele pentru dezvoltatori de browser, solicitarea Collabora WebSocket ar trebui să se actualizeze cu succes, în loc să se reconecteze în mod repetat sau să returneze o eroare 400/502. O sesiune funcțională ar trebui să vă permită să tastați, să salvați și să redeschideți documentul.

Dacă shell-ul editorului se încarcă, dar documentul eșuează la scurt timp după aceea, acordați prioritate căii WebSocket, timeout-ului proxy, listei de permisiuni WOPI și comportamentului antetului gazdă. Dacă jurnalele Nginx arată o eroare de conexiune în amonte înainte de stabilirea oricărui WebSocket, inspectați mai întâi listener-ul și versiunea imaginii CODE.

Cum se diagnostichează modurile comune de defecțiune

502 Bad Gateway

Un cod 502 înseamnă de obicei că Nginx nu a putut obține un răspuns valid de la upstream-ul configurat. Verificați dacă CODE ascultă efectiv pe 9980 și dacă utilizați protocolul upstream corect. În designul de terminare SSL intenționat, saltul proxy-to-CODE este HTTP. Dacă o regresie de imagine face ca CODE să continue să servească HTTPS intern în ciuda semnalizărilor dvs., jurnalele și un curltest direct vor dezvălui nepotrivirea. Nu treceți permanent la un upstream HTTPS doar pentru a ascunde o regresie de configurare inexplicabilă; verificați mai întâi comportamentul imaginii CODE exacte pe care o rulați.

Descoperirea funcționează, dar documentele nu se deschid

Acest lucru indică adesea redirecționarea WebSocket sau autorizarea WOPI, mai degrabă decât TLS în sine. Verificați /cool/.../wsruta, anteturile de actualizare și gazda pe care ați permis-o ca sursă WOPI. Collabora poate fi perfect accesibil prin HTTPS, în timp ce respinge sau eșuează o sesiune de editare.

URL-uri cu conținut mixt sau schemă incorectă

Dacă un browser vede o pagină HTTPS care face referire la resurse HTTP, verificați ssl.termination=true, antetul schemei redirecționate și numele serverului. Partea publică a implementării trebuie să se identifice în mod constant ca HTTPS, chiar dacă hop-ul privat este HTTP.

Containerul raportează că este incorect, chiar dacă editarea funcționează

Versiunile recente 26.04 au introdus un comportament de verificare a stării de funcționare care s-a modificat în timpul tranziției de la imaginea fără distribuție. Collabora a urmărit un caz în care sonda nu a respectat o configurație HTTP backend în spatele terminării TLS. Dacă testele funcționale au reușit, dar starea de funcționare a Dockerului este în mod neașteptat de roșie, verificați istoricul problemelor specifice versiunii înainte de a reproiecta un proxy funcțional. Consultați problema CollaboraOnline/online #16032 .

Când să folosești un design diferit

Terminarea SSL pe partea de proxy este potrivită atunci când proxy-ul invers și Collabora comunică printr-o interfață locală de încredere sau o rețea privată izolată. Dacă traficul dintre Nginx și CODE traversează o rețea nede încredere, HTTP simplu pe hop-ul intern poate să nu îndeplinească cerințele de securitate. În acest caz, utilizați TLS și pentru backend sau plasați ambele servicii într-o rețea protejată unde interceptarea nu reprezintă o amenințare realistă.

În mod similar, dacă deja operați o rețea de intrare gestionată de platformă care gestionează corect certificatele, rutarea și WebSocket-urile, există puține beneficii în adăugarea unui al doilea strat Nginx doar pentru Collabora. Arhitectura corectă este cea care vă oferă o singură limită TLS observabilă, fără salturi inutile.

Listă de verificare finală pentru validare

• Numele de gazdă Collabora se rezolvă în proxy-ul invers.
• Portul 443 prezintă un certificat de încredere pentru numele de gazdă respectiv.
• CODE nu este expus inutil la internetul public pe portul 9980.
• ssl.enable=falseși ssl.termination=truesunt aplicate pentru designul backend-ului HTTP.
• Nginx poate accesa CODE pe adresa sa privată.
• /hosting/discoveryrăspunde prin adresa URL HTTPS publică.
• WebSocket /cool/.../ws-ul s-a actualizat cu succes.
• Un document real se deschide, se editează, se salvează și se redeschide.
• Ai fixat și testat exact versiunea imaginii CODE pe care intenționezi să o implementezi.

Dacă toate aceste verificări trec cu succes, terminarea SSL își face treaba: traficul extern este protejat de HTTPS, Collabora înțelege conexiunea publică ca fiind securizată, iar calea de editare rămâne funcțională. Dacă o verificare eșuează, depanați la nivelul respectiv în loc să modificați mai multe părți ale stivei simultan.