Übersicht und Alerts
Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-ios/uebersicht-und-alerts.md
Übersicht und Alerts
Die Tabs Übersicht und Alerts im Modus PKR-Lab. Sie zeigen den Zustand des Homelabs aus GET /api/dashboard und GET /api/updates der carplay-api.
Code: Views/HomeView.swift, HostCardsView.swift, StatusGridView.swift, AlertsView.swift, AlertsGridView.swift, DetailView.swift, ViewModels/DashboardViewModel.swift, Services/HomeserverAPIClient.swift, Models/
Was es tut
| Bereich | Quelle im Backend | Darstellung |
|---|---|---|
| Hosts | VictoriaMetrics (node-exporter) | Eine Karte je Host, der online ist: CPU, RAM und Disk als Prozentwerte mit Farbe, Temperatur (wenn der Host einen Sensor meldet, also Wert > 0) und Uptime. Offline-Hosts erscheinen nicht, statt mit 0 % verwirrend auszusehen. Gibt es keinen Host: „Kein Host ist gerade erreichbar.“ |
| Status | Uptime-Kuma-Status-Page | Eine Zeile je Monitor: UP · <Ping> · <Uptime>, DOWN, MAINTENANCE, PAUSED, mit Symbol und Farbe. Tippen öffnet ein Detail-Sheet (Status, Ping, Uptime 24 h, letzter Check). Leer: „Keine Monitore konfiguriert“ |
| Dienst-Aktivität | VictoriaMetrics (Traefik-Request-Rate) | Balken je Dienst, sortiert nach Requests pro Sekunde. Die Zahl ist eine Näherung für Aktivität, keine Nutzerzahl |
| Updates | ConfigMap des github-release-watcher | Karte nur, wenn die Liste nicht leer ist oder der Abruf fehlschlug (dann mit „Updates konnten nicht geladen werden: …“): Apps mit neuer Version (aktuell → neu, Link auf das Release) oder „Alle Apps aktuell.“. Bei Apps ohne bekannte aktuelle Version steht ein Hinweis, currentVersion im Watcher nachzutragen |
| Alerts (eigener Tab) | ntfy über ntfy-bridge und Host-Skripte |
Liste aktiver Alarme mit Symbol und Farbe nach Stufe (critical rot, warning orange, info grün). Titel auf 20, Nachricht auf 30 Zeichen gekürzt. Tippen öffnet das Detail (Topic, Level, Empfangen, volle Nachricht). Leer: „Keine aktiven Alerts“ |
Unter den Karten steht „Aktualisiert vor …“ (relative Zeit des letzten erfolgreichen Abrufs), während eines Abrufs „Aktualisiere …“. Pull-to-Refresh lädt Dashboard und Updates neu, auf dem Alerts-Tab nur das Dashboard.
Die Alarme erscheinen nicht auf der Übersicht, sondern nur im Tab Alerts. Woher die Alarme kommen: ntfy, Monitoring und Alerting.
Ablauf
sequenceDiagram
participant V as HomeView
participant M as DashboardViewModel
participant C as HomeserverAPIClient
participant A as carplay-api
V->>M: .task: startAutoRefresh()
loop alle 30 Sekunden
M->>C: getDashboard()
C->>A: GET /api/dashboard (Bearer-Token, Timeout 10 s)
alt HTTP 200
A-->>C: JSON
C-->>M: DashboardPayload
M->>M: dashboard, lastUpdate setzen
C->>C: TailscaleConnectivity: Erfolg
else Fehler
A-->>C: Statuscode oder Netzwerkfehler
C->>C: TailscaleConnectivity: Fehlschlag
C-->>M: Fehler wird in error gespeichert
end
end
V->>M: fetchUpdates() (einmal pro Erscheinen und beim Ziehen)
M->>C: getUpdates() (GET /api/updates)
Die 30-Sekunden-Schleife startet, sobald die Übersicht zum ersten Mal erscheint, und wird nie gestoppt (stopAutoRefresh() wird im Code nicht aufgerufen). Der Alerts-Tab nutzt dieselbe Instanz (DashboardViewModel.shared) und zeigt daher die Daten, die die Schleife liefert. Startet die App im Modus Alltag, läuft die Schleife erst, wenn man einmal zum Modus PKR-Lab wechselt.
Der Abruf der Updates ist einmalig, nicht Teil der Schleife. Ein Fehler landet in updatesError und steht in der Karte „Updates“.
Tolerantes Decodieren
| Feld | Verhalten bei fehlendem oder unbekanntem Wert |
|---|---|
alerts, hosts, status, service_activity |
fehlt oder null: leere Liste |
updated_at |
fehlt: 0 |
| Felder eines Alerts, Hosts, Monitors oder einer Dienst-Aktivität | fehlt: Leerstring, 0 bzw. false; ein fehlendes Feld lässt nicht mehr das ganze Dashboard scheitern. Fehlt id, nimmt die App den Namen (Alert: Topic, Zeit und Titel) |
level eines Alerts |
unbekannt oder fehlt: info |
status eines Monitors |
unbekannt oder fehlt: unknown (grau, Fragezeichen, „UNBEKANNT“), nicht mehr rot wie down |
latest_url eines Updates |
ungültig: kein Link |
hasUpdate |
null: Eintrag erscheint nur im Hinweis „kein bekannter aktueller Stand“ |
Farben
Prozentwerte (CPU, RAM, Disk) färben sich nach Schwelle: unter 50 grün, 50 bis 75 gelb, 75 bis 90 orange, ab 90 rot (StatusPalette.color(forPercentage:)). Die Temperatur hat eigene Schwellen in °C (StatusPalette.color(forTemperature:)): unter 60 grün, 60 bis 75 gelb, 75 bis 85 orange, ab 85 rot.
Randfälle und Einschränkungen
- Fehler stehen im gelben Hinweis. Schlägt ein Abruf fehl, bleibt der zuletzt bekannte Stand stehen, und unter „Homeserver nicht erreichbar — zeige letzten bekannten Stand.“ steht der Fehlertext aus
DashboardViewModel.error(z. B. HTTP-Status oder Decodierfehler). - Der Hinweis erscheint, sobald kein Netzpfad besteht oder die letzte Anfrage an
carplay-apifehlschlug. Dazu zählt jeder Statuscode außerhalb von 200 bis 299, also auch ein falsches Token (401), und ein fehlendes Token („Kein Token im Schlüsselbund gespeichert …“). „Nicht erreichbar“ heißt deshalb nicht zwingend, dass das Netzwerk fehlt. - Wetter-, News- und Tankerkönig-Aufrufe beeinflussen den Hinweis nicht.
- Beim ersten Start ohne Daten sind die Karten leer (
hosts: [],status: []), bis der erste Abruf gelungen ist. - Gelöschte Alarme gibt es nicht: Das Backend liefert nur die Nachrichten der letzten Stunden (
NTFY_SINCE, Standard 12 Stunden). Ältere Alarme verschwinden von selbst. - Es gibt keine Push-Benachrichtigungen. Alarme erreichen das Telefon über ntfy bzw. den Telefon-Alarm, nicht über diese App.
Debugging und Fehlersuche
Das Backend liefert eigene Fehlertexte (JSON {"error": "…"}), die App zeigt sie im gelben Hinweis. Zur Diagnose ruft man die Endpunkte direkt auf:
TOKEN=<TOKEN>
curl --cacert pki/homeserver-root-ca.pem -H "Authorization: Bearer $TOKEN" https://carplay-api.prod.homeserver/api/dashboard | jq .
curl --cacert pki/homeserver-root-ca.pem https://carplay-api.prod.homeserver/health
kubectl -n carplay-api logs deploy/carplay-api --tail=100 # Logs des Backends
| Symptom | Ursache | Lösung |
|---|---|---|
| Gelber Hinweis „Homeserver nicht erreichbar …“ | Netzwerk, VPN oder TLS-Pinning, oder HTTP-Fehler (zum Beispiel 401) | Debugging, curl wie oben |
| Karten bleiben leer, Hinweis fehlt | Abruf gelungen, aber hosts und status leer |
Backend: config.hosts, Uptime-Kuma-Slug prüfen (carplay-api: Fehlerbehebung) |
| Host fehlt, obwohl er läuft | im Backend steht online: false, instance passt nicht zum Label |
instance in config.hosts gegen …/api/v1/targets prüfen |
| Host zeigt 0 % | Metriken fehlen | Backend-Log: PromQL-Fehler, Monitoring |
| Status-Liste leer („Keine Monitore konfiguriert“) | Status-Page-Slug falsch oder Monitore fehlen auf der Page | Uptime-Kuma, Slug in values.yaml |
| Alerts leer, obwohl ntfy Nachrichten hat | config.ntfy.topic oder NTFY_SINCE |
ntfy |
Alle Alerts erscheinen grün (info) |
ntfy-Priorität 1 bis 3 wird zu info |
Priorität im Absender setzen (4 = warning, 5 = critical, siehe 60080) |
| Dienst-Aktivität leer oder 0 req/s | Traefik-Label passt nicht zu ServiceConfig.match oder noch nicht gescrapt |
Backend-Konfiguration, curl $VM_URL/api/v1/label/service/values |
| Karte „Updates“ fehlt | /api/updates leer (ConfigMap nicht vorhanden, Watcher lief noch nicht) oder Abruf fehlgeschlagen (still verworfen) |
github-release-watcher, Backend-Log „reading updates configmap failed“ |
| Update-Karte nennt „Kein bekannter aktueller Stand …“ | currentVersion im Watcher nicht gepflegt |
currentVersion in values.yaml des github-release-watcher nachtragen |
| „Aktualisiert vor …“ bleibt alt | Schleife läuft nicht (App im Modus Alltag gestartet) oder Abrufe schlagen fehl | in den Modus PKR-Lab wechseln, ziehen zum Aktualisieren |
Could not parse response: … (nur im Debugger sichtbar) |
Pflichtfeld status oder updated_at fehlt |
Backend-Version und Antwort prüfen |
Allgemeines: Debugging und Fehlersuche.