Jak skonfigurować Collabora Online za pomocą Nginx

Co powinien robić działający serwer proxy odwrotny

Prawidłowe wdrożenie Collabora Online z wykorzystaniem Nginx zapewnia użytkownikom jeden publiczny adres HTTPS dla edytora, jednocześnie utrzymując usługę Collabora w sieci prywatnej. Edytor powinien załadować zasoby przeglądarki, odkryć możliwości pakietu Office, otworzyć dokument za pośrednictwem podłączonej platformy pamięci masowej i utrzymać aktywne połączenie WebSocket podczas edycji. Samo poprawne sprawdzenie składni Nginx nie dowodzi, że te ścieżki działają.

W tym przykładzie założono, że samodzielny serwer Collabora lub kontener CODE nasłuchuje na porcie 9980, Nginx obsługuje office.example.com, a protokół TLS kończy się na Nginx. Zastąp nazwę hosta i ścieżki certyfikatów swoimi. Adres zaplecza 127.0.0.1:9980ma zastosowanie tylko wtedy, gdy Nginx i Collabora współdzielą hosta, a usługa jest powiązana z pętlą zwrotną. W przypadku oddzielnych kontenerów użyj nazwy usługi Collabora w prywatnej sieci Docker, takiej jak http://collabora:9980.

Przed zmianą Nginx

Sprawdź, czy publiczna nazwa DNS jest rozpoznawana przez serwer proxy, czy certyfikat TLS obejmuje tę samą nazwę oraz czy Nginx może połączyć się z Collabora na swoim adresie wewnętrznym. Jeśli używasz Dockera, podłącz obie usługi do sieci zdefiniowanej przez użytkownika i nie publikuj portu Collabora publicznie. Jeśli Nginx działa na hoście, powiąż port kontenera z pętlą zwrotną, na przykład 127.0.0.1:9980:9980. Zapora sieciowa powinna udostępniać publiczne porty internetowe, które zamierzasz obsługiwać, a nie port zaplecza Collabora.

Wybierz jeden układ TLS. Poniższa konfiguracja wykorzystuje TLS z przeglądarki do Nginx i zwykły HTTP w zaufanym, prywatnym hoście do Collabora. To oznacza zakończenie TLS. Jeśli polityka wymaga również szyfrowania między serwerem proxy a Collabora, użyj HTTPS dla upstream i skonfiguruj Nginx tak, aby ufał certyfikatowi zaplecza. Nie zmieniaj tylko schematu proxy_pass: ustawienia TLS po stronie serwera muszą być zgodne z rzeczywistym odbiornikiem Collabora. Collabora dokumentuje oba układy proxy w swoich wytycznych dotyczących odwrotnego proxy Nginx oraz podręczniku SDK 25.04 .

Ustaw opcje protokołu TLS obsługujące serwery proxy w Collabora

coolwsdW przypadku zakończenia protokołu TLS skonfiguruj usługę Collabora za pomocą ssl.enable=falseparametrów i ssl.termination=true. Sposób ustawienia tych wartości zależy od sposobu instalacji Collabora: edytuj obsługiwaną coolwsd.xmlkonfigurację lub użyj udokumentowanych opcji dla swojego pakietu lub kontenera. W przypadku obrazu Docker CODE, wdrożenia zazwyczaj przekazują opcje w postaci extra_params; sprawdź dokumentację obrazu dla swojej wersji i poprawnie zacytuj argumenty w Compose. Po zmianie konfiguracji uruchom ponownie lub utwórz ponownie usługę Collabora.

Te ustawienia informują Collaborę, że połączenie zewnętrzne jest chronione przez serwer proxy, mimo że przeskok między serwerem proxy a serwerem back-end korzysta z protokołu HTTP. Nie instalują one certyfikatu publicznego, nie konfigurują DNS ani nie autoryzują serwera pamięci masowej do korzystania z Collabory. Skonfiguruj listę dozwolonych hostów WOPI lub ustawienia integracji osobno, zgodnie z platformą pamięci masowej.

Skonfiguruj Nginx do przekazywania tras edytora

Nginx musi przekazać zasoby wykrywania i przeglądarki oraz zachować aktualizację WebSocket używaną podczas edycji interaktywnej. Poniżej znajduje się przykład dla pojedynczego serwera. Zdefiniuj mapw kontekście Nginx http, takim jak main nginx.conf, a nie wewnątrz hosta wirtualnego:

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

Umieść blok serwera w konfiguracji witryny dołączonej przez Nginx. Zakłada to, że certyfikaty TLS są już zainstalowane, a połączenie proxy-Collabora jest realizowane przez 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;
    }
}

Ścieżki rozpoczynające się od /coolniosą główne żądania WebSocket i edytora; wzorzec zawiera również starsze /loolścieżki dla zapewnienia zgodności. Proxy WebSocket w Nginx wymagają nagłówków aktualizacji HTTP/1.1, ponieważ Upgradei Connectionsą nagłówkami typu „hop-by-hop”. Długi limit czasu odczytu pomaga uniknąć zamknięcia aktywnego połączenia edycyjnego z powodu zwykłego krótkiego limitu czasu proxy. Zapoznaj się z dokumentacją proxy WebSocket w Nginx i informacjami o module proxy .

W przypadku protokołu HTTPS w strumieniu upstream zmień adresy URL zaplecza https://i odpowiednio skonfiguruj weryfikację certyfikatów upstream Nginx oraz łańcuch zaufanych certyfikatów. Unikaj wyłączania weryfikacji certyfikatów jako trwałego obejścia. Jeśli Nginx znajduje się w innym kontenerze, zastąp adres pętli zwrotnej nazwą usługi Collabora; 127.0.0.1adres wewnątrz kontenera proxy wskazuje na ten kontener proxy.

Jeśli używasz prefiksu URI, np. /collabora/zamiast dedykowanej nazwy hosta, konfiguracja i generowane przez Collabora adresy URL do wykrywania wymagają dodatkowej obsługi ścieżki. Zacznij od dedykowanej nazwy hosta, chyba że Twoja platforma wyraźnie obsługuje wdrożenie z wykorzystaniem ścieżki podrzędnej. Blok serwera, który przekazuje żądania do katalogu głównego, nie sprawia automatycznie, że adresy URL generowane przez wykrywanie działają pod prefiksem.

Załaduj ponownie i zweryfikuj każdą warstwę

Przed zastosowaniem sprawdź poprawność konfiguracji Nginx, a następnie przeładuj usługę:

sudo nginx -t
sudo systemctl reload nginx

Jeśli sprawdzanie składni się nie powiedzie, najpierw popraw zgłoszony plik i wiersz. Pomyślne przeładowanie potwierdza, że ​​Nginx zaakceptował konfigurację, a nie, że backend, certyfikat lub ścieżka WebSocket działają. Sprawdź osobno poprawność DNS i certyfikatu, a następnie wyślij żądanie do dwóch punktów końcowych Collabora przez publiczną nazwę hosta:

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

Punkt końcowy wykrywania powinien zwracać kod XML, a nie stronę Nginx 404 lub stronę logowania; funkcja capabilities powinna zwracać odpowiedź z Collabora. Sprawdź adresy URL edytora kodu XML wykrywania: powinny one używać publicznej nazwy hosta HTTPS i dostępnych ścieżek, a nie nazwy kontenera ani adresu wewnętrznego. Poniższy przykładowy obraz pokazuje typy odpowiedzi, których należy szukać; wyświetlane wartości mają charakter poglądowy i nie pochodzą z serwera.

Na koniec skonfiguruj platformę dokumentów tak, aby działała https://office.example.comjako serwer Collabora i otwórz dokument testowy. Przydatnym sygnałem powodzenia jest to, że edytor ładuje się i pozostaje responsywny podczas pisania, zapisywania i ponownego otwierania dokumentu. W narzędziach programistycznych przeglądarek, żądanie WebSocket /cool/powinno zostać pomyślnie zaktualizowane; status HTTP 101 Switching Protocolsto oczekiwany wynik uzgadniania WebSocket. Nie traktuj narysowanego przykładowego statusu jako dowodu, że Twój serwer pomyślnie przeszedł tę kontrolę.

Odczytaj awarie po objawach

• 502 Nieprawidłowa brama: Nginx nie może nawiązać połączenia z serwerem nadrzędnym. Sprawdź nazwę usługi, port, sieć kontenera, nasłuchiwacz i logi. Jeśli kontenery są oddzielne, nie używaj adresu pętli zwrotnej kontenera proxy.
• Błąd 404 w przypadku wyszukiwania lub zasobów przeglądarki: Sprawdź, czy żądanie dociera do właściwego hosta wirtualnego i czy lokalizacja przekazuje ścieżkę bez niezamierzonego przepisania URI. Przetestuj publiczny adres URL, a nie tylko adres URL zaplecza.
• Edytor ładuje się, ale zawiesza się lub rozłącza: Sprawdź /cool/.../wsżądanie. Brakujące nagłówki aktualizacji, połączenie HTTP/1.0, krótki limit czasu lub serwer proxy buforujący połączenie mogą przerwać edycję. Sprawdź, czy żądanie jest aktualizowane i pozostaje otwarte, dopóki dokument jest aktywny.
• Nieautoryzowany host WOPI: Serwer proxy może działać prawidłowo, podczas gdy Collabora odrzuca platformę pamięci masowej. Sprawdź rzeczywistą nazwę hosta WOPI na liście dozwolonych Collabora i konfiguracji łącznika platformy. Nie rozwiązuj tego problemu, otwierając zaplecze dla publicznego internetu.
• Ostrzeżenie o mieszanej zawartości lub certyfikacie: Upewnij się, że publiczny adres URL edytora i adresy URL w odkryciu używają protokołu HTTPS, a certyfikat jest zgodny z nazwą hosta. Jeśli kończysz TLS na serwerze Nginx, sprawdź również ustawienie zakończenia w Collabora.

Po pomyślnym zakończeniu tych kontroli, zachowaj prywatność zaplecza Collabora i monitoruj logi Nginx i Collabora podczas aktualizacji któregokolwiek z komponentów. Ten przykład pojedynczego serwera nadrzędnego nie konfiguruje wysokiej dostępności, równoważenia obciążenia ani powinowactwa sesji dla poszczególnych dokumentów. W przypadku wielu replik Collabora, postępuj zgodnie ze wskazówkami dotyczącymi wdrażania dla odpowiedniego kontrolera Collabora lub modułu równoważenia obciążenia i przetestuj powinowactwo dokumentów przed skierowaniem ruchu produkcyjnego.

Źródła i notatki dotyczące wersji

Szczegóły konfiguracji zostały sprawdzone 6 października 2026 r. pod kątem zgodności z dokumentacją serwera proxy Collabora i podręcznikiem SDK 25.04, a także odniesieniami do WebSocket i proxy-module Nginx. Opcje pakietów i kontenerów mogą się różnić w zależności od wersji Collabora; przed ich zastosowaniem należy sprawdzić nazwy ustawień dla używanej wersji. Artykuł nie zakłada konkretnej platformy pamięci masowej ani nie udowadnia wdrożenia na żywo.