Intégrer Collabora derrière Nginx sans perturber les WebSockets

Installez Collabora sur un serveur HTTPS dédié chez Nginx, redirigez ses chemins d'accès à l'éditeur et à la découverte vers coolwsdce serveur, et transmettez explicitement les en-têtes de mise à niveau WebSocket sur les routes de socket actives. Pour un hôte unique, Nginx peut terminer le TLS public et envoyer des requêtes HTTP à Collabora sur une interface privée ; si Nginx et Collabora s'exécutent dans des conteneurs différents, utilisez le nom de service Collabora sur leur réseau partagé 127.0.0.1.

Cet exemple suppose que les utilisateurs ouvrent le https://office.example.comserveur et que Nginx gère son certificat. Le port d'écoute par défaut de Collabora est 9980 ; utilisez le port accessible dans votre déploiement. Un préfixe d'URL tel que `/` https://example.com/collabora/nécessite une configuration coordonnée des chemins et du service racine ; par conséquent, cette configuration de l'hôte racine ne s'appliquera pas sans modification.

1. Définir la table de correspondance entre le serveur en amont et la connexion WebSocket

Dans le httpcontexte Nginx, ajoutez un nom de serveur amont pour Collabora et une configuration qui définit l'en-tête de connexion upgradeuniquement lorsqu'un client effectue une requête WebSocket. Placez ce bloc en dehors de tout autre serverbloc. Modifiez l'adresse si Nginx accède à Collabora par un autre moyen.

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

upstream coolwsd {
    server 127.0.0.1:9980;
}

Si Nginx est lui-même un conteneur, 127.0.0.1cela fait référence à ce conteneur Nginx, et non au conteneur Collabora. Sur un réseau Docker partagé, le service en amont peut être server collabora:9980;spécifié par son nom, qui correspond au nom de service résolu sur ce réseau.

2. Ajoutez l'hôte virtuel HTTPS et les routes Collabora

Dans le serverbloc HTTPS office.example.com, redirigez les ressources du navigateur, les points de terminaison de découverte, les connexions WebSocket et les autres chemins Collabora. Ces emplacements respectent les recommandations de proxy de Collabora. Placez les emplacements spécifiques des sockets au-dessus de la route principale cool(/ lool) afin que Nginx applique correctement les en-têtes WebSocket.

server {
    listen 443 ssl;
    server_name office.example.com;

    ssl_certificate     /path/to/fullchain.pem;
    ssl_certificate_key /path/to/private-key.pem;

    location ^~ /browser {
        proxy_pass http://coolwsd;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $http_host;
    }

    location ^~ /hosting/discovery {
        proxy_pass http://coolwsd;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $http_host;
    }

    location ^~ /hosting/capabilities {
        proxy_pass http://coolwsd;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $http_host;
    }

    location ~ ^/cool/(.*)/ws$ {
        proxy_pass http://coolwsd;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 3600s;
    }

    location ^~ /cool/adminws {
        proxy_pass http://coolwsd;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 3600s;
    }

    location ~ ^/(c|l)ool {
        proxy_pass http://coolwsd;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Remplacez les chemins d'accès aux certificats par les fichiers correspondant à votre hôte. Si votre installation n'utilise pas la console d'administration, l' /cool/adminwsemplacement indiqué peut ne pas être nécessaire pour la modification des documents ; le /cool/.../wschemin principal est indispensable. La proxy_read_timeoutdurée d'une heure est donnée à titre d'exemple et ne constitue pas une exigence universelle. Le délai d'expiration par défaut du proxy Nginx pour la lecture est de 60 secondes entre deux lectures successives. Choisissez une valeur supérieure aux périodes d'inactivité nécessaires à vos sessions, ou utilisez un trafic ping WebSocket approprié lorsque celui-ci est pris en charge.

3. Faites correspondre le mode TLS de Collabora au saut proxy.

Les utilisateurs doivent accéder à Collabora via HTTPS, même si le relais Nginx privé vers Collabora utilise HTTP. Dans ce cas, configurez coolwsdle proxy pour qu'il agisse comme terminateur TLS : désactivez SSL sur l'écouteur interne et activez la terminaison SSL. Appliquez ces paramètres via la méthode prise en charge par votre package ou image de conteneur, puis redémarrez/rechargez Collabora conformément à sa documentation.

Utilisez un serveur HTTP en amont uniquement sur un réseau privé de confiance et bloquez l'accès public au port 9980. Si votre politique exige le chiffrement entre Nginx et Collabora, utilisez un serveur HTTPS en amont et configurez correctement la vérification des certificats ; ne désactivez pas la vérification pour masquer une incompatibilité de certificats. La documentation relative aux paramètres de proxy de Collabora fait la distinction entre le protocole SSL au niveau du proxy et le protocole SSL entre le proxy et Collabora coolwsd.

Configurez également l'URL Collabora dans l'intégration de stockage avec le nom d'hôte HTTPS public. Pour Nextcloud, son manuel d'administration exige que le navigateur et les deux serveurs puissent communiquer entre eux via HTTP(S), avec des protocoles externes compatibles. Limitez la liste blanche WOPI à l'hôte de stockage et à l'adresse Collabora prévus ; ne l'élargissez pas pour résoudre une erreur de routage proxy.

4. Testez la configuration des deux côtés

Vérifiez la syntaxe Nginx avant de la recharger :

sudo nginx -t
sudo systemctl reload nginx

Si Nginx s'exécute dans un conteneur, utilisez la procédure de validation et de rechargement de ce conteneur. Depuis l'hôte Nextcloud, testez les points de terminaison publics de Collabora avec le nom d'hôte réel :

curl -fsS https://office.example.com/hosting/discovery -o /dev/null
curl -fsS https://office.example.com/hosting/capabilities -o /dev/null

Ouvrez également ces URL HTTPS depuis un navigateur utilisateur. Elles vérifient l'accessibilité, mais une réponse positive de la requête de découverte ne garantit pas à elle seule le bon fonctionnement de l'édition de documents. Ouvrez un document et utilisez le panneau Réseau du navigateur pour vérifier que les ressources se chargent et que la /cool/.../wsconnexion reste ouverte. Une connexion WebSocket HTTP/1.1 réussie affiche généralement un message 101 Switching Protocolsd'erreur ; l'affichage exact peut varier selon le navigateur et le protocole de transport. Si cette configuration standard fonctionne sous Firefox mais échoue sous Chromium, examinez la méthode et le protocole de la requête. Un rapport de problème Collabora ouvert pour la version 25.04 documente un problème de connexion WebSocket Chromium via HTTP/2 avec CONNECTune erreur 405 ; ce rapport est toujours ouvert (au 9 octobre 2026). Il s'agit d'un problème spécifique à cette version et non d'un comportement général. Comparez vos versions de Collabora, Nginx et de navigateur avant de modifier les paramètres HTTP/2. Voir le problème Collabora n° 12155 .

Si la découverte échoue, consultez le journal d'erreurs de Nginx et vérifiez le nom d'hôte, le port et le protocole en amont. Si la découverte réussit mais que la connexion pour l'édition est impossible, vérifiez la route WebSocket, les en-têtes, le délai d'expiration et les journaux de Collabora. Une erreur d'autorisation WOPI indique un problème avec la liste blanche du serveur de stockage. Le guide de dépannage de Nextcloud Office recommande de vérifier l'accessibilité depuis le navigateur, Nextcloud et Collabora, puis de consulter les journaux des deux serveurs.

Le guide de configuration du proxy WebSocket Nginx explique pourquoi Upgradeles Connectionparamètres doivent être spécifiés explicitement et pourquoi le comportement du délai d'inactivité est important. Consultez la documentation du module proxy Nginx pour plus d'informations sur le comportement de cette directive. Une fois les vérifications effectuées, ouvrez, modifiez, enregistrez et rouvrez un document de test avant d'inviter les utilisateurs à emprunter la nouvelle route.