Kapitel 18/Premium Rohtext.md hinzugefügt

2025-10-21 14:43:37 +00:00
parent ce25284e33
commit 50ce8b2643
1 changed files with 362 additions and 0 deletions
--- a/Rohtext.md
+++ b/Rohtext.md
@@ -0,0 +1,362 @@
+# Premium – WAHA: Automatisierte Statusmeldungen & KI-gestützte Antworten
+
+WAHA ist im UCC weit mehr als ein Werkzeug zum Senden einzelner WhatsApp-Nachrichten.  
+Im Premium-Kapitel wird der Dienst zu einem **intelligenten Kommunikationsmodul**, das auf Ereignisse in deinem System reagieren und Informationen automatisiert weitergeben kann.  
+
+Ziel ist eine **vollständige Integration von WAHA in deine bestehende Infrastruktur** – vor allem in Verbindung mit n8n und Netdata.  
+So kannst du dich über wichtige Systemereignisse informieren lassen oder, optional, eingehende Nachrichten automatisch beantworten lassen – datensouverän, lokal und ohne externe Cloud-APIs.  
+
+Das Kapitel ist in zwei praxisnahe Szenarien unterteilt:
+
+1. **Automatische Statusbenachrichtigung über WhatsApp**  
+   – Wenn Netdata einen Alarm oder kritischen Wert erkennt, löst n8n automatisch eine WhatsApp-Nachricht über WAHA aus.  
+   – Du erhältst sofort eine Benachrichtigung über Auslastung, Fehler oder Warnungen, ohne dich aktiv einloggen zu müssen.
+
+2. **KI-gestützte, regelkonforme Antwortfunktion**  
+   – Eine eingehende WhatsApp-Nachricht wird von WAHA empfangen, in n8n verarbeitet und an eine lokale KI weitergeleitet.  
+   – Die KI generiert eine personalisierte Antwort, die über WAHA zurückgesendet wird.  
+   – Diese Variante bewegt sich aktuell **im erlaubten Rahmen**, da sie nur auf vom Nutzer initiierte Nachrichten reagiert,  
+     liegt jedoch **im Graubereich zukünftiger Richtlinienänderungen**.
+
+> [!CAUTION]  
+> Die Nutzung einer automatisierten KI-Antwort über WAHA ist derzeit zulässig, solange jede Kommunikation vom Nutzer selbst initiiert wird  
+> und keine Werbung oder massenhafte Nachrichten versendet werden.  
+> Beachte jedoch, dass Meta die WhatsApp-Richtlinien jederzeit ändern kann.  
+> Sollte WhatsApp künftig KI-basierte Antworten oder WAHA-ähnliche Systeme einschränken,  
+> kann dieses Setup Anpassungen erfordern.
+
+👉 **Screenshot geeignet:** Diagramm mit Datenfluss zwischen Netdata, n8n, KI-Agent und WAHA
+
+Am Ende dieses Kapitels verfügst du über ein vollständig integriertes Benachrichtigungs- und Kommunikationssystem,  
+das deine Infrastruktur in Echtzeit überwacht und bei Bedarf automatisiert reagiert –  
+ein klarer Schritt in Richtung eines selbstlernenden, souveränen Kontrollzentrums.
+
+---
+
+## Statusbenachrichtigung über WAHA
+
+### Schritt 1 – n8n-Workflow mit Deduplizierung und WAHA-Versand
+
+Ziel: Ein **n8n-Workflow** soll Systemereignisse aus Netdata empfangen, diese in Textform bringen, doppelte Alarme herausfiltern und anschließend über **WAHA** als WhatsApp-Nachricht versenden.  
+Damit entsteht ein zentraler Benachrichtigungsweg für kritische Zustände im gesamten UCC.
+
+👉 **Screenshot geeignet:** n8n-Canvas mit drei verbundenen Nodes: *Webhook (POST)* → *Function (Nachricht & Filter)* → *HTTP Request (WAHA)*
+
+#### Node 1 – Webhook (Trigger)
+**Zweck:** Erstellt eine Empfangsadresse, über die Netdata Alarmmeldungen an n8n sendet.
+
+**Node-Typ:** Webhook  
+**Name:** Eingang – Statusalarm  
+**Parameter:**
+- **HTTP Method:** `POST`  
+- **Path:** `/waha/statusalarm`  
+- **Response Mode:** `Last Node`  
+- **Response Code:** `200`
+
+> [!NOTE]  
+> Nach dem Speichern zeigt n8n automatisch die Webhook-URL an, z. B.:  
+> `https://n8n.deinedomain.tld/webhook/waha/statusalarm`  
+> Diese URL wird später in der Netdata-Alarmregel eingetragen, damit Netdata Alarme direkt an diesen Workflow sendet.
+
+👉 **Screenshot geeignet:** Webhook-Node mit sichtbarer URL `.../webhook/waha/statusalarm`
+
+#### Node 2 – Function (Nachricht aufbereiten + Dedupe)
+**Zweck:** Formatiert die eingehenden Daten und verhindert, dass wiederholt identische Alarme mehrfach gesendet werden.  
+Die Funktion merkt sich den letzten Alarm jedes Containers für 10 Minuten.  
+Wenn innerhalb dieses Zeitraums derselbe Host und Alarm erneut eintreffen, wird die Nachricht unterdrückt.
+
+**Node-Typ:** Function  
+**Name:** Nachricht & Filter  
+**Code:**
+```js
+const p = items[0].json || {};
+const host = p.host || 'unbekannt';
+const alarm = p.alarm || 'Alarm';
+const status = p.status || 'warn';
+const value = (p.value !== undefined && p.value !== null) ? String(p.value) : '-';
+const when = p.when || new Date().toISOString();
+
+const key = `${host}_${alarm}_${status}`;
+const now = Date.now();
+const last = $flow.get(key) || 0;
+const interval = 10 * 60 * 1000; // 10 Minuten
+
+if (now - last < interval) {
+  // gleicher Alarm innerhalb von 10 Minuten -> überspringen
+  return [];
+}
+
+$flow.set(key, now);
+
+const text =
+  `⚠️ ${alarm}\n` +
+  `Host: ${host}\n` +
+  `Status: ${status}\n` +
+  `Wert: ${value}\n` +
+  `Zeit: ${when}`;
+
+return [{ json: { text } }];
+```
+
+> [!TIP]  
+> Die Filterzeit lässt sich über die Variable `interval` anpassen.  
+> Für produktive Umgebungen mit vielen Containern sind 10 bis 15 Minuten meist ideal.
+
+👉 **Screenshot geeignet:** Function-Node mit geöffnetem Code-Editor, markiertem Kommentar `// gleicher Alarm innerhalb von 10 Minuten`
+
+#### Node 3 – HTTP Request (WAHA – Statusmeldung senden)
+**Zweck:** Sendet die aufbereitete Nachricht über WAHA an WhatsApp.
+
+**Node-Typ:** HTTP Request  
+**Name:** WAHA – Statusmeldung senden  
+**Parameter:**
+- **Method:** `POST`  
+- **URL:**  
+  ```
+  https://waha.deinedomain.tld/api/sendText
+  ```
+- **Headers:**  
+  - `Content-Type`: `application/json`
+  - *(optional)* `Authorization`: `Bearer <DEIN_WAHA_API_TOKEN>`  
+- **Body → JSON:**  
+  ```json
+  {
+    "chatId": "49XXXXXXXXXXX@c.us",
+    "text": "={{$json[\"text\"]}}"
+  }
+  ```
+
+> [!NOTE]  
+> **Chat-ID ermitteln:**  
+> 1. Sende mit deinem WhatsApp-Gerät eine Testnachricht an den Ziel-Chat.  
+> 2. Öffne `https://waha.deinedomain.tld/api/messages`.  
+> 3. Kopiere den Wert `chatId` aus der letzten eingegangenen Nachricht.  
+>   – Einzelchat endet auf `@c.us`  
+>   – Gruppenchat endet auf `@g.us`  
+> 4. Trage diese ID im Node ein.
+
+> [!IMPORTANT]  
+> WAHA muss im Webinterface den Status **Connected** anzeigen.  
+> Bei *Pairing* oder *Disconnected* kann keine Nachricht gesendet werden.
+
+👉 **Screenshot geeignet:** HTTP-Request-Node mit sichtbarer `chatId`
+
+#### Test des Workflows
+Der Workflow kann manuell getestet werden, bevor Netdata angebunden ist:
+
+```bash
+curl -X POST "https://n8n.deinedomain.tld/webhook/waha/statusalarm" \
+  -H "Content-Type: application/json" \
+  -d '{
+        "host": "ucc-core-01",
+        "alarm": "CPU high",
+        "status": "crit",
+        "value": "96%",
+        "when": "2025-10-20T18:42:00Z"
+      }'
+```
+
+Wenn alles funktioniert, erscheint die Meldung wenige Sekunden später als WhatsApp-Nachricht.
+
+👉 **Screenshot geeignet:** WhatsApp-Chat mit empfangener Meldung „⚠️ CPU high …“
+
+> [!TIP]  
+> Wenn keine Nachricht ankommt, prüfe in n8n die **Execution Logs**.  
+> Dort sollte der HTTP-Request-Node den Statuscode `200` zurückgeben.  
+> Wird keine Ausführung gestartet, ist meist der Webhook-Pfad falsch oder Netdata erreicht den Server nicht.
+
+### Schritt 2 – Netdata-Alarmregel im Parent-LXC für WAHA-Benachrichtigung
+
+Die zentrale Netdata-Instanz im UCC empfängt bereits alle Metriken der Child-Container per Streaming.  
+Damit entfällt die Notwendigkeit, in jedem einzelnen LXC eigene Alarme zu konfigurieren.  
+Stattdessen wird **eine einzige Alarmregel** direkt im **Parent-Container** hinterlegt,  
+die auf aggregierte Systemwerte zugreift und bei Erreichen bestimmter Schwellwerte eine Nachricht über **n8n → WAHA** sendet.
+
+👉 **Screenshot geeignet:** Netdata-Parent-Dashboard mit aktivem Alarm für einen Child-Container
+
+> [!INFO]  
+> Die zentrale Überwachung mit Netdata setzt voraus, dass alle Child-LXC-Container korrekt angebunden sind.  
+> Im **Kapitel 15 – Netdata** wird beschrieben, wie du das Streaming-System einrichtest  
+> und wie die einzelnen Container ihre Metriken an den Parent weitergeben.  
+> Es wird **dringend empfohlen**, dieses Kapitel vollständig umzusetzen,  
+> bevor du hier mit der WAHA-Benachrichtigung fortfährst –  
+> sonst können Alarme fehlen oder falsche Hostnamen übermittelt werden.
+
+#### Zentrale Alarmregel anlegen
+
+1. Öffne auf deinem **Netdata-Parent-LXC** die Health-Konfiguration:
+   ```bash
+   nano /etc/netdata/health.d/waha_notify.conf
+   ```
+
+2. Füge folgende Definition ein:
+   ```
+   alarm: ucc_cpu_high
+   on: system.cpu
+   lookup: average -1m unaligned of user + system
+   units: %
+   every: 1m
+   warn: $this > 80
+   crit: $this > 95
+   exec: /usr/libexec/netdata/plugins.d/alarm-notify.sh
+   to: webhook
+   WEBHOOK_URL="https://n8n.deinedomain.tld/webhook/waha/statusalarm"
+   WEBHOOK_HEADER="Content-Type: application/json"
+   WEBHOOK_BODY="{\"host\":\"${hostname}\",\"alarm\":\"CPU high\",\"status\":\"${status}\",\"value\":\"${value}\",\"when\":\"$(date -Iseconds)\"}"
+   ```
+
+   Diese Regel löst aus, sobald die durchschnittliche CPU-Last eines überwachten Systems über **80 %** steigt (Warnung)  
+   oder **95 %** erreicht (Kritisch).  
+   Netdata ruft dann automatisch den im ersten Schritt erstellten **n8n-Webhook** auf,  
+   der die Nachricht an WAHA weiterleitet.
+
+3. Datei speichern (STRG + O, Enter) und schließen (STRG + X).
+
+4. Konfiguration neu laden:
+   ```bash
+   systemctl restart netdata
+   ```
+
+👉 **Screenshot geeignet:** geöffnete `waha_notify.conf` mit markierten Zeilen `WEBHOOK_URL` und `WEBHOOK_BODY`
+
+#### Test des zentralen Alarms
+
+Um die Funktion zu prüfen, kann ein Test-Alarm ausgelöst werden:
+
+```bash
+sudo -u netdata /usr/libexec/netdata/plugins.d/alarm-notify.sh test webhook
+```
+
+Wenn die Konfiguration korrekt ist,  
+sollte im n8n-Log eine eingehende Anfrage erscheinen  
+und kurz darauf eine WhatsApp-Nachricht mit dem simulierten Alarmtext eintreffen.
+
+👉 **Screenshot geeignet:** WhatsApp-Chat mit empfangener Testnachricht „⚠️ CPU high … (Test)“
+
+> [!NOTE]  
+> Diese Konfiguration gilt global für alle über Streaming verbundenen Systeme.  
+> Netdata sendet bei jeder betroffenen Instanz den Hostnamen automatisch mit (`${hostname}`),  
+> sodass du in WhatsApp genau siehst, **welcher Container** den Alarm ausgelöst hat.
+
+#### Erweiterung auf weitere Ressourcen
+
+Analog zur CPU-Überwachung können weitere Alarme hinzugefügt werden.  
+Dazu kopierst du den Block und passt lediglich den Metrikpfad (`on:`) und Namen (`alarm:`) an.
+
+Beispiele:
+
+**RAM-Überwachung**
+```
+alarm: ucc_ram_high
+on: system.ram
+lookup: average -1m unaligned of used
+units: %
+warn: $this > 80
+crit: $this > 95
+exec: /usr/libexec/netdata/plugins.d/alarm-notify.sh
+to: webhook
+WEBHOOK_URL="https://n8n.deinedomain.tld/webhook/waha/statusalarm"
+WEBHOOK_HEADER="Content-Type: application/json"
+WEBHOOK_BODY="{\"host\":\"${hostname}\",\"alarm\":\"RAM high\",\"status\":\"${status}\",\"value\":\"${value}\",\"when\":\"$(date -Iseconds)\"}"
+```
+
+**Speicherplatz-Überwachung**
+```
+alarm: ucc_disk_low
+on: disk_space._
+lookup: max -5m unaligned of used
+units: %
+warn: $this > 85
+crit: $this > 95
+exec: /usr/libexec/netdata/plugins.d/alarm-notify.sh
+to: webhook
+WEBHOOK_URL="https://n8n.deinedomain.tld/webhook/waha/statusalarm"
+WEBHOOK_HEADER="Content-Type: application/json"
+WEBHOOK_BODY="{\"host\":\"${hostname}\",\"alarm\":\"Disk usage high\",\"status\":\"${status}\",\"value\":\"${value}\",\"when\":\"$(date -Iseconds)\"}"
+```
+
+> [!TIP]  
+> So entsteht eine skalierbare Struktur mit mehreren einfachen Health-Regeln,  
+> die alle denselben Webhook nutzen.  
+> Dadurch bleibt das System wartungsarm, aber du erhältst bei kritischen Zuständen sofort eine Nachricht auf dein Smartphone.
+
+---
+
+## Premium – Elyra: Intelligente WhatsApp-Interaktion mit Opt-In-Trigger
+
+In diesem Premium-Abschnitt erweiterst du dein bestehendes WAHA-Setup um **Elyra** –  
+eine KI-Instanz, die über WhatsApp gezielt auf Nachrichten reagiert, wenn sie vom Nutzer aktiviert wird.  
+Dadurch bleibt die Nutzung im Rahmen der WhatsApp-Richtlinien, da Elyra niemals selbstständig Kontakt aufnimmt.  
+
+👉 **Screenshot geeignet:** WhatsApp-Chat mit „Ich brauche deine Hilfe, Elyra“ als Startbefehl und automatischer Antwort
+
+> [!NOTE]  
+> Elyra ist ein optionales Modul, das lokale oder externe KI-Modelle (z. B. OpenAI, Ollama) ansprechen kann.  
+> Die Integration setzt ein funktionierendes WAHA- und n8n-System aus dem Free-Kapitel voraus.  
+>  
+> Der Ansatz bewegt sich in einem **zulässigen Graubereich**,  
+> da die Kommunikation ausschließlich **user-initiiert** erfolgt und somit kein unerlaubtes Messaging stattfindet.
+
+### Aktivierungslogik
+
+Elyra reagiert nur, wenn sie bewusst aktiviert wird.  
+Die Aktivierung erfolgt über eine eindeutige Eingabe, die als **Opt-In-Trigger** dient:
+
+**Trigger-Phrase:**  
+> „Ich brauche deine Hilfe, Elyra“
+
+Sobald diese Nachricht eingeht, aktiviert n8n den zugehörigen Workflow  
+und leitet den Inhalt an den KI-Knoten weiter.  
+Elyra verarbeitet die Anfrage, erstellt eine Antwort und sendet sie über WAHA an den Chat zurück.
+
+### Beendigungslogik
+
+Die Sitzung endet automatisch, wenn:
+
+1. Der Nutzer „Danke, Elyra“ schreibt, **oder**  
+2. **10 Minuten** lang keine neue Nachricht eingeht.
+
+Beide Bedingungen setzen den Workflow-Status zurück,  
+sodass Elyra keine weiteren Nachrichten beantwortet, bis erneut ein gültiger Trigger empfangen wird.
+
+> [!TIP]  
+> Dieses Verhalten entspricht dem Prinzip klassischer Sprachassistenten wie „Hey Siri“ oder „Alexa“  
+> und sorgt für klare Grenzen zwischen aktiver und passiver Phase.
+
+### Beispielhafte Gesprächssequenz
+
+```
+👤 Nutzer: Ich brauche deine Hilfe, Elyra  
+🤖 Elyra: Natürlich. Wobei darf ich dir helfen?  
+👤 Nutzer: Wann ist der nächste Stream?  
+🤖 Elyra: Der nächste Stream findet am Freitag um 19:30 Uhr statt – Thema: Disney Dreams 🌟  
+👤 Nutzer: Danke, Elyra  
+🤖 Elyra: Gern geschehen. Ich bin wieder im Ruhemodus.
+```
+
+👉 **Screenshot geeignet:** WhatsApp-Chat mit Elyra, die freundlich auf eine Zuschauerfrage reagiert und danach automatisch inaktiv wird.
+
+### Technische Grundlage
+
+Die Logik besteht aus einer kleinen n8n-Kette mit klar definierten Knoten:
+
+| Node | Aufgabe |
+|------|----------|
+| **Webhook (Trigger)** | empfängt eingehende WhatsApp-Nachrichten über WAHA |
+| **IF (Bedingung)** | prüft, ob die Nachricht „Ich brauche deine Hilfe, Elyra“ enthält |
+| **KI-Node (OpenAI / Ollama)** | verarbeitet den Text und erstellt eine Antwort |
+| **HTTP Request → WAHA** | sendet die Antwort an den Chat |
+| **Wait / Timeout-Node** | beendet nach 10 Minuten Inaktivität |
+| **IF („Danke, Elyra“) → Stop** | erkennt das manuelle Opt-Out und stoppt sofort |
+
+Elyra interagiert damit ausschließlich auf Anfrage,  
+arbeitet ressourcenschonend und wahrt alle datenschutzrelevanten Grenzen.
+
+> [!IMPORTANT]  
+> Elyra darf **niemals eigenständig** Nachrichten senden oder neue Chats starten.  
+> Jede Kommunikation muss eindeutig vom Nutzer ausgehen.  
+> Nur so bleibt die Nutzung im Einklang mit den WhatsApp-AGB.
+
+Mit dieser Implementierung erhält dein UCC eine intelligente, aber kontrollierte Interaktionsebene,  
+die sinnvoll zwischen Automatisierung und Nutzerhoheit vermittelt.
+