Résolution de l'erreur interne du serveur 500 du tableau de bord Greenlight de BigBlueButton

Une 500 Internal Server Errorerreur 500 signifie qu'une requête côté serveur a échoué ; elle n'identifie pas le composant défaillant. Pour un tableau de bord Greenlight de BigBlueButton, commencez par rechercher la requête ayant échoué dans les journaux de l'application Greenlight. Le guide de dépannage de BigBlueButton indique qu'une erreur 500 est très probablement une erreur Greenlight. L'exception est utile : si seuls certains ordinateurs du réseau local voient l'erreur et que le journal signale une « Erreur d'hôte non sécurisé », un paramètre de proxy du navigateur peut être en cause.

Greenlight v3 est la version actuellement documentée et utilise une architecture de déploiement différente de celle de la version v2. Ce guide vous aide à identifier votre version, à rassembler les preuves nécessaires et à vérifier les causes courantes de manière sécurisée. Il suppose un déploiement Greenlight basé sur Docker. Utilisez les commandes en tant qu'administrateur serveur et adaptez le nom et le chemin du conteneur si votre installation diffère.

Identifiez le composant qui renvoie une erreur 500.

Greenlight est l'application web permettant de se connecter, de gérer les salles et de lancer des réunions BigBlueButton. Un proxy inverse tel que Nginx reçoit les requêtes du navigateur et les transmet à Greenlight. Greenlight communique ensuite avec l'API de BigBlueButton et utilise des services comme PostgreSQL et Redis. Une erreur 500 peut provenir de Greenlight, d'un proxy ou d'une dépendance ; le redémarrage des services multimédias de BigBlueButton ne résoudra pas les problèmes liés à la base de données ou à l'application.

Commencez par identifier l'action qui déclenche l'erreur : ouverture du tableau de bord, connexion, chargement de la liste des salles ou démarrage d'une réunion. Notez l'URL, l'heure approximative, si tous les utilisateurs sont concernés et toute modification récente (mise à jour, modification DNS, changement de proxy ou renouvellement des identifiants). Si la page d'accueil se charge mais qu'une action renvoie une erreur 500, cela permet de cibler la requête à examiner.

Préparez-vous avant de changer quoi que ce soit.

• Vérifiez s'il s'agit bigbluebutton/greenlight:v3d'une image v2 ou d'une image personnalisée. N'appliquez pas les instructions v2 à la v3.
• Avant de modifier le fichier Docker Compose et le fichier d'environnement concernés, conservez une copie en lieu sûr. Ils contiennent des informations d'identification.
• Consignez l'horodatage de l'erreur et n'examinez que la courte période de journalisation qui l'entoure. Masquez les mots de passe, les jetons d'accès, les secrets d'API, les adresses e-mail et les liens de réunions privées avant de partager les journaux.
• N’exécutez pas de commande docker compose down -v, ne supprimez pas les volumes de base de données ni le stockage Greenlight pour « réinitialiser » le tableau de bord. Ces actions peuvent détruire les comptes, les paramètres ou les ressources téléchargées.

Étape 1 : Vérifiez les conteneurs en cours d’exécution et capturez l’exception.

Sur l'hôte Docker, listez les conteneurs liés à Greenlight, leurs images et leur statut :

sudo docker ps -a --filter name=greenlight \
  --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}'

Pour une installation standard de Greenlight v3, le conteneur d'application est généralement nommé greenlight-v3. Consultez sa sortie récente aux alentours de l'heure de l'échec :

sudo docker logs --since=15m --tail=200 greenlight-v3

Si votre installation utilise Compose, exécutez la commande docker compose psdepuis docker compose logs --since=15m --tail=200le répertoire contenant son fichier Compose. L'installation BigBlueButton peut conserver les fichiers v3 sous~/greenlight-v3 ; les installations autonomes peuvent différer. Utilisez l'emplacement et le nom du conteneur indiqués par votre hébergeur. Pour les anciennes installations v2, consultez le journal Rails monté, généralement log/production.logdans le répertoire d'installation de Greenlight, ou examinez-le /usr/src/app/log/production.logdans le conteneur s'il n'est pas monté.

Recherchez la première exception survenue lors de l'échec de la requête, et non pas seulement la réponse 500 finale. Les erreurs de connexion à la base de données, les erreurs Redis, les échecs de requêtes API, les erreurs de validation de certificat et les exceptions Rails nécessitent des solutions différentes. Si le conteneur s'est arrêté, ses journaux peuvent encore être accessibles via [URL manquante] docker logs.

Étape 2 : Vérifier la connexion de Greenlight à BigBlueButton

Si le tableau de bord ne s'affiche pas correctement lors du chargement des salles ou du démarrage d'une réunion, vérifiez l'URL BigBlueButton et le secret partagé utilisés par Greenlight. Pour la version 3, le fichier d'environnement inclut BIGBLUEBUTTON_ENDPOINTles éléments suivants : BIGBLUEBUTTON_SECRET`<URL_API_GlobalButton>` et `<URL_réunion_GlobalButton>`. Le point de terminaison doit correspondre à l'URL de l'API de votre déploiement, et non à un hôte deviné ou à une URL de réunion accessible uniquement via un navigateur. Si vous utilisez un équilibreur de charge tel que Scalelite, utilisez le point de terminaison et les identifiants fournis pour cette configuration.

Sur le serveur BigBlueButton, sudo bbb-conf --secretl'URL et le secret configurés s'affichent. Comparez-les en privé avec les valeurs de Greenlight. Ne collez pas le secret dans un ticket, une conversation shell ou un chat public. Un secret obsolète après une réinstallation ou un renouvellement d'identifiants peut entraîner l'échec des appels API, même si le tableau de bord fonctionne correctement.

Exécutez également cette commande sudo bbb-conf --checksur le serveur BigBlueButton. Elle vérifie les services BigBlueButton et les problèmes de configuration courants ; elle ne remplace pas la consultation des journaux Greenlight. Si Greenlight est installé sur un serveur dédié, cette commande doit être exécutée sur le serveur BBB où bbb-confil est installé.

Étape 3 : Vérifiez la base de données, Redis et les mises à jour récentes.

L'environnement d'exemple de Greenlight v3 définit les connexions à la base de données et au cache DATABASE_URL. REDIS_URLVérifiez que les conteneurs PostgreSQL et Redis sont en cours d'exécution et que les valeurs de l'environnement de l'application correspondent aux noms de service, aux ports, au nom de la base de données et aux identifiants définis dans Compose. Un conteneur Greenlight apparemment fonctionnel peut néanmoins renvoyer une erreur 500 s'il ne parvient pas à accéder à l'une de ces dépendances.

Si l'erreur est apparue après une mise à niveau, comparez l'étiquette de l'image déployée, le fichier Compose et le fichier d'environnement avec la procédure de déploiement suivie. Évitez de télécharger une image arbitraire ou de modifier manuellement le schéma de la base de données lors du diagnostic en production. Sauvegardez d'abord la base de données, puis utilisez la procédure de mise à niveau Greenlight documentée pour votre installation. Vérifiez également l'espace disque disponible : un volume saturé peut empêcher les écritures PostgreSQL, les écritures de journaux ou les mises à jour du stockage des ressources.

Étape 4 : Vérifiez les paramètres du proxy, du nom d’hôte et du sous-chemin.

Si l'erreur n'apparaît que via le nom d'hôte public, vérifiez le chemin d'accès depuis le navigateur jusqu'à Greenlight, en passant par le proxy inverse. Assurez-vous que le proxy redirige vers le port interne approprié et conserve les en-têtes d'hôte et de protocole attendus. Testez la configuration du proxy avant de recharger Nginx sudo nginx -t, puis consultez le journal des erreurs du proxy à l'horodatage correspondant.

Greenlight v3 s'exécute par défaut à la racine du projet. S'il est publié sous un chemin tel que `/var/log/`, /glses RELATIVE_URL_ROOTrègles de configuration et de proxy inverse doivent correspondre. Le guide d'installation officiel indique qu'une modification de l'URL racine relative nécessite une mise à niveau/reconfiguration via la procédure d'installation ; la simple définition d'une variable shell ne résout pas un problème de configuration existant. Une configuration incorrecte entraîne généralement des redirections ou des ressources corrompues, mais une requête proxy ayant échoué peut être interprétée comme une erreur applicative.

BigBlueButton décrit un cas spécifique de réseau local : si seuls certains ordinateurs derrière un proxy reçoivent l’erreur 500 et que le journal Greenlight contient des informations d’erreur Error::Unsafe Host Error, vérifiez que Windows est configuré pour ignorer le proxy pour les adresses locales ou intranet. Il s’agit d’un problème de chemin réseau côté client, et non d’une raison de désactiver la validation de l’hôte globalement.

Étape 5 : Vérifier les modifications apportées à l’authentification et à l’adresse électronique

Si l'erreur 500 survient lors de la connexion, vérifiez les modifications récentes apportées aux paramètres OpenID Connect, aux URL de rappel ou au fournisseur d'identité. Greenlight v3 utilise des valeurs telles que `<username>` OPENID_CONNECT_ISSUER, `<username> OPENID_CONNECT_CLIENT_ID` et OPENID_CONNECT_REDIRECT`<username>` lorsque l'authentification externe est configurée. Assurez-vous que l'URL de redirection correspond à l'URL publique de Greenlight, y compris tout sous-chemin configuré, et consultez les journaux de Greenlight et du fournisseur d'identité pour vérifier que l'horodatage est identique.

La documentation de Greenlight v3 indique qu'une adresse e-mail est requise pour les fonctionnalités de base de la plateforme. Si le tableau de bord rencontre un problème lors de l'envoi d'une invitation, d'une inscription, d'une réinitialisation de mot de passe ou de toute autre action liée à l'e-mail, vérifiez la connectivité et les identifiants SMTP, les paramètres TLS et le journal d'application. Conservez vos identifiants SMTP confidentiels. Un dysfonctionnement limité aux actions liées à la messagerie doit vous inciter à examiner la configuration de la messagerie avant de modifier les identifiants de l'API BigBlueButton.

Ne redémarrez qu'après avoir identifié la cause probable.

Une fois un problème d'environnement ou de proxy confirmé corrigé, redémarrez le service Greenlight concerné à l'aide du fichier Compose de cette installation. Par exemple, depuis le répertoire d'installation de la v3 :

cd ~/greenlight-v3
sudo docker compose ps
sudo docker compose restart greenlight-v3

Les noms des services Compose peuvent différer des noms des conteneurs. Si la commande de redémarrage indique que le service est inconnu, examinez docker compose config --serviceset redémarrez le service Greenlight indiqué, ou utilisez la commande de mise à jour documentée du déploiement. Évitez de redémarrer PostgreSQL ou de supprimer des volumes, sauf si les journaux révèlent un problème de dépendance et que vous disposez d'un plan de reprise d'activité.

Vérifiez la correction et sachez quand faire remonter le problème.

Répétez exactement l'action qui a échoué précédemment, puis vérifiez la réponse dans le navigateur et le journal Greenlight au nouvel horodatage. Assurez-vous que les utilisateurs peuvent accéder au tableau de bord et, si l'échec initial concernait une réunion, lancez une réunion test. Si bbb-conf --checkle test réussit mais que l'application renvoie toujours une erreur 500, cela oriente l'investigation vers Greenlight, ses dépendances ou le proxy.

Si le problème persiste, veuillez fournir la version ou l'étiquette d'image Greenlight, le type de déploiement, l'URL concernée, l'heure de l'incident, l'exception masquée pertinente, l'état du conteneur et les modifications récentes. Ne partagez pas les fichiers d'environnement complets, les secrets d'API, les mots de passe de base de données, les cookies de session utilisateur ni les journaux non masqués.

Consultez le guide de dépannage de BigBlueButton pour l'interprétation officielle des erreurs 500 et la documentation d'installation et de configuration de Greenlight v3 pour le modèle de déploiement actuel. Le fichier d'environnement d'exemple Greenlight v3 du projet répertorie les variables d'environnement prises en charge. Greenlight v2 et v3 diffèrent ; utilisez donc la documentation correspondant à votre version déployée.