docs: Integrationsanleitungen auf Stand 2.0 bringen, Status "stopped" ergänzen
Watchdog-Anleitung vollständig überarbeitet - Alle drei Codebeispiele trugen das geseedete Demo-Token fest im Quelltext. Es ist an die Source "srv-db-01" gebunden — wer es übernommen hätte, wäre für jeden anderen Dienst abgewiesen worden. Jetzt Umgebungsvariable und eine Anleitung, wie man ein eigenes Token erzeugt. - Der Ratschlag "sende beim Beenden einen Ping mit Status stopped" beschrieb etwas, das die API nicht konnte. Statt die Anleitung an die Lücke anzupassen, ist die Lücke geschlossen: status akzeptiert jetzt "stopped" und "maintenance". Der Evaluator lässt solche Monitore in Ruhe, statt wenige Minuten nach jedem sauberen Shutdown einen Fehlalarm zu erzeugen. - Neu dokumentiert: checks (Gesundheitszustand per Push, ohne offene Ports), metrics samt Verlauf und Abweichungsvergleich, Alarmunterdrückung über die Hierarchie, die Schwellen des Evaluators (2x warning, 4x down) und der erforderliche Cron-Job. Lizenz-Anleitung - Neuer Abschnitt zum Antwortformat. Die Lizenz-Endpunkte antworten bewusst ohne den status/error-Umschlag der übrigen API; das Feld status auf oberster Ebene trägt den Lizenzzustand. Genau diese Besonderheit hatte ich beim Umbau übersehen, weshalb sie jetzt ausdrücklich festgehalten ist — samt Tabelle aller Zustände. - Ergänzt: Deaktivierung braucht den shared_key, mit Beispiel für den .NET- Client und curl. Verhalten bei Ratenbegrenzung. UpdateService-Anleitung - Prüf-Endpunkte dokumentiert (check, latest, releases) samt Antwortformat. - Tabelle zum Versionsvergleich mit den Fällen, die vorher falsch liefen. - Auto-Resolve beim Veröffentlichen beschrieben. Agent-Prompt-Vorlage - Fehler-Schnittstelle ergänzt, inklusive Hinweis auf "ignored": true, damit ein Agent bekannte Fehler nicht untersucht. Alle in der Dokumentation genannten API-Pfade und Scopes wurden maschinell gegen Routing und TokenManager abgeglichen. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Deploymentcenter Bot
co-authored by
Claude Opus 5
Claude Opus 5
parent
65e60899f9
commit
5f9b0c5596
@@ -1,16 +1,58 @@
|
||||
# Deploymentcenter — Lizenzsystem Integration für KI-Agenten
|
||||
|
||||
> **⚠️ Geändert in Version 2.0** — `/api/license/v1/validate` bleibt unverändert
|
||||
> und ohne Token erreichbar. `/api/license/v1/deactivate` verlangt weiterhin
|
||||
> Authentifizierung, allerdings mit dem **neu erzeugten** `shared_key`: der alte
|
||||
> Wert lag im Repository und wurde ersetzt. Die Signatur der Offline-Lizenzdateien
|
||||
> ist jetzt ein ehrlich benanntes HMAC-SHA256 statt der irreführenden Bezeichnung
|
||||
> `ED25519_SIG_`. Umstellungsschritte: **[UPGRADE.md](./UPGRADE.md)**.
|
||||
> **Zielgruppe**: KI-Agenten & Softwareentwickler
|
||||
> **Gültig ab**: Hardware-ID v2, Deploymentcenter 2.0
|
||||
> **Plattformen**: Windows, Linux (inkl. systemd und Docker), macOS
|
||||
|
||||
> **⚠️ Änderungen in Version 2.0**
|
||||
> - `/api/license/v1/validate` bleibt **unverändert** und ohne Token erreichbar.
|
||||
> Ausgelieferte Clients laufen ohne Anpassung weiter.
|
||||
> - `/api/license/v1/deactivate` verlangt weiterhin Authentifizierung — aber mit
|
||||
> dem **neu erzeugten** `shared_key`. Der alte Wert lag im Repository und wurde
|
||||
> ersetzt; wer ihn irgendwo eingetragen hat, muss nachziehen.
|
||||
> - Die Signatur der Offline-Lizenzdateien heißt jetzt ehrlich HMAC-SHA256 statt
|
||||
> irreführend `ED25519_SIG_`. Der frühere „Server Public Key" im WebUI war frei
|
||||
> erfunden und wurde entfernt.
|
||||
>
|
||||
> Umstellungsschritte: **[UPGRADE.md](./UPGRADE.md)**
|
||||
|
||||
> **Zielgruppe**: KI-Agenten & Softwareentwickler
|
||||
> **Gültig ab**: Hardware-ID v2 Specification (August 2026)
|
||||
> **Plattformen**: Windows, Linux (inkl. systemd Services & Docker-Container), macOS
|
||||
---
|
||||
|
||||
## 0. Antwortformat — bitte beachten
|
||||
|
||||
Die Lizenz-Endpunkte antworten **ohne** den `status`/`error`-Umschlag der
|
||||
übrigen Deploymentcenter-API. Das Feld `status` auf oberster Ebene trägt den
|
||||
**Lizenzzustand**:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "validation_result",
|
||||
"status": "valid",
|
||||
"issued_at": 1786435199,
|
||||
"expires_at": 1817971199,
|
||||
"cache_ttl_hours": 168,
|
||||
"hardware_id": "2:win:a765bd47...",
|
||||
"license_key": "XXXXX-XXXXX-XXXXX-XXXXX-XXXXX",
|
||||
"nonce": "der übergebene Wert",
|
||||
"endpoints": { "validate": "/api/license/v1/validate",
|
||||
"deactivate": "/api/license/v1/deactivate" },
|
||||
"message": "License is valid"
|
||||
}
|
||||
```
|
||||
|
||||
| `status` | Bedeutung |
|
||||
|---|---|
|
||||
| `valid` | Lizenz gültig, Aktivierung eingetragen |
|
||||
| `not_found` | Projekt oder Schlüssel unbekannt |
|
||||
| `revoked` | Lizenz widerrufen **oder diese Hardware gesperrt** |
|
||||
| `suspended` | Lizenz vorübergehend ausgesetzt |
|
||||
| `expired` | Ablaufdatum überschritten |
|
||||
| `activation_limit` | Maximale Anzahl Aktivierungen erreicht |
|
||||
|
||||
> Diese Sonderstellung ist bewusst: Ein Umschlag mit `status: "success"` würde
|
||||
> von jedem bestehenden Client als „nicht valid" gelesen — sämtliche Lizenzen
|
||||
> gälten schlagartig als ungültig. Wer eine eigene Anbindung schreibt, muss
|
||||
> `status` also **von der obersten Ebene** lesen, nicht aus einem `result`-Objekt.
|
||||
|
||||
---
|
||||
|
||||
@@ -123,6 +165,41 @@ my-service --license-set-key LLAB1-98A72-B3C4D-5E6F7-89012
|
||||
my-service --license-deactivate
|
||||
```
|
||||
|
||||
### Deaktivierung braucht Authentifizierung
|
||||
|
||||
`/api/license/v1/deactivate` gibt einen Aktivierungsplatz frei und ist deshalb
|
||||
geschützt — sonst könnte jeder fremde Installationen abmelden. Der Aufruf
|
||||
verlangt den `shared_key` aus `config/config.php`:
|
||||
|
||||
```csharp
|
||||
// Der Schlüssel gehört auf den Administrationsrechner, nicht in die
|
||||
// ausgelieferte Anwendung.
|
||||
var client = new LicenseClient();
|
||||
bool released = await client.DeactivateAsync(
|
||||
productSlug: "myapp",
|
||||
licenseKey: "LLAB1-98A72-B3C4D-5E6F7-89012",
|
||||
serverBaseUrl: "https://dc.mhdf.de",
|
||||
authToken: Environment.GetEnvironmentVariable("DC_SHARED_KEY"));
|
||||
```
|
||||
|
||||
```bash
|
||||
curl -X POST https://dc.mhdf.de/api/license/v1/deactivate \
|
||||
-H "Authorization: Bearer $DC_SHARED_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"product":"myapp","license_key":"XXXXX-...","hardware_id":"2:win:a765..."}'
|
||||
```
|
||||
|
||||
Alternativ genügt für Einzelfälle der Knopf **Freigeben** in der Hardware-Liste
|
||||
des WebUI — das ist der übliche Weg und braucht keinen Schlüssel im Feld.
|
||||
|
||||
### Was passiert bei Ratenbegrenzung
|
||||
|
||||
`/validate` ist auf 120 Anfragen pro Minute und IP begrenzt. Darüber kommt
|
||||
`429` mit `{"status":"error","error":{"code":"rate_limited"}}` — hier greift
|
||||
ausnahmsweise das Umschlagformat, weil die Drosselung vor der Lizenzlogik
|
||||
zuschlägt. Ein Client sollte in dem Fall den lokalen Cache verwenden und es
|
||||
später erneut versuchen, statt die Anwendung zu blockieren.
|
||||
|
||||
---
|
||||
|
||||
## 5. Migration v1 → v2 ohne Platzverlust
|
||||
|
||||
Reference in New Issue
Block a user