Cedric Abonnel
4.1 KiB
(Méthode basée sur l’installation via le script communautaire Proxmox : https://community-scripts.github.io/ProxmoxVE/scripts?id=uptimekuma)
Lorsque Uptime Kuma rencontre des problèmes de démarrage, des erreurs dans la base SQLite, ou des comportements anormaux après une mise à jour, il peut être nécessaire d’effectuer une série de vérifications et de corrections. Le guide ci-dessous détaille les étapes recommandées pour diagnostiquer et réparer votre instance Uptime Kuma tout en minimisant les risques de perte de données.
1. Arrêt du service Uptime Kuma
Avant toute manipulation sur les fichiers de données, il est indispensable d’arrêter correctement le service :
systemctl stop uptime-kuma
L’arrêt garantit que la base SQLite ne subit aucune écriture pendant la maintenance. Sans cela, on risque d’aggraver les corruptions ou de provoquer des pertes de données.
2. Accéder au dossier de l’application
Le script communautaire installe généralement Uptime Kuma dans /opt/uptime-kuma :
cd /opt/uptime-kuma
Ce répertoire contient le code de Kuma ainsi que le dossier data, qui renferme toutes les données utilisateur, les paramètres, les historiques de monitoring et la base de données kuma.db.
3. Sauvegarde des données avant intervention
Avant toute réparation, il est impératif de créer une copie de la base SQLite :
cp -r data data-backup-$(date +%Y%m%d)
Cette sauvegarde permet de revenir en arrière en cas de problème. Elle inclut notamment :
- la base de données
kuma.db - les historiques de monitoring
- les configurations des sondes
- les paramètres de l’interface
⚠️ Ne jamais sauter cette étape, surtout si vous modifiez la base à la main.
4. Vérification de l’intégrité de la base SQLite
On se rend ensuite dans le dossier des données :
cd data/
Puis on effectue une vérification complète :
sqlite3 kuma.db "PRAGMA integrity_check;"
Cette commande retourne :
- ok → la base est saine
- un ou plusieurs messages d’erreur → corruption ou index endommagé
Selon le résultat, il faudra peut-être appliquer une des corrections suivantes.
5. Suppression d’un paramètre problématique dans la base
Certaines versions d’Uptime Kuma ont rencontré un problème lié à l’entrée migrateAggregateTableState dans la table setting.
Si cette clé est corrompue ou mal migrée, elle peut empêcher le service de démarrer.
La correction consiste à supprimer cette entrée :
sqlite3 kuma.db "DELETE FROM setting WHERE key = 'migrateAggregateTableState';"
Cette action force Uptime Kuma à recréer proprement l’état de migration au prochain démarrage.
6. Solution extrême : vider toute la table heartbeat
Si les problèmes concernent uniquement les historiques (table heartbeat corrompue), une solution radicale consiste à vider la table :
sqlite3 kuma.db "DELETE FROM heartbeat;"
⚠️ Cette commande supprime tout l’historique des sondes, mais ne touche pas aux sondes ni aux paramètres. À utiliser uniquement en dernier recours si :
- la vérification SQLite échoue
- Uptime Kuma ne démarre plus
- l’historique est corrompu
7. Redémarrage du service
Une fois les corrections effectuées :
systemctl start uptime-kuma
Si la base est correcte, Uptime Kuma devrait redémarrer normalement.
8. Consultation des journaux pour valider les corrections
Pour suivre en temps réel les messages du service et détecter d’éventuelles anomalies persistantes :
journalctl -u uptime-kuma -f
Points à surveiller dans les logs :
- erreurs SQLite
- migrations bloquées
- permissions incorrectes
- modules Node.js manquants
- services stoppés subitement
Les journaux permettent de confirmer que la base est stable et que le service démarre correctement.