99 lines
3.7 KiB
Markdown
99 lines
3.7 KiB
Markdown
# 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
|
|
|
|
1. **In Uptime Kuma** einen eigenen Benutzer für CluPilot anlegen (nicht den
|
|
persönlichen Admin verwenden).
|
|
|
|
2. **`.env` ausfüllen:**
|
|
|
|
```dotenv
|
|
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
|
|
```
|
|
|
|
3. **Bridge starten** (eigenes Compose-Profil, läuft nicht im normalen `up`):
|
|
|
|
```bash
|
|
docker compose --profile monitoring up -d --build kuma-bridge
|
|
```
|
|
|
|
4. **Prüfen:**
|
|
|
|
```bash
|
|
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
|
|
```
|
|
|
|
5. 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).
|