Configurare HTTPS per la documentazione ONLYOFFICE in Docker

Per una connessione diretta a ONLYOFFICE Docs, pubblica la porta 443 del container, rendi persistenti i file del certificato nella directory dei dati montata e configura il container in modo che punti a tali file. Se un proxy inverso fornisce già HTTPS, mantieni TLS su tale proxy e inoltra l'host e il protocollo originali a ONLYOFFICE anziché abilitare un secondo endpoint TLS per impostazione predefinita.

Ad esempio, se il nome host pubblico è docs.example.com, innanzitutto determina se punta direttamente al Document Server o a un proxy. Utilizza solo la configurazione corrispondente riportata di seguito.

1. Decidi dove termina HTTPS

La connessione TLS termina dove viene decrittografata la connessione HTTPS: all'interno del container ONLYOFFICE o presso un proxy inverso. Scegliere il componente che riceve la connessione pubblica.

• Accesso diretto: i client si connettono https://docs.example.comalla porta 443 dell'host, che è mappata alla porta 443 del container. Il container del Document Server necessita di un certificato e della relativa chiave privata.
• Accesso tramite proxy: i client si connettono al proxy tramite HTTPS; il proxy inoltra il traffico al Document Server attraverso la rete interna. In questa configurazione, il certificato si trova normalmente sul proxy. Le linee guida di ONLYOFFICE per l'utilizzo del proxy richiedono le intestazioni X-Forwarded-Protoe X-Forwarded-Hostin modo che l'applicazione possa identificare lo schema di richiesta pubblico e il nome host.

Il port mapping 443:443non crea HTTPS; si limita a mappare le porte. Per l'accesso diretto, il container deve anche leggere il certificato e la chiave. Se il proxy possiede l'URL pubblico, utilizzare le istruzioni ufficiali di ONLYOFFICE per il reverse proxy .

2. Configurare HTTPS diretto in Docker Compose

Utilizzare questo percorso quando il container fornisce HTTPS direttamente. Per l'accesso pubblico, utilizzare un certificato considerato attendibile dai client per il nome host pubblico. Un certificato autofirmato può crittografare il traffico, ma i client visualizzeranno un avviso sull'identità a meno che non siano configurati separatamente per considerarlo attendibile.

ONLYOFFICE Docs memorizza i certificati di seguito /var/www/onlyoffice/Data/certsper impostazione predefinita e la sua configurazione Docker corrente elenca tls.crte tls.keycome percorsi predefiniti per certificati e chiavi. Gli esempi della documentazione non hanno sempre utilizzato nomi di file identici, quindi questo esempio imposta entrambi i percorsi esplicitamente.

services:
  documentserver:
    # Keep your existing image, environment, networks, and other settings.
    ports:
      - "443:443"
    volumes:
      - ./documentserver-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

Questo è un estratto, non una definizione di servizio sostitutiva. Mantieni le impostazioni esistenti di immagine, JWT, rete e volume. Rispetto al file Compose, posiziona il certificato in ./documentserver-data/certs/tls.crte la chiave corrispondente in ./documentserver-data/certs/tls.key. Includi la catena di certificati fornita dal tuo provider e assicurati che il certificato copra docs.example.com.

Il bind mount mantiene i file al di fuori di un contenitore sostituibile. Limita l'accesso alla chiave privata, assicurandoti al contempo che il contenitore possa leggerla; in caso contrario, l'avvio di HTTPS potrebbe non riuscire. Non condividere mai la chiave in una richiesta di supporto.

3. Applicare la modifica senza sostituire accidentalmente la distribuzione

1. Esegui il backup del file Compose e della directory dei certificati, quindi verifica che il certificato e la chiave corrispondano per il nome host pubblico.
2. Apporta le modifiche a porta, volume e percorso nel servizio esistente. Non avviare un secondo container con la stessa porta host né eliminare i volumi esistenti per applicare TLS.
3. Ricrea il servizio se hai modificato le porte, i punti di montaggio o l'ambiente. Con Compose, esegui il comando docker compose up -d documentserverdalla directory contenente il file Compose, sostituendo il nome effettivo del servizio. Se hai sostituito solo i file del certificato in una directory già montata, riavvia il container esistente in modo che il server ricarichi i file: docker restart <container_name>.
4. Se HTTPS non si avvia, controlla i log di avvio docker logs <container_name>. Prima di modificare impostazioni non correlate, verifica la presenza di errori relativi a file mancanti, autorizzazioni o certificati/chiavi.

Un riavvio non consente di aggiungere un punto di montaggio o modificare le porte pubblicate; per apportare tali modifiche è necessario ricreare il servizio. La sostituzione dei file in un punto di montaggio persistente esistente non richiede una modifica in Compose.

4. Mantieni TLS su un proxy inverso quando questo serve già il dominio

Se un proxy inverso è già terminato https://docs.example.com, conserva la sua chiave privata sul proxy. Inoltra il traffico su una rete controllata e imposta X-Forwarded-Proto: httpsil valore di + X-Forwarded-Hostsull'hostname pubblico. Utilizza l'esempio ufficiale del tuo software proxy.

Il lucchetto del browser protegge la connessione client-proxy, non necessariamente ogni singolo passaggio interno. HTTP su una rete Docker controllata potrebbe essere adatto ad alcune implementazioni; proteggere il passaggio dal proxy al container se attraversa una rete non attendibile.

Un altro limite: la modifica del TLS non risolve un JWT non valido, una porta del firewall bloccata o un indirizzo del server di documenti pubblico errato nelle impostazioni di integrazione. Se il certificato è valido ma il caricamento o la modifica del documento continuano a non funzionare, è consigliabile controllare i log dell'applicazione e del proxy pertinenti anziché rigenerare ripetutamente i certificati.

Verifica il risultato

Da un client in grado di raggiungere il servizio pubblico, apri https://docs.example.come controlla i dettagli del certificato nel browser. Verifica che il nome host corrisponda, che il certificato sia ancora valido e che il browser non segnali un emittente non attendibile o una mancata corrispondenza del nome. Puoi anche controllare l'handshake TLS da un terminale curl -Iv https://docs.example.com; esamina il certificato e l'output della connessione anziché basarti solo sul caricamento della pagina.

Infine, apri un documento dall'applicazione di integrazione. Il successo del browser conferma l'endpoint pubblico, non tutte le impostazioni di integrazione o i percorsi interni. Per gli avvisi relativi ai certificati, ricontrolla hostname, catena, percorsi, autorizzazioni e terminazione TLS. Se HTTPS viene verificato ma la modifica non riesce, controlla i log e le impostazioni di autenticazione o di routing.

Per informazioni dettagliate sui percorsi Docker supportati, le variabili del certificato e le opzioni Let's Encrypt integrate, consultare la documentazione di ONLYOFFICE sull'installazione di Docker e HTTPS . Il comando esatto per aggiornare una distribuzione esistente dipende da come è stata creata originariamente; è importante conservare i volumi e le impostazioni di integrazione correnti di tale distribuzione durante l'applicazione delle modifiche TLS pertinenti.