3.7 KiB

Raw Blame History

Monitoring mit Uptime Kuma

CluPilot registriert für jede Kundeninstanz ein Uptime-Ziel (https://<subdomain>/status.php) und fragt dessen Gesundheit während der Abnahmeprüfung ab.

Warum eine Bridge?

Uptime Kuma hat keine schreibende REST-API. Monitore anlegen/löschen läuft ausschließlich über Socket.IO — offiziell nur für Kumas eigenes Frontend gedacht. Statt Socket.IO in PHP nachzubauen, läuft ein kleiner Dienst mit:

CluPilot (PHP)  ──REST──▶  kuma-bridge  ──Socket.IO──▶  Uptime Kuma

Die Bridge implementiert exakt den Vertrag, den HttpMonitoringClient ohnehin spricht — am PHP-Code musste nichts geändert werden:

Route	Zweck
`GET /monitors`	Liste (für Idempotenz: existiert die URL schon?)
`POST /monitors`	Monitor anlegen (`{friendly_name, url, type}`)
`GET /monitors/{id}`	Status lesen (`up` / `down` / `pending` / `maintenance`)
`DELETE /monitors/{id}`	Monitor entfernen (bei Kündigung)
`GET /health`	Liveness: 200 solange die Bridge läuft (prüft Kuma NICHT)
`GET /ready`	Readiness: 503, wenn Kuma nicht erreichbar ist

Alle Monitor-Routen erfordern Authorization: Bearer $BRIDGE_TOKEN.

Einrichtung

In Uptime Kuma einen eigenen Benutzer für CluPilot anlegen (nicht den persönlichen Admin verwenden).

.env ausfüllen:

KUMA_URL=http://kuma.dein-host.tld:3001
KUMA_USERNAME=clupilot
KUMA_PASSWORD=<passwort>
KUMA_TOTP=                       # nur falls 2FA aktiv

MONITORING_API_URL=http://kuma-bridge:8080
MONITORING_API_TOKEN=<langes-zufälliges-token>   # = Bridge-Token

Bridge starten (eigenes Compose-Profil, läuft nicht im normalen up):
```
docker compose --profile monitoring up -d --build kuma-bridge
```

Prüfen:

docker compose exec app curl -s http://kuma-bridge:8080/health
# {"bridge":"up"}

# Readiness (eignet sich als Check in Kuma selbst — 503 wenn Kuma fehlt):
docker compose exec app curl -s -o /dev/null -w '%{http_code}\n' http://kuma-bridge:8080/ready
# 200

Config-Cache leeren, falls gesetzt: clupilot artisan config:clear

Verhalten bei Ausfall

Monitoring ist Beobachtung, nicht das Produkt. Fällt Kuma oder die Bridge aus, darf die Bereitstellung eines bezahlten Kunden nicht scheitern:

Der Schritt register_monitoring versucht es genau MONITORING_ATTEMPTS mal (Standard 2 = 1 Versuch + 1 Wiederholung),
danach läuft die Bereitstellung degradiert weiter und schreibt ein sichtbares info-Ereignis in die Admin-Konsole,
mit MONITORING_REQUIRED=true wird Monitoring stattdessen erzwungen (der Lauf schlägt fehl, wenn es nicht erreichbar ist).

Bleibt MONITORING_API_URL leer, ist Monitoring komplett aus: die Bereitstellung notiert eine stabile Kennung und die eigenen Gesundheitsprüfungen (occ status, TLS-Zertifikat, Admin-User) entscheiden weiterhin über die Abnahme.

Wartung

Die Bridge nutzt Kumas interne Socket.IO-API (über uptime-kuma-api). Diese kann sich zwischen Kuma-Releases ändern:

Nach einem Kuma-Upgrade: GET /ready und einen Testkunden prüfen.
Kuma-Version notieren, gegen die getestet wurde.
Bei Bruch ist der Ausfall dank obigem Verhalten nicht kundenwirksam — es fehlen nur neue Monitore, sichtbar als info-Ereignis.

Alternativen (falls Kuma zu fragil wird)

Gatus — Config-as-Code: eine YAML-Datei pro Instanz in einem gemergten Verzeichnis, Hot-Reload, eingebaute Statusseite. Passt zum Muster, mit dem CluPilot schon Traefik-Routen schreibt. Keine API nötig.
Kuvasz — laut Doku vollständige REST-API; der bestehende HttpMonitoringClient wäre dann ohne Bridge nutzbar (evtl. Feld-Mapping).

3.7 KiB Raw Blame History