Files
backup-orchestrator/docs/UPTIME_KUMA_INTEGRATION.md
T

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

  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:
    http://<uptime-kuma-host>:3001/api/push/abc123token?status=up&msg=OK&ping=
    
  4. 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.json geschü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.log protokolliert.