Pune Collabora în spatele Nginx fără a deteriora WebSockets

Plasați Collabora pe un nume de gazdă HTTPS dedicat la Nginx, redirecționați editorul și căile de descoperire către coolwsdși transmiteți explicit anteturile de actualizare WebSocket pe rutele socket live. Pentru o singură gazdă, Nginx poate termina TLS public și trimite HTTP către Collabora pe o interfață privată; dacă Nginx și Collabora rulează în containere diferite, utilizați numele serviciului Collabora din rețeaua lor partajată în loc de 127.0.0.1.

Acest exemplu presupune că utilizatorii deschid https://office.example.comși Nginx gestionează certificatul său. Portul implicit de ascultare al Collabora este 9980; utilizați portul accesibil în implementarea dvs. Un prefix URL, cum ar fi, https://example.com/collabora/necesită o cale coordonată și setări service-root, deci această configurație root-host nu se va aplica neschimbată.

1. Definiți harta conexiunilor upstream și WebSocket

În httpcontextul Nginx, adăugați un nume upstream pentru Collabora și o hartă care setează antetul conexiunii la upgradedoar atunci când un client solicită un WebSocket. Plasați acest bloc în afara oricărui serverbloc. Înlocuiți adresa dacă Nginx ajunge la Collabora în altă parte.

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

upstream coolwsd {
    server 127.0.0.1:9980;
}

Dacă Nginx este el însuși un container, 127.0.0.1se referă la acel container Nginx, nu la containerul Collabora. Într-o rețea Docker partajată, upstream-ul poate fi în schimb server collabora:9980;, folosind numele serviciului care se rezolvă în acea rețea.

2. Adăugați gazda virtuală HTTPS și rutele Collabora

În interiorul blocului HTTPS serverpentru office.example.com, redirecționează resursele browserului, punctele finale de descoperire, conexiunile WebSocket și căile Collabora rămase. Locațiile respectă instrucțiunile proxy ale Collabora. Păstrați locațiile specifice ale socketurilor deasupra rutei cool/ mai largi lool, astfel încât Nginx să aplice corect antetele 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;
    }
}

Înlocuiți căile certificatelor cu fișierele pentru gazda dvs. Dacă instalarea dvs. nu utilizează consola de administrare, /cool/adminwseste posibil ca locația să nu fie necesară pentru editarea documentelor; /cool/.../wsruta principală este esențială. proxy_read_timeoutIată o oră ca exemplu, nu o cerință universală. Timeout-ul implicit de citire a proxy-ului Nginx este de 60 de secunde între citiri succesive. Alegeți o valoare mai lungă decât perioadele de inactivitate de care au nevoie sesiunile dvs. sau bazați-vă pe traficul ping WebSocket adecvat, acolo unde este acceptat.

3. Potriviți modul TLS al Collabora cu punctul de proxy

Utilizatorii ar trebui să acceseze Collabora prin HTTPS, chiar și atunci când hop-ul privat Nginx-to-Collabora folosește HTTP. În acest aranjament de terminare TLS, configurați coolwsdpentru a trata proxy-ul ca terminator TLS: SSL este dezactivat pe listener-ul intern, iar terminarea SSL este activată. Aplicați aceste setări prin metoda acceptată de pachetul sau imaginea containerului, apoi reporniți/reîncărcați Collabora conform cerințelor documentației sale.

Folosește un protocol HTTP în amonte doar pe o rețea privată de încredere și blochează accesul public la portul 9980. Dacă politica necesită criptare între Nginx și Collabora, folosește un protocol HTTPS în amonte și configurează corect verificarea certificatului; nu dezactivează verificarea pentru a ascunde o nepotrivire de certificat. Documentația setărilor proxy Collabora distinge SSL la proxy de SSL între proxy și coolwsd.

De asemenea, setați adresa URL Collabora în integrarea spațiului de stocare la numele public de gazdă HTTPS. Pentru Nextcloud, manualul său de administrare necesită ca browserul și ambele servere să poată interacționa prin HTTP(S), cu protocoale externe corespunzătoare. Restricționați lista de acces permise WOPI la gazda de stocare și adresa Collabora așteptate; nu o relaxați excesiv pentru a rezolva o eroare de rutare proxy.

4. Testați configurația din ambele părți

Verificați sintaxa Nginx înainte de a o reîncărca:

sudo nginx -t
sudo systemctl reload nginx

Dacă Nginx rulează într-un container, utilizați în schimb procedura de validare și reîncărcare a containerului respectiv. Din gazda Nextcloud, testați endpoint-urile publice Collabora cu numele de gazdă real:

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

Deschideți acele adrese URL HTTPS și dintr-un browser de utilizator. Acestea verifică accesibilitatea, dar un răspuns de descoperire reușit nu dovedește că editarea documentului funcționează. Deschideți un document și utilizați panoul Rețea din browser pentru a confirma încărcarea resurselor și că /cool/.../wsconexiunea rămâne deschisă. Un WebSocket HTTP/1.1 reușit afișează de obicei 101 Switching Protocols; afișarea exactă poate depinde de browser și transport. Dacă această configurare standard funcționează în Firefox, dar eșuează în Chromium, inspectați metoda și protocolul solicitării. Un raport de problemă Collabora deschis pentru versiunea 25.04 documentează un WebSocket Chromium prin HTTP/2 utilizând CONNECTși primind cod 405; rămâne deschis, așa cum a fost verificat pe 9 octombrie 2026. Acesta este un raport specific versiunii, nu un comportament universal. Comparați versiunile Collabora, Nginx și browser înainte de a modifica setările HTTP/2. Consultați problema Collabora 12155 .

Dacă descoperirea eșuează, inspectați jurnalul de erori Nginx și verificați numele de gazdă, portul și protocolul din amonte. Dacă descoperirea funcționează, dar editarea nu se poate conecta, verificați ruta WebSocket, anteturile, timeout-ul și jurnalele Collabora. O eroare de autorizare WOPI indică lista de permisiuni a gazdelor de stocare. Ghidul de depanare Nextcloud Office recomandă verificarea accesibilității din browser, Nextcloud și Collabora, apoi revizuirea jurnalelor ambelor servere.

Ghidul de proxy Nginx WebSocket explică de ce Upgradeși Connectiontrebuie transmise explicit și de ce este important comportamentul de timeout de inactivitate. Consultați referința modulului proxy Nginx pentru comportamentul directivelor. După ce verificările trec, deschideți, editați, salvați și redeschideți un document de test înainte de a invita utilizatorii să se bazeze pe noua rută.