Réparer une instance Uptime Kuma installée via le script Proxmox

Méthode basée sur l'installation via le script communautaire : community-scripts.github.io/ProxmoxVE/scripts?id=uptimekuma

Si tu utilises Uptime Kuma pour monitorer ton infra, tu finiras tôt ou tard par tomber sur un de ces grands classiques : le service qui refuse de démarrer après une mise à jour, des erreurs SQLite louches dans journalctl, ou pire — l'interface qui tourne mais ne remonte plus aucun heartbeat. Dans 90 % des cas, c'est la base SQLite qui a pris cher, souvent à cause d'un arrêt brutal du conteneur LXC ou d'une migration qui s'est mal passée.

Avant de paniquer et de tout réinstaller, il y a une série d'étapes à dérouler. Je les mets ici dans l'ordre, parce que l'ordre compte : on commence toujours par le moins destructif.

Pourquoi SQLite et pas un vrai SGBD ?

Petite parenthèse pour les juniors qui se demanderaient. Uptime Kuma embarque SQLite parce que c'est une appli pensée pour être facile à déployer : pas de serveur de base à installer à côté, pas de credentials à gérer, juste un fichier kuma.db sur le disque. C'est génial pour démarrer, mais ça a un défaut majeur — SQLite n'aime pas du tout être coupé en plein milieu d'une écriture. Si ton LXC tombe pendant que Kuma écrit un heartbeat, tu peux te retrouver avec un fichier corrompu. D'où l'importance de toujours arrêter proprement le service avant de toucher au fichier.

1. Arrêter le service proprement

systemctl stop uptime-kuma

C'est la première chose à faire, toujours. Tant que le service tourne, il a un verrou sur kuma.db et il continue d'y écrire. Tu peux ouvrir le fichier en lecture avec sqlite3 malgré ce verrou, mais dès que tu veux faire un DELETE ou un PRAGMA, tu vas soit avoir une erreur database is locked, soit — pire — corrompre encore plus la base si tu forces.

Vérifie que c'est bien arrêté avant de continuer :

systemctl status uptime-kuma

Tu dois voir inactive (dead). Pas active, pas activating, pas failed avec un process encore en l'air.

2. Aller dans le dossier de l'app

Le script communautaire installe Kuma dans /opt/uptime-kuma :

cd /opt/uptime-kuma

Dans ce dossier, ce qui nous intéresse c'est le sous-dossier data/. C'est là que vit tout ce qui compte : le fichier kuma.db (la base), les uploads, et quelques fichiers de config. Le reste (server/, node_modules/, etc.) c'est le code de l'application — tu peux le casser, un git pull ou une réinstallation le remettra en place. Mais data/, si tu le perds, tu perds toute ta config de monitoring.

3. Sauvegarder avant de toucher à quoi que ce soit

Règle d'or de l'ops : on ne touche jamais à une base de données sans avoir une copie au chaud. Jamais.

cp -r data data-backup-$(date +%Y%m%d)

Le $(date +%Y%m%d) te génère un suffixe du genre data-backup-20260512. Comme ça si tu fais plusieurs interventions dans la même semaine, tu sais laquelle date de quand, et tu ne risques pas d'écraser une sauvegarde par une autre.

Cette copie embarque :

• la base kuma.db elle-même
• les fichiers WAL (kuma.db-wal, kuma.db-shm) si SQLite est en mode Write-Ahead Logging — c'est important de les prendre avec, sinon ta sauvegarde est incomplète
• les uploads et certificats si tu en as

Si tu sautes cette étape et que tu te plantes à l'étape 5 ou 6, tu n'auras aucun moyen de revenir en arrière. Sérieusement, fais-le.

4. Vérifier l'intégrité de la base

cd data/
sqlite3 kuma.db "PRAGMA integrity_check;"

PRAGMA integrity_check, c'est la commande de diagnostic native de SQLite. Elle parcourt toute la base, vérifie que les index pointent bien sur les bonnes lignes, que les pages ne sont pas corrompues, que les contraintes sont respectées. Deux issues possibles :

• ok : la base est saine sur le plan structurel. Si Kuma ne démarre toujours pas, le problème vient probablement d'une migration coincée (voir étape 5) ou du code de l'app, pas du fichier.
• Une liste d'erreurs : il y a de la corruption. Selon ce qui est touché, on passera à l'étape 5 ou 6.

Pour les juniors qui découvrent SQLite : PRAGMA, c'est le mot-clé que SQLite utilise pour les commandes qui ne sont pas du SQL standard — c'est spécifique à SQLite, tu ne le verras pas dans PostgreSQL ou MySQL.

5. Supprimer un paramètre de migration corrompu

Sur certaines versions de Kuma (notamment autour des montées de version qui touchent à l'agrégation des heartbeats), il y a un bug connu : l'entrée migrateAggregateTableState dans la table setting se retrouve dans un état incohérent, et le service refuse de démarrer parce qu'il pense être au milieu d'une migration qui n'avance plus.

La fix :

sqlite3 kuma.db "DELETE FROM setting WHERE key = 'migrateAggregateTableState';"

Ce qu'on fait, c'est qu'on dit à Kuma : "oublie où tu en étais, repars de zéro sur ce point". Au redémarrage, il va recréer la clé proprement et relancer la migration depuis le début. C'est non destructif pour tes données de monitoring — on ne touche qu'à un drapeau d'état interne.

Si ce n'est pas ton problème (clé absente ou suppression sans effet), passe à la suite.

6. Solution radicale : vider la table heartbeat

Si la corruption est concentrée sur l'historique de monitoring (et c'est souvent le cas, parce que c'est la table où Kuma écrit le plus souvent — un INSERT toutes les 20-60 secondes par sonde, ça finit par faire du volume), tu peux la vider :

sqlite3 kuma.db "DELETE FROM heartbeat;"

À lire attentivement : cette commande supprime tout l'historique des sondes. Tu perds les graphes de uptime, les SLA calculés sur les 30/90/365 derniers jours, tout. En revanche :

• tes sondes sont conservées (table monitor)
• tes utilisateurs aussi (table user)
• tes notifications également (table notification)
• ta config générale est intacte (table setting)

C'est à utiliser uniquement quand :

• PRAGMA integrity_check pointe vers des problèmes sur heartbeat ou ses index
• Kuma refuse de démarrer et l'étape 5 n'a rien donné
• ou plus simplement, ta base a tellement grossi que Kuma rame et que tu acceptes de perdre l'historique pour repartir propre

Tant qu'à faire, profites-en pour faire un VACUUM derrière, qui va vraiment libérer l'espace disque (un DELETE seul ne récupère pas la place sur le disque, il marque juste les pages comme libres pour réutilisation) :

sqlite3 kuma.db "VACUUM;"

7. Redémarrer le service

systemctl start uptime-kuma

Et vérifie qu'il a bien démarré :

systemctl status uptime-kuma

Tu dois voir active (running). Si tu vois failed ou si le service redémarre en boucle, ne le laisse pas dans cet état — passe directement à l'étape 8 pour comprendre pourquoi.

8. Lire les logs

journalctl -u uptime-kuma -f

Le -u uptime-kuma cible le service, le -f fait du follow (équivalent de tail -f) — les nouvelles lignes s'affichent en temps réel. Laisse tourner pendant deux ou trois minutes, le temps que Kuma rejoue ses migrations, recharge ses sondes, et envoie les premiers heartbeats.

Ce qu'il faut chercher dans les logs :

• erreurs SQLite : SQLITE_CORRUPT, database disk image is malformed, attempt to write a readonly database — ça veut dire que t'as encore un problème de fichier, voire de permissions
• migrations bloquées : des messages du genre Running migration... qui ne sont jamais suivis d'un Migration done
• permissions : EACCES, permission denied — typiquement après une intervention faite en root sur des fichiers qui doivent appartenir à un autre utilisateur. Vérifie avec ls -la data/ que les fichiers sont bien possédés par l'user qui fait tourner le service
• modules Node manquants : Cannot find module 'xxx' — ça arrive après une mise à jour qui s'est mal passée. La fix, c'est généralement de relancer npm ci --production dans /opt/uptime-kuma
• port déjà utilisé : EADDRINUSE — tu as un autre process qui squatte le port 3001 (ou celui que tu as configuré)

Pour sortir du journalctl -f, c'est Ctrl+C.

Et après ?

Une fois que Kuma tourne propre, prends cinq minutes pour mettre en place ce qui t'aurait évité d'arriver ici :

1. Une sauvegarde régulière de data/. Un simple cron qui fait tar czf du dossier vers un autre serveur, ça suffit largement pour un Kuma perso. Pense à arrêter le service avant le tar, ou utilise sqlite3 kuma.db ".backup /chemin/sauvegarde.db" qui fait un snapshot cohérent sans devoir couper Kuma.
2. Un monitoring du monitoring. Oui, c'est méta. Mais si Kuma tombe, c'est lui qui t'aurait alerté de la chute de tes autres services — donc personne ne te prévient. Un check externe (UptimeRobot gratuit, healthchecks.io, ou un autre Kuma sur une autre machine) qui ping ton instance, c'est cinq minutes à mettre en place.
3. Garder ta sauvegarde data-backup-AAAAMMJJ au moins une semaine avant de la supprimer. Au cas où un effet de bord apparaîtrait quelques jours plus tard.

Et voilà. Avec ces huit étapes, tu couvres 95 % des cas de Kuma cassé. Pour les 5 % restants — typiquement quand le LXC lui-même a un souci de filesystem — c'est une autre histoire, et il faudra sortir l'artillerie côté Proxmox.