4.7 KiB
4.7 KiB
Uptime Kuma Monitoring & Alerting Guide
Der backup-orchestrator verfügt über eine native, out-of-the-box Integration mit Uptime Kuma.
Dieses Dokument beschreibt das Monitoring-Konzept, die Schritt-für-Schritt-Einrichtung und die Konfiguration.
1. Duales Überwachungskonzept
Das Gesamtsystem wird auf zwei komplementären Ebenen überwacht:
flowchart TD
subgraph "1. Passive Push-Überwachung (Backup-Läufe & Restores)"
BO["backup-orchestrator<br/>(systemd daily 05:30)"]
BO -->|"HTTP Push: JOB_SUCCESS (up) / JOB_FAILED (down)"| K1["Uptime Kuma<br/>Push Monitor: Einzeljobs"]
BO -->|"HTTP Push: RUN_FINISHED (overall ok/failed)"| K2["Uptime Kuma<br/>Push Monitor: Täglicher Gesamtlauf"]
end
subgraph "2. Aktive Pull-Überwachung (Live-Dienste auf llm-node)"
K3["Uptime Kuma<br/>HTTP(s) Monitor: 60s Intervall"]
K3 -->|"GET /api/health/ready (Port 8003, 8001...)"| APP1["Shinkan / Kairo Backend"]
K3 -->|"GET / (Port 3003, 8080...)"| APP2["Frontend & Web-UIs"]
end
A. Passive Push-Überwachung (Heartbeat / Dead Man's Snitch)
- Problem bei Crons/Timern: Wenn ein Cronjob gar nicht erst startet (Server abgestürzt, Timer deaktiviert, NAS-Mount fehlt), gibt es keine Fehlermeldung.
- Lösung via Kuma Push: Der Orchestrator sendet am Ende eines Laufs aktiv ein Signal (
/api/push/<token>?status=up&msg=OK). Bleibt dieses Signal nach 24 Stunden aus, schlägt Uptime Kuma automatisch Alarm ("Monitor DOWN"). - Einzelne kritische Jobs (z. B.
paperless-db,shinkan-prod-db,nas-data) können zudem dedizierte Push-Monitore bedienen.
B. Aktive Pull-Überwachung (Service Health)
- Uptime Kuma pollt im Regelbetrieb alle 60 Sekunden die Health-Endpoints (
ready_url) der Container. - Nach einem Staging-Restore durch den Orchestrator wird so sofort verifiziert, ob die Anwendung auch von außen im Netzwerk wieder uneingeschränkt antwortet.
2. Einrichtung in Uptime Kuma (Schritt für Schritt)
Schritt 1: Push-Monitor für den täglichen Backup-Lauf anlegen
- In Uptime Kuma auf "Neuen Monitor hinzufügen" klicken.
- Folgende Werte eintragen:
- Monitortyp:
Push - Name:
Backup: Täglicher Gesamtlauf (Pi 5)(oderBackup: Gesamtlauf llm-node) - Intervall (Heartbeat):
86400Sekunden (24 Stunden) - Wiederholungsintervall:
300Sekunden (5 Minuten) - Max. Wiederholungen:
2
- Monitortyp:
- Speichern. Uptime Kuma zeigt nun eine Push-URL an:
http://<uptime-kuma-host>:3001/api/push/abc123token?status=up&msg=OK&ping= - Den Basis-Teil der URL kopieren:
http://<uptime-kuma-host>:3001/api/push/abc123token.
Schritt 2 (Optional): Push-Monitore für Einzeljobs anlegen
Wiederhole den Vorgang für kritische Einzel-Jobs:
Backup: Shinkan DB (Phase 10)Backup: Paperless DB (Phase 10)Backup: NAS Data Sync (Phase 20)
3. Konfiguration im Backup-Orchestrator
Auf dem jeweiligen Server (raspberrypi5 oder llm-node) wird die Datei /etc/backup-orchestrator/notifications.json gepflegt:
{
"timeout_seconds": 3,
"webhooks": [],
"kuma": {
"overall_push_url": "http://192.168.2.xxx:3001/api/push/YOUR_OVERALL_TOKEN",
"job_push_urls": {
"shinkan-prod-db": "http://192.168.2.xxx:3001/api/push/YOUR_SHINKAN_TOKEN",
"paperless-db": "http://192.168.2.xxx:3001/api/push/YOUR_PAPERLESS_TOKEN",
"nas-data": "http://192.168.2.xxx:3001/api/push/YOUR_NAS_DATA_TOKEN"
}
}
}
Important
- Dateirechte: Die Datei muss mit
chmod 0600 /etc/backup-orchestrator/notifications.jsongeschützt werden.- Der Orchestrator akzeptiert sowohl die reine Basis-URL (
.../api/push/<token>) als auch die von Kuma kopierte Beispiel-URL (.../api/push/<token>?status=up&msg=OK); Abfrageparameter werden automatisch bereinigt.
4. Testen der Uptime Kuma Push-Benachrichtigung
Um die Benachrichtigung zu testen, ohne ein vollständiges Backup auszulösen:
# Trockenlauf / Status-Check (zeigt an, wie viele Kuma-URLs konfiguriert sind):
backup-orchestrator --check
# Testlauf für einen einzelnen Job:
BACKUP_ORCHESTRATOR_CUTOVER_APPROVED=YES backup-orchestrator --run --job shinkan-prod-db
In Uptime Kuma wechselt der Monitor sofort auf "UP" (grün) und zeigt im Ereignisprotokoll die Job-ID, den Laufzeit-Timestamp und die Run-ID an.
5. Fehlertoleranz & Logging
- Entkopplung: Push-Benachrichtigungen werden asynchron über einen Thread-Pool versendet.
- Sicherheitsgarantie: Netzwerk-Timeouts oder Fehler von Uptime Kuma verändern niemals den Exit-Code des Backup-Laufs. Ein erfolgreiches Backup bleibt immer
Exit 0. - Fehlerhafte Push-Versuche werden in
/var/log/backup-orchestrator/<run_id>/notifications.logprotokolliert.