Jak skonfigurować protokół HTTPS i certyfikat SSL dla systemu ONLYOFFICE Docker

Aby umieścić ONLYOFFICE Docs za HTTPS w Dockerze, użyj certyfikatu pasującego do publicznej nazwy hosta, udostępnij go w kontenerze i opublikuj port HTTPS kontenera. HTTPS to szyfrowane połączenie internetowe; certyfikat TLS pomaga przeglądarkom zweryfikować, czy dotarły do ​​oczekiwanego serwera. W tym przewodniku wykorzystano certyfikat i klucz prywatny, które uzyskano już od zaufanego urzędu certyfikacji (CA). Jeśli korzystasz z odwrotnego serwera proxy, skorzystaj z oddzielnej opcji poniżej, ponieważ serwer proxy może obsługiwać HTTPS.

Która konfiguracja HTTPS jest odpowiednia dla Twojego wdrożenia?

ONLYOFFICE Docs może obsługiwać HTTPS bezpośrednio z kontenera Docker, a odwrotny serwer proxy, taki jak NGINX lub Traefik, może akceptować HTTPS i przekierowywać żądania do Docs. Bezpośredni TLS to prosty wybór dla samodzielnego serwera, którego publiczne porty 80 i 443 są dostępne. Odwrotny serwer proxy jest często prostszy, gdy inna usługa sieciowa już posiada te porty lub kilka witryn współdzieli jeden serwer. Unikaj konfigurowania obu warstw „na ślepo”: zdecyduj, który komponent kończy TLS i udokumentuj, czy połączenie proxy z kontenerem jest HTTP, czy HTTPS.

Ten przewodnik konfiguruje bezpośredni protokół HTTPS z certyfikatem wydanym przez urząd certyfikacji. ONLYOFFICE dokumentuje również automatyczną opcję Let's Encrypt z użyciem komend LETS_ENCRYPT_DOMAINi LETS_ENCRYPT_MAIL; wymaga ona, aby porty 80 i 443 były osiągalne i nie były już zajęte przez serwer proxy. Certyfikat podpisany samodzielnie jest przydatny w prywatnej sieci testowej, ale przeglądarki publiczne i usługi pamięci masowej nie będą mu automatycznie ufać.

Co należy przygotować w pierwszej kolejności?

• Host Linux z zainstalowanym Docker Engine i wtyczką Docker Compose.
• Rekord DNS dla nazwy hosta, taki jak docs.example.com, wskazujący na publiczny adres IPv4 hosta. Dodaj rekord AAAA tylko wtedy, gdy IPv6 jest skonfigurowany i osiągalny.
• Reguły zapory przychodzącej i zapory w chmurze, które zezwalają na protokół TCP 443. Jeśli żądasz lub odnawiasz certyfikaty z walidacją HTTP, może być również wymagany protokół TCP 80.
• Łańcuch certyfikatów dla dokładnej nazwy hosta i odpowiadającego jej klucza prywatnego. Urzędy certyfikacji zazwyczaj udostępniają pełny plik łańcucha i plik klucza prywatnego.
• Trwały katalog hosta dla woluminu danych ONLYOFFICE i silny tajny klucz JWT. JWT (JSON Web Token) to współdzielony tajny klucz używany do uwierzytelniania żądań między Docs a integrującą aplikacją.

Krok 1: Umieść certyfikat i klucz prywatny na hoście

W tym przykładzie host przechowuje trwałe dane w katalogu /srv/onlyoffice/data. Zastąp przykładową nazwę hosta i ścieżki własnymi. Przechowuj cały łańcuch certyfikatu jako tls.crti pasujący klucz prywatny jako tls.keyw certspodkatalogu:

sudo mkdir -p /srv/onlyoffice/data/certs
sudo install -m 0644 /path/to/fullchain.pem /srv/onlyoffice/data/certs/tls.crt
sudo install -m 0600 /path/to/privkey.pem /srv/onlyoffice/data/certs/tls.key
sudo chown root:root /srv/onlyoffice/data/certs/tls.key

Klucz prywatny powinien być czytelny tylko dla konta lub usługi, która go potrzebuje. Nie wklejaj go do pliku Compose, zgłoszenia problemu ani publicznego repozytorium. Jeśli Docker nie może odczytać klucza z powodu własności lub uprawnień, dostosuj dostęp ściśle do środowiska wykonawczego kontenera, zamiast udostępniać klucz wszystkim użytkownikom.

Przed uruchomieniem usługi sprawdź daty i nazwy hostów certyfikatu:

openssl x509 -in /srv/onlyoffice/data/certs/tls.crt -noout -subject -issuer -dates -ext subjectAltName

Lista alternatywnych nazw podmiotu (SAN) powinna zawierać dokładną nazwę hosta, którą będą odwiedzać użytkownicy. Możesz porównać klucze publiczne uzyskane z certyfikatu i klucza prywatnego; oba skróty powinny być zgodne:

openssl x509 -in /srv/onlyoffice/data/certs/tls.crt -pubkey -noout | openssl sha256
openssl pkey -in /srv/onlyoffice/data/certs/tls.key -pubout | openssl sha256

Krok 2: Skonfiguruj usługę Docker Compose

Dokumentacja Dockera firmy ONLYOFFICE umieszcza certyfikaty w domenie /var/www/onlyoffice/Data/certs. Aktualna lista zmiennych środowiskowych zawiera domyślne nazwy plików certyfikatów jako , tls.crta tls.keyprzykładowe instrukcje instalacji również używają onlyoffice.crt. onlyoffice.keyJawne ustawienie ścieżek pozwala uniknąć polegania na konwencji nazw plików. Katalog hosta jest montowany metodą bind-mount w odpowiadającym mu katalogu danych kontenera, a port 443 jest publikowany jako port hosta 443.

Utwórz compose.yamlplik podobny do tego, zastępując przykładową wartość JWT kluczem tajnym wygenerowanym dla Twojej instalacji. Poniższy tag obrazu to wersja przykładowa; sprawdź oficjalną listę obrazów i użyj wersji, którą zamierzasz zachować.

services:
  documentserver:
    image: onlyoffice/documentserver:9.4.0
    container_name: onlyoffice-documentserver
    restart: unless-stopped
    ports:
      - "443:443"
    volumes:
      - /srv/onlyoffice/data:/var/www/onlyoffice/Data
    environment:
      SSL_CERTIFICATE_PATH: /var/www/onlyoffice/Data/certs/tls.crt
      SSL_KEY_PATH: /var/www/onlyoffice/Data/certs/tls.key
      JWT_SECRET: replace_with_a_long_random_secret

Wygeneruj silny klucz tajny openssl rand -hex 32i umieść go w pliku środowiska lub konfiguracji Compose z odpowiednimi uprawnieniami. Jeśli inna aplikacja integruje się z Dokumentami, skonfiguruj ją z tym samym kluczem tajnym JWT i publicznym adresem HTTPS. Jeśli jest to istniejąca instalacja, zachowaj jej woluminy, sieci, inne zmienne środowiskowe i ustawienia integracji podczas edycji istniejącego pliku Compose; nie zastępuj działającej definicji usługi tym prostym przykładem.

Uruchom lub utwórz ponownie usługę z katalogu zawierającego plik Compose:

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

Krok 3: Przetestuj protokół HTTPS i certyfikat

Otwórz https://docs.example.comw przeglądarce, zastępując ją nazwą hosta. Sprawdź, czy przeglądarka wyświetla bezpieczne połączenie i nie zgłasza niezgodności nazw, wygasłego certyfikatu ani niezaufanego wystawcy. Upewnij się, że strona powitalna ONLYOFFICE Docs się ładuje. Gdy Docs jest połączony z NextCloud, ownCloud lub inną platformą, przetestuj również otwieranie i zapisywanie dokumentu; sama blokada przeglądarki nie jest dowodem na to, że żądania zwrotne integracji ani konfiguracja JWT działają.

Z poziomu powłoki poproś serwer o certyfikat TLS i przetestuj odpowiedź HTTPS:

openssl s_client -connect docs.example.com:443 -servername docs.example.com </dev/null
curl -I https://docs.example.com/

Opcja -servernamewysyła nazwę hosta za pomocą funkcji Server Name Indication (SNI), która umożliwia serwerowi wybór odpowiedniego certyfikatu, gdy wiele nazw hostów współdzieli adres. Daty certyfikatu, wystawca i SAN powinny być zgodne z zainstalowanym certyfikatem. Sprawdź, docker compose logsczy przeglądarka nie może nawiązać połączenia lub czy kontener wielokrotnie się restartuje.

A co jeśli odwrotny serwer proxy obsługuje już protokół HTTPS?

Jeśli NGINX, Traefik, Caddy lub brama hostingowa posiada już publiczne porty 80 i 443, lepszym rozwiązaniem może być instalacja certyfikatu publicznego na tym serwerze proxy. W takiej topologii należy opublikować kontener Docs tylko w prywatnej sieci Docker lub powiązać jego port HTTP z pętlą zwrotną, a następnie skonfigurować serwer proxy do przekazywania wymaganych żądań i ruchu WebSocket. Należy ustawić adres ONLYOFFICE aplikacji integrującej na publiczny https://adres URL. Postępuj zgodnie z aktualnymi instrukcjami serwera proxy i ONLYOFFICE dotyczącymi przekazywanych nagłówków i upstream TLS; nie należy publikować portu 443 kontenera na tym samym porcie hosta, którego serwer proxy już używa.

Wybierz ten wzorzec, gdy jeden serwer proxy kieruje ruchem dla wielu usług. Użyj opisanej powyżej bezpośredniej konfiguracji kontenera, gdy Docs powinien być właścicielem publicznego punktu końcowego HTTPS, a wymagane porty są wolne. Jeśli serwer proxy łączy się z kontenerem przez HTTP, ten wewnętrzny przeskok nie jest szyfrowany; przechowuj go w zaufanej sieci prywatnej lub skonfiguruj protokół TLS dla nadrzędnego serwera, jeśli wymagają tego Twoje wymagania bezpieczeństwa.

Typowe problemy i sposoby ich rozwiązania

• Przeglądarka informuje, że certyfikat jest nieprawidłowy. Sprawdź nazwę hosta SAN, datę ważności certyfikatu, cały łańcuch i upewnij się, że DNS wskazuje na docelowego hosta. Certyfikat dla domeny podstawowej nie obejmuje automatycznie subdomeny.
• Kontener zgłasza brak certyfikatu lub klucza. Sprawdź ścieżkę źródłową hosta, miejsce docelowe montowania powiązania, dokładne nazwy plików i dwie SSL_..._PATHwartości. Składnia Dockera --mountwymaga, aby ścieżka źródłowa istniała; montowania powiązania Compose powinny również wskazywać na docelowy istniejący katalog.
• Port 443 jest już przydzielony. Zatrzymaj usługę powodującą konflikt, użyj odwrotnego proxy lub wybierz inny publiczny port hosta i upewnij się, że adres URL i zapora sieciowa to odzwierciedlają. Jeśli serwer proxy jest na froncie, zazwyczaj powinien posiadać publiczny port 443.
• HTTPS działa, ale edycja dokumentów nie działa. Sprawdź adres URL integracji, tajny klucz JWT w obu usługach, reguły przekierowania proxy oraz czy Dokumenty mogą połączyć się z platformą pamięci masowej. Przetestuj rzeczywisty cykl otwierania i zapisywania.
• Certyfikat odnawia się, ale witryna nadal obsługuje stary certyfikat. Sprawdź, czy odnowienie zaktualizowało plik zamontowany na hoście i czy ONLYOFFICE go przeładował. W razie potrzeby uruchom ponownie usługę po odnowieniu, na przykład za pomocą haka wdrożenia Certbota uruchamianego docker compose restart documentserverz katalogu projektu Compose. Przetestuj odnowienie za pomocą opcji uruchomienia próbnego Certbota, zanim zaczniesz polegać na automatyzacji.

Utrzymuj aktualność certyfikatu

Konfiguracja protokołu HTTPS nie zostanie ukończona, dopóki nie zostanie zaplanowane odnowienie. Zapisz, kto wystawia i odnawia certyfikat, gdzie przechowywany jest klucz prywatny, który proces kopiuje odnowione pliki do zamontowanego katalogu oraz w jaki sposób usługa je przeładowuje. Przeprowadź test próbny klienta odnawiania, monitoruj wygasanie certyfikatu i weryfikuj publiczny punkt końcowy po każdym odnowieniu. Jeśli używasz wbudowanych zmiennych Let's Encrypt usługi ONLYOFFICE zamiast certyfikatu zarządzanego przez hosta, postępuj zgodnie z aktualnymi instrukcjami Dockera dla tej metody i sprawdź jej zachowanie podczas odnawiania dla konkretnego obrazu i wdrożenia, które uruchamiasz.

W celu uzyskania informacji zapoznaj się z dokumentacją ONLYOFFICE Docs dotyczącą instalacji Dockera i protokołu HTTPS , dokumentacją Docker bind-mount , dokumentacją Docker Compose , oficjalnymi tagami obrazów Dockera w ONLYOFFICE oraz oficjalnymi instrukcjami Certbota . Dostępne tagi i szczegóły interfejsu mogą ulec zmianie; sprawdź je podczas przygotowywania nowego wdrożenia.