La regola più importante è questa: posizionare ONLYOFFICE Document Server dietro HAProxy è semplice per un singolo backend, ma un cluster di editor multi-nodo richiede più di un semplice round-robin. La documentazione API attuale di ONLYOFFICE afferma che le richieste per lo stesso documento devono raggiungere lo stesso nodo del Document Server durante la modifica collaborativa. Per le integrazioni moderne, il meccanismo consigliato è il shardkeyparametro di query, che il bilanciatore di carico può utilizzare per l'affinità basata sul documento.
Se si dispone di un solo Document Server e si desidera utilizzare HAProxy per la terminazione HTTPS, un nome host pubblico stabile o controlli di integrità centralizzati, la configurazione è più semplice. Se si dispone di due o più nodi Document Server, è necessario utilizzare gli stessi principi di base del proxy, ma aggiungere il routing basato su shardkeyanziché presumere che il normale round-robin sia sufficiente.
Gli esempi seguenti sono stati verificati rispetto alla documentazione attuale del proxy ONLYOFFICE , alla documentazione della chiave di partizionamento ONLYOFFICE e alle linee guida attuali di HAProxy WebSocket .
HAProxy è un'interfaccia valida quando si desidera un URL pubblico https://docs.example.com, come ad esempio la terminazione TLS sul bilanciatore di carico, controlli di integrità attivi o più nodi Document Server dietro un singolo endpoint. È utile anche quando Nextcloud, ownCloud, DMS personalizzato o applicazione non devono mai connettersi direttamente a un singolo nodo Document Server.
Questa guida presuppone:
Non iniziare dal bilanciatore di carico. Prima verifica che ogni backend sia integro dall'host HAProxy. ONLYOFFICE documenta /healthcheckcome endpoint per il controllo della disponibilità dell'editor. Un server integro restituisce true; il controllo copre le dipendenze principali come il database, il message broker, la connessione Redis e lo storage.
curl -sS http://10.0.10.21/healthcheck
curl -sS http://10.0.10.22/healthcheckRisultato atteso:
true
true
Se uno dei backend non funziona, è necessario innanzitutto risolvere il problema relativo a quel nodo. Le cause più comuni includono regole del firewall, una porta interna errata, servizi del server documenti non in esecuzione o servizi di supporto non disponibili.
ONLYOFFICE è un'applicazione HTTP e utilizza connessioni WebSocket a lunga durata durante la modifica. HAProxy può fungere da proxy per i WebSocket automaticamente dopo l'aggiornamento a HTTP, ma la sua politica di timeout rimane comunque importante. La documentazione di HAProxy raccomanda un timeout tunnelvalore per le connessioni WebSocket aggiornate.
Un punto di riferimento pratico è:
global
log /dev/log local0
log /dev/log local1 notice
daemon
maxconn 4096
defaults
log global
mode http
option httplog
option dontlognull
timeout connect 5s
timeout client 60s
timeout server 60s
timeout tunnel 1h
Un timeout del tunnel di un'ora è solo un esempio, non un requisito universale. Scegli un valore adatto al comportamento di modifica, alle politiche di sicurezza e ai limiti delle risorse della tua organizzazione. Se gli editor si disconnettono a intervalli molto regolari, confronta tale intervallo con i timeout di inattività di HAProxy e di eventuali firewall o reverse proxy a monte.
ONLYOFFICE richiede esplicitamente l'inoltro delle intestazioni quando viene eseguito dietro un proxy. In particolare, X-Forwarded-Protoindica a Document Server se il client originale ha utilizzato HTTP o HTTPS, mentre X-Forwarded-Hostconserva il nome host richiesto dal client.
Un'interfaccia utente pulita per HAProxy potrebbe apparire così:
frontend onlyoffice_http
bind *:80
mode http
http-request redirect scheme https code 301
frontend onlyoffice_https
bind *:443 ssl crt /etc/haproxy/certs/docs.example.com.pem
mode http
option httplog
http-request set-header X-Forwarded-Proto https
http-request set-header X-Forwarded-Host %[req.hdr(Host)]
default_backend onlyoffice_docs
Normalmente, nella moderna modalità HTTP di HAProxy, non è necessario ricreare manualmente le regole in stile NGINX Upgradee Connectionle regole di intestazione. HAProxy riconosce l'aggiornamento da HTTP a WebSocket e commuta la connessione in modalità tunnel. L'importante è non inserire regole che annullino o interrompano la richiesta di aggiornamento.
Per visualizzare l'indirizzo IP del client, aggiungilo option forwardfornel backend. Questo genera X-Forwarded-Forun'intestazione dall'indirizzo sorgente del client.
Se HAProxy funge da front-end per un Document Server, il back-end può essere semplice:
backend onlyoffice_docs
mode http
option forwardfor
option httpchk GET /healthcheck
http-check expect status 200
timeout tunnel 1h
server ds1 10.0.10.21:80 checkIn questa configurazione, HAProxy funge principalmente da proxy inverso, endpoint TLS e controllo di integrità.
Per una vera implementazione multi-nodo, non affidatevi al semplice round-robin per la modifica collaborativa. La documentazione attuale di ONLYOFFICE afferma che tutte le richieste relative allo stesso documento devono raggiungere lo stesso server. Le richieste di modifica dal browser al server includono automaticamente una chiave di partizionamento e le applicazioni dovrebbero aggiungerla ?shardkey=<document-key>alle richieste di comando, conversione e Document Builder laddove documentato.
HAProxy supporta l'hashing sui parametri di query URL, quindi un backend adatto per l'API standard ONLYOFFICE Docs è:
backend onlyoffice_docs
mode http
option forwardfor
option httpchk GET /healthcheck
http-check expect status 200
timeout tunnel 1h
balance url_param shardkey
server ds1 10.0.10.21:80 check
server ds2 10.0.10.22:80 check
shardkeyil routing basato su per l'API standard di Docs anziché il semplice round-robin.L'algoritmo di HAProxy url_paramesegue l'hashing del parametro della stringa di query selezionato. Se tale parametro è assente, HAProxy ricorre al normale comportamento di bilanciamento del carico. Per questo motivo è particolarmente importante che la tua integrazione invii la chiave di partizionamento nelle richieste in cui ONLYOFFICE lo raccomanda.
WOPI è diverso. ONLYOFFICE afferma che le integrazioni WOPI utilizzano il WOPISrcparametro di query per lo stesso scopo di instradamento. Non copiare la balance url_param shardkeyriga senza modifiche in un progetto WOPI e presumere che fornisca l'affinità richiesta.
Prima di ricaricare il servizio, verificare la configurazione:
sudo haproxy -c -f /etc/haproxy/haproxy.cfgRicarica il caricatore solo dopo che la convalida della sintassi è andata a buon fine:
sudo systemctl reload haproxy
sudo systemctl status haproxySe la tua distribuzione utilizza un gestore di servizi o un percorso di configurazione diverso, adatta di conseguenza i comandi. Un ricaricamento è preferibile a un riavvio forzato non necessario quando il pacchetto HAProxy supporta il ricaricamento graduale della configurazione.
Ora verifica quali risultati saranno effettivamente raggiunti dagli utenti e dalla tua piattaforma di gestione documentale:
curl -sS https://docs.example.com/healthcheckIl corpo previsto è:
trueSuccessivamente, verifica il certificato TLS:
openssl s_client -connect docs.example.com:443 -servername docs.example.com </dev/null 2>/dev/null | openssl x509 -noout -subject -issuer -datesInfine, apri un documento reale tramite l'applicazione di integrazione. Un controllo di integrità dimostra solo che l'endpoint del server dei documenti è pronto; non verifica che gli URL di callback, la configurazione JWT, i download dei documenti, i callback di salvataggio o l'affinità multi-nodo siano tutti corretti.
| Sintomo | Strato probabile da ispezionare | Azione utile |
|---|---|---|
/healthcheckFallimenti pubblici | Routing HAProxy, TLS o stato di salute del backend | Testa ciascun backend direttamente, quindi controlla lo stato e i log di HAProxy. |
| La finestra dell'editor si carica, poi si disconnette. | Percorso WebSocket o timeout di inattività | Verifica timeout tunnella presenza di eventuali firewall o proxy tra il browser e HAProxy. |
| Gli URL generati utilizzano HTTP anziché HTTPS | Intestazioni inoltrate | Verifica X-Forwarded-Proto: httpse X-Forwarded-Host. |
| La modifica multi-nodo si comporta in modo incoerente | Affinità del documento | Conferma shardkeyche sia presente e che HAProxy lo abbia sottoposto ad hashing in modo coerente. |
| Il controllo dello stato di salute funziona, ma il salvataggio fallisce. | Callback di integrazione/percorso di rete | Verificare che Document Server sia in grado di raggiungere gli URL di callback e dei documenti dell'applicazione di archiviazione. |
| Alcuni nodi escono ripetutamente dalla rotazione | Controllo delle dipendenze o dello stato di salute del backend | Eseguire una query /healthcheckdirettamente sul nodo interessato e analizzare i log del Document Server. |
La tradizionale persistenza dell'indirizzo IP di origine non è la soluzione predefinita migliore per ONLYOFFICE. Più utenti che modificano lo stesso file possono avere indirizzi IP client diversi e un singolo utente può aprire documenti diversi che non devono necessariamente risiedere sullo stesso nodo. L'affinità basata sul documento e sulla chiave di sharding di ONLYOFFICE è più precisa perché la chiave di routing rappresenta il documento in fase di modifica anziché l'indirizzo di rete dell'utente.
La stessa distinzione spiega perché una semplice sessione persistente basata su cookie non dovrebbe essere considerata un sostituto del comportamento di routing documentato da ONLYOFFICE. Utilizza la chiave di partizionamento documentata dell'applicazione quando crei un'implementazione multi-nodo dell'API Docs.
trueun valore /healthcheckprecedente all'aggiunta ad HAProxy.X-Forwarded-Protoe X-Forwarded-Hostvengono inoltrati correttamente.shardkeyl'affinità basata su , non il semplice round-robin.WOPISrc.Per un singolo Document Server, HAProxy funge principalmente da reverse proxy e da livello TLS. Per più nodi Document Server, la differenza decisiva risiede nel routing consapevole dei documenti. È quindi fondamentale progettare il proxy in base a questo requisito, per poi aggiungere controlli di integrità, HTTPS e ottimizzazione dei timeout.
Risolvere i problemi di copia e incolla di Collabora Online con le app locali testando le scorciatoie da tastiera, le autorizzazioni degli appunti del browser, HTTPS, le policy iframe e i formati dei contenuti.
Risolvi il problema del testo sfocato negli editor desktop di ONLYOFFICE su Linux verificando, in un ordine sicuro, la scalatura dello schermo, la scalatura dell'interfaccia dell'applicazione, la disponibilità dei caratteri e l'ambito di rendering.
Scopri come bloccare la stampa e il download nelle integrazioni di ONLYOFFICE Workspace, DocSpace o Docs e verifica quali controlli si applicano a ciascun metodo di condivisione.
Risolvere gli errori 502 del server documenti ONLYOFFICE dietro Nginx. Verificare lo stato del servizio, i log, le porte upstream, le intestazioni inoltrate, i WebSocket e la rete Docker.
Risolvere i problemi di timeout dei documenti ONLYOFFICE su un server self-hosted verificando l'URL del portale o WebDAV corretto, l'accesso alla rete, HTTPS, le credenziali e il routing del server.
Imposta un modello personalizzato di LibreOffice Writer come predefinito, aggiornalo o reimpostalo e verifica che i nuovi documenti utilizzino gli stili e il layout di pagina che preferisci.
Risolvi i problemi di esportazione PDF di ONLYOFFICE separando i problemi di conversione, di download dal browser e del server, quindi verifica che il PDF salvato si apra e mantenga il suo layout.
Rimuovere ONLYOFFICE Document Server da Linux in modo sicuro. Seguire le istruzioni relative a pacchetti, Docker, Snap e Kubernetes, preservare i dati e verificare i servizi rimanenti.
Configure LDAP or Active Directory sync in ONLYOFFICE Workspace with secure connection settings, user and group filters, attribute mapping, admin rights, scheduled sync, and practical verification checks.
Posiziona ONLYOFFICE Document Server dietro HAProxy con terminazione TLS, intestazioni inoltrate, controlli di integrità, timeout sicuri per WebSocket e routing consapevole dei documenti per implementazioni multi-nodo.
