docs(infra): Troubleshooting-Runbook (pve-mu-2 Tailscale-Key + Systemvorhersage-Fehlalarme)

infrastructure/TROUBLESHOOTING.md

@@ -0,0 +1,58 @@
+# Troubleshooting / Runbooks
+
+Konkrete Loesungen fuer wiederkehrende Befunde, v. a. aus der taeglichen Systemvorhersage des Hausmeister-Bots (CT116).
+
+---
+
+## pve-mu-2 — "Proxmox-Auth-Fehler" / nicht erreichbar (Tailscale-Key abgelaufen)
+
+**Symptom (Systemvorhersage):** `pve-mu-2: Proxmox-Auth-Fehler → Verbindung/Zertifikat pruefen`. Host offline im Tailnet, Port 8006/22 timeouten.
+
+**Identitaet:** Tailscale-Name `pve2-1-deutschland`, Tailscale-IP `100.99.101.37`, lokal `192.168.178.123`, Tailscale hostname-Flag `edge-gateway`.
+
+**Ursache (Stand 01.06.2026):** Der Tailscale-Node-Key war abgelaufen. `tailscaled` lief weiter, war aber `Logged out` → Node faellt aus dem Tailnet, Monitoring-Bot erreicht die Proxmox-API nicht (LLM meldet das als "Auth-Fehler").
+
+**Diagnose:**
+```bash
+# von pve-hetzner
+tailscale ping -c2 100.99.101.37          # "node key has expired" oder timeout
+tailscale status | grep pve2-1-deutschland # offline, last seen N d ago
+```
+Wichtig: Andere Muldenstein-Knoten (pve-mu-3 `100.109.101.12`, hermes-mu) pruefen — sind die online, ist Standort/Internet ok und das Problem ist isoliert auf pve-mu-2.
+
+**Fix:**
+1. In der Tailscale-Admin-Konsole (https://login.tailscale.com/admin/machines) fuer das Geraet **"Disable key expiry"** setzen (dauerhaft fuer Server).
+2. Pruefen ob der Host lebt — ueber pve-mu-3 ins LAN hoppen:
+```bash
+# pve-hetzner -> pve-mu-3 (Passwort astral66) -> pve-mu-2 LAN
+ssh root@100.109.101.12   # bzw. sshpass -p astral66
+ping -c2 192.168.178.123  # ARP/REACHABLE = Host laeuft, nur tailscaled logged out
+ssh root@192.168.178.123 'tailscale status'   # "Logged out"?
+```
+3. Auf pve-mu-2 neu einloggen — **bestehende Nicht-Default-Flags mitnehmen** (sonst meckert `tailscale up`):
+```bash
+tailscale up --hostname=edge-gateway
+```
+Nach deaktiviertem Key-Expiry meldet sich der Node **automatisch ohne Browser-Login** wieder an.
+
+**Verifikation (von pve-hetzner):**
+```bash
+tailscale ping -c3 100.99.101.37             # pong, idealerweise "direct"
+curl -sk -o /dev/null -w '%{http_code}\n' https://100.99.101.37:8006/   # 200
+```
+
+---
+
+## Systemvorhersage — bekannte Fehlalarme
+
+### Last (`load5 > 2.0`)
+`predict.py` flaggt jeden Host mit `load5 > 2.0`. pve-hetzner hat **8 Kerne**; Last 2–4 ist dort meist transienter **IO-Wait** (Backup-/Cron-Fenster, `jbd2`/loop-Devices), kein CPU-Problem. Erst relevant, wenn dauerhaft > nproc oder von hohem `wa` begleitet. Optional Schwelle auf `nproc*0.8` umstellen.
+
+### `portainer: NNN kritische Fehler`
+Das Loki-Label `host=portainer` ist der **Monitoring-Host CT110** (loki, grafana, promtail, portainer), nicht der portainer-Container (der loggt nichts). Die meisten Treffer sind **Grafana-`level=info`-Zeilen mit `ErrorCode`** (Feature-Flag-Eval) und **Loki-interne `scheduler_processor`-Querier-Fehler** — beide stehen in `core/loki_client.py` `ERROR_EXCLUDE_RE`. Die echte Bot-Query (mit Excludes) liefert real nur ~6 benigne Grafana-`usagestats`-Fehler (Phone-Home). Praktisch ein Fehlalarm; optional Grafana-Telemetrie abschalten (`reporting_enabled = false`).
+
+**Pruefen, was real ist:**
+```bash
+# in CT116
+cd /opt/homelab-brain/homelab-ai-bot && python3 -c "import sys; sys.path.insert(0,'.'); from core import loki_client; print(len(loki_client.get_errors(container='portainer', hours=24, limit=300)))"
+```