Cum se rulează serverul de documente ONLYOFFICE în spatele unui echilibrator de încărcare HAProxy

Cea mai importantă regulă este următoarea: plasarea serverului de documente ONLYOFFICE în spatele HAProxy este simplă pentru un singur backend, dar un cluster de editori cu mai multe noduri are nevoie de mai mult decât o simplă operațiune round-robin. Documentația API actuală a ONLYOFFICE precizează că solicitările pentru același document trebuie să ajungă la același nod al serverului de documente în timpul editării colaborative. Pentru integrările moderne, mecanismul recomandat este shardkeyparametrul de interogare, pe care echilibratorul de încărcare îl poate utiliza pentru afinitate în funcție de documente.

Dacă aveți un singur server de documente și doriți HAProxy pentru terminarea HTTPS, un nume de gazdă public stabil sau verificări centralizate ale stării de funcționare, configurația este mai simplă. Dacă aveți două sau mai multe noduri de server de documente, utilizați aceleași principii fundamentale de proxy, dar adăugați rutare bazată pe, shardkeyîn loc să presupuneți că este suficientă o rutare round-robin obișnuită.

Exemplele de mai jos au fost verificate în raport cu documentația actuală pentru proxy-ul ONLYOFFICE , documentația pentru cheile shard ONLYOFFICE și îndrumările actuale pentru HAProxy WebSocket .

Când această configurație este potrivită

HAProxy este un front-end util atunci când doriți o adresă URL publică https://docs.example.com, cum ar fi terminarea TLS la echilibratorul de încărcare, verificări active ale stării de funcționare sau mai multe noduri Document Server în spatele unui endpoint. De asemenea, este util atunci când Nextcloud, ownCloud, DMS personalizat sau aplicația dvs. nu ar trebui să se conecteze niciodată direct la un nod individual Document Server.

Acest ghid presupune:

• HAProxy poate ajunge la fiecare server de documente prin rețeaua internă.
• Fiecare server de documente funcționează deja direct înainte de introducerea echilibratorului de încărcare.
• Numele public de gazdă se rezolvă în HAProxy.
• Certificatul TLS acoperă numele de gazdă public.
• Dacă rulați mai multe noduri, acestea sunt implementate ca o arhitectură ONLYOFFICE multi-server acceptată, mai degrabă decât ca servere independente fără legătură care pur și simplu partajează un echilibrator de încărcare.

Pasul 1: Verificați fiecare server de documente înainte de a adăuga HAProxy

Nu începeți cu echilibratorul de încărcare. Mai întâi demonstrați că fiecare backend este sănătos de la gazda HAProxy. ONLYOFFICE documentează /healthcheckca punct final pentru verificarea disponibilității editorului. Un server sănătos returnează true; verificarea acoperă dependențele de bază, cum ar fi baza de date, brokerul de mesaje, conexiunea Redis și stocarea.

curl -sS http://10.0.10.21/healthcheck
curl -sS http://10.0.10.22/healthcheck

Rezultatul așteptat:

true
true

Dacă un backend eșuează aici, depanați mai întâi acel nod. Cauzele frecvente includ regulile firewall, un port intern incorect, serviciile Document Server care nu rulează sau serviciile de asistență indisponibile.

Pasul 2: Setați modul HTTP și timeout-urile care tolerează conexiunile editorului

ONLYOFFICE este o aplicație HTTP și folosește conexiuni WebSocket de lungă durată în timpul editării. HAProxy poate face proxy automat pentru WebSocket-uri după actualizarea HTTP, dar politica sa de timeout este în continuare importantă. Documentația proprie a HAProxy recomandă o timeout tunnelvaloare pentru conexiunile WebSocket actualizate.

O bază practică este:

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

O expirare de o oră pentru tunel este un exemplu, nu o cerință universală. Alegeți o valoare care se potrivește comportamentului de editare, politicii de securitate și limitelor de resurse ale organizației dvs. Dacă editorii se deconectează la intervale foarte regulate, comparați intervalul respectiv cu expirarea de inactivitate a HAProxy și a oricăror expirari de inactivitate pentru firewall-ul sau reverse-proxy-ul din amonte.

Pasul 3: Terminați HTTPS și păstrați contextul original al solicitării

ONLYOFFICE necesită în mod explicit anteturi redirecționate atunci când rulează în spatele unui proxy. În special, X-Forwarded-Protoîi spune serverului de documente dacă clientul original a folosit HTTP sau HTTPS, X-Forwarded-Hostpăstrând în același timp numele de gazdă solicitat de client.

Un frontend HAProxy curat poate arăta astfel:

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

În mod normal, nu este nevoie să recreați manual regulile în stil NGINX Upgradeși Connectioncele ale antetului în modul HTTP HAProxy modern. HAProxy recunoaște actualizarea HTTP-to-WebSocket și comută conexiunea în modul tunel. Important este să nu inserați reguli care elimină sau întrerup solicitarea de actualizare.

Pentru vizibilitatea adresei IP a clientului, adăugați option forwardforbackend-ul. Aceasta generează un X-Forwarded-Forantet de la adresa sursă a clientului.

Pasul 4: Adăugați verificări de stare și alegeți regula de echilibrare potrivită

Server unic de documente

Dacă HAProxy este un server de documente pe front, backend-ul poate fi simplu:

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 check

În acest design, HAProxy este în principal un proxy invers, un endpoint TLS și o poartă de sănătate.

Noduri multiple de server de documente

Pentru o implementare reală cu mai multe noduri, nu vă bazați pe round-robin simplu pentru editarea colaborativă. Documentația actuală a ONLYOFFICE precizează că toate cererile aparținând aceluiași document trebuie să ajungă la același server. Cererile editorului de tip browser-to-server includ automat o cheie shard, iar aplicațiile ar trebui să adauge ?shardkey=<document-key>la comenzi, conversii și cereri Document Builder, acolo unde este documentat.

HAProxy acceptă hashing pe un parametru de interogare URL, așadar un backend potrivit pentru API-ul standard ONLYOFFICE Docs este:

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

Algoritmul HAProxy url_paramanalizează parametrul selectat prin hashing. Dacă parametrul respectiv lipsește, HAProxy revine la comportamentul obișnuit de echilibrare a încărcării. Din acest motiv, este deosebit de important ca integrarea dvs. să trimită cheia shard la solicitările unde ONLYOFFICE o recomandă.

WOPI este diferit. ONLYOFFICE afirmă că integrările WOPI utilizează WOPISrcparametrul de interogare în același scop de rutare. Nu copiați balance url_param shardkeylinia neschimbată într-un design WOPI și presupuneți că oferă afinitatea necesară.

Validați și reîncărcați HAProxy în siguranță

Înainte de a reîncărca serviciul, validați configurația:

sudo haproxy -c -f /etc/haproxy/haproxy.cfg

Reîncărcați doar după ce validarea sintaxei are succes:

sudo systemctl reload haproxy
sudo systemctl status haproxy

Dacă distribuția dvs. folosește un alt manager de servicii sau o altă cale de configurare, adaptați comenzile respective în consecință. O reîncărcare este preferabilă unei reporniri inutile atunci când pachetul HAProxy acceptă reîncărcări de configurare corecte.

Testează prin URL-ul public, nu doar din interiorul rețelei backend

Acum testați ce vor atinge de fapt utilizatorii și platforma dvs. de gestionare a documentelor:

curl -sS https://docs.example.com/healthcheck

Corpul așteptat este:

true

Apoi verificați certificatul TLS:

openssl s_client -connect docs.example.com:443   -servername docs.example.com </dev/null 2>/dev/null   | openssl x509 -noout -subject -issuer -dates

În final, deschideți un document real prin aplicația de integrare. O verificare a stării de funcționare dovedește doar că endpoint-ul Document Server este pregătit; nu dovedește că URL-urile de apel invers, configurația JWT, descărcările de documente, apelurile inverse de salvare sau afinitatea multi-nod sunt corecte.

Ce trebuie verificat când editorul se încarcă, dar se deconectează sau nu reușește să salveze

Ai nevoie de sesiuni captivante?

Fixarea tradițională a adresei IP sursă nu este cea mai bună soluție implicită pentru ONLYOFFICE. Mai mulți utilizatori care editează același fișier pot avea adrese IP diferite ale clienților, iar un utilizator poate deschide documente diferite care nu trebuie să se afle pe același nod. Afinitatea față de documente bazată pe cheia shard a ONLYOFFICE este mai precisă, deoarece cheia de rutare reprezintă documentul care editează, mai degrabă decât adresa de rețea a persoanei.

Aceeași distincție explică de ce o simplă sesiune fixă ​​bazată pe cookie-uri nu ar trebui tratată ca un substitut pentru comportamentul de rutare documentat de ONLYOFFICE. Folosește cheia shard documentată a aplicației atunci când construiești o implementare API Docs cu mai multe noduri.

Listă de verificare a configurării finale

• Fiecare server de documente revine truedin /healthcheckstarea anterioară adăugării sale la HAProxy.
• HAProxy rulează în modul HTTP pentru frontend-ul și backend-ul ONLYOFFICE.
• HTTPS se termină cu un certificat valid pentru numele de gazdă public al serverului de documente.
• X-Forwarded-Protoși X-Forwarded-Hostsunt transmise mai departe corect.
• Timpul de expirare al tunelului WebSocket este suficient de lung pentru sesiuni reale de editare.
• Verificările de sănătate backend elimină nodurile defecte din serviciu.
• Traficul API Docs cu mai multe noduri folosește shardkeyafinitate bazată pe , nu doar round-robin simplu.
• Implementările WOPI utilizează rutare adecvată pentru WOPISrc.
• Verificarea sănătății publice funcționează, iar un document real poate fi deschis, editat și salvat prin integrare.

Pentru un server de documente, HAProxy este în principal un proxy invers curat și un strat TLS. Pentru mai multe noduri ale serverului de documente, diferența decisivă este rutarea bazată pe documente. Construiți proxy-ul în jurul acestei cerințe mai întâi, apoi adăugați verificări de sănătate, HTTPS și reglarea timeout-ului în jurul acesteia.