Deploymentcenter BotandClaude Opus 5
e7fbc85db4
Sicherheit
- install_db.php war ohne Authentifizierung erreichbar und setzte bei jedem
Aufruf das Admin-Passwort auf einen fest im Code stehenden Wert zurück.
Jetzt Auth-Pflicht; ein Konto wird nur bei leerer Benutzertabelle angelegt.
- Stored XSS im Bugtracker-Detail-Modal: Titel, Beschreibung, Fehlermeldung,
Stacktrace und Kommentare gingen ungefiltert durch innerHTML.
- report.php, projects.php und das Veröffentlichen von Releases verlangen jetzt
zwingend ein Token. Publish war zuvor völlig ungeschützt.
- CSRF-Token in allen Formularen, Session-Regenerierung nach Login,
Drosselung fehlgeschlagener Anmeldeversuche.
- Zugangsdaten aus der Versionskontrolle entfernt (Serverdaten.txt,
config.php, .htpasswd, deploy_config.json). Historie enthält sie weiterhin,
Rotation erforderlich (siehe docs/UPGRADE.md).
- Token-Validierung nur noch über SHA-256-Hash; expires_at wird ausgewertet.
Behobene 500er
- Audit::log() war in index.php weder eingebunden noch importiert. Jeder
Klick auf "Aktivierung freigeben" endete in einem Fatal Error.
- Derselbe benannte PDO-Platzhalter mehrfach je Statement (:id in
revokeToken/deleteToken, :q siebenfach in der Volltextsuche). Bei
EMULATE_PREPARES=false ist das nicht zulässig und warf HY093.
- Migration 005 nutzte dynamisches SQL, dessen Semikolons in String-Literalen
vom alten explode(';')-Installer als Statement-Ende gelesen wurden. Sie
schlug still fehl, wodurch push_id/target_agent/tags dauerhaft fehlten.
- Monitor-Umbenennung ohne Transaktion, verschachtelte Transaktionen im
RateLimiter.
Funktionale Korrekturen
- Der Watchdog-Evaluator fehlte vollständig: Monitor-Zustände änderten sich nur
beim Eintreffen eines Heartbeats, ein ausgefallenes System blieb dauerhaft
"up". Erster Lauf auf dem Produktivsystem: 7 von 10 Monitoren waren
tatsächlich seit über einem Tag nicht erreichbar.
- Das Feld "os" fehlte im Monitor-Dialog, wurde aber gespeichert und löschte
damit bei jedem Speichern das Betriebssystem.
- Der Resolve-Dialog existierte im HTML nicht; der Button war funktionslos.
- Versionsvergleich erfolgte lexikografisch, wodurch 1.9.0 als neuer galt
als 1.10.0.
- Schreiboperationen meldeten Erfolg auch für nicht existierende IDs.
- Post/Redirect/Get gegen doppelte Einträge beim Neuladen.
Neue Struktur
- src/bootstrap.php mit PSR-4-Autoloader ersetzt die require-Ketten.
- Core: Config, Http, Csrf, ApiAuth, Logger, Migrator, ErrorReporter.
- Migrator mit zeichenweisem SQL-Parser, dc_migrations und Baseline-Verfahren,
damit bestehende Installationen keine Beispieldaten zurückbekommen.
Agenten-Workflow
- Claim/Lease: Items werden exklusiv übernommen, damit nicht zwei Agenten am
selben Problem arbeiten. action=next holt und reserviert in einem Zug.
- Idempotenz über client_ref, Deduplizierung auch für Feature Requests,
Erkennung von Regressionen, automatische Eskalation des Schweregrads.
- Strukturierter Code-Kontext (repo_url, commit_sha, file_path, line_no).
- Delta-Abfragen über updated_since, Pagination, Bulk-Update.
- Beim Veröffentlichen eines Releases schließen sich Items mit passendem
resolved_in_build selbst.
- Ausgehende Webhooks mit HMAC-Signatur, /api/health, /api/openapi.json.
- Unbehandelte Fehler meldet die Plattform in ihren eigenen Bugtracker.
WebUI
- Serverseitige Filterung mit Pagination statt Rendern aller Datensätze.
- Migrations-Schranke, Evaluator-Warnung, Übersicht aktiver Agenten.
Zeitstempel liegen in der Datenbank durchgängig in UTC und werden für die
Anzeige in die App-Zeitzone umgerechnet.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
91 lines
3.8 KiB
Markdown
91 lines
3.8 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. |
|
|
| [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
|
|
- **[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 |
|
|
| **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.
|
|
|
|
---
|
|
|
|
## 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.
|