Jak skonfigurować zakończenie protokołu SSL dla kontenera Collabora CODE

Zakończenie protokołu SSL doskonale sprawdza się w kontenerze Collabora Online Development Edition (CODE), gdy potrzebny jest jeden publiczny punkt końcowy HTTPS, a jednocześnie zarządzanie certyfikatami odbywa się na odwrotnym serwerze proxy, takim jak Nginx. W tym projekcie przeglądarka łączy się z Nginx przez HTTPS, Nginx odszyfrowuje ruch, a Collabora odbiera zwykły protokół HTTP na swoim porcie wewnętrznym. Celem jakościowym nie jest samo „ładowanie strony”. Pomyślne wdrożenie powinno obejmować ważny certyfikat publiczny, osiągalny punkt końcowy wykrywania WOPI, działające aktualizacje WebSocket oraz rzeczywistą sesję edycji dokumentów z ciągłym połączeniem.

Własna dokumentacja serwera proxy Collabora opisuje ten wzorzec odciążenia SSL jako połączenie wyłącznie HTTP między serwerem proxy a Collabora, z ssl.enable=falsei ssl.termination=truepo stronie Collabora. Zobacz ustawienia odwrotnego serwera proxy Collabora Online . Poniższe przykłady wykorzystują Nginx i Docker Compose, ale ten sam wynik można osiągnąć za pomocą innych odwrotnych serwerów proxy, jeśli zachowają one wymagane zachowanie hosta i WebSocket.

Co powinna osiągnąć dobra konfiguracja zakończenia SSL

Krok 1: Potwierdź granicę sieci przed zmianą współpracy

Zdecyduj, gdzie kończy się TLS i które hosty mogą dotrzeć do portu 9980. Jeśli Nginx działa na tym samym komputerze co Docker, powiązanie opublikowanego portu z portem 127.0.0.1to prosty sposób na uniemożliwienie bezpośredniego dostępu do internetu. Docker dokumentuje, że opublikowanie portu z portem 127.0.0.1utrzymuje go lokalnie dla hosta; zobacz dokumentację Dockera dotyczącą publikowania portów .

Jeśli Nginx działa w innym kontenerze, współdzielona prywatna sieć Dockera jest zazwyczaj bardziej przejrzysta niż publiczne publikowanie 9980. Zasada jest ta sama: klienci powinni używać nazwy hosta HTTPS z odwrotnym serwerem proxy, a nie bezpośrednio kontenera Collabora.

Krok 2: Uruchom KOD w trybie zakończenia protokołu SSL

W przypadku zakończenia protokołu TLS po stronie serwera proxy, Collabora powinna wiedzieć, że oryginalny schemat skierowany do klienta to HTTPS, mimo że jego bezpośrednie połączenie nadrzędne jest realizowane za pomocą protokołu HTTP. Udokumentowane ustawienia to:

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

Minimalny przykład Compose wygląda następująco:

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"

Zastąp ją YOUR_TESTED_TAGwersją, którą zweryfikowałeś, zamiast automatycznie zakładać, że latestjest bezpieczna dla wdrożenia produkcyjnego. Skonfiguruj również odpowiednie ustawienia hosta WOPI lub aliasu dla swojej integracji; wartości te zależą od tego, czy łączysz się z NextCloud, ownCloud, innym hostem WOPI, czy integracją niestandardową.

Po uruchomieniu kontenera sprawdź, czy jest on uruchomiony i czy mapowanie portów jest zgodne z zamierzoną granicą:

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

Notatka dotycząca wersji wdrożeń 26.04

Nie traktuj dwóch flag SSL jako jedynej zmiennej podczas rozwiązywania problemów z bieżącym obrazem 26.04. W połowie 2026 roku firma Collabora śledziła regresje w obrazie Dockera bez dystrybucji i konfiguracjach z wyłączonym SSL. Oficjalny problem w serwisie GitHub dokumentuje regresję podczas uruchamiania wersji 26.04, a społeczność Collabora zgłosiła, że ​​problem z zakończeniem SSL działa ponownie w późniejszej wersji obrazu 26.04.2.4.1. Sprawdź problem CollaboraOnline/online nr 16019, jeśli wcześniej działająca konfiguracja zakończenia SSL przestaje działać natychmiast po aktualizacji obrazu.

To również powód, aby przypiąć i przetestować wersję obrazu. Błąd konfiguracji i regresja obrazu kontenera mogą wyglądać podobnie w Nginx: oba mogą zostać wyświetlone jako odpowiedź 502 lub nieudane połączenie upstream.

Krok 3: Skonfiguruj Nginx, aby zakończyć ścieżki TLS i proxy Collabora

Nginx wymaga ważnego certyfikatu dla nazwy hosta Collabora i musi przekierować punkty końcowe HTTP Collabora oraz ruch WebSocket. Przewodnik po proxy Collabora pokazuje dedykowane lokalizacje zasobów przeglądarki, wyszukiwania, funkcji, głównych połączeń WebSocket, ścieżek pobierania/przesyłania oraz WebSocket administratora. Poniższa konfiguracja jest zgodna z tą strukturą, ale dodaje typowe przekierowane nagłówki:

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

Nagłówki WebSocket nie są kosmetyczne. Oficjalna dokumentacja Nginx wyjaśnia, że Upgrade​​są Connectionto nagłówki typu „hop-by-hop” i muszą być przekazywane jawnie w przypadku WebSocketów z odwrotnym proxy. Zobacz artykuł „Nginx WebSocket proxying” . Standardowa dokumentacja modułu proxy obejmuje również proxy_set_header: , proxy_pass, i proxy_read_timeout: ngx_http_proxy_module .

Krok 4: Sprawdź poprawność Nginx przed ponownym załadowaniem

Przed zastąpieniem znanej, dobrej konfiguracji działającej przetestuj konfigurację Nginx:

sudo nginx -t

Załaduj ponownie tylko wtedy, gdy test składni zakończy się powodzeniem:

sudo systemctl reload nginx

Następnie sprawdź, czy sam Nginx może połączyć się z lokalnym serwerem Collabora. W konfiguracji z tym samym hostem, przydatne jest sprawdzenie:

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

Dokładne nagłówki odpowiedzi mogą się różnić w zależności od wersji Collabora, ale kluczowym rezultatem jest nawiązanie połączenia TCP i odpowiedź punktu końcowego zamiast przekroczenia limitu czasu lub odmowy połączenia. Jeśli to lokalne żądanie się nie powiedzie, zmiana publicznych ustawień TLS nie rozwiąże problemu z kontenerem ani siecią.

Krok 5: Zweryfikuj publiczny punkt końcowy HTTPS

Z poziomu klienta rozwiązującego publiczną nazwę hosta należy zażądać punktu końcowego wykrywania za pośrednictwem Nginx:

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

Żądanie przeglądarki https://office.example.com/hosting/discoverypowinno zwrócić XML. Jest to lepsze sprawdzenie funkcjonalności niż poleganie na adresie URL głównym, ponieważ zachowanie strony głównej nie jest głównym kontraktem WOPI i może się różnić w zależności od wersji.

Sprawdź również łańcuch certyfikatów za pomocą przeglądarki lub narzędzia diagnostycznego TLS. Nazwa hosta powinna być zgodna z certyfikatem, łańcuch powinien być zaufany i nie powinny pojawiać się żadne ostrzeżenia o mieszanej zawartości spowodowane reklamowaniem przez Collabora zwykłych adresów URL HTTP w przeglądarce.

Krok 6: Przetestuj prawdziwy dokument i protokół WebSocket

Sukces w odkrywaniu jest konieczny, ale niewystarczający. Otwórz dokument z hosta WOPI i utrzymuj go otwartym wystarczająco długo, aby przeprowadzić sesję na żywo. W narzędziach programistycznych przeglądarek, żądanie Collabora WebSocket powinno zostać pomyślnie zaktualizowane, zamiast wielokrotnie nawiązywać połączenie lub zwracać błąd 400/502. Prawidłowa sesja powinna umożliwiać pisanie, zapisywanie i ponowne otwieranie dokumentu.

Jeśli powłoka edytora załaduje się, ale dokument wkrótce potem ulegnie awarii, priorytetowo potraktuj ścieżkę WebSocket, limit czasu proxy, listę dozwolonych WOPI i zachowanie nagłówka hosta. Jeśli logi Nginx wykażą błąd połączenia upstream przed nawiązaniem jakiegokolwiek połączenia WebSocket, najpierw sprawdź program nasłuchujący CODE i wersję obrazu.

Jak diagnozować typowe tryby awarii

502 Zła brama

Błąd 502 zazwyczaj oznacza, że ​​Nginx nie mógł uzyskać prawidłowej odpowiedzi od skonfigurowanego serwera nadrzędnego. Sprawdź, czy CODE faktycznie nasłuchuje na porcie 9980 i czy używasz prawidłowego protokołu nadrzędnego. W zamierzonym projekcie zakończenia SSL, przeskok z proxy do CODE odbywa się przez HTTP. Jeśli regresja obrazu powoduje, że CODE nadal obsługuje wewnętrznie HTTPS pomimo ustawionych flag, logi i bezpośredni curltest ujawnią niezgodność. Nie przełączaj się trwale na protokół nadrzędny HTTPS tylko po to, aby ukryć niewyjaśnioną regresję konfiguracji; najpierw sprawdź zachowanie konkretnego obrazu CODE, który uruchamiasz.

Odkrycie działa, ale dokumenty się nie otwierają

Często wskazuje to na przekierowanie WebSocket lub autoryzację WOPI, a nie na sam protokół TLS. Sprawdź /cool/.../wstrasę, nagłówki aktualizacji i hosta, którego zezwoliłeś jako źródło WOPI. Collabora może być w pełni dostępna przez HTTPS, a jednocześnie odrzucać lub kończyć sesję edycji niepowodzeniem.

Adresy URL o mieszanej zawartości lub nieprawidłowe schematy

Jeśli przeglądarka zobaczy stronę HTTPS odwołującą się do zasobów HTTP, należy zweryfikować ssl.termination=true, nagłówek schematu przekierowania oraz nazwę serwera. Publiczna strona wdrożenia musi być konsekwentnie identyfikowana jako HTTPS, nawet jeśli prywatny przeskok to HTTP.

Kontener zgłasza nieprawidłową pracę, mimo że edycja działa

W ostatnich wersjach 26.04 wprowadzono mechanizm kontroli stanu, który uległ zmianie podczas przejścia na obraz distroless. Collabora wykryła przypadek, w którym sonda nie uwzględniała konfiguracji zaplecza HTTP po zakończeniu TLS. Jeśli testy funkcjonalne zakończą się pomyślnie, ale stan Dockera będzie nieoczekiwanie czerwony, przed przeprojektowaniem działającego serwera proxy należy sprawdzić historię problemów dla danej wersji. Zobacz CollaboraOnline/zgłoszenie online nr 16032 .

Kiedy zastosować inny projekt

Zakończenie połączenia SSL po stronie serwera proxy jest uzasadnione, gdy odwrotny serwer proxy i Collabora komunikują się przez zaufany interfejs lokalny lub odizolowaną sieć prywatną. Jeśli ruch między Nginx a CODE przechodzi przez niezaufaną sieć, zwykły protokół HTTP na wewnętrznym hoście może nie spełniać wymagań bezpieczeństwa. W takim przypadku należy użyć protokołu TLS również do obsługi backendu lub umieścić obie usługi w chronionej sieci, w której przechwycenie nie stanowi realnego zagrożenia.

Podobnie, jeśli korzystasz już z zarządzanego przez platformę ruchu przychodzącego, który poprawnie obsługuje certyfikaty, routing i WebSockets, dodanie drugiej warstwy Nginx tylko dla Collabora nie przyniesie większych korzyści. Prawidłowa architektura to taka, która zapewnia pojedynczą, obserwowalną granicę TLS bez zbędnych przeskoków.

Ostateczna lista kontrolna walidacji

• Nazwa hosta Collabora jest rozwiązywana na odwrotny serwer proxy.
• Port 443 reprezentuje zaufany certyfikat dla tej nazwy hosta.
• CODE nie jest niepotrzebnie udostępniany publicznemu Internetowi na porcie 9980.
• ssl.enable=falsei ssl.termination=truesą stosowane w projektowaniu zaplecza HTTP.
• Nginx może nawiązać połączenie z CODE na swoim prywatnym adresie.
• /hosting/discoveryodpowiada poprzez publiczny adres URL HTTPS.
• Aktualizacja WebSocket /cool/.../wsprzebiegła pomyślnie.
• Prawdziwy dokument otwiera się, edytuje, zapisuje i ponownie otwiera.
• Przypiąłeś i przetestowałeś dokładną wersję obrazu KODU, którą planujesz wdrożyć.

Jeśli wszystkie te kontrole zakończą się powodzeniem, zakończenie SSL działa: ruch zewnętrzny jest chroniony przez HTTPS, Collabora uznaje połączenie publiczne za bezpieczne, a ścieżka edycji pozostaje funkcjonalna. Jeśli jedna kontrola się nie powiedzie, rozwiąż problem na tym poziomie, zamiast zmieniać kilka części stosu jednocześnie.