# 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: ```mermaid flowchart TD subgraph "1. Passive Push-Überwachung (Backup-Läufe & Restores)" BO["backup-orchestrator
(systemd daily 05:30)"] BO -->|"HTTP Push: JOB_SUCCESS (up) / JOB_FAILED (down)"| K1["Uptime Kuma
Push Monitor: Einzeljobs"] BO -->|"HTTP Push: RUN_FINISHED (overall ok/failed)"| K2["Uptime Kuma
Push Monitor: Täglicher Gesamtlauf"] end subgraph "2. Aktive Pull-Überwachung (Live-Dienste auf llm-node)" K3["Uptime Kuma
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/?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 1. In Uptime Kuma auf **"Neuen Monitor hinzufügen"** klicken. 2. Folgende Werte eintragen: - **Monitortyp**: `Push` - **Name**: `Backup: Täglicher Gesamtlauf (Pi 5)` (oder `Backup: Gesamtlauf llm-node`) - **Intervall (Heartbeat)**: `86400` Sekunden (24 Stunden) - **Wiederholungsintervall**: `300` Sekunden (5 Minuten) - **Max. Wiederholungen**: `2` 3. Speichern. Uptime Kuma zeigt nun eine Push-URL an: ```text http://:3001/api/push/abc123token?status=up&msg=OK&ping= ``` 4. Den Basis-Teil der URL kopieren: `http://: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: ```json { "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.json` geschützt werden. > - Der Orchestrator akzeptiert sowohl die reine Basis-URL (`.../api/push/`) als auch die von Kuma kopierte Beispiel-URL (`.../api/push/?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: ```bash # 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//notifications.log` protokolliert.