Résoudre le problème d'écran noir ou de document vierge au chargement de Collabora Online

Commencez par vérifier la connexion WebSocket et la disponibilité des deux serveurs. Un éditeur Collabora Online qui s'ouvre sur un écran noir, une page blanche ou un canevas vide présente souvent un dysfonctionnement avant même que l'interface utilisateur du document ne soit complètement chargée. Si le problème affecte tous les fichiers, examinez d'abord la connexion entre le navigateur et Collabora, le proxy inverse et la connexion entre Nextcloud et Collabora. Si un seul fichier pose problème, testez un autre document et vérifiez ses permissions et son format avant de modifier les paramètres du serveur.

Procédez comme suit : vérifiez le navigateur, testez les points de terminaison de découverte de Collabora, consultez les journaux d’intégration et du serveur, puis corrigez uniquement le paramètre de proxy ou WOPI indiqué par les éléments de preuve. La réinitialisation du cache du navigateur peut résoudre le problème des ressources obsolètes, mais ne corrigera pas une connexion WebSocket défaillante ni un hôte WOPI inaccessible. Les images d’interface ci-dessous sont des exemples schématiques ; les libellés et les chemins de requête exacts varient selon le navigateur, la plateforme cloud, le proxy et la version de Collabora.

Diagnostic rapide par symptômes

1. Déterminez si le problème provient du navigateur ou du serveur.

Ouvrez d'abord un second document dont vous êtes certain de la lisibilité, puis essayez d'ouvrir le même fichier dans un autre navigateur ou une fenêtre de navigation privée. Si un document ne s'ouvre pas alors que d'autres s'ouvrent, vérifiez que l'utilisateur peut toujours le télécharger ou le prévisualiser sur la plateforme de fichiers. Un fichier endommagé, un format non pris en charge, un partage expiré ou des autorisations manquantes peuvent être confondus avec un problème d'éditeur, mais modifier le proxy inverse ne résoudra pas un problème spécifique à un fichier.

Pour une vérification côté navigateur, ouvrez les outils de développement avant de recharger le document vierge. Dans les navigateurs basés sur Chromium, appuyez sur Ctrl+F F12ou Ctrl+Shift+IMaj+F, sélectionnez Réseau , activez Conserver le journal et rechargez la page. Filtrez les résultats pour rechercher les erreurs suivantes : ws[ insérer les erreurs coolici] browser. Consultez également l’onglet Console pour détecter les scripts bloqués, les avertissements de certificat ou les erreurs de politique de sécurité du contenu.

Une requête ayant échoué /cool/…/wsindique un problème de connexion WebSocket ou de proxy. Un code d'état 0 502signifie généralement que le proxy n'a pas pu obtenir de réponse exploitable de son serveur en amont ; un code d' état 0 404peut indiquer que le chemin n'est pas routé ; et un 403code d'état 0 peut indiquer un hôte ou une règle d'accès refusés. Ces codes d'état permettent de restreindre la recherche, mais les journaux du proxy et de Collabora correspondants sont nécessaires pour identifier la cause exacte. Si les requêtes ayant échoué concernent des fichiers JavaScript ou CSS situés dans le répertoire ` /browser/usr/local/collabora`, vérifiez que le proxy transmet bien ces ressources statiques au service Collabora.

Si les requêtes réseau aboutissent en navigation privée, désactivez temporairement les extensions de navigateur bloquant les scripts ou les requêtes intersites, puis effacez les données de site uniquement pour les noms d'hôte du cloud et de Collabora. Effectuez un nouveau test avant de modifier la configuration du serveur. Si la même requête échoue toujours dans l'onglet Réseau, ne videz pas le cache comme solution principale.

2. Confirmez l'URL Collabora et les points de terminaison de découverte

Pour une intégration Nextcloud, vérifiez l'URL du serveur Collabora Online dans les paramètres d'administration d'Office. Utilisez l'URL publique accessible par les navigateurs, avec le nom d'hôte et le port corrects. Nextcloud recommande que les services Collabora et Nextcloud utilisent le même protocole ; HTTPS est conseillé. Une incompatibilité, par exemple si un service est configuré avec HTTPS http://tandis que l'autre est accessible via HTTP, https://peut entraîner le blocage des requêtes à contenu mixte ou l'échec des rappels.

Depuis un navigateur sur le client concerné, ouvrez ` <adresse_du_serveur> https://office.example.com/hosting/discovery` et https://office.example.com/hosting/capabilities`<adresse_du_serveur>`, en remplaçant le nom d'hôte d'exemple par le vôtre. Le point de terminaison de découverte devrait renvoyer du XML décrivant les actions de document prises en charge ; `<adresse_du_serveur>` devrait renvoyer une réponse du serveur Collabora. Une erreur de navigateur, une page de connexion, une erreur 404 liée au proxy ou une erreur de passerelle signifie que la route publique n'atteint pas le point de terminaison Collabora attendu.

Ensuite, effectuez un test depuis l'hôte Nextcloud, car le test via navigateur seul ne prouve pas que les serveurs peuvent communiquer entre eux :

curl -sS -o /dev/null -w "%{http_code}\n" https://office.example.com/hosting/discovery
curl -sS -o /dev/null -w "%{http_code}\n" https://office.example.com/hosting/capabilities

Remplacez office.example.compar le nom d'hôte Collabora configuré. Une réponse HTTP positive constitue un test d'accessibilité utile, tandis qu'un délai d'attente dépassé, une erreur DNS, une erreur TLS ou une réponse 5xx doivent être résolus au niveau du réseau, du certificat, du DNS ou du proxy concerné. Pour les installations où le serveur Collabora doit communiquer avec Nextcloud, testez également l'URL d'état de Nextcloud depuis l'hôte Collabora :

curl -fsS https://cloud.example.com/status.php

Utilisez votre nom d'hôte Nextcloud réel. Les installations CODE intégrées peuvent utiliser une URL de proxy interne au lieu d'un nom d'hôte Collabora public distinct ; suivez donc les instructions de déploiement correspondantes plutôt que d'appliquer littéralement l'exemple du serveur autonome.

3. Vérifiez la route WebSocket et le proxy inverse

Collabora distribue les ressources du navigateur et les sessions de documents via plusieurs routes. Un proxy inverse doit rediriger les chemins attendus par la version installée, notamment les ressources de l'éditeur, les points de terminaison de découverte et de fonctionnalités, ainsi que la route WebSocket des documents. La documentation actuelle de Collabora utilise/cool/…/ws ; les déploiements plus anciens peuvent encore comporter une configuration pour des chemins hérités /lool. La documentation de migration de Nextcloud mentionne spécifiquement les changements de chemin historiques de loleafletà browseret de loolà cool.

Dans la configuration de votre proxy, vérifiez que l'emplacement WebSocket est pris en compte avant les règles générales, que le proxy transmet les en-têtes de mise à jour nécessaires à votre logiciel proxy et que le serveur en amont pointe vers le service et le port Collabora. Assurez-vous également que le proxy conserve les informations d'hôte et de schéma attendues et qu'il autorise les connexions persistantes. Si le protocole TLS se termine au niveau du proxy, vérifiez que les paramètres de terminaison SSL de Collabora correspondent à cette configuration.

L'extrait de code ci-dessus illustre les en-têtes WebSocket nécessaires à un proxy de type Nginx ; il ne s'agit pas d'une configuration complète. Ne le copiez pas tel quel et n'y intégrez pas de directives provenant de versions différentes. Comparez votre configuration complète avec le guide officiel de Collabora sur les proxys inverses, en fonction du proxy et de la version de Collabora que vous utilisez. Après avoir modifié un fichier de configuration de proxy, vérifiez sa syntaxe à l'aide de la commande `configuration-test` du serveur avant de le recharger.

4. Vérifiez la validation de l'hôte WOPI et les journaux du serveur.

Collabora utilise WOPI (Web Application Open Platform Interface) pour récupérer un document auprès d'un service de stockage connecté, tel que Nextcloud. Le serveur Collabora doit accepter l'hôte WOPI et le serveur de stockage doit pouvoir accéder au service Collabora. Dans Nextcloud, vérifiez les paramètres Office et la liste blanche pour les requêtes WOPI. Ajoutez uniquement l'adresse du serveur Collabora attendu ; ne désactivez pas la validation de l'hôte et n'autorisez pas d'hôtes arbitraires, car cela pourrait entraîner la disparition d'un écran blanc.

Consultez les journaux au moment où vous reproduisez le problème. Pour un déploiement Docker, le guide de dépannage de Nextcloud explique comment vérifier le journal du conteneur ; utilisez le nom ou l’ID du conteneur.

docker logs --tail 100 collabora

Pour une installation par paquet, les noms des services et les destinations des journaux dépendent du système d'exploitation et de la version du paquet. Une vérification systemd courante consiste à :

sudo journalctl -u coolwsd -n 100 --no-pager

Recherchez un horodatage correspondant et les erreurs relatives à un hôte WOPI non autorisé, CheckFileInfoune requête ayant échoué, une vérification TLS défaillante, un stockage indisponible ou une connexion WebSocket défaillante. Un message indiquant qu'aucun hôte WOPI acceptable ne correspond signifie généralement que le nom d'hôte du stockage configuré pour l'intégration ne correspond pas à l'hôte autorisé par Collabora. Corrigez le nom d'hôte ou l'entrée de la liste blanche plutôt que d'ajouter des domaines non pertinents.

Consultez également le journal de la plateforme de fichiers pour la même heure de requête. Si Collabora ne parvient pas à joindre Nextcloud, vérifiez la résolution DNS depuis l'hôte Collabora, les règles du pare-feu, la route publique ou interne, et assurez-vous que le service n'essaie pas de se joindre via un nom d'hôte dont la résolution diffère au sein du réseau de conteneurs. Le manuel de dépannage de Nextcloud recommande de vérifier la connectivité dans les deux sens et d'utiliser les journaux du serveur pour identifier le côté défaillant.

5. Testez à nouveau le document et n'apportez que les modifications ciblées.

Après avoir corrigé une route, une URL, un certificat ou une entrée de liste blanche, rechargez le proxy et les services concernés uniquement lorsque votre déploiement l'exige. Rouvrez les outils de développement, rechargez le fichier et vérifiez que la requête précédente ayant échoué aboutit. Le document devrait afficher ses pages ou feuilles, accepter une modification mineure et enregistrer cette modification avec succès. Une page blanche qui disparaît mais ne peut être enregistrée indique toujours un problème de connexion WOPI ou de stockage.

• La découverte fonctionne, mais WebSocket échoue : concentrez-vous sur la route WebSocket du proxy, la gestion des mises à niveau, l’adresse en amont et le délai d’expiration de la connexion.
• Le navigateur peut accéder à Collabora, mais pas Nextcloud : testez le DNS, le pare-feu, la confiance TLS et le routage depuis l’hôte Nextcloud.
• Collabora signale un hôte WOPI non autorisé : comparez le nom d’hôte de stockage exact dans les paramètres d’intégration avec la liste d’autorisation des hôtes WOPI.
• Seules les anciennes installations peuvent rencontrer des problèmes après une mise à niveau : comparez les chemins de proxy avec la documentation de la version installée et mettez à jour les routes existantes /loolsi /loleafletnécessaire.
• Un seul fichier pose problème après la réussite des vérifications de connectivité : vérifiez l’accès au fichier et testez une copie ou un format pris en charge différent avant de modifier les paramètres globaux.

À quoi ressemble une réparation réussie

Un résultat fiable ne se limite pas à l'affichage d'une barre d'outils d'éditeur. Le contenu du document s'affiche correctement, aucune requête WebSocket ou d'éditeur n'échoue de manière persistante, et une modification de test sans conséquence est enregistrée et conservée après une actualisation. Si le problème persiste, conservez un court extrait expurgé de la console réseau du navigateur ainsi que les lignes correspondantes des journaux Nextcloud, proxy et Collabora. Ces journaux peuvent contenir des noms d'hôtes, des noms d'utilisateurs, des identifiants de fichiers ou des jetons ; supprimez donc les informations sensibles avant de les partager.

Pour connaître les étapes spécifiques à votre déploiement actuel, consultez le guide de dépannage de Nextcloud Office , le guide de configuration de Nextcloud Office et les notes de migration Collabora . Les vérifications exactes pour ownCloud, un autre hôte WOPI, un service CODE intégré ou une plateforme de conteneurs peuvent différer des exemples de Nextcloud.