Suivi des échecs de connexion Collabora avec les journaux coolwsd

Pour un conteneur Collabora Online Development Edition (CODE), augmentez coolwsdle niveau de journalisation debug, assurez-vous que les zones Socketcorrespondantes ne sont pas désactivées, puis reproduisez l'ouverture d'un document ayant échoué tout en consultant les journaux du conteneur. Dans Docker Compose, transmettez les paramètres via la variable d'environnement de l'image CODE et recréez le service. Utilisez cette méthode uniquement si la sortie de débogage n'indique pas où la connexion s'interrompt, et revenez au niveau précédent une fois terminé.WebSocketextra_paramstrace

Cette méthode convient à un déploiement Docker ou Compose permettant de mettre à jour la configuration du conteneur. L'installation d'un paquet natif utilise /etc/coolwsd/coolwsd.xmlson gestionnaire de services. Ce paramètre ajoute des informations de diagnostic ; il ne résout pas à lui seul un problème de proxy, d'hôte WOPI, de certificat ou de réseau.

1. Commencez par une reproduction contrôlée

Choisissez un document et notez l'heure à laquelle vous tentez de l'ouvrir, l'URL publique de Collabora et le nom du conteneur ou du service Compose. Évitez d'actualiser plusieurs fichiers à répétition : une seule tentative facilite la concordance entre le symptôme du navigateur, le journal du proxy, le journal du serveur d'intégration et les entrées coolwsd.

Vérifiez que le conteneur est en cours d'exécution et identifiez son nom :

docker ps --format 'table {.Names}	{.Status}	{.Ports}'

Remplacez collaboraci-dessous par le nom du conteneur affiché sur votre hôte. Commencez à suivre les résultats peu avant de reproduire le problème :

docker logs --since 2m --follow --timestamps collabora

--followCe flux permet d'afficher les nouvelles données, --sincede limiter l'historique initial et --timestampsd'ajouter les horodatages Docker. Docker documente ces options dans sa documentation sur les journaux de conteneurs . Dans Compose, vous pouvez utiliser `<service_key>` docker compose logs --since=2m --follow collabora, où collabora`<service_key>` est la clé du service.

2. Activez le mode débogage de coolwsd pour le test.

Le schéma de configuration Collabora prend en charge les niveaux nommés, notamment warning`<level> notice`, information... debuget `<level> trace`. Il définit également disabled_areas`<level>`. La valeur par défaut, documentée, désactive les sorties détaillées de `<level>` Socketet `<level> WebSocket`, entre autres. Ceci est important pour le dépannage de la connexion : modifier le niveau de verbosité seul peut ne pas afficher les informations les plus utiles concernant l’établissement de la liaison. Ces options sont documentées dans le modèle de configuration coolwsd de Collabora et dans le manuel du SDK Collabora Online (section Configuration Docker ; consulté en octobre 2026).

Pour l' collabora/codeimage officielle, ajoutez les deux options à la valeur existante du service extra_params. Conservez les options déjà requises par votre installation, telles que la terminaison SSL ou le nom du serveur.

services:
  collabora:
    environment:
      extra_params: "--o:logging.level=debug --o:logging.disabled_areas=Admin,Pixel"

La seconde option active Socketla WebSocketjournalisation détaillée tout en désactivant certaines options Admin. PixelNe réactivez pas ces deux options pendant ce test. La documentation de l'image CODE décrit extra_paramscomment transmettre des options de ligne de commande à coolwsd. Si votre déploiement utilise un fichier de configuration monté ou une image gérée par le fournisseur, suivez plutôt la méthode de configuration de ce déploiement.

Appliquez la modification Compose en recréant le service :

docker compose up -d --force-recreate collabora

Utilisez le nom réel de votre service Compose. Pour un conteneur éphémère démarré avec `coolwsd` docker run, mettez à jour sa configuration d'exécution et recréez-le avec les mêmes volumes, réseaux, ports et autres options. Le manuel CODE indique que l'image accepte `coolwsd` extra_paramsau démarrage ; ne présumez pas que la modification de l'environnement d'un conteneur déjà créé modifie le processus coolwsd en cours d'exécution.

3. Lisez la connexion dans l'ordre

Reproduisez l'erreur une seule fois et analysez uniquement cet intervalle. Recherchez dans les résultats des termes tels que « » WebSocket, WOPI« » ERR, « » et WRN« », puis comparez les horodatages. La formulation exacte et les zones de journalisation varient selon la version de Collabora ; considérez-les donc comme des catégories à examiner plutôt que comme des messages littéraux garantis.

• Aucune nouvelle entrée coolwsd au moment du test : la requête n'atteint peut-être pas ce conteneur. Vérifiez l'URL publique configurée, le DNS, l'équilibreur de charge, les journaux d'accès/d'erreurs du proxy inverse et assurez-vous de suivre la bonne réplique.
• Le navigateur accède au service, mais la connexion WebSocket ne reste pas ouverte : examinez la gestion du proxy lors de la mise à niveau de la connexion WebSocket, l’hôte et le schéma transférés, la terminaison TLS, le routage et les délais d’inactivité. Comparez ces informations avec la console de développement du navigateur et les journaux du proxy ; coolwsd ne peut pas expliquer une requête que le proxy ne transfère jamais.
• Une requête WOPI apparaît et échoue : vérifiez l’URL WOPI du serveur d’intégration, la configuration de la liste blanche ou des alias des hôtes, l’accessibilité depuis le conteneur Collabora et la réponse du serveur d’intégration. Une erreur WOPI est un événement distinct de la connexion WebSocket entre le navigateur et Collabora.
• L'authentification WOPI réussit, mais le navigateur se déconnecte toujours : concentrez-vous ensuite sur la route WebSocket et les erreurs de connexion côté navigateur. Cette démarche permet de restreindre la recherche, mais n'indique pas quel proxy ou paramètre réseau est en cause.

Si Docker n'affiche aucune sortie alors que le service est actif, vérifiez la configuration de journalisation à l'intérieur du conteneur. La commande `log` de Docker lit les flux de sortie standard et d'erreur du conteneur ; une installation configurée pour écrire dans un fichier peut utiliser un chemin tel que `/etc/docker/log/` /var/log/coolwsd.log, comme défini dans sa configuration. Examinez le fichier lui-même plutôt que de supposer ce chemin.

docker exec collabora sh -c 'grep -n -A25 "<logging>" /etc/coolwsd/coolwsd.xml'

Si la journalisation des fichiers est activée, utilisez le chemin configuré, par exemple :

docker exec collabora sh -c 'tail -n 200 /var/log/coolwsd.log'

4. Vérifiez le résultat et rétablissez la journalisation normale.

Après le test, effectuez une lecture limitée pour confirmer que la tentative prévue a produit de nouvelles entrées :

docker logs --since 5m --timestamps collabora

Vous obtenez un résultat utile lorsque vous pouvez associer l'échec d'ouverture à un événement coolwsd ou établir que la requête n'a jamais atteint ce conteneur, puis identifier l'étape de connexion nécessitant un suivi. Si vous devez filtrer les résultats, commencez par utiliser une fenêtre temporelle courte.

docker logs --since 5m collabora | grep -Ei 'coolwsd|WOPI|WebSocket|ERR|WRN'

logging.levelRestaurez les valeurs précédentes disabled_areas, puis recréez le service. Les niveaux de débogage et de traçage peuvent générer beaucoup plus d'informations et inclure des détails opérationnels sensibles. Avant de partager les journaux, masquez les jetons d'accès, les noms de documents, les identifiants utilisateur, les noms d'hôtes et les adresses internes. Si le service n'est pas l'image CODE officielle, vérifiez son chemin de configuration et les paramètres pris en charge auprès du responsable de cette image.