PKR-Lab

Ü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


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.