Cedric Abonnel
151 lines
9.3 KiB
Markdown
151 lines
9.3 KiB
Markdown
> Méthode basée sur l'installation via le script communautaire :
|
|
> [community-scripts.github.io/ProxmoxVE/scripts?id=uptimekuma](https://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
|
|
|
|
```bash
|
|
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 :
|
|
|
|
```bash
|
|
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` :
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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 :
|
|
|
|
```bash
|
|
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 :
|
|
|
|
```bash
|
|
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) :
|
|
|
|
```bash
|
|
sqlite3 kuma.db "VACUUM;"
|
|
```
|
|
|
|
## 7. Redémarrer le service
|
|
|
|
```bash
|
|
systemctl start uptime-kuma
|
|
```
|
|
|
|
Et vérifie qu'il a bien démarré :
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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. |