feat(license): implement Hardware-ID v2, multi-platform Linux support, StateStore LLS2 hardening, and AI Agent docs

2026-08-06 11:39:21 +02:00
parent e9dbe793e2
commit 70b35f7b8b
16 changed files with 1602 additions and 41 deletions
@@ -0,0 +1,153 @@
+# Deploymentcenter — Watchdog Integration für KI-Agenten
+
+> **Zielgruppe**: KI-Agenten & Softwareentwickler  
+> **Zweck**: Einbindung von Heartbeat-Monitoring, Statusmeldungen und Telemetrie in Anwendungen & Serverdienste.
+
+---
+
+## 1. Übersicht
+
+Der **Watchdog** in Deploymentcenter überwacht kontinuierlich den Zustand von Hosts, Diensten, Cronjobs und Proxmox-Hypervisoren. 
+
+Anwendungen senden in regelmäßigen Abständen (standardmäßig alle 60 Sekunden) einen HTTP POST Ping an die Watchdog API. Ausbleibende Pings oder gemeldete Fehler erzeugen automatisch Warnungen im Admin-Dashboard.
+
+---
+
+## 2. API Endpunkt & Authentifizierung
+
+- **URL**: `POST https://dc.mhdf.de/api/watchdog/v1/ping`
+- **Content-Type**: `application/json`
+- **Header**: `X-Agent-Token: <dein_watchdog_agent_token>`
+
+### Request Body Schema (JSON)
+```json
+{
+  "source": "srv-db-01",
+  "instance": "default",
+  "type": "heartbeat",
+  "status": "ok",
+  "message": "Service running smoothly",
+  "interval": 60,
+  "group": "Infrastructure",
+  "os": "Ubuntu 24.04 LTS"
+}
+```
+
+#### Felder:
+- `source` *(string, erforderlich)*: Eindeutiger Name des Dienstes oder Hostnames (z.B. `srv-db-01` oder `PolyTrader Worker`).
+- `instance` *(string, optional)*: Instanzbezeichner (Standard: `default`).
+- `type` *(string)*: `heartbeat`, `host`, `hypervisor_node` oder `guest`.
+- `status` *(string)*: `ok`, `warning` oder `error`.
+- `message` *(string, optional)*: Status- oder Fehlermeldung.
+- `interval` *(int)*: Erwarteter Abstand in Sekunden zwischen zwei Pings (Standard: `60`).
+- `group` *(string, optional)*: Gruppierung im Dashboard (z.B. `Applications`, `Infrastructure`).
+- `os` *(string, optional)*: Betriebssystem-Name (z.B. `.NET 8 Service`, `Debian 12`).
+
+---
+
+## 3. Implementierungsbeispiele
+
+### 3.1 C# (.NET Core / .NET 8+)
+
+```csharp
+using System;
+using System.Net.Http;
+using System.Text;
+using System.Text.Json;
+using System.Threading.Tasks;
+
+public class WatchdogHeartbeatService
+{
+    private static readonly HttpClient Client = new HttpClient();
+    private static readonly string PingUrl = "https://dc.mhdf.de/api/watchdog/v1/ping";
+    private static readonly string Token = "wd_live_token_infra_01_secure";
+
+    public static async Task SendPingAsync(string sourceName, string status = "ok", string message = "Service active")
+    {
+        var payload = new
+        {
+            source = sourceName,
+            instance = "default",
+            type = "heartbeat",
+            status = status,
+            message = message,
+            interval = 60,
+            group = "Services",
+            os = Environment.OSVersion.ToString()
+        };
+
+        string json = JsonSerializer.Serialize(payload);
+        var request = new HttpRequestMessage(HttpMethod.Post, PingUrl)
+        {
+            Content = new StringContent(json, Encoding.UTF8, "application/json")
+        };
+        request.Headers.Add("X-Agent-Token", Token);
+
+        try
+        {
+            HttpResponseMessage response = await Client.SendAsync(request);
+            if (response.IsSuccessStatusCode)
+            {
+                Console.WriteLine("[✔] Watchdog Heartbeat erfolgreich gesendet.");
+            }
+        }
+        catch (Exception ex)
+        {
+            Console.WriteLine($"[✖] Watchdog Ping Fehlgeschlagen: {ex.Message}");
+        }
+    }
+}
+```
+
+### 3.2 Python 3
+
+```python
+import requests
+
+WATCHDOG_URL = "https://dc.mhdf.de/api/watchdog/v1/ping"
+AGENT_TOKEN = "wd_live_token_infra_01_secure"
+
+def send_heartbeat(source_name, status="ok", message="Python Background Task running"):
+    headers = {
+        "Content-Type": "application/json",
+        "X-Agent-Token": AGENT_TOKEN
+    }
+    payload = {
+        "source": source_name,
+        "instance": "default",
+        "type": "heartbeat",
+        "status": status,
+        "message": message,
+        "interval": 60,
+        "group": "Python Services"
+    }
+    try:
+        response = requests.post(WATCHDOG_URL, json=payload, headers=headers, timeout=10)
+        if response.status_code == 200:
+            print("[✔] Watchdog Ping OK")
+    except Exception as e:
+        print(f"[✖] Watchdog Ping Error: {e}")
+```
+
+### 3.3 Bash / Cronjob (Linux)
+
+```bash
+#!/usr/bin/env bash
+
+WATCHDOG_URL="https://dc.mhdf.de/api/watchdog/v1/ping"
+TOKEN="wd_live_token_infra_01_secure"
+SOURCE="$(hostname)"
+
+curl -s -X POST "$WATCHDOG_URL" \
+     -H "Content-Type: application/json" \
+     -H "X-Agent-Token: $TOKEN" \
+     -d '{"source": "'"$SOURCE"'", "status": "ok", "message": "Hourly Backup Task Completed", "interval": 3600}'
+```
+
+---
+
+## 4. Best Practices für KI-Agenten
+
+1. **Heartbeat-Schleife**: Lasse in eigenständigen Hoster-Diensten einen periodischen Timer (z.B. `System.Threading.Timer` oder `BackgroundService`) alle 60s `SendPingAsync` aufrufen.
+2. **Graceful Shutdown**: Sende beim Beenden des Dienstes einen Ping mit Status `stopped` oder `maintenance`.
+3. **Fehlerbehandlung**: Fange Netzwerkfehler bei Watchdog-Pings stets stumm/abgefangen ab, damit der Ausfall des Monitoring-Servers niemals den Hauptanwendungsfluss unterbricht.