So konfigurieren Sie HTTPS und ein SSL-Zertifikat für ONLYOFFICE Docker

Um ONLYOFFICE Docs in Docker hinter HTTPS zu betreiben, verwenden Sie ein Zertifikat, das mit dem öffentlichen Hostnamen übereinstimmt, stellen Sie es im Container bereit und veröffentlichen Sie den HTTPS-Port des Containers. HTTPS ist eine verschlüsselte Webverbindung; ein TLS-Zertifikat hilft Browsern zu bestätigen, dass sie den erwarteten Server erreicht haben. Diese Anleitung verwendet ein Zertifikat und einen privaten Schlüssel, die Sie bereits von einer vertrauenswürdigen Zertifizierungsstelle (CA) erhalten haben. Wenn Sie einen Reverse-Proxy verwenden, folgen Sie der separaten Anleitung unten, da der Proxy möglicherweise HTTPS verarbeitet.

Welche HTTPS-Konfiguration passt zu Ihrer Bereitstellung?

ONLYOFFICE Docs kann HTTPS direkt aus seinem Docker-Container bereitstellen. Alternativ kann ein Reverse-Proxy wie NGINX oder Traefik HTTPS-Anfragen entgegennehmen und an Docs weiterleiten. Direktes TLS ist eine unkomplizierte Lösung für einen eigenständigen Server, dessen öffentliche Ports 80 und 443 verfügbar sind. Ein Reverse-Proxy ist oft einfacher, wenn ein anderer Webdienst diese Ports bereits belegt oder mehrere Websites einen Server gemeinsam nutzen. Vermeiden Sie eine unstrukturierte Konfiguration beider Ebenen: Legen Sie fest, welche Komponente die TLS-Terminierung übernimmt, und dokumentieren Sie, ob die Verbindung zwischen Proxy und Container über HTTP oder HTTPS erfolgt.

Diese Anleitung konfiguriert HTTPS direkt mit einem von einer Zertifizierungsstelle ausgestellten Zertifikat. ONLYOFFICE beschreibt außerdem eine automatische Let's Encrypt-Option LETS_ENCRYPT_DOMAIN; LETS_ENCRYPT_MAILhierfür müssen die Ports 80 und 443 erreichbar und nicht von einem Proxy belegt sein. Ein selbstsigniertes Zertifikat ist für ein privates Testnetzwerk nützlich, wird aber von öffentlichen Browsern und verbundenen Speicherdiensten nicht automatisch als vertrauenswürdig eingestuft.

Was sollten Sie zuerst vorbereiten?

• Ein Linux-Host mit installierter Docker Engine und dem Docker Compose-Plugin.
• Ein DNS-A-Eintrag für den Hostnamen, z. B. „example.com“ docs.example.com, der auf die öffentliche IPv4-Adresse des Hosts verweist. Fügen Sie einen AAAA-Eintrag nur dann hinzu, wenn IPv6 konfiguriert und erreichbar ist.
• Regeln für eingehende Firewalls und Cloud-Firewalls, die TCP 443 zulassen. Wenn Sie Zertifikate mit HTTP-Validierung anfordern oder erneuern, kann auch TCP 80 erforderlich sein.
• Eine Zertifikatskette für den exakten Hostnamen und den zugehörigen privaten Schlüssel. Zertifizierungsstellen stellen üblicherweise eine vollständige Zertifikatskettendatei und eine Datei mit dem privaten Schlüssel bereit.
• Ein persistentes Hostverzeichnis für das ONLYOFFICE-Datenvolume und ein sicheres JWT-Geheimnis. JWT (JSON Web Token) ist ein gemeinsames Geheimnis, das zur Authentifizierung von Anfragen zwischen Docs und einer integrierenden Anwendung verwendet wird.

Schritt 1: Zertifikat und privaten Schlüssel auf dem Host ablegen

In diesem Beispiel speichert der Host persistente Daten unter /srv/onlyoffice/data. Ersetzen Sie den Beispiel-Hostnamen und die Pfade durch Ihre eigenen. Speichern Sie die vollständige Zertifikatskette als tls.crtund den zugehörigen privaten Schlüssel als tls.keyin einem certsUnterverzeichnis:

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

Der private Schlüssel darf nur von dem Konto oder Dienst gelesen werden, der ihn benötigt. Fügen Sie ihn nicht in eine Compose-Datei, einen Fehlerbericht oder ein öffentliches Repository ein. Falls Docker den Schlüssel aufgrund von Besitzverhältnissen oder Berechtigungen nicht lesen kann, beschränken Sie den Zugriff auf die Laufzeitumgebung des Containers, anstatt den Schlüssel für alle zugänglich zu machen.

Überprüfen Sie vor dem Start des Dienstes die Gültigkeitsdaten und Hostnamen des Zertifikats:

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

Die Liste der alternativen Subjektnamen (SAN) sollte den exakten Hostnamen enthalten, den die Benutzer besuchen werden. Sie können die aus dem Zertifikat abgeleiteten öffentlichen Schlüssel und den privaten Schlüssel vergleichen; die beiden Hashwerte sollten übereinstimmen.

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

Schritt 2: Konfigurieren Sie den Docker Compose-Dienst

/var/www/onlyoffice/Data/certsDie Docker-Dokumentation von ONLYOFFICE platziert Zertifikate unter `/var/ tls.crtlib tls.key/ document onlyoffice.crt...onlyoffice.key

Erstellen Sie eine compose.yamlDatei wie diese und ersetzen Sie den Beispiel-JWT-Wert durch ein für Ihre Installation generiertes Geheimnis. Das untenstehende Image-Tag ist eine Beispielversion; prüfen Sie die offizielle Image-Liste und verwenden Sie eine Version, die Sie dauerhaft pflegen möchten.

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

Generieren Sie ein sicheres Geheimnis openssl rand -hex 32und fügen Sie es mit den entsprechenden Dateiberechtigungen in die Umgebungsvariablen-Datei oder die Compose-Konfiguration ein. Wenn eine andere Anwendung mit Docs integriert ist, konfigurieren Sie diese Anwendung mit demselben JWT-Geheimnis und der öffentlichen HTTPS-Adresse. Bei einer bestehenden Installation müssen Sie die vorhandenen Volumes, Netzwerke, Umgebungsvariablen und Integrationseinstellungen beim Bearbeiten der Compose-Datei beibehalten; ersetzen Sie keine funktionierende Dienstdefinition durch dieses Minimalbeispiel.

Starten oder erstellen Sie den Dienst neu aus dem Verzeichnis, das die Compose-Datei enthält:

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

Schritt 3: Testen Sie HTTPS und das Zertifikat

Öffnen Sie die https://docs.example.comSeite in einem Browser und ersetzen Sie dabei Ihren Hostnamen. Prüfen Sie, ob der Browser eine sichere Verbindung anzeigt und keine Namenskonflikte, abgelaufene Zertifikate oder nicht vertrauenswürdige Aussteller meldet. Stellen Sie sicher, dass die Willkommensseite von ONLYOFFICE Docs geladen wird. Wenn Docs mit Nextcloud, ownCloud oder einer anderen Plattform verbunden ist, testen Sie zusätzlich das Öffnen und Speichern eines Dokuments; ein Browser-Lock allein beweist nicht, dass die Callback-Anfragen der Integration oder die JWT-Konfiguration funktionieren.

Fragen Sie den Server über die Shell nach seinem TLS-Zertifikat und testen Sie die HTTPS-Antwort:

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

Diese -servernameOption sendet den Hostnamen per Server Name Indication (SNI). Dadurch kann ein Server das richtige Zertifikat auswählen, wenn mehrere Hostnamen dieselbe Adresse verwenden. Datum, Aussteller und SAN des Zertifikats müssen mit dem installierten Zertifikat übereinstimmen. Überprüfen Sie dies, docker compose logsfalls der Browser keine Verbindung herstellen kann oder der Container wiederholt neu startet.

Was ist, wenn ein Reverse-Proxy bereits HTTPS verarbeitet?

Wenn NGINX, Traefik, Caddy oder ein Hosting-Gateway bereits die öffentlichen Ports 80 und 443 belegt, empfiehlt es sich, das öffentliche Zertifikat auf diesem Proxy zu installieren. In dieser Topologie sollte der Docs-Container nur in einem privaten Docker-Netzwerk veröffentlicht oder sein HTTP-Port an Loopback gebunden werden. Anschließend wird der Proxy so konfiguriert, dass er die erforderlichen Anfragen und den WebSocket-Verkehr weiterleitet. Die ONLYOFFICE-Adresse der integrierenden Anwendung wird auf die öffentliche https://URL gesetzt. Beachten Sie die aktuellen Anweisungen des Proxys und von ONLYOFFICE bezüglich weitergeleiteter Header und Upstream-TLS. Der Port 443 des Containers darf nicht auf demselben Host-Port veröffentlicht werden, den der Proxy bereits verwendet.

Wählen Sie dieses Muster, wenn ein Proxy den Datenverkehr für mehrere Dienste weiterleitet. Verwenden Sie die oben beschriebene direkte Container-Konfiguration, wenn Docs den öffentlichen HTTPS-Endpunkt verwalten soll und die benötigten Ports frei sind. Wenn der Proxy über HTTP eine Verbindung zum Container herstellt, ist dieser interne Hop unverschlüsselt. Halten Sie ihn in einem vertrauenswürdigen privaten Netzwerk oder konfigurieren Sie Upstream-TLS, falls Ihre Sicherheitsanforderungen dies erfordern.

Häufige Probleme und wie man sie behebt

• Der Browser meldet, dass das Zertifikat ungültig ist. Überprüfen Sie den SAN-Hostnamen, das Ablaufdatum des Zertifikats, die vollständige Zertifikatskette und ob der DNS-Eintrag auf den gewünschten Host verweist. Ein Zertifikat für die Hauptdomain deckt nicht automatisch eine Subdomain ab.
• Der Container meldet ein fehlendes Zertifikat oder einen fehlenden Schlüssel. Überprüfen Sie den Quellpfad des Hosts, das Zielverzeichnis für die Bind-Mount-Einbindung, die exakten Dateinamen und die beiden SSL_..._PATHWerte. Die Docker- --mountSyntax erfordert, dass der Quellpfad existiert; Compose-Bind-Mounts müssen ebenfalls auf das vorgesehene, vorhandene Verzeichnis verweisen.
• Port 443 ist bereits belegt. Beenden Sie den Konflikt verursachenden Dienst, verwenden Sie einen Reverse-Proxy oder wählen Sie einen anderen öffentlichen Host-Port und stellen Sie sicher, dass die URL und die Firewall dies widerspiegeln. Wenn ein Proxy vorgeschaltet ist, sollte dieser üblicherweise den öffentlichen Port 443 belegen.
• HTTPS funktioniert, aber die Dokumentbearbeitung schlägt fehl. Überprüfen Sie die Integrations-URL, das JWT-Geheimnis beider Dienste, die Proxy-Weiterleitungsregeln und ob Docs die Speicherplattform erreichen kann. Testen Sie einen tatsächlichen Öffnungs- und Speichervorgang.
• Das Zertifikat wurde erneuert, aber die Website verwendet weiterhin das alte. Prüfen Sie, ob die Erneuerung die eingebundene Datei aktualisiert und ONLYOFFICE sie neu geladen hat. Starten Sie den Dienst nach der Erneuerung gegebenenfalls neu, beispielsweise mit einem Certbot-Bereitstellungshook, der docker compose restart documentserveraus dem Compose-Projektverzeichnis ausgeführt wird. Testen Sie die Erneuerung mit der Testlaufoption von Certbot, bevor Sie auf Automatisierung setzen.

Halten Sie das Zertifikat auf dem neuesten Stand.

Die HTTPS-Einrichtung ist erst mit der geplanten Zertifikatserneuerung abgeschlossen. Protokollieren Sie, wer das Zertifikat ausstellt und erneuert, wo der private Schlüssel gespeichert ist, welcher Prozess die erneuerten Dateien in das eingebundene Verzeichnis kopiert und wie der Dienst diese neu lädt. Führen Sie nach jeder Erneuerung einen Testlauf des Erneuerungsclients durch, überwachen Sie den Ablauf des Zertifikats und überprüfen Sie den öffentlichen Endpunkt. Wenn Sie die integrierten Let's Encrypt-Variablen von ONLYOFFICE anstelle eines hostverwalteten Zertifikats verwenden, befolgen Sie die aktuellen Docker-Anweisungen für diese Methode und überprüfen Sie das Erneuerungsverhalten für das von Ihnen verwendete Image und die entsprechende Bereitstellung.

Weitere Informationen finden Sie in der ONLYOFFICE-Dokumentation zur Docker-Installation und HTTPS-Verwaltung , der Docker-Bind-Mount-Dokumentation , der Docker-Compose-Dokumentation , den offiziellen ONLYOFFICE-Docker-Image-Tags und den offiziellen Anweisungen von Certbot . Die verfügbaren Tags und Schnittstellendetails können sich ändern; überprüfen Sie diese daher vor der Vorbereitung einer neuen Bereitstellung.