Deploymentcenter BotandClaude Opus 5
f8771c8d1b
Sieben Rueckmeldungen aus einer laufenden Integration. Der schwerwiegendste Punkt ist ein Fehler von mir. D2 - Predictalytics ist ausgesperrt. Bestaetigt: /releases/predictalytics/ antwortet mit 401, waehrend die API weiter "Update verfuegbar" meldet. Jede ausgelieferte Installation laeuft damit in die Wand. Ursache ist nicht der Schutz an sich, sondern dass ich ihn scharfgeschaltet habe, ohne zu pruefen, ob die Verbraucher nachgezogen sind - genau der Fall, vor dem UPGRADE §16.1 warnt. Behoben wird die Klasse des Problems, nicht nur dieser Fall: Produkte lassen sich unter UpdateService -> Zugangsschutz einzeln ausnehmen. Damit ist der gestaffelte Rollout moeglich, der bisher fehlte: ausnehmen, Build mit Schluessel ausliefern, wieder einschalten. Ausgenommene Produkte sind in der Uebersicht deutlich als AUSGENOMMEN markiert und faerben den Selbsttest nicht gruen. D5 - BuildInfo.targets verhinderte inkrementelle Builds. BuildDateUtc trug die volle Uhrzeit, aenderte sich also bei jedem Build; WriteOnlyWhenDifferent griff nie, und jedes einbindende Projekt wurde jedes Mal neu uebersetzt. Jetzt tagesgenau. Das Commit-Datum waere stabiler, laesst sich aber nicht verlaesslich holen - die Formatangabe von git log ueberlebt MSBuild und cmd.exe nicht, wie ein Fehlversuch gezeigt hat. D4 - LicenseConfig war uneinheitlich und fuer Dienste unbrauchbar. SetStorageDirectory benutzte den Pfad roh, waehrend der Weg ueber die Umgebungsvariable <slug>/license anhaengte: zwei Produkte im selben Prozess schrieben in dieselbe state.dat. Und ohne $HOME - systemd User= ohne Heimatverzeichnis - landete der Rueckfall im Installationsverzeichnis, unter /opt nicht beschreibbar. Neu: einheitliches Anhaengen und ein Rueckfall auf /var/lib/<slug>, der vorher prueft, ob dort ueberhaupt geschrieben werden kann. D1 - Woher die Anwendung den Lizenzschluessel fuer den Update-Zugang nimmt, stand nirgends zusammenhaengend. Jetzt ein Beispiel in UPDATESERVICE §5A, das TryGetCachedKey und CheckForUpdateAsync verbindet. D3 - Fuer einen laufenden systemd-Dienst gab es keinen Update-Weg. Neu: SETUP §4A mit einer oneshot-Unit, die stoppt, aktualisiert und wieder startet - ohne --restart, weil der Agent sonst an systemd vorbei einen zweiten Prozess startet. Inklusive EnvironmentFile fuer den Schluessel und dem Hinweis auf die Dateirechte nach einem Lauf als root. D6 - Die Empfehlung Environment.Exit(1) passt fuer handelnde Systeme nicht. Ein neuer Abschnitt im Lizenz-Leitfaden beschreibt den Sperrbetrieb: abschalten, was neue Verpflichtungen eingeht; weiterlaufen lassen, was bestehende abwickelt. D7 - Die Drosselungsgrenzen aller Endpunkte stehen jetzt in docs/README.md. /api/errors/v1/report erlaubt 300 pro Minute, nicht 60; die Einstellung bugtracker.error_rate fehlte in der Beispielkonfiguration. Der zweite Teil des Befunds war veraltet: docs/README.md fuehrt die Release-Anleitung bereits. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
112 lines
5.0 KiB
Markdown
112 lines
5.0 KiB
Markdown
# Deploymentcenter — Entwickler- und Agenten-Dokumentation
|
|
|
|
Zentrale Plattform für Lizenzverwaltung, Software-Updates, Infrastruktur-
|
|
Monitoring und einen Bugtracker, den Coding-Agenten selbständig bedienen.
|
|
|
|
---
|
|
|
|
## Zuerst lesen
|
|
|
|
| Dokument | Wofür |
|
|
|---|---|
|
|
| **[UPGRADE.md](./UPGRADE.md)** | **Ablaufplan für die Umstellung auf 2.0.** Enthält Pflichtschritte: Zugangsdaten wechseln, Migration, Evaluator-Cron. |
|
|
| **[Änderungen](../public/docs/changelog.json)** | Was sich je Fassung geändert hat und was zu tun ist. Öffentlich unter `/docs/changelog.php`, maschinenlesbar über `GET /api/updateservice/v1/changelog?since=X` |
|
|
| **[Release-Anleitung für Agenten](../public/docs/release.md)** | Ein Projekt veröffentlichungsfähig machen: Vorlage kopieren, konfigurieren, ausliefern |
|
|
| [Agent-Prompt-Vorlage](./AGENT_PROMPT_TEMPLATE.md) | Textbaustein für `CLAUDE.md` / `AGENTS.md` eines Projekts |
|
|
| [Agenten-Handbuch](../public/docs/bugtracker.md) | Vollständige Beschreibung des Bugtracker-Workflows, öffentlich unter `/docs/` |
|
|
|
|
## Modul-Handbücher
|
|
|
|
- **[Lizenzsystem (Hardware-ID v2)](./LICENSE_INTEGRATION_GUIDE.md)** — Hardware-Anbindung, Schlüsselvalidierung, Offline-Cache, CLI, Windows und Linux/Docker
|
|
- **[Watchdog (Heartbeat & Telemetrie)](./WATCHDOG_INTEGRATION_GUIDE.md)** — Überwachung von Anwendungen, Diensten und Infrastruktur
|
|
- **[UpdateService](./UPDATESERVICE_INTEGRATION_GUIDE.md)** — Release-Verteilung und Update-Prüfung
|
|
- **[Erstinstallation](./SETUP_INTEGRATION_GUIDE.md)** — `setup.json`, Installationskonto, `update-agent --action install`
|
|
- **[Bugtracker](./BUGTRACKER_INTEGRATION_GUIDE.md)** — Anbindung aus Anwendungen heraus
|
|
|
|
---
|
|
|
|
## Modulübersicht
|
|
|
|
| Modul | Aufgabe | Endpunkte | Authentifizierung |
|
|
|---|---|---|---|
|
|
| **Bugtracker** | Fehler, Feature Requests und Ideen; Agenten-Workflow mit Claim/Lease | `/api/bugtracker/v1/report`<br>`/api/bugtracker/v1/projects`<br>`/api/bugtracker/v1/manage` | Token mit `bugtracker:*` |
|
|
| **UpdateService** | Release-Verteilung, semantischer Versionsvergleich | `/api/updateservice/v1/check`<br>`/api/updateservice/v1/publish` | Lesen offen, Publish braucht `updateservice:publish` |
|
|
| **Watchdog** | Heartbeat-Monitoring, Zustandsbewertung, Alarmierung | `/api/watchdog/v1/ping`<br>`/api/watchdog/v1/evaluate` | Token mit `watchdog:ping` |
|
|
| **Lizenzen** | Lizenzprüfung, Hardware-ID v2, Offline-Cache | `/api/license/v1/validate`<br>`/api/license/v1/deactivate` | Validierung offen, Deaktivierung authentifiziert |
|
|
| **Tokens** | Selbst-Provisionierung von Sub-Tokens | `/api/tokens/v1/provision` | Master-Token |
|
|
| **Setup** | Erstinstallation: Anmeldung, Katalog, Anwendungstoken | `/api/setup/v1/login`<br>`/api/setup/v1/catalog`<br>`/api/setup/v1/token` | Login offen, Rest `setup:*` |
|
|
| **System** | Verfügbarkeit, Schema-Status, Schnittstellenbeschreibung | `/api/health`<br>`/api/openapi.json` | Health optional, OpenAPI offen |
|
|
|
|
---
|
|
|
|
## Schnittstelle maschinenlesbar
|
|
|
|
```
|
|
GET https://dc.mhdf.de/api/openapi.json
|
|
```
|
|
|
|
Ein Agent kann sich daran selbst orientieren — der früher fest im WebUI
|
|
hinterlegte Textblock entfällt damit.
|
|
|
|
---
|
|
|
|
## Drosselung
|
|
|
|
Je IP und Minute. Wird die Grenze überschritten, antwortet der Endpunkt mit
|
|
`429 rate_limited` — dann das Intervall verdoppeln und später erneut versuchen,
|
|
nicht sofort wiederholen.
|
|
|
|
| Endpunkt | Grenze | Einstellbar über |
|
|
|---|---|---|
|
|
| `/api/errors/v1/report` | **300** | `bugtracker.error_rate` |
|
|
| `/api/bugtracker/v1/report` | 60 | `bugtracker.report_rate` |
|
|
| `/api/license/v1/*` | 120 | fest |
|
|
| `/api/updateservice/v1/*` | 240 | fest |
|
|
| `/api/setup/v1/login` | 10 | fest — dort werden Passwörter geprüft |
|
|
| `/api/tokens/v1/provision` | 20 | fest |
|
|
|
|
---
|
|
|
|
## Antwortformat
|
|
|
|
Alle JSON-Endpunkte antworten einheitlich:
|
|
|
|
```json
|
|
{ "status": "success", "…": "…" }
|
|
```
|
|
|
|
```json
|
|
{ "status": "error", "error": { "code": "already_claimed", "message": "…" } }
|
|
```
|
|
|
|
Der `code` ist stabil und für Programme gedacht; die `message` richtet sich an
|
|
Menschen und kann sich ändern.
|
|
|
|
---
|
|
|
|
## Betrieb
|
|
|
|
| Aufgabe | Befehl |
|
|
|---|---|
|
|
| Deployment | `python scripts/deploy.py` |
|
|
| Migration | `php public/install_db.php` oder WebUI → System → DB-Migration |
|
|
| Evaluator (Cron, minütlich) | `curl -fsS -H "Authorization: Bearer <SHARED_KEY>" https://dc.mhdf.de/api/watchdog/v1/evaluate` |
|
|
| Zustand prüfen | `curl https://dc.mhdf.de/api/health` |
|
|
| Logs | `var/log/dc-<datum>.log` auf dem Server |
|
|
|
|
## Aufbau
|
|
|
|
```
|
|
config/ Zugangsdaten (nicht versioniert), Vorlage in config.example.php
|
|
src/ Anwendungscode, PSR-4 unter dem Namensraum Deploymentcenter\
|
|
Core/ Bootstrap, Konfiguration, DB, Auth, CSRF, HTTP, Tokens, Migrator
|
|
Modules/ Bugtracker, License, UpdateService, Watchdog, Notify
|
|
public/ Webroot-Inhalte: WebUI, API-Endpunkte, öffentliche Dokumentation
|
|
sql/ Schema und Migrationen (fortlaufend nummeriert)
|
|
var/log/ Laufzeitprotokolle
|
|
scripts/ Deployment
|
|
```
|
|
|
|
Neue Klassen werden automatisch geladen, sobald sie dem Namensraum-Pfad
|
|
entsprechen — eine `require`-Zeile ist nicht mehr nötig.
|