Dépannage
Ce guide couvre les problèmes les plus courants que vous pouvez rencontrer avec votre PCS et comment les résoudre.
L'application ne démarre pas
Symptômes : Une application s'affiche comme « Down » dans le panneau d'administration, ou vous voyez une erreur en visitant son URL.
Étapes de diagnostic :
- Allez dans Panneau d'administration → Applications et vérifiez si l'application affiche des problèmes.
- Allez dans Panneau d'administration → Terminal, cliquez sur Connecter, et exécutez :
Cela montre si le conteneur s'est arrêté et son code de sortie.docker ps -a | grep <nom-app>
- Vérifiez les logs de l'application :
docker logs <nom-conteneur> --tail 100
Causes courantes et solutions :
| Cause | Solution |
|---|---|
| Conflit de port | Un autre conteneur utilise le même port. Arrêtez le conteneur en conflit ou changez le port. |
| Mémoire insuffisante | Vérifiez Ressources → CPU pour l'utilisation mémoire. Arrêtez les applications inutilisées pour libérer de la RAM. |
| Données corrompues | Restaurez depuis une sauvegarde via la page Applications, ou supprimez et réinstallez l'application. |
| Échec du téléchargement de l'image Docker | Vérifiez la connectivité internet. Exécutez docker pull <image> manuellement depuis le Terminal. |
Domaine inaccessible
Symptômes : Visiter votredomaine.nsl.sh affiche une erreur de connexion ou un timeout.
Étapes de diagnostic :
- Vérifiez si le PCS est joignable via le domaine de secours sslip.io (ex.
169-58-42-143.sslip.io). - Allez dans Panneau d'administration → Domaine et vérifiez que l'IP publique correspond à votre IP réelle.
- Allez dans Panneau d'administration → Santé et cliquez sur Exécuter maintenant pour lancer un auto-diagnostic.
Causes courantes et solutions :
| Cause | Solution |
|---|---|
| Adresse IP modifiée | Votre FAI a attribué une nouvelle IP. Lancez un auto-diagnostic depuis la page Santé — il détectera la nouvelle IP et mettra à jour le routage. |
| Caddy (serveur web) est arrêté | Depuis le Terminal : docker ps | grep caddy. S'il ne fonctionne pas : sudo systemctl restart caddy ou lancez un auto-diagnostic. |
| FAI bloquant le port 443 | Certains FAI bloquent le HTTPS entrant. Contactez votre FAI ou envisagez d'utiliser le proxy Cloudflare (voir page Domaine). |
| Délai de propagation DNS | Si vous avez récemment modifié vos paramètres de domaine, attendez jusqu'à 24 heures pour la propagation DNS. |
Erreurs de certificat
Symptômes : Le navigateur affiche « Votre connexion n'est pas privée » ou un avertissement de certificat.
Étapes de diagnostic :
- Allez dans Panneau d'administration → Certificats et cliquez sur Actualiser.
- Vérifiez si le domaine concerné affiche « Let's Encrypt » ou « Internal CA ».
Causes courantes et solutions :
| Cause | Solution |
|---|---|
| Certificat CA interne | Caddy n'a pas pu obtenir un certificat Let's Encrypt. Vérifiez que le port 443 est ouvert et accessible depuis internet. |
| Limite de délivrance dépassée | Let's Encrypt a des limites de délivrance. Attendez quelques heures et le certificat sera automatiquement réessayé. |
| Certificat expiré | Lancez un auto-diagnostic depuis Santé → Exécuter maintenant. La maintenance nocturne aurait dû le renouveler, mais une exécution manuelle forcera le renouvellement. |
| Domaine personnalisé sans Cloudflare | Si vous utilisez un DNS direct sans Cloudflare, vous devez configurer les certificats vous-même. Envisagez de passer à Cloudflare (recommandé). |
Les routes gateway (domaines .nsl.sh) et les routes .nip.io utilisent intentionnellement le CA interne de Yundera. C'est par conception. Seuls les domaines .sslip.io utilisent Let's Encrypt.
Problèmes de connexion SSO
Symptômes : Impossible de se connecter au panneau d'administration ou aux applications, la page SSO affiche des erreurs.
Étapes de diagnostic :
- Essayez d'accéder directement au tableau de bord CasaOS :
https://casaos-votredomaine.nsl.sh/ - Si CasaOS fonctionne, le problème vient du service d'authentification Dex.
- Depuis le Terminal, vérifiez les logs de Dex :
docker logs dex --tail 50
Causes courantes et solutions :
| Cause | Solution |
|---|---|
| Mauvais mot de passe | Utilisez les identifiants affichés dans Informations système → Utilisateur par défaut. |
| Service Dex arrêté | Lancez un auto-diagnostic depuis Santé → Exécuter maintenant pour redémarrer tous les services système. |
| Cookies du navigateur | Supprimez les cookies de votre navigateur pour le domaine .nsl.sh et réessayez. |
| Décalage d'horloge | Si l'horloge du PCS est significativement décalée, les tokens SSO peuvent être rejetés. Redémarrez l'hôte depuis Informations système → Redémarrer l'hôte. |
Performances lentes
Symptômes : Les applications répondent lentement, les pages mettent longtemps à charger.
Étapes de diagnostic :
- Allez dans Panneau d'administration → Ressources.
- Vérifiez l'onglet CPU : la charge moyenne dépasse-t-elle le nombre de cœurs ?
- Vérifiez la Mémoire : le swap est-il fortement utilisé ?
- Vérifiez l'onglet Disque : le système de fichiers racine dépasse-t-il 90 % ?
Causes courantes et solutions :
| Cause | Solution |
|---|---|
| Surcharge CPU | Vérifiez les processus principaux. Arrêtez les applications inutilisées depuis la page Applications. |
| Épuisement de la RAM | L'utilisation du swap indique un manque de RAM. Arrêtez les applications gourmandes en mémoire ou passez à un PCS avec plus de RAM. |
| Disque plein | Nettoyez les anciennes sauvegardes depuis la page Applications, ou supprimez les données d'applications inutilisées. Depuis le Terminal : docker system prune pour nettoyer les ressources Docker inutilisées. |
| Goulot d'étranglement réseau | Lancez un test de vitesse depuis l'onglet Ressources → Réseau pour vérifier la bande passante. |
| I/O disque lent | Lancez un benchmark disque depuis l'onglet Ressources → Disque. Si les résultats sont bien inférieurs aux attentes, le disque pourrait être défaillant. |
Données d'application perdues
Symptômes : Les données d'une application ont disparu ou sont corrompues.
Étapes de diagnostic :
- Allez dans Panneau d'administration → Applications et vérifiez si des sauvegardes existent pour l'application.
- Depuis le Terminal, vérifiez si le répertoire de données existe :
ls -la /DATA/AppData/<nom-app>/
Options de récupération :
- Restaurer depuis une sauvegarde — Si des sauvegardes existent, utilisez le bouton Restaurer sur la page Applications.
- Vérifier les volumes Docker — Certaines données peuvent être dans des volumes Docker plutôt que dans
/DATA/AppData. - Réinstaller l'application — Si les données sont vraiment perdues et qu'aucune sauvegarde n'existe, réinstallez via CasaOS.
Créez toujours des sauvegardes régulières depuis la page Applications avant d'effectuer des modifications. La prévention est le meilleur remède.
Échec de l'auto-diagnostic / mise à jour
Symptômes : La maintenance nocturne affiche des erreurs dans le journal de santé.
Étapes de diagnostic :
- Allez dans Panneau d'administration → Santé et vérifiez la Fin du journal.
- Recherchez les messages d'erreur en rouge ou les lignes contenant « ERROR » ou « FAILED ».
Causes courantes et solutions :
| Cause | Solution |
|---|---|
| Pas de connexion internet | Vérifiez la connectivité réseau depuis le Terminal : ping 8.8.8.8. |
| Registre Docker indisponible | Problème temporaire avec le registre de conteneurs. La prochaine exécution nocturne réessayera. |
| Disque plein | Docker ne peut pas télécharger de nouvelles images. Libérez d'abord de l'espace disque. |
| Mauvais canal de mise à jour | Si vous avez changé pour un canal non stable, revenez à Stable depuis la page Santé. |
Besoin d'aide supplémentaire ?
Si aucune des solutions ci-dessus ne fonctionne :
- Allez dans Panneau d'administration → Support.
- Activez Joindre yundera.log et Accorder l'accès SSH.
- Décrivez votre problème en détail et cliquez sur Envoyer au support.
L'équipe de support Yundera pourra diagnostiquer le problème directement sur votre PCS.