Metti ONLYOFFICE Docs dietro HAProxy senza interrompere la modifica

Esegui ONLYOFFICE Docs dietro HAProxy terminando HTTPS sul proxy, inoltrando l'host e lo schema originali e consentendo connessioni WebSocket a lunga durata. Inizia con un Document Server funzionante; aggiungi altri backend solo quando la tua implementazione di ONLYOFFICE è configurata per il funzionamento multi-nodo supportato, non semplicemente perché HAProxy può distribuire le richieste.

È possibile che HAProxy bilanci il carico di due Document Server indipendenti?

HAProxy può distribuire le richieste HTTP tra i nodi, ma ciò non trasforma due installazioni autonome di ONLYOFFICE in un cluster di modifica coordinato. Una sessione di modifica ha connessioni persistenti e uno stato dell'applicazione. L' esempio ufficiale ONLYOFFICE attivo-attivo utilizza controlli di integrità del backend e un cookie di persistenza; questi sono meccanismi di routing, non sostitutivi dei servizi condivisi e dell'architettura a livello di applicazione richiesti dalla tua edizione.

Per un'installazione convenzionale a server singolo, utilizzare solo docs1il backend indicato di seguito. Per due nodi, verificare innanzitutto l'architettura del cluster, l'edizione supportata, le dipendenze condivise, la compatibilità della versione e la configurazione JWT con la documentazione di distribuzione di ONLYOFFICE o con il supporto del fornitore. Gli indirizzi di esempio — 10.0.10.21e 10.0.10.22— sono IP privati ​​a scopo illustrativo, non host rilevati.

Quali elementi devono funzionare correttamente prima di modificare HAProxy?

Il nome pubblico docs.example.comdeve risolversi nell'endpoint HAProxy. HAProxy necessita delle porte TCP in entrata 80 e 443 e dell'accesso alla rete privata per ogni Document Server sulla porta 80. L'applicazione di gestione documentale deve inoltre essere in grado di raggiungere l'indirizzo pubblico di Docs, mentre ONLYOFFICE deve essere in grado di recuperare i documenti e inviare callback all'applicazione. Mantieni privato il traffico HTTP del backend; crittografa separatamente il passaggio al backend se attraversa una rete non attendibile.

1. Verificare ogni Document Server dall'host proxy. Eseguire curl -i http://10.0.10.21/healthchecke, se presente, curl -i http://10.0.10.22/healthcheck. Un endpoint di integrità operativo normalmente restituisce HTTP 200 con un corpo di true. Indagare su routing, firewall o integrità del server prima di configurare il bilanciamento se uno di questi non funziona.
2. Confermare un segreto JWT fisso. Il Document Server e il suo connettore devono concordare sul segreto del token. Per le installazioni Docker, ONLYOFFICE documenta la JWT_SECRETvariabile d'ambiente; a partire dalla versione 7.2 di Docs, affidarsi a un segreto generato automaticamente può causare errori di integrazione dopo la ricreazione o il riavvio. Nelle implementazioni multi-nodo supportate, allineare i segreti tra i nodi in base all'architettura del fornitore.

Questi controlli seguono le linee guida di installazione di Docker e le istruzioni di configurazione JWT del fornitore . Non disabilitare JWT solo per aggirare un errore del proxy.

Come si configura HTTPS e si inoltrano le intestazioni corrette?

Passaggio 1: Preparare il certificato

Ottieni un certificato attendibile che copra l'area di validità docs.example.com. In questo esempio Linux, HAProxy legge un file PEM contenente la catena di certificati seguita dalla chiave privata. Se i certificati esistono già altrove, sostituisci i percorsi con quelli. Limita l'accesso al file PEM combinato e predisponi la sua ricostruzione al rinnovo del certificato.

sudo install -d -m 700 /etc/haproxy/certs
sudo sh -c 'umask 077; cat /etc/letsencrypt/live/docs.example.com/fullchain.pem /etc/letsencrypt/live/docs.example.com/privkey.pem > /etc/haproxy/certs/docs.example.com.pem'

Passaggio 2: Aggiungere il frontend e il backend

Eseguite un backup della configurazione esistente /etc/haproxy/haproxy.cfge adattate le sezioni seguenti, anziché sostituire ciecamente le impostazioni di logging o di servizio specifiche della distribuzione. Questa è una configurazione esemplificativa per le versioni moderne di HAProxy. Accetta solo HTTP per il reindirizzamento, termina HTTPS sulla porta 443, inoltra l'host pubblico e lo schema e monitora l'endpoint di integrità dell'applicazione.

global
    log /dev/log local0

defaults
    mode http
    log global
    option httplog
    option forwardfor
    timeout connect 5s
    timeout client 60s
    timeout server 60s
    timeout tunnel 1h

frontend docs_http
    bind :80
    http-request redirect scheme https code 301

frontend docs_https
    bind :443 ssl crt /etc/haproxy/certs/docs.example.com.pem
    http-request set-header X-Forwarded-Proto https
    http-request set-header X-Forwarded-Host %[req.hdr(Host)]
    default_backend docs_nodes

backend docs_nodes
    option http-server-close
    balance roundrobin
    cookie SERVERID insert indirect nocache
    option httpchk GET /healthcheck
    http-check expect string true
    server docs1 10.0.10.21:80 check cookie docs1
    server docs2 10.0.10.22:80 check cookie docs2

Rimuovi la docs2riga a meno che il secondo nodo non sia effettivamente pronto. Il cookie di persistenza aiuta le successive richieste HTTP a tornare al nodo selezionato. HAProxy gestisce un aggiornamento HTTP WebSocket senza una riscrittura URL speciale; timeout tunnel 1hconsente alle connessioni aggiornate inattive di rimanere aperte più a lungo rispetto alle richieste normali. La documentazione di HAProxy WebSocket spiega questo comportamento.

X-Forwarded-ProtoL' impostazione httpsè corretta in questo caso perché questo frontend termina HTTPS pubblico. Non fidarti di uno schema di inoltro fornito dal client o di un host arbitrario al confine esposto a Internet. La documentazione del proxy ONLYOFFICE richiede specificamente X-Forwarded-Protodi X-Forwarded-Hostmantenere il contesto URL esterno.

Come si deve ricaricare e testare il bilanciatore di carico?

Passaggio 3: Convalidare prima di invertire il traffico

Verifica la sintassi prima di ricaricare. Un codice di uscita diverso da zero indica che è necessario risolvere l'errore di configurazione o di certificato segnalato prima di procedere.

sudo haproxy -c -f /etc/haproxy/haproxy.cfg
sudo systemctl reload haproxy
curl -i https://docs.example.com/healthcheck

La risposta pubblica al controllo di integrità dovrebbe mostrare HTTP 200 truequando un backend è integro. HAProxy utilizza le direttive option httpchke http-check expectper rimuovere i nodi non funzionanti dalla rotazione delle nuove richieste; consultare la relativa documentazione di riferimento sul controllo di integrità . Un controllo superato non dimostra che la modifica dei documenti o la consegna delle callback funzionino correttamente.

Passaggio 4: Conferma la modifica, i WebSocket e il salvataggio

Apri un documento tramite la tua applicazione integrata, ad esempio un sistema di gestione documentale connesso a ONLYOFFICE Docs. Negli strumenti per sviluppatori del browser, utilizza il pannello Rete per esaminare la connessione WebSocket: l'handshake di aggiornamento dovrebbe avere esito positivo, in genere con stato HTTP 101 Switching Protocols. Apporta una piccola modifica, chiudi l'editor, riapri il documento e verifica che la modifica sia stata salvata. Per una distribuzione a due nodi correttamente supportata, testa anche un secondo collaboratore e un'eventuale disattivazione di un singolo nodo durante una finestra di manutenzione.

Se il controllo di integrità pubblico funziona ma l'editor si blocca o si disconnette, esaminare gli avvisi di contenuto misto, gli errori WebSocket, le mancate corrispondenze JWT e verificare se l'applicazione del documento riesce a raggiungere l'URL di Documents pubblicizzato. Se un documento si apre ma non viene salvato, verificare la raggiungibilità del callback dal Document Server all'applicazione di origine anziché modificare la policy round-robin di HAProxy. Una sessione WebSocket attiva interrotta potrebbe comunque richiedere la riconnessione del client; i controlli di integrità del backend non garantiscono un failover di modifica senza interruzioni.

Verifica finale: sia l'endpoint di salute pubblica che un test di modifica e riapertura reale dovrebbero avere esito positivo. Mantenere in rotazione solo nodi verificati e supportati, confermare che il rinnovo del certificato ricarichi il PEM corretto e monitorare i log di HAProxy per rilevare risposte 502/503 ripetute o disconnessioni WebSocket impreviste.