Cum să configurezi Collabora Online în spatele Nginx

Ce ar trebui să facă un proxy invers funcțional

O implementare Collabora Online sănătoasă în spatele Nginx oferă utilizatorilor o adresă HTTPS publică pentru editor, menținând în același timp serviciul Collabora într-o rețea privată. Editorul ar trebui să încarce resursele browserului său, să descopere funcționalitățile Office, să deschidă un document prin platforma de stocare conectată și să mențină conexiunea WebSocket activă în timpul editării. O verificare validă a sintaxei Nginx nu dovedește, în sine, că aceste căi funcționează.

Acest exemplu presupune că un server Collabora independent sau un container CODE ascultă pe portul 9980, Nginx deservește office.example.com, iar TLS se termină la Nginx. Înlocuiți numele de gazdă și căile certificatului cu ale dvs. Adresa backend 127.0.0.1:9980se aplică numai atunci când Nginx și Collabora partajează o gazdă și serviciul este legat la loopback. Pentru containere separate, utilizați numele serviciului Collabora pe o rețea Docker privată, cum ar fi http://collabora:9980.

Înainte de a schimba Nginx

Confirmați că numele DNS public se rezolvă la proxy, că certificatul TLS acoperă exact acel nume și că Nginx poate ajunge la Collabora pe adresa sa internă. Dacă utilizați Docker, atașați ambele servicii la o rețea definită de utilizator și nu publicați public portul Collabora. Dacă Nginx rulează pe gazdă, legați portul containerului la loopback, de exemplu 127.0.0.1:9980:9980. Firewall-ul dvs. ar trebui să expună porturile web publice pe care intenționați să le deserviți, nu portul backend Collabora.

Alegeți un aranjament TLS. Configurația de mai jos utilizează TLS de la browser la Nginx și HTTP simplu pe o saltă privată de încredere către Collabora. Aceasta este terminarea TLS. Dacă politica necesită criptare și între proxy și Collabora, utilizați HTTPS pentru upstream și configurați Nginx să aibă încredere în certificatul backend. Nu schimbați doar schema proxy_pass: setările TLS de pe server trebuie să corespundă cu listener-ul Collabora real. Collabora documentează ambele aranjamente proxy în ghidul său Nginx reverse-proxy și în manualul SDK 25.04 .

Setați opțiunile TLS compatibile cu proxy ale Collabora

coolwsdPentru terminarea TLS, configurați serviciul Collabora cu ssl.enable=falseși ssl.termination=true. Modul în care setați aceste valori depinde de modul în care a fost instalat Collabora: editați coolwsd.xmlconfigurația acceptată sau utilizați opțiunile documentate pentru pachetul sau containerul dvs. Cu imaginea CODE Docker, implementările transmit de obicei opțiunile ca extra_params; verificați documentația imaginii pentru versiunea dvs. și citați corect argumentele în Compose. Reporniți sau recreați serviciul Collabora după modificarea configurației sale.

Aceste setări indică serviciul Collabora că conexiunea externă este protejată de proxy, chiar dacă hop-ul proxy-backend utilizează HTTP. Nu instalează un certificat public, nu configurează DNS și nu autorizează un server de stocare să utilizeze Collabora. Configurați separat lista de gazde permise WOPI sau setările de integrare, în funcție de platforma dvs. de stocare.

Configurați Nginx pentru a redirecționa rutele editorului

Nginx trebuie să transmită resursele de descoperire și de browser și să păstreze actualizarea WebSocket utilizată de editarea interactivă. Următorul este un exemplu pentru un singur server. Definiți mapîn contextul Nginx http, cum ar fi main nginx.conf, nu în interiorul gazdei virtuale:

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

Plasați blocul de server în configurația site-ului inclusă de Nginx. Aceasta presupune că certificatele TLS sunt deja instalate și conexiunea proxy-to-Collabora este 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;
    }
}

Căile care încep cu /cooltransportă cererile principale WebSocket și de editor; modelul include și /loolcăi vechi pentru compatibilitate. Proxy-ul WebSocket al Nginx necesită anteturile de actualizare HTTP/1.1 deoarece Upgradeși Connectionsunt anteturi hop-by-hop. Timeout-ul lung de citire ajută la evitarea închiderii unei conexiuni de editare altfel active din cauza unui timeout proxy scurt obișnuit. Consultați documentația proxy-ului Nginx WebSocket și referința modulului proxy .

Pentru HTTPS în amonte, schimbați adresele URL backend la https://și configurați în mod corespunzător verificarea certificatelor în amonte a Nginx și lanțul de certificate de încredere. Evitați dezactivarea verificării certificatelor ca soluție permanentă. Dacă Nginx se află într-un alt container, înlocuiți adresa de loopback cu numele serviciului Collabora; 127.0.0.1interiorul containerului proxy indică înapoi la acel container proxy.

Când utilizați un prefix URI, cum ar fi /collabora/în loc de un nume de gazdă dedicat, configurația și adresele URL de descoperire generate de Collabora necesită o gestionare suplimentară a căii. Începeți cu un nume de gazdă dedicat, cu excepția cazului în care platforma dvs. acceptă în mod explicit o implementare de subcăi. Un bloc de server care redirecționează cererile la rădăcină nu face ca adresele URL generate de descoperire să funcționeze automat sub un prefix.

Reîncărcați și verificați fiecare strat

Validați configurația Nginx înainte de a o aplica, apoi reîncărcați serviciul:

sudo nginx -t
sudo systemctl reload nginx

Dacă verificarea sintaxei eșuează, corectați mai întâi fișierul și linia raportate. O reîncărcare reușită confirmă că Nginx a acceptat configurația, nu că backend-ul, certificatul sau calea WebSocket funcționează. Verificați separat validitatea DNS și a certificatului, apoi solicitați cele două endpoint-uri Collabora prin numele de gazdă public:

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

Punctul final de descoperire ar trebui să returneze XML în loc de o pagină Nginx 404 sau o pagină de conectare; capabilitățile ar trebui să returneze un răspuns de la Collabora. Verificați adresele URL ale editorului XML de descoperire: acestea ar trebui să utilizeze numele de gazdă HTTPS public și căile accesibile, nu un nume de container sau o adresă internă. Imaginea exemplu de mai jos arată tipurile de răspunsuri de căutat; valorile afișate sunt ilustrative, nu sunt generate de un server live.

În cele din urmă, configurați platforma de documente pentru a o utiliza https://office.example.comdrept server Collabora și deschideți un document de test. Un semnal util de succes este faptul că editorul se încarcă și rămâne receptiv în timp ce tastează, salvează și redeschide documentul. În instrumentele pentru dezvoltatori de browser, solicitarea WebSocket de sub /cool/ar trebui să se actualizeze cu succes; starea HTTP 101 Switching Protocolseste rezultatul așteptat al handshake-ului WebSocket. Nu tratați o stare exemplu desenată ca dovadă că propriul server a trecut această verificare.

Citiți eșecurile după simptomele lor

• 502 Gateway defect: Nginx nu poate accesa upstream-ul. Verificați numele serviciului, portul, rețeaua containerului, listener-ul și jurnalele. Dacă containerele sunt separate, nu utilizați adresa de loopback a containerului proxy.
• 404 la descoperire sau la resursele browserului: Confirmați că solicitarea ajunge la gazda virtuală corectă și că locația redirecționează calea fără o rescriere neintenționată a URI-ului. Testați adresa URL publică, nu doar adresa URL backend.
• Editorul încarcă, dar se blochează sau se deconectează: Verificați /cool/.../wssolicitarea. Lipsa antetelor de actualizare, o conexiune HTTP/1.0 în amonte, o expirare scurtă sau un proxy care stochează conexiunea în buffer pot întrerupe editarea. Confirmați că solicitarea se actualizează și rămâne deschisă cât timp documentul este activ.
• Gazdă WOPI neautorizată: Proxy-ul poate fi funcțional în timp ce Collabora respinge platforma de stocare. Verificați numele real al gazdei WOPI în raport cu lista de permisiuni a Collabora și cu configurația conectorului platformei. Nu rezolvați această problemă prin deschiderea backend-ului către internetul public.
• Avertisment privind conținutul mixt sau certificatul: Asigurați-vă că adresa URL a editorului public și adresele URL din Discovery utilizează HTTPS și că certificatul se potrivește cu numele de gazdă. Dacă terminați TLS la Nginx, verificați și setarea de terminare Collabora.

După ce aceste verificări trec, păstrați backend-ul Collabora privat și monitorizați jurnalele atât Nginx, cât și Collabora atunci când actualizați oricare dintre componente. Acest exemplu cu un singur upstream nu configurează disponibilitate ridicată, echilibrarea încărcării sau afinitatea sesiunii per document. Pentru mai multe replici Collabora, urmați instrucțiunile de implementare pentru controlerul sau echilibratorul de încărcare Collabora relevant și testați afinitatea documentelor înainte de a ruta traficul de producție.

Surse și note de versiune

Detaliile de configurare au fost verificate pe 6 octombrie 2026 în raport cu documentația proxy Collabora și manualul SDK-ului 25.04, precum și cu referințele WebSocket și modulului proxy ale Nginx. Opțiunile pachetului și containerului pot varia în funcție de versiunea Collabora; confirmați numele setărilor pentru versiunea pe care o executați înainte de a le aplica. Articolul nu presupune o anumită platformă de stocare și nu demonstrează o implementare live.