PKR-Lab

Steuerung

Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-ios/steuerung.md

Steuerung

Der Tab Steuerung im Modus PKR-Lab: Bildschirmhelligkeit des Homeservers, Wake und Shutdown der Worker, Shutdown des Homeservers und Wake-on-LAN für den Windows-PC im Vereinsheim.

Code: Views/PowerView.swift, ViewModels/PowerViewModel.swift, Services/HomeserverAPIClient.swift, Services/RemoteWolAgentClient.swift, Models/PowerModels.swift, Models/RemoteWolTarget.swift

Das Backend dazu: carplay-api mit dem power-agent auf dem Homeserver. Der Cluster-Betrieb (Worker nachts aus): Cluster Power Manager.


Was es tut

Karte Aktion Wirkung
Bildschirmhelligkeit Slider 0 bis 100 % in 5er-Schritten Setzt die Helligkeit des eingebauten Bildschirms des Homeservers (HP ProBook 450 G9)
ControlPlane-1 keine (reine Statusanzeige) Zeigt nur Online/Offline. ControlPlane-1 läuft dauerhaft und wird nicht per Wake-on-LAN oder Shutdown gesteuert
Worker 1 Aufwecken (aktiv, wenn der Host offline ist), Ausschalten (aktiv, wenn online) Wake-on-LAN bzw. Shutdown über carplay-api. Ausschalten fragt vorher „… wirklich herunterfahren?“
Homeserver Homeserver herunterfahren Öffnet ein Warn-Sheet mit Code-Eingabe. Kein Wake-on-LAN möglich. Das Sheet warnt: ohne ControlPlane-0 ist die Kubernetes-API nicht schreibbar, auch wenn ControlPlane-1 läuft
Windows-PC (Vereinsheim) Aufwecken Sendet ein Magic Packet über den Banana Pi am Standort. Kein Online-Status, keine Rückfrage

Der Online-Status der Karten kommt aus den Host-Metriken der Übersicht (hosts[], Kennung controlplane-1, worker-1, homeserver). Ist ein Host dort nicht aufgeführt, gilt er auf den Worker-Karten und auf der ControlPlane-1-Karte als offline, auf der Homeserver-Karte als online.


Technische Umsetzung

Aktion Aufruf Authentifizierung
Helligkeit lesen GET /api/brightness → {"percent": n} Bearer-Token carplay-api
Helligkeit setzen PUT /api/brightness mit {"percent": n} wie oben
Wake POST /api/power/wake mit {"target": "worker-1"} wie oben
Shutdown POST /api/power/shutdown mit {"target": …, "code": …}; code nur beim Homeserver wie oben, Code serverseitig geprüft
Windows-PC wecken POST https://100.123.214.4:9102/wol mit {"target": "windows-pc"} eigenes Token des WoL-Agents

carplay-api reicht Helligkeit, Wake und Shutdown an den power-agent auf dem Host weiter, weil der Pod selbst keinen Zugriff auf Backlight, poweroff oder SSH hat. Den Vereinsheim-PC erreicht die App direkt, am Backend vorbei, weil das Vereinsheim kein Dashboard-Eintrag ist (Planung: WoL über Router/VPN, Alarmmonitor).


Ablauf: Homeserver herunterfahren

sequenceDiagram
    participant N as Nutzer
    participant A as App (PowerView)
    participant B as carplay-api
    participant P as power-agent (Homeserver)
    N->>A: Homeserver herunterfahren
    A-->>N: Warn-Sheet, Code-Eingabe
    N->>A: Code, Bestätigen
    A->>B: POST /api/power/shutdown {target: homeserver, code}
    alt Code falsch oder leer
        B-->>A: 401, nichts passiert
        A-->>N: Fehlertext im Sheet, Sheet bleibt offen
    else Secret nicht konfiguriert
        B-->>A: 503
    else Code stimmt
        B->>P: Shutdown weiterreichen (eigenes Token)
        P-->>B: 200
        B-->>A: 200
        A-->>N: Sheet schließt, Dashboard wird neu geladen
        P->>P: cordon, drain (bis 180 s), k3s stoppen, poweroff
    end

Der Code ist derselbe wie das ArgoCD-Admin-Passwort, wird aber nicht live dagegen geprüft: Er steht als SealedSecret carplay-api-shutdown-code im Cluster und wird bei jeder Passwort-Rotation von Hand erneuert (carplay-api: Ersteinrichtung, Schritt 4). Der Shutdown ist nicht sofort: Der Node wird geleert, k3s gestoppt, erst dann folgt der Poweroff, was einige Minuten dauert. Ein Wiedereinschalten geht nur vor Ort.

Nach jeder Wake- oder Shutdown-Aktion lädt die App das Dashboard neu (DashboardViewModel.fetchDashboard()), damit der Online-Status nachzieht. Ein gerade geweckter Host erscheint erst als online, wenn er hochgefahren ist und Metriken liefert.


Einschränkungen


Debugging und Fehlersuche

Meldung (rote Zeile) Ursache Lösung
carplay-api returned HTTP 401 oder die Fehlermeldung des Servers Bearer-Token fehlt oder falsch Token unter Einstellungen neu eingeben (Wert wie beim Versiegeln)
Nach Homeserver-Shutdown: 401 mit Fehlertext im Sheet Code stimmt nicht mit secrets.shutdownConfirmationCode überein, meist nach einer ArgoCD-Passwort-Rotation Secret im Backend nachziehen (Ersteinrichtung)
… HTTP 503 beim Homeserver-Shutdown secrets.shutdownConfirmationCode.enabled ist false im Backend aktivieren und versiegeln
… HTTP 502 bei Helligkeit, Wake oder Shutdown power-agent nicht erreichbar oder Token passt nicht zu /etc/power-agent/token systemctl status power-agent auf dem Homeserver, Secret carplay-api-power-agent-token prüfen, Rolle power_agent
… HTTP 403 IP-Allowlist im Backend blockt das Gerät config.trustedProxies und Allowlist prüfen
… HTTP 429 Rate-Limit pro Minute überschritten kurz warten
The request timed out. / Zeitüberschreitung (iOS-Systemtext) 10 Sekunden Timeout, Host oder VPN nicht erreichbar Tailscale prüfen (Tailscale)
cancelled / abgebrochen (iOS-Systemtext) bei allen Aufrufen TLS-Pinning lehnt das Zertifikat ab (Root-CA fehlt, falsche CA, abgelaufen) Verbindung und Sicherheit
Vereinsheim: No API token stored in Keychain — open Settings to add one. Token des WoL-Agents fehlt im Einstellungs-Sheet eintragen, Auslesen siehe Alarmmonitor
Vereinsheim: HTTP 401 mit Fehlertext falsches Agent-Token Token neu auslesen (/etc/banana-pi-wol-agent/token auf dem Pi)
Vereinsheim: Timeout oder Verbindungsfehler Banana Pi nicht im Tailnet, Agent läuft nicht tailscale status, systemctl status des WoL-Agents, Rolle banana_pi_kiosk
Helligkeitskarte zeigt dauerhaft Spinner GET /api/brightness hängt, power-agent nicht erreichbar wie 502 oben
„Aufwecken“ ist ausgegraut App hält den Host für online (Metriken da) Übersicht prüfen, ggf. Metriken im Backend
Worker wird nach „Aufwecken“ nicht online WoL kommt nicht an (Router, BIOS, Kabel) oder Host bootet noch Wake-on-LAN, Cluster Power Manager
Homeserver-Shutdown meldet Erfolg, Host läuft minutenlang weiter Erwartet: drain mit bis zu 180 s Timeout läuft zuerst journalctl -u power-agent -f auf dem Homeserver

Checkliste „Steuerung funktioniert nicht“:

  1. Zeigt die Übersicht Daten? Wenn nicht: Übersicht und Alerts zuerst.
  2. Token vorhanden? Einstellungen → „Es ist bereits ein Token gespeichert.“
  3. Backend direkt prüfen: curl -H "Authorization: Bearer <TOKEN>" https://carplay-api.prod.homeserver/api/brightness.
  4. kubectl -n carplay-api logs deploy/carplay-api und journalctl -u power-agent auf dem Homeserver.
  5. Vereinsheim: Agent direkt prüfen (Token, curl -k nur zur Diagnose, TLS-Zertifikat mit IP-SAN).

Allgemeines: Debugging und Fehlersuche.