Postaw Collabora na Nginx bez naruszania WebSockets

Umieść Collabora na dedykowanej nazwie hosta HTTPS w Nginx, przekieruj ścieżki edytora i wykrywania do [usługa] coolwsdi jawnie przekaż nagłówki aktualizacji WebSocket na trasach gniazd live. W przypadku pojedynczego hosta Nginx może zakończyć publiczny TLS i wysłać HTTP do Collabora na prywatnym interfejsie; jeśli Nginx i Collabora działają w różnych kontenerach, użyj nazwy usługi Collabora w ich współdzielonej sieci zamiast [usługa] 127.0.0.1.

W tym przykładzie zakłada się, że użytkownicy otwierają https://office.example.com, a Nginx obsługuje jego certyfikat. Domyślny port nasłuchu Collabora to 9980; należy użyć portu dostępnego w danym wdrożeniu. Prefiks adresu URL, taki jak ten, https://example.com/collabora/wymaga skoordynowanej ścieżki i ustawień katalogu głównego usługi, więc ta konfiguracja hosta głównego nie zostanie zastosowana bez zmian.

1. Zdefiniuj mapę połączeń upstream i WebSocket

W kontekście Nginx httpdodaj nazwę nadrzędną dla Collabora i mapę, która ustawia nagłówek połączenia upgradetylko wtedy, gdy klient żąda WebSocket. Umieść ten blok poza dowolnym serverblokiem. Zastąp adres, jeśli Nginx połączy się z Collabora inną drogą.

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

upstream coolwsd {
    server 127.0.0.1:9980;
}

Jeśli Nginx sam w sobie jest kontenerem, 127.0.0.1odnosi się do tego kontenera Nginx, a nie kontenera Collabora. W sieci współdzielonej Docker, nadrzędnym serwerem może być server collabora:9980;, używając nazwy usługi, która jest rozpoznawana w tej sieci.

2. Dodaj wirtualnego hosta HTTPS i trasy Collabora

Wewnątrz bloku HTTPS serverdla office.example.com, przekieruj zasoby przeglądarki, punkty końcowe wykrywania, połączenia WebSocket i pozostałe ścieżki Collabora. Lokalizacje są zgodne z wytycznymi serwera proxy Collabora. Zachowaj konkretne lokalizacje gniazd powyżej szerszej trasy cool/ lool, aby Nginx poprawnie stosował nagłówki 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;
    }
}

Zastąp ścieżki certyfikatów plikami dla swojego hosta. Jeśli instalacja nie korzysta z konsoli administracyjnej, lokalizacja /cool/adminwsmoże nie być potrzebna do edycji dokumentów; /cool/.../wsścieżka główna jest niezbędna. proxy_read_timeoutPowyższy przykład to jedna godzina, a nie jest to wymaganie uniwersalne. Domyślny limit czasu odczytu proxy Nginx wynosi 60 sekund między kolejnymi odczytami. Wybierz wartość dłuższą niż okresy bezczynności wymagane przez Twoje sesje lub polegaj na odpowiednim ruchu ping WebSocket, jeśli jest obsługiwany.

3. Dopasuj tryb TLS Collabora do przeskoku proxy

Użytkownicy powinni łączyć się z Collabora przez HTTPS, nawet jeśli prywatny przeskok Nginx-do-Collabora korzysta z protokołu HTTP. W tym układzie z terminacją TLS należy skonfigurować coolwsdserwer proxy jako terminator TLS: SSL jest wyłączony na wewnętrznym odbiorniku, a terminacja SSL jest włączona. Zastosuj te ustawienia za pomocą metody obsługiwanej przez pakiet lub obraz kontenera, a następnie uruchom ponownie/przeładuj Collabora zgodnie z wymaganiami dokumentacji.

Używaj protokołu HTTP upstream tylko w zaufanej sieci prywatnej i blokuj dostęp publiczny do portu 9980. Jeśli polityka wymaga szyfrowania między Nginx a Collabora, użyj protokołu HTTPS upstream i poprawnie skonfiguruj weryfikację certyfikatów; nie wyłączaj weryfikacji, aby ukryć niezgodność certyfikatów. Dokumentacja ustawień proxy Collabora rozróżnia protokół SSL na serwerze proxy od protokołu SSL między serwerem proxy a serwerem coolwsd.

Ustaw również adres URL Collabora w integracji pamięci masowej na publiczną nazwę hosta HTTPS. W przypadku NextCloud, instrukcja administracyjna wymaga, aby przeglądarka i oba serwery mogły się ze sobą komunikować przez HTTP(S) z użyciem zgodnych protokołów zewnętrznych. Ogranicz listę dozwolonych połączeń WOPI do oczekiwanego hosta pamięci masowej i adresu Collabora; nie zmieniaj jej zbytnio, aby rozwiązać błąd routingu proxy.

4. Przetestuj konfigurację z obu stron

Sprawdź składnię Nginx przed ponownym załadowaniem:

sudo nginx -t
sudo systemctl reload nginx

Jeśli Nginx działa w kontenerze, użyj procedury walidacji i ponownego ładowania tego kontenera. Z poziomu hosta Nextcloud przetestuj publiczne punkty końcowe Collabora z rzeczywistą nazwą hosta:

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

Otwórz te adresy URL HTTPS również w przeglądarce użytkownika. Sprawdzają one dostępność, ale sama pomyślna odpowiedź na żądanie odkrycia nie dowodzi, że edycja dokumentu działa. Otwórz dokument i użyj panelu Sieć w przeglądarce, aby potwierdzić załadowanie zasobów, a połączenie /cool/.../wspozostanie otwarte. Pomyślne wykonanie protokołu WebSocket HTTP/1.1 zazwyczaj pokazuje 101 Switching Protocols; dokładny sposób wyświetlania może zależeć od przeglądarki i transportu. Jeśli ta standardowa konfiguracja działa w przeglądarce Firefox, ale nie działa w przeglądarce Chromium, sprawdź metodę żądania i protokół. Raport o problemie z Collabora, otwarty dla wersji 25.04, dokumentuje protokół WebSocket Chromium przez HTTP/2 używający CONNECTi otrzymujący 405; pozostaje otwarty, jak sprawdzono 9 października 2026 r. Jest to raport specyficzny dla wersji, a nie uniwersalne zachowanie. Porównaj wersje Collabora, Nginx i przeglądarki przed zmianą ustawień HTTP/2. Zobacz problem Collabora nr 12155 .

Jeśli wyszukiwanie się nie powiedzie, sprawdź dziennik błędów Nginx i zweryfikuj nazwę hosta, port i protokół nadrzędny. Jeśli wyszukiwanie działa, ale edycja nie może nawiązać połączenia, sprawdź trasę WebSocket, nagłówki, limit czasu i dzienniki Collabora. Błąd autoryzacji WOPI wskazuje na listę dozwolonych hostów pamięci masowej. Przewodnik rozwiązywania problemów Nextcloud Office zaleca sprawdzenie dostępności z przeglądarki, Nextcloud i Collabora, a następnie przejrzenie dzienników obu serwerów.

Przewodnik po proxy Nginx WebSocket wyjaśnia, dlaczego Upgradei Connectionmuszą być przekazywane jawnie oraz dlaczego zachowanie limitu czasu bezczynności ma znaczenie. Informacje na temat zachowania dyrektyw można znaleźć w dokumentacji modułu proxy Nginx . Po pomyślnym sprawdzeniu otwórz, edytuj, zapisz i ponownie otwórz dokument testowy, zanim zaprosisz użytkowników do korzystania z nowej trasy.