Files

T

Deploymentcenter BotandClaude Opus 5 f8771c8d1b fix(guard): Zugangsschutz je Produkt abschaltbar, Dienst-Betrieb, Buildzeiten

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>

2026-08-14 21:41:53 +02:00

5.0 KiB

Raw Blame History

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	Ablaufplan für die Umstellung auf 2.0. Enthält Pflichtschritte: Zugangsdaten wechseln, Migration, Evaluator-Cron.
Änderungen	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	Ein Projekt veröffentlichungsfähig machen: Vorlage kopieren, konfigurieren, ausliefern
Agent-Prompt-Vorlage	Textbaustein für `CLAUDE.md` / `AGENTS.md` eines Projekts
Agenten-Handbuch	Vollständige Beschreibung des Bugtracker-Workflows, öffentlich unter `/docs/`

Modul-Handbücher

Lizenzsystem (Hardware-ID v2) — Hardware-Anbindung, Schlüsselvalidierung, Offline-Cache, CLI, Windows und Linux/Docker
Watchdog (Heartbeat & Telemetrie) — Überwachung von Anwendungen, Diensten und Infrastruktur
UpdateService — Release-Verteilung und Update-Prüfung
Erstinstallation — setup.json, Installationskonto, update-agent --action install
Bugtracker — 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` `/api/bugtracker/v1/projects` `/api/bugtracker/v1/manage`	Token mit `bugtracker:*`
UpdateService	Release-Verteilung, semantischer Versionsvergleich	`/api/updateservice/v1/check` `/api/updateservice/v1/publish`	Lesen offen, Publish braucht `updateservice:publish`
Watchdog	Heartbeat-Monitoring, Zustandsbewertung, Alarmierung	`/api/watchdog/v1/ping` `/api/watchdog/v1/evaluate`	Token mit `watchdog:ping`
Lizenzen	Lizenzprüfung, Hardware-ID v2, Offline-Cache	`/api/license/v1/validate` `/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` `/api/setup/v1/catalog` `/api/setup/v1/token`	Login offen, Rest `setup:*`
System	Verfügbarkeit, Schema-Status, Schnittstellenbeschreibung	`/api/health` `/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:

{ "status": "success", "…": "…" }

{ "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.

5.0 KiB Raw Blame History