Intégrez ONLYOFFICE Docs derrière HAProxy sans interrompre l'édition.

Exécutez ONLYOFFICE Docs derrière HAProxy en terminant le trafic HTTPS au niveau du proxy, en redirigeant l'hôte et le schéma d'origine, et en autorisant les connexions WebSocket persistantes. Commencez avec un serveur de documents opérationnel ; n'ajoutez d'autres serveurs que lorsque votre déploiement ONLYOFFICE est configuré pour un fonctionnement multi-nœuds pris en charge, et non pas simplement parce que HAProxy peut distribuer les requêtes.

HAProxy peut-il équilibrer la charge de deux serveurs de documents indépendants ?

HAProxy peut répartir les requêtes HTTP entre les nœuds, mais cela ne transforme pas deux installations ONLYOFFICE autonomes en un cluster d'édition coordonné. Une session d'édition conserve des connexions persistantes et un état d'application. L' exemple actif-actif officiel d'ONLYOFFICE utilise des contrôles d'intégrité du serveur et un cookie de persistance ; il s'agit de mécanismes de routage, et non de substituts aux services partagés et à l'architecture applicative requis par votre édition.

Pour une installation classique sur un seul serveur, utilisez uniquement docs1la configuration backend ci-dessous. Pour une installation à deux nœuds, vérifiez d'abord l'architecture du cluster, l'édition prise en charge, les dépendances partagées, la compatibilité des versions et la configuration JWT à l'aide de la documentation de déploiement ONLYOFFICE ou auprès du support technique de votre fournisseur. Les adresses indiquées en exemple ( 10.0.10.21et 10.0.10.22) sont des adresses IP privées illustratives et non des hôtes découverts.

Que doit-on configurer correctement avant de modifier HAProxy ?

Le nom public docs.example.comdoit correspondre à votre point de terminaison HAProxy. HAProxy nécessite l'accès aux ports TCP entrants 80 et 443 ainsi qu'un accès au réseau privé de chaque serveur de documents sur le port 80. Votre application de gestion documentaire doit également pouvoir accéder à l'adresse publique Docs, tandis que ONLYOFFICE doit pouvoir récupérer des documents et envoyer des notifications à l'application. Sécurisez le trafic HTTP du serveur ; chiffrez la connexion au serveur séparément si elle traverse un réseau non sécurisé.

1. Vérifiez chaque serveur de documents depuis l'hôte proxy. Exécutez la commande curl -i http://10.0.10.21/healthchecket, le cas échéant, la curl -i http://10.0.10.22/healthcheckcommande correspondante. Un point de terminaison opérationnel renvoie normalement une réponse HTTP 200 avec un corps contenant «  » true. Si l'un de ces éléments échoue, examinez le routage, les pare-feu ou l'état du serveur avant de configurer l'équilibrage de charge.
2. Confirmez un secret JWT fixe. Le serveur de documents et son connecteur doivent utiliser le même secret. Pour les installations Docker, ONLYOFFICE documente la JWT_SECRETvariable d'environnement ; depuis Docs 7.2, l'utilisation d'un secret généré automatiquement peut entraîner des échecs d'intégration après une recréation ou un redémarrage. Dans les déploiements multi-nœuds pris en charge, harmonisez les secrets entre les nœuds conformément à l'architecture du fournisseur.

Ces vérifications suivent les recommandations du fournisseur concernant l'installation de Docker et la configuration de JWT . Ne désactivez pas JWT pour contourner une erreur de proxy.

Comment configurer HTTPS et transmettre les en-têtes appropriés ?

Étape 1 : Préparer le certificat

Obtenez un certificat de confiance couvrant le domaine docs.example.com. Dans cet exemple Linux, HAProxy lit un fichier PEM contenant la chaîne de certificats suivie de la clé privée. Si des certificats existent déjà ailleurs, remplacez leurs chemins d'accès. Limitez l'accès au fichier PEM combiné et configurez sa reconstruction lors du renouvellement du certificat.

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'

Étape 2 : Ajouter le frontend et le backend

Sauvegardez votre configuration actuelle /etc/haproxy/haproxy.cfget adaptez les sections suivantes plutôt que de remplacer aveuglément les paramètres de journalisation ou de service spécifiques à votre distribution. Voici une configuration illustrative pour les versions récentes d'HAProxy. Elle accepte uniquement le protocole HTTP pour la redirection, termine le trafic HTTPS sur le port 443, redirige l'hôte et le schéma publics et surveille le point de terminaison d'état de l'application.

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

Supprimez cette docs2ligne sauf si le second nœud est réellement prêt. Le cookie de persistance permet aux requêtes HTTP suivantes de revenir au nœud sélectionné. HAProxy gère la mise à niveau d'une connexion WebSocket HTTP sans réécriture d'URL spécifique ; timeout tunnel 1hles connexions mises à niveau et inactives restent ouvertes plus longtemps que les requêtes ordinaires. La documentation WebSocket de HAProxy explique ce comportement.

X-Forwarded-ProtoLe paramétrage httpsest correct ici car cette interface termine les requêtes HTTPS publiques. Ne faites pas confiance à un schéma de redirection arbitraire fourni par le client ou à un hôte situé à la périphérie d'Internet. La documentation du proxy ONLYOFFICE exige explicitement que X-Forwarded-Protole X-Forwarded-Hostcontexte de l'URL externe soit conservé.

Comment recharger et tester l'équilibreur de charge ?

Étape 3 : Valider avant de basculer le trafic

Vérifiez la syntaxe avant de recharger. Un code de sortie différent de zéro signifie que vous devez résoudre l'erreur de configuration ou de certificat signalée avant de continuer :

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

La réponse du contrôle d'intégrité public doit afficher un code HTTP 200 truelorsqu'un serveur est opérationnel. HAProxy utilise les directives option httpchk`remove` et `remove` http-check expectpour retirer les nœuds défaillants de la rotation des nouvelles requêtes ; consultez sa documentation sur les contrôles d'intégrité . Un contrôle réussi ne garantit pas le bon fonctionnement de l'édition de documents ni de la distribution des rappels.

Étape 4 : Confirmer la modification, les WebSockets et l’enregistrement

Ouvrez un document via votre application intégrée, telle qu'un système de gestion documentaire connecté à ONLYOFFICE Docs. Dans les outils de développement de votre navigateur, utilisez le panneau Réseau pour examiner la connexion WebSocket : la négociation de mise à niveau doit réussir, généralement avec le code d'état HTTP101 Switching Protocols 90. Apportez une modification mineure, fermez l'éditeur, rouvrez le document et vérifiez que la modification a bien été enregistrée. Pour un déploiement à deux nœuds correctement pris en charge, testez également avec un deuxième collaborateur et lors d'une interruption planifiée sur un seul nœud pendant une fenêtre de maintenance.

Si le contrôle d'intégrité public fonctionne mais que l'éditeur se bloque ou se déconnecte, examinez les avertissements de contenu mixte, les échecs WebSocket, les incohérences JWT et vérifiez si l'application de documents peut accéder à l'URL Docs annoncée. Si un document s'ouvre mais ne s'enregistre jamais, vérifiez la connectivité du serveur de documents avec l'application source plutôt que de modifier la politique de répartition de charge d'HAProxy. Une session WebSocket active interrompue peut nécessiter une reconnexion du client ; les contrôles d'intégrité du serveur ne garantissent pas une reprise d'édition transparente.

Vérification finale : le point de terminaison de santé publique et un test réel de modification et de réouverture doivent être concluants. Conservez uniquement les nœuds vérifiés et pris en charge en rotation, assurez-vous que le renouvellement du certificat recharge le fichier PEM correct et surveillez les journaux HAProxy pour détecter les réponses 502/503 répétées ou les déconnexions WebSocket inattendues.