Comment exécuter ONLYOFFICE Document Server derrière un équilibreur de charge HAProxy

La règle la plus importante est la suivante : l’utilisation d’ONLYOFFICE Document Server derrière HAProxy est simple pour un serveur unique, mais un cluster d’éditeurs multi-nœuds nécessite une architecture plus complexe qu’une simple répartition de charge. La documentation API actuelle d’ONLYOFFICE indique que, lors d’une édition collaborative, les requêtes concernant un même document doivent atteindre le même nœud du serveur de documents. Pour les intégrations modernes, le mécanisme recommandé est le shardkeyparamètre de requête, que l’équilibreur de charge peut exploiter pour une gestion de l’affinité des documents.

Si vous ne disposez que d'un seul serveur de documents et souhaitez utiliser HAProxy pour la terminaison HTTPS, un nom d'hôte public stable ou des contrôles d'intégrité centralisés, la configuration est simplifiée. Si vous avez plusieurs serveurs de documents, utilisez les mêmes principes de proxy, mais ajoutez un routage basé sur des critères spécifiques shardkeyplutôt que de supposer qu'une répartition de charge classique est suffisante.

Les exemples ci-dessous ont été vérifiés par rapport à la documentation actuelle du proxy ONLYOFFICE , à la documentation de la clé de partition ONLYOFFICE et aux directives actuelles de HAProxy WebSocket .

Lorsque cette configuration convient

HAProxy est une solution idéale pour gérer une URL publique unique https://docs.example.com, la terminaison TLS au niveau de l'équilibreur de charge, les contrôles d'intégrité actifs ou plusieurs nœuds de serveur de documents derrière un seul point de terminaison. Il est également utile lorsque votre application Nextcloud, ownCloud, votre système de gestion documentaire personnalisé ou votre application ne doit jamais se connecter directement à un nœud de serveur de documents individuel.

Ce guide part du principe que :

• HAProxy peut atteindre chaque serveur de documents via le réseau interne.
• Chaque serveur de documents fonctionne déjà directement avant l'introduction de l'équilibreur de charge.
• Le nom d'hôte public correspond à HAProxy.
• Votre certificat TLS couvre le nom d'hôte public.
• Si vous exécutez plusieurs nœuds, ils sont déployés sous la forme d'une architecture ONLYOFFICE multi-serveurs prise en charge plutôt que sous la forme de serveurs autonomes non liés qui partagent simplement un équilibreur de charge.

Étape 1 : Vérifiez chaque serveur de documents avant d’ajouter HAProxy.

Ne commencez pas par l'équilibreur de charge. Vérifiez d'abord que chaque serveur backend est opérationnel depuis l'hôte HAProxy. La documentation ONLYOFFICE /healthchecksert de point de terminaison pour vérifier la disponibilité des éditeurs. Un serveur opérationnel renvoie une réponsetrue ; la vérification couvre les dépendances essentielles telles que la base de données, le courtier de messages, la connexion Redis et le stockage.

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

Résultat attendu :

true
true

Si un serveur dorsal tombe en panne, commencez par le dépanner. Les causes fréquentes incluent les règles de pare-feu, un port interne incorrect, l'arrêt des services du serveur de documents ou l'indisponibilité des services de support.

Étape 2 : Configurer le mode HTTP et les délais d’attente pour tolérer les connexions de l’éditeur

ONLYOFFICE est une application HTTP qui utilise des connexions WebSocket persistantes lors de l'édition. HAProxy peut gérer automatiquement les connexions WebSocket après la mise à niveau HTTP, mais sa politique de délai d'expiration reste importante. La documentation d'HAProxy recommande une timeout tunnelvaleur pour les connexions WebSocket mises à niveau.

Une base pratique est :

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 délai d'expiration d'une heure pour le tunnel est un exemple, et non une exigence universelle. Choisissez une valeur adaptée aux habitudes d'édition, à la politique de sécurité et aux limites de ressources de votre organisation. Si les éditeurs se déconnectent à intervalles réguliers, comparez cet intervalle avec les délais d'inactivité de HAProxy et des pare-feu ou proxys inverses en amont.

Étape 3 : Terminer la connexion HTTPS et préserver le contexte de la requête d’origine

ONLYOFFICE exige explicitement la transmission des en-têtes lorsqu'il s'exécute derrière un proxy. En particulier, X-Forwarded-Protoil indique au serveur de documents si le client d'origine a utilisé HTTP ou HTTPS, tout en X-Forwarded-Hostpréservant le nom d'hôte demandé par le client.

Une interface HAProxy propre peut ressembler à ceci :

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

En général, il n'est pas nécessaire de recréer manuellement les règles de type NGINX Upgradeet Connectionles en-têtes dans le mode HTTP moderne de HAProxy. HAProxy reconnaît la conversion HTTP vers WebSocket et bascule la connexion en mode tunnel. L'important est de ne pas insérer de règles qui bloquent ou interrompent la requête de conversion.

Pour la visibilité de l'adresse IP du client, ajoutez-la option forwardfordans le backend. Cela génère un X-Forwarded-Foren-tête à partir de l'adresse source du client.

Étape 4 : Ajouter des contrôles de santé et choisir la règle d’équilibrage appropriée

Serveur de documents unique

Si HAProxy fait office de serveur de documents en façade, le backend peut être simple :

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

Dans cette architecture, HAProxy joue principalement le rôle de proxy inverse, de point de terminaison TLS et de passerelle de santé.

Plusieurs nœuds de serveur de documents

Pour un véritable déploiement multi-nœuds, n'utilisez pas une simple répartition circulaire pour l'édition collaborative. La documentation actuelle d'ONLYOFFICE indique que toutes les requêtes relatives à un même document doivent atteindre le même serveur. Les requêtes de l'éditeur navigateur vers le serveur incluent automatiquement une clé de partitionnement, et les applications doivent l'ajouter ?shardkey=<document-key>aux requêtes de commande, de conversion et de Document Builder lorsque cela est documenté.

HAProxy prend en charge le hachage des paramètres de requête d'URL ; un backend adapté à l'API standard ONLYOFFICE Docs est donc :

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

L'algorithme d'HAProxy url_paramhache le paramètre de chaîne de requête sélectionné. Si ce paramètre est absent, HAProxy utilise le comportement d'équilibrage de charge classique. Il est donc essentiel que votre intégration envoie la clé de partitionnement pour les requêtes où ONLYOFFICE le recommande.

WOPI est différent. ONLYOFFICE indique que les intégrations WOPI utilisent le WOPISrcparamètre de requête à des fins de routage similaires. Ne copiez pas la balance url_param shardkeyligne telle quelle dans une conception WOPI en supposant qu'elle assure l'affinité requise.

Validez et rechargez HAProxy en toute sécurité

Avant de recharger le service, validez la configuration :

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

Ne rechargez que lorsque la validation de la syntaxe a réussi :

sudo systemctl reload haproxy
sudo systemctl status haproxy

Si votre distribution utilise un gestionnaire de services ou un chemin de configuration différent, adaptez ces commandes en conséquence. Un rechargement est préférable à un redémarrage forcé inutile lorsque votre package HAProxy prend en charge les rechargements de configuration progressifs.

Effectuez le test via l'URL publique, et pas seulement depuis l'intérieur du réseau backend.

Testez maintenant quels utilisateurs et quelle audience votre plateforme de gestion documentaire atteindront réellement :

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

Le corps attendu est :

true

Vérifiez ensuite le certificat TLS :

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

Enfin, ouvrez un document réel via l'application intégrée. Un contrôle d'intégrité vérifie uniquement que le point de terminaison du serveur de documents est prêt ; il ne garantit pas que les URL de rappel, la configuration JWT, les téléchargements de documents, les rappels d'enregistrement ou l'affinité multi-nœuds sont corrects.

Que vérifier lorsque l'éditeur se charge mais se déconnecte ou ne parvient pas à enregistrer ?

Avez-vous besoin de séances collantes ?

L'affinité traditionnelle basée sur l'adresse IP source n'est pas la solution optimale par défaut pour ONLYOFFICE. Plusieurs utilisateurs modifiant le même fichier peuvent avoir des adresses IP client différentes, et un utilisateur peut ouvrir différents documents qui n'ont pas besoin d'être stockés sur le même nœud. L'affinité basée sur le document et utilisant la clé de partitionnement d'ONLYOFFICE est plus précise, car la clé de routage représente le document en cours d'édition plutôt que l'adresse réseau de l'utilisateur.

Cette même distinction explique pourquoi une simple session persistante basée sur les cookies ne doit pas être considérée comme un substitut au comportement de routage documenté par ONLYOFFICE. Utilisez la clé de partitionnement documentée de l'application lors du déploiement d'une API Docs multi-nœuds.

Liste de vérification de la configuration finale

• Chaque serveur de documents renvoie les données trueantérieures à /healthcheckson ajout à HAProxy.
• HAProxy fonctionne en mode HTTP pour le frontend et le backend d'ONLYOFFICE.
• Le protocole HTTPS est terminé par un certificat valide pour le nom d'hôte public du serveur de documents.
• X-Forwarded-Protoet X-Forwarded-Hostsont correctement transmis.
• Le délai d'expiration du tunnel WebSocket est suffisamment long pour de véritables sessions d'édition.
• Les contrôles d'intégrité du système dorsal suppriment les nœuds défaillants du service.
• Le trafic de l'API Docs multi-nœuds utilise shardkeyune affinité basée sur les nœuds, et non pas une simple répartition circulaire.
• Les déploiements WOPI utilisent un routage approprié à WOPISrc.
• Le contrôle sanitaire fonctionne et un document réel peut être ouvert, modifié et enregistré grâce à l'intégration.

Pour un serveur de documents unique, HAProxy se limite principalement à un proxy inverse et une couche TLS. Pour plusieurs nœuds de serveur de documents, la différence cruciale réside dans le routage prenant en compte les documents. Il convient donc de concevoir le proxy en fonction de cette exigence, puis d'y ajouter les contrôles d'intégrité, le protocole HTTPS et le réglage des délais d'expiration.