3140 lines
71 KiB
Markdown
3140 lines
71 KiB
Markdown
# Cursor Master-Prompt: HexaHost GameCloud
|
||
|
||
> Diesen gesamten Inhalt in Cursor Agent/Composer einfügen.
|
||
> Der Projektname **HexaHost GameCloud** ist ein Arbeitstitel und muss zentral konfigurierbar sein.
|
||
|
||
---
|
||
|
||
## Rolle und Arbeitsweise
|
||
|
||
Du bist Principal Software Architect, Senior Full-Stack Engineer, Senior Go Engineer, DevOps Engineer und Security Engineer. Du entwickelst eine produktionsfähige, mandantenfähige Plattform für selbstverwaltete Minecraft-Server nach dem funktionalen Vorbild moderner On-Demand-Hoster wie Aternos und dem früheren PloudOS.
|
||
|
||
Es soll **keine optische oder technische 1:1-Kopie** eines existierenden Anbieters entstehen. Branding, Texte, Benutzeroberfläche, Quellcode und Datenmodell müssen eigenständig sein. Übernommen werden ausschließlich allgemeine Produktideen wie:
|
||
|
||
- Minecraft-Server über ein Webpanel erstellen und verwalten
|
||
- Server bei Bedarf starten und bei Inaktivität automatisch stoppen
|
||
- kostenlose und kostenpflichtige Tarife
|
||
- Ressourcenwarteschlange bei ausgelasteten Nodes
|
||
- Java- und Bedrock-Unterstützung
|
||
- auswählbare Server-Software und Versionen
|
||
- Mods, Plugins, Modpacks und Datapacks
|
||
- Webkonsole, Dateimanager, Spielerlisten und Einstellungen
|
||
- Welten hochladen, herunterladen und zurücksetzen
|
||
- Backups erstellen und wiederherstellen
|
||
- Server mit Freunden teilen und Rechte granular vergeben
|
||
- Multi-Node-Betrieb mit Scheduler, Quotas und Ausfallsicherheit
|
||
- Adminbereich für Nodes, Benutzer, Server, Jobs und Missbrauchsfälle
|
||
|
||
Arbeite selbstständig und frage nicht nach grundlegenden Technologieentscheidungen. Verwende die in diesem Dokument festgelegte Architektur. Stelle nur dann eine Rückfrage, wenn eine technisch zwingende Information fehlt, die nicht sinnvoll über eine Konfiguration oder einen sicheren Standardwert gelöst werden kann.
|
||
|
||
Arbeite iterativ. Implementiere zuerst einen funktionierenden vertikalen Durchstich und erweitere ihn anschließend. Hinterlasse zu keinem Zeitpunkt eine Ansammlung unverbundener Mockups.
|
||
|
||
Bei jeder Arbeitsphase:
|
||
|
||
1. Analysiere den bestehenden Repository-Zustand.
|
||
2. Aktualisiere `docs/IMPLEMENTATION_STATUS.md`.
|
||
3. Dokumentiere Architekturentscheidungen in `docs/adr/`.
|
||
4. Implementiere die kleinste vollständig funktionsfähige Einheit.
|
||
5. Erstelle oder aktualisiere Datenbankmigrationen.
|
||
6. Ergänze Unit-, Integrations- und End-to-End-Tests.
|
||
7. Führe Linter, Typprüfung und Tests aus.
|
||
8. Behebe Fehler, bevor du zur nächsten Phase wechselst.
|
||
9. Liste am Ende knapp auf:
|
||
- umgesetzte Funktionen
|
||
- geänderte Dateien
|
||
- ausgeführte Tests
|
||
- bekannte Einschränkungen
|
||
- nächste sinnvolle Aufgabe
|
||
|
||
Verwende in produktivem Code keine Platzhalter wie `TODO`, `mock`, `fake`, `later`, leere Handler oder hartcodierte Erfolgsantworten. Noch nicht implementierte Funktionen müssen sauber über Feature Flags deaktiviert oder mit einem klaren `501 Not Implemented` und dokumentierter Roadmap behandelt werden.
|
||
|
||
---
|
||
|
||
# 1. Produktziel
|
||
|
||
Baue eine selbstgehostete Plattform namens **HexaHost GameCloud**, über die Benutzer Minecraft-Server erstellen, konfigurieren und on demand betreiben können.
|
||
|
||
Die Plattform soll zunächst auf eigener Infrastruktur unter Proxmox VE betrieben werden. Der MVP darf keine Kubernetes-Abhängigkeit besitzen. Die Architektur muss mehrere Game-Nodes unterstützen, die als eigenständige Linux-VMs betrieben werden.
|
||
|
||
Zielsysteme:
|
||
|
||
- Control Plane: Ubuntu Server 24.04 LTS oder Debian 13
|
||
- Game Nodes: Ubuntu Server 24.04 LTS oder Debian 13
|
||
- Reverse Proxy: vorhandenes Traefik
|
||
- Externes Docker-Netzwerk: `traefik-network`
|
||
- Datenbank: PostgreSQL
|
||
- Cache, Locks und Job Queue: Redis
|
||
- Objekt-Storage: S3-kompatibel, beispielsweise MinIO oder Ceph RGW
|
||
- Container Runtime auf Game-Nodes: Docker Engine mit cgroup v2
|
||
- Monitoring: Prometheus, Grafana und Loki
|
||
- Deployment: Docker Compose für Control Plane, systemd für Node Agent
|
||
- DNS: eigener Wildcard-Domainbereich, beispielsweise `*.play.example.net`
|
||
|
||
Das System muss lokal mit einer einzigen Maschine entwickelbar sein, produktiv aber Control Plane und Game-Nodes trennen.
|
||
|
||
---
|
||
|
||
# 2. Verbindliche Technologiearchitektur
|
||
|
||
Erstelle ein Monorepo mit `pnpm` und Turborepo.
|
||
|
||
## 2.1 Anwendungen
|
||
|
||
```text
|
||
apps/
|
||
web/ Next.js Weboberfläche
|
||
api/ NestJS API mit Fastify
|
||
worker/ Hintergrundjobs und Scheduler
|
||
node-agent/ Go-Daemon auf jedem Game-Node
|
||
edge-gateway/ Go TCP/UDP Gateway, zunächst als spätere Phase
|
||
docs/ optionale Dokumentationsseite
|
||
packages/
|
||
database/ Prisma Schema, Client und Migrationen
|
||
contracts/ Zod-Schemas, DTOs und API-Verträge
|
||
auth/ gemeinsame Authentifizierungslogik
|
||
ui/ gemeinsames UI-Komponentenpaket
|
||
config/ typisierte Konfiguration
|
||
eslint-config/
|
||
typescript-config/
|
||
deploy/
|
||
compose/
|
||
traefik/
|
||
ansible/
|
||
systemd/
|
||
monitoring/
|
||
integrations/
|
||
whmcs/
|
||
modules/
|
||
servers/
|
||
hexagamecloud/
|
||
addons/
|
||
hexagamecloud/
|
||
tests/
|
||
packaging/
|
||
docs/
|
||
architecture/
|
||
adr/
|
||
operations/
|
||
security/
|
||
api/
|
||
```
|
||
|
||
## 2.2 Web
|
||
|
||
- Next.js mit App Router
|
||
- TypeScript im Strict Mode
|
||
- React Server Components, wo sinnvoll
|
||
- Tailwind CSS
|
||
- zugängliche Komponenten, bevorzugt auf Basis von Radix-Primitiven
|
||
- TanStack Query nur für tatsächlich clientseitige Serverzustände
|
||
- React Hook Form und Zod
|
||
- Internationalisierung für Deutsch und Englisch
|
||
- Dark Mode und Light Mode
|
||
- responsive Oberfläche
|
||
- keine Abhängigkeit von einer proprietären UI-Bibliothek
|
||
- keine kopierte Aternos- oder PloudOS-Oberfläche
|
||
|
||
## 2.3 API
|
||
|
||
- NestJS
|
||
- Fastify Adapter
|
||
- REST API unter `/api/v1`
|
||
- OpenAPI-Dokumentation
|
||
- Zod oder äquivalente Laufzeitvalidierung an Systemgrenzen
|
||
- strukturierte JSON-Logs
|
||
- Request-ID und Correlation-ID
|
||
- globale Rate Limits
|
||
- einheitliches Fehlerformat nach RFC-7807-Prinzipien
|
||
- idempotente Endpunkte für Provisionierung, Start, Stop, Backup und Restore
|
||
|
||
## 2.4 Worker und Queue
|
||
|
||
- BullMQ mit Redis
|
||
- getrennte Queues:
|
||
- `server-lifecycle`
|
||
- `server-provisioning`
|
||
- `server-installation`
|
||
- `backups`
|
||
- `restores`
|
||
- `catalog-sync`
|
||
- `usage-metering`
|
||
- `notifications`
|
||
- `maintenance`
|
||
- Retry mit exponentiellem Backoff
|
||
- Dead-Letter-Handling
|
||
- Job-Deduplizierung
|
||
- verteilte Locks
|
||
- Job-Fortschritt und verständliche Fehlermeldungen im Benutzerpanel
|
||
|
||
## 2.5 Datenbank
|
||
|
||
- PostgreSQL
|
||
- Prisma
|
||
- UUIDv7 oder ULID als externe IDs
|
||
- Transaktionen für Zustandsübergänge
|
||
- optimistic locking über Versionsspalte
|
||
- Soft Delete nur dort, wo Auditierbarkeit notwendig ist
|
||
- Zeitstempel immer in UTC
|
||
- keine fachliche Logik ausschließlich in der UI
|
||
|
||
## 2.6 Node Agent
|
||
|
||
Implementiere den Node Agent in Go.
|
||
|
||
Der Agent:
|
||
|
||
- läuft als dedizierter systemd-Dienst
|
||
- verbindet sich ausgehend zur Control Plane
|
||
- authentifiziert sich per mTLS und Node-Token
|
||
- verwendet keinen öffentlich erreichbaren Docker-Socket
|
||
- greift ausschließlich lokal auf die Container Runtime zu
|
||
- besitzt eine klar definierte, versionierte API
|
||
- sendet Heartbeats und Ressourceninformationen
|
||
- führt nur signierte bzw. autorisierte Befehle der Control Plane aus
|
||
- ist idempotent
|
||
- überlebt Control-Plane-Neustarts
|
||
- meldet laufende Container nach einem Agent-Neustart erneut an
|
||
- kann Logs streamen und Konsolenbefehle schreiben
|
||
- misst CPU, RAM, Netzwerk, Disk und Containerzustand
|
||
- erzwingt Ressourcenlimits
|
||
- verwaltet Serververzeichnisse sicher
|
||
- besitzt keine generische Remote-Shell-Funktion
|
||
|
||
Verwende für die Agent-Kommunikation zunächst einen ausgehenden, dauerhaft gehaltenen WebSocket mit mTLS. Definiere das Protokoll als versionierte JSON-Nachrichten. Halte die Protokollschicht austauschbar, sodass später NATS oder gRPC verwendet werden kann.
|
||
|
||
---
|
||
|
||
# 3. Sicherheitsgrundsätze
|
||
|
||
Sicherheit ist ein Kernbestandteil und keine spätere Erweiterung.
|
||
|
||
## 3.1 Grundregeln
|
||
|
||
- Kein Docker-Socket im Web-, API- oder Worker-Container
|
||
- Kein direkter Docker-Zugriff aus der Control Plane
|
||
- Keine generische Shell für Kunden
|
||
- Kein Upload beliebiger Docker-Images
|
||
- Keine Ausführung vom Benutzer definierter Startbefehle
|
||
- Keine Ausführung von Host-Binaries aus Serververzeichnissen
|
||
- Alle Pfade serverseitig normalisieren und gegen Path Traversal absichern
|
||
- Symlinks beim Upload und Entpacken standardmäßig ablehnen
|
||
- ZIP-Bombs durch Größen-, Datei- und Kompressionslimits verhindern
|
||
- MIME-Type und Magic Bytes prüfen
|
||
- Uploads optional mit ClamAV scannen
|
||
- CSRF-Schutz bei Cookie-basierten Aktionen
|
||
- sichere Session-Cookies mit `HttpOnly`, `Secure` und geeignetem `SameSite`
|
||
- Passwort-Hashing mit Argon2id
|
||
- TOTP-2FA und Recovery Codes
|
||
- Login-Rate-Limits und Account-Lockout mit zeitlicher Begrenzung
|
||
- Audit-Log für sicherheitsrelevante Aktionen
|
||
- Secrets ausschließlich über Umgebungsvariablen oder Secret Files
|
||
- keine Secrets in Logs
|
||
- keine Default-Admin-Zugangsdaten
|
||
- Admin-Erstellung über Bootstrap-CLI
|
||
|
||
## 3.2 Container-Härtung
|
||
|
||
Jeder Minecraft-Server läuft in einem separaten Container mit:
|
||
|
||
- nicht privilegiertem Benutzer
|
||
- `no-new-privileges`
|
||
- Drop aller nicht benötigten Linux Capabilities
|
||
- PID-Limit
|
||
- CPU-Quota
|
||
- RAM-Limit
|
||
- Swap-Limit
|
||
- Disk-Quota
|
||
- optionalem IO-Limit
|
||
- eigener Netzwerkisolation
|
||
- eigener persistenter Datenablage
|
||
- read-only Root Filesystem, soweit mit dem Runtime-Image kompatibel
|
||
- schreibbaren Mounts ausschließlich für notwendige Pfade
|
||
- Seccomp-Profil
|
||
- AppArmor-Profil, sofern verfügbar
|
||
- Healthcheck
|
||
- maximaler Loggröße und Logrotation
|
||
|
||
Exponiere keine zufälligen Host-Pfade in Container. Mounts müssen aus einer zentral validierten Storage-Definition erzeugt werden.
|
||
|
||
## 3.3 Netzwerk
|
||
|
||
- Web/API nur über TLS
|
||
- Node Agent nur über mTLS
|
||
- Game-Ports getrennt vom Management-Netz
|
||
- Datenbank und Redis nicht öffentlich erreichbar
|
||
- standardmäßig kein Zugriff eines Gameservers auf interne Infrastruktur-Netze
|
||
- Egress-Regeln konfigurierbar
|
||
- Schutz gegen Port-Scanning aus Gameservern
|
||
- keine Host-Netzwerk-Container
|
||
- DDoS-Schutz als externe Infrastrukturabhängigkeit dokumentieren
|
||
- Rate Limits für Status-Pings, API und Authentifizierung
|
||
|
||
## 3.4 Datenschutz und Compliance
|
||
|
||
Implementiere:
|
||
|
||
- Einwilligungs- und Datenschutzhinweise
|
||
- Datenexport des Benutzerkontos
|
||
- Kontolöschung mit definierter Aufbewahrungslogik
|
||
- Löschung oder Anonymisierung personenbezogener Auditdaten nach Frist
|
||
- einstellbare Log-Retention
|
||
- keine Werbe- oder Tracking-Cookies ohne Consent
|
||
- konfigurierbare E-Mail-Retention
|
||
- Impressum, Datenschutz und Nutzungsbedingungen als editierbare CMS-Seiten
|
||
- klaren Hinweis, dass der Dienst nicht mit Mojang oder Microsoft verbunden ist
|
||
- keine Verwendung offizieller Logos oder irreführender Markenauftritte
|
||
|
||
Die Plattform darf keine Minecraft-Clientdateien oder andere nicht zur Weitergabe erlaubte Dateien verteilen. Server-Software muss aus den jeweils zulässigen Originalquellen geladen werden.
|
||
|
||
---
|
||
|
||
# 4. Benutzer- und Rechtemodell
|
||
|
||
## 4.1 Rollen auf Plattformebene
|
||
|
||
- `USER`
|
||
- `SUPPORT`
|
||
- `MODERATOR`
|
||
- `ADMIN`
|
||
- `SUPER_ADMIN`
|
||
|
||
## 4.2 Rollen je Server
|
||
|
||
- `OWNER`
|
||
- `ADMIN`
|
||
- `OPERATOR`
|
||
- `DEVELOPER`
|
||
- `VIEWER`
|
||
- benutzerdefinierte Rolle mit Einzelrechten
|
||
|
||
## 4.3 Einzelrechte je Server
|
||
|
||
Mindestens:
|
||
|
||
- Server anzeigen
|
||
- Server starten
|
||
- Server stoppen
|
||
- Server neu starten
|
||
- Server hart beenden
|
||
- Konsole anzeigen
|
||
- Konsolenbefehle senden
|
||
- Dateien anzeigen
|
||
- Dateien bearbeiten
|
||
- Dateien hochladen
|
||
- Dateien herunterladen
|
||
- Dateien löschen
|
||
- Software ändern
|
||
- Version ändern
|
||
- Plugins verwalten
|
||
- Mods verwalten
|
||
- Modpacks verwalten
|
||
- Welten verwalten
|
||
- Spielerlisten verwalten
|
||
- Whitelist verwalten
|
||
- Operatoren verwalten
|
||
- Bans verwalten
|
||
- Backups anzeigen
|
||
- Backups erstellen
|
||
- Backups wiederherstellen
|
||
- Backups löschen
|
||
- Zeitpläne verwalten
|
||
- Mitglieder verwalten
|
||
- Netzwerkdaten anzeigen
|
||
- Server löschen
|
||
- Abrechnung anzeigen
|
||
|
||
Prüfe Berechtigungen in der API und niemals nur in der UI.
|
||
|
||
---
|
||
|
||
# 5. Authentifizierung
|
||
|
||
Implementiere:
|
||
|
||
- Registrierung mit E-Mail und Passwort
|
||
- E-Mail-Verifizierung
|
||
- Login und Logout
|
||
- sichere Passwort-Zurücksetzung
|
||
- TOTP-2FA
|
||
- Recovery Codes
|
||
- Sessionübersicht und Abmelden einzelner Sessions
|
||
- optional OIDC
|
||
- optional Passkeys/WebAuthn als spätere Phase
|
||
- Sperrung und Suspendierung durch Administratoren
|
||
- Benutzername und Anzeigename getrennt
|
||
- Änderungsprotokoll für E-Mail und Sicherheitsoptionen
|
||
|
||
Verwende keine öffentliche Authentifizierungslösung, die das Produkt unnötig an einen SaaS-Anbieter bindet.
|
||
|
||
---
|
||
|
||
# 6. Kernobjekte und Datenmodell
|
||
|
||
Erstelle mindestens folgende Entitäten:
|
||
|
||
```text
|
||
User
|
||
UserCredential
|
||
UserSession
|
||
EmailVerificationToken
|
||
PasswordResetToken
|
||
TotpCredential
|
||
RecoveryCode
|
||
PlatformRole
|
||
UserPlatformRole
|
||
|
||
Organization
|
||
OrganizationMember
|
||
OrganizationInvite
|
||
|
||
GameServer
|
||
GameServerMember
|
||
GameServerRole
|
||
GameServerPermission
|
||
GameServerStateTransition
|
||
GameServerAllocation
|
||
GameServerEnvironmentVariable
|
||
GameServerProperty
|
||
GameServerSecret
|
||
|
||
GameNode
|
||
GameNodeCapability
|
||
GameNodeHeartbeat
|
||
GameNodeAllocation
|
||
GameNodeMaintenanceWindow
|
||
|
||
SoftwareFamily
|
||
SoftwareBuild
|
||
MinecraftVersion
|
||
RuntimeImage
|
||
CatalogProvider
|
||
CatalogProject
|
||
CatalogVersion
|
||
CatalogDependency
|
||
InstalledAddon
|
||
|
||
World
|
||
WorldArchive
|
||
Backup
|
||
BackupRestore
|
||
Schedule
|
||
ScheduledTask
|
||
|
||
UsageRecord
|
||
ResourceQuota
|
||
Plan
|
||
Subscription
|
||
CreditWallet
|
||
CreditTransaction
|
||
Invoice
|
||
Payment
|
||
|
||
JobRecord
|
||
Notification
|
||
AuditEvent
|
||
AbuseReport
|
||
SupportTicket
|
||
FeatureFlag
|
||
SystemSetting
|
||
|
||
WhmcsInstallation
|
||
WhmcsClientLink
|
||
WhmcsUserLink
|
||
WhmcsServiceLink
|
||
WhmcsProductMapping
|
||
WhmcsOptionMapping
|
||
WhmcsAddonMapping
|
||
WhmcsWebhookEvent
|
||
WhmcsModuleOperation
|
||
WhmcsSyncCursor
|
||
WhmcsUsageExport
|
||
WhmcsReconciliationResult
|
||
```
|
||
|
||
|
||
## 6.1 Server-Zustandsautomat
|
||
|
||
Verwende eine serverseitig validierte State Machine.
|
||
|
||
Zustände:
|
||
|
||
```text
|
||
DRAFT
|
||
QUEUED
|
||
ALLOCATING
|
||
PROVISIONING
|
||
INSTALLING
|
||
STOPPED
|
||
STARTING
|
||
RUNNING
|
||
STOPPING
|
||
BACKING_UP
|
||
RESTORING
|
||
MIGRATING
|
||
SUSPENDED
|
||
MAINTENANCE
|
||
ERROR
|
||
DELETING
|
||
DELETED
|
||
```
|
||
|
||
Definiere erlaubte Übergänge explizit. Jeder Übergang erzeugt einen Datensatz mit:
|
||
|
||
- vorherigem Zustand
|
||
- neuem Zustand
|
||
- Auslöser
|
||
- Benutzer oder Systemakteur
|
||
- Correlation-ID
|
||
- Zeitstempel
|
||
- optionaler Fehlercode
|
||
- optionaler technischer Fehler
|
||
- benutzerfreundlicher Meldung
|
||
|
||
Doppelte Start- oder Stop-Anfragen dürfen keine parallelen Lifecycle-Jobs erzeugen.
|
||
|
||
---
|
||
|
||
# 7. Servererstellung
|
||
|
||
Implementiere einen Assistenten:
|
||
|
||
1. Servername
|
||
2. Edition:
|
||
- Java
|
||
- Bedrock
|
||
3. Software:
|
||
- Java Vanilla
|
||
- Paper
|
||
- Purpur
|
||
- Fabric
|
||
- Forge
|
||
- NeoForge
|
||
- Quilt
|
||
- optional Velocity als Proxy in einer späteren Phase
|
||
- Bedrock Dedicated Server
|
||
4. Minecraft-Version
|
||
5. Tarif und Ressourcen
|
||
6. Standort oder automatische Auswahl
|
||
7. optionale Vorlage oder Modpack
|
||
8. Datenschutz- und Nutzungsbestätigung
|
||
9. Zusammenfassung
|
||
10. Provisionierung
|
||
|
||
Ressourcenparameter:
|
||
|
||
- CPU-Anteil oder vCPU-Gewichtung
|
||
- RAM
|
||
- Disk
|
||
- maximale Spieler
|
||
- maximale Backupgröße
|
||
- maximale Backupanzahl
|
||
- maximale Anzahl Mods/Plugins nur, falls tariflich notwendig
|
||
- Laufzeit- oder Credit-Limit
|
||
- Priorität in der Startwarteschlange
|
||
|
||
Nach erfolgreicher Erstellung muss ein Server zunächst im Zustand `STOPPED` vorliegen und vollständig startbar sein.
|
||
|
||
---
|
||
|
||
# 8. Minecraft-Softwarekatalog
|
||
|
||
Baue einen Provider-basierten Katalog.
|
||
|
||
## 8.1 Unterstützte Quellen
|
||
|
||
- Mojang/PaperMC/Purpur/Fabric/Forge/NeoForge/Quilt über deren zulässige APIs oder Downloadquellen
|
||
- Modrinth als primäre Quelle für Mods, Plugins, Modpacks und Datapacks
|
||
- CurseForge nur optional und nur mit konfiguriertem offiziellen API-Key
|
||
- keine inoffiziellen Scraper
|
||
|
||
## 8.2 Kataloganforderungen
|
||
|
||
- regelmäßige Synchronisation
|
||
- Provider-Abstraktion
|
||
- Checksums speichern und validieren
|
||
- Download-URL nie ungeprüft vom Client übernehmen
|
||
- Kompatibilität nach Edition, Minecraft-Version und Loader prüfen
|
||
- erforderliche und optionale Abhängigkeiten auflösen
|
||
- Konflikte anzeigen
|
||
- installierte Version pinnen
|
||
- Updates erkennen
|
||
- Rollback-Metadaten speichern
|
||
- changelog optional anzeigen
|
||
- Assets über serverseitigen Proxy nur dort ausliefern, wo dies lizenzrechtlich erlaubt ist
|
||
- API-Rate-Limits respektieren
|
||
- Cache-Header und Provider-Vorgaben berücksichtigen
|
||
|
||
## 8.3 Runtime-Images
|
||
|
||
Verwende eine Runtime-Adapter-Schicht. Unterstütze zunächst ein geprüftes Minecraft-Server-OCI-Image, aber kapsle dessen Umgebungsvariablen und Startlogik vollständig im Backend.
|
||
|
||
Anforderungen:
|
||
|
||
- Images per Digest pinnen
|
||
- Java-Version anhand der Minecraft-Version auswählen
|
||
- keine `latest`-Tags in Produktion
|
||
- Runtime-Image im Adminbereich verwaltbar
|
||
- EULA-Zustimmung muss pro Server explizit gespeichert werden
|
||
- Downloads beim Provisionieren verifizieren
|
||
- keine ungeprüften benutzerdefinierten Images
|
||
|
||
---
|
||
|
||
# 9. Serverpanel
|
||
|
||
Erstelle für jeden Server folgende Bereiche:
|
||
|
||
## 9.1 Übersicht
|
||
|
||
- Status
|
||
- Start, Stop, Restart und Kill
|
||
- Adresse und Port
|
||
- Kopierbutton
|
||
- Software und Version
|
||
- aktuelle Spieler
|
||
- CPU
|
||
- RAM
|
||
- Disk
|
||
- Netzwerk
|
||
- Uptime
|
||
- Credits oder Laufzeitverbrauch
|
||
- letzte Fehler
|
||
- letzte Backups
|
||
- aktuelle Jobs
|
||
- Warteschlangenposition
|
||
- Hinweis bei notwendigem Neustart
|
||
|
||
## 9.2 Konsole
|
||
|
||
- Live-Logstream über WebSocket
|
||
- ANSI-Sequenzen sicher darstellen
|
||
- Suchfunktion
|
||
- Pausieren und Fortsetzen
|
||
- Download eines begrenzten Logausschnitts
|
||
- Konsolenbefehle senden
|
||
- Befehlsverlauf lokal im Browser
|
||
- sensible Werte filtern
|
||
- maximale Zeilenanzahl im Browser
|
||
- serverseitige Backpressure
|
||
- Reconnect mit Cursor/Offset
|
||
- keine generische Shell
|
||
|
||
## 9.3 Dateien
|
||
|
||
- Verzeichnisnavigation
|
||
- Datei öffnen
|
||
- Textdateien bearbeiten
|
||
- Syntaxhervorhebung für Properties, YAML, JSON, TOML und einfache Configs
|
||
- sichere Uploads
|
||
- sichere Downloads
|
||
- Archive erstellen
|
||
- Archive entpacken
|
||
- Umbenennen
|
||
- Verschieben
|
||
- Löschen
|
||
- Größenlimits
|
||
- Pfadvalidierung
|
||
- symlink-sichere Operationen
|
||
- optimistic concurrency beim Bearbeiten
|
||
- Dateien oberhalb einer konfigurierbaren Größe nicht im Browser öffnen
|
||
- binäre Dateien nicht als Text behandeln
|
||
|
||
Der Dateimanager darf ausschließlich auf das dem Server zugeordnete Datenverzeichnis zugreifen.
|
||
|
||
## 9.4 Eigenschaften
|
||
|
||
Erzeuge eine validierte Oberfläche für relevante `server.properties`-Werte:
|
||
|
||
- MOTD
|
||
- Gamemode
|
||
- Difficulty
|
||
- Hardcore
|
||
- Online Mode
|
||
- Whitelist
|
||
- PVP
|
||
- Command Blocks
|
||
- View Distance
|
||
- Simulation Distance
|
||
- Max Players
|
||
- Spawn Protection
|
||
- Flight
|
||
- Nether
|
||
- Query
|
||
- RCON nur intern und nicht öffentlich
|
||
- Resource Pack URL und Hash
|
||
- Seed nur bei Weltneuerstellung
|
||
- Bedrock-spezifische Optionen
|
||
|
||
Unbekannte Properties müssen erhalten bleiben.
|
||
|
||
## 9.5 Spieler
|
||
|
||
- Online-Spieler
|
||
- Whitelist
|
||
- Operatoren
|
||
- Bans
|
||
- IP-Bans
|
||
- Benutzer-Cache
|
||
- Aktionen nur mit Berechtigung
|
||
- Audit-Log für Änderungen
|
||
|
||
## 9.6 Software
|
||
|
||
- Softwarefamilie wechseln
|
||
- Version wechseln
|
||
- Warnung vor inkompatiblen Änderungen
|
||
- automatisches Backup vor destruktivem Wechsel
|
||
- definierter Reinstall-Workflow
|
||
- EULA-Bestätigung
|
||
- verständlicher Installationsfortschritt
|
||
- Rollback, wenn Installation fehlschlägt
|
||
|
||
## 9.7 Add-ons
|
||
|
||
Getrennte Bereiche für:
|
||
|
||
- Plugins
|
||
- Mods
|
||
- Modpacks
|
||
- Datapacks
|
||
- Bedrock Add-ons
|
||
- Resource Packs
|
||
|
||
Funktionen:
|
||
|
||
- Suche
|
||
- Filter nach Version und Loader
|
||
- Installieren
|
||
- Deinstallieren
|
||
- Aktualisieren
|
||
- Version pinnen
|
||
- Abhängigkeiten
|
||
- Konfliktanzeige
|
||
- Änderungsübersicht
|
||
- Neustarthinweis
|
||
- Transaktionsähnlicher Installationsvorgang mit Rollback
|
||
|
||
## 9.8 Welten
|
||
|
||
- aktive Welt anzeigen
|
||
- Welt hochladen
|
||
- Welt herunterladen
|
||
- neue Welt generieren
|
||
- Seed setzen
|
||
- Welt zurücksetzen
|
||
- zusätzliche Welten erkennen
|
||
- Dateigröße und Uploadfortschritt
|
||
- Validierung von `level.dat` und erwarteten Verzeichnissen
|
||
- Backup vor Austausch
|
||
- Server muss für destruktive Aktionen gestoppt sein
|
||
- sichere Archive ohne Path Traversal
|
||
|
||
## 9.9 Backups
|
||
|
||
- manuelles Backup
|
||
- geplantes Backup
|
||
- Restore
|
||
- Löschen
|
||
- Download, falls Tarif erlaubt
|
||
- Aufbewahrungsregeln
|
||
- Checksums
|
||
- Verschlüsselung serverseitig
|
||
- S3 Multipart Upload
|
||
- Fortschrittsanzeige
|
||
- fehlgeschlagene Uploads bereinigen
|
||
- konsistente Backups über RCON:
|
||
1. `save-off`
|
||
2. `save-all flush`
|
||
3. Snapshot oder Dateisicherung
|
||
4. `save-on`
|
||
- bei gestopptem Server direkt sichern
|
||
- Restore nur nach Bestätigung
|
||
- automatisches Sicherheitsbackup vor Restore
|
||
- Restore-Vorgang auditieren
|
||
|
||
## 9.10 Zeitpläne
|
||
|
||
Aufgaben:
|
||
|
||
- Start
|
||
- Stop
|
||
- Restart
|
||
- Backup
|
||
- Konsolenbefehl
|
||
- Update-Prüfung
|
||
- geplante Wartung
|
||
|
||
Zeitpläne müssen Zeitzonen unterstützen und intern in UTC gespeichert werden.
|
||
|
||
## 9.11 Zugriffe
|
||
|
||
- Benutzer per E-Mail oder Benutzername einladen
|
||
- Rolle auswählen
|
||
- Einzelrechte überschreiben
|
||
- Einladung widerrufen
|
||
- Zugriff entfernen
|
||
- Besitzer übertragen mit erneuter Authentifizierung und 2FA
|
||
- Audit-Log
|
||
|
||
---
|
||
|
||
# 10. On-Demand-Betrieb und automatische Abschaltung
|
||
|
||
## 10.1 Idle Shutdown
|
||
|
||
Implementiere einen Idle-Controller.
|
||
|
||
Konfigurierbare Regeln:
|
||
|
||
- Server nach X Minuten ohne Spieler stoppen
|
||
- Grace Period nach Serverstart
|
||
- Grace Period nach letztem Spieler
|
||
- Stop-Countdown im Panel
|
||
- Countdown abbrechen, sobald ein Spieler verbunden ist
|
||
- optional eine kurze Verlängerung durch berechtigten Benutzer
|
||
- kein Idle Stop während Backup, Restore oder Wartung
|
||
- kein Stop, solange ein definierter Lifecycle-Lock aktiv ist
|
||
- maximaler ununterbrochener Lauf für Free-Tarife optional
|
||
|
||
Spielerzahl bevorzugt über Query/RCON oder einen kontrollierten Statusmechanismus ermitteln. Ein bloß laufender Container gilt nicht als aktiver Spielerbetrieb.
|
||
|
||
## 10.2 Startwarteschlange
|
||
|
||
Wenn nicht genügend Ressourcen verfügbar sind:
|
||
|
||
- Startanfrage in Queue setzen
|
||
- Position anzeigen
|
||
- geschätzte Wartezeit nur anzeigen, wenn ausreichend belastbare Daten vorliegen
|
||
- Priorität nach Tarif, Wartezeit und Fairness
|
||
- Schutz vor wiederholtem Queue-Hopping
|
||
- Reservierung verfällt nach Timeout
|
||
- Benutzer kann Anfrage abbrechen
|
||
- Scheduler prüft Ressourcen bei jedem relevanten Event und zusätzlich periodisch
|
||
- keine Überbelegung über harte RAM-Grenzen
|
||
- CPU-Overcommit nur konfigurierbar und transparent
|
||
|
||
## 10.3 Join-to-Start
|
||
|
||
Implementiere dies erst nach stabilem Multi-Node-MVP.
|
||
|
||
Ziel:
|
||
|
||
- Benutzer verbindet sich mit einer festen Hostname-Adresse
|
||
- Edge Gateway erkennt den Zielserver aus Minecraft-Handshake oder Zuordnung
|
||
- ist der Server gestoppt, wird eine idempotente Startanforderung erzeugt
|
||
- Status-Ping zeigt „Server startet“ und Fortschritt
|
||
- bis zur Betriebsbereitschaft erhält der Spieler eine verständliche Nachricht
|
||
- nach Start wird zum korrekten Backend geroutet
|
||
- Fehler und Timeout werden sauber dargestellt
|
||
- Schutz gegen Start-Spam und Bots
|
||
- Start nur, wenn Tarif, Credits und Serverzustand es erlauben
|
||
|
||
Für das MVP genügen feste Portzuweisungen und DNS-SRV-Einträge. Implementiere das Protokoll-Gateway nicht halb fertig in einer frühen Phase.
|
||
|
||
---
|
||
|
||
# 11. Scheduler und Multi-Node-Betrieb
|
||
|
||
Der Scheduler wählt Nodes anhand folgender Kriterien:
|
||
|
||
- Node online und heartbeat aktuell
|
||
- Node nicht in Wartung
|
||
- unterstützte Architektur und Runtime
|
||
- ausreichend reservierbarer RAM
|
||
- ausreichend Disk
|
||
- CPU-Auslastung
|
||
- vorhandene Portallokation
|
||
- Standort
|
||
- Storage-Lokalität
|
||
- Server-Affinität
|
||
- Tarifpriorität
|
||
- Anti-Affinität für optionale Proxy-Setups
|
||
- Sicherheits- oder Capability-Anforderungen
|
||
|
||
## 11.1 Reservierungsmodell
|
||
|
||
Unterscheide:
|
||
|
||
- physischer Gesamt-RAM
|
||
- für Plattform reservierter RAM
|
||
- bereits hart reservierter RAM
|
||
- laufend genutzter RAM
|
||
- überbuchbarer CPU-Anteil
|
||
- freier Diskplatz
|
||
- reservierter Diskplatz
|
||
|
||
Eine Allocation muss transaktional reserviert werden. Wenn die Provisionierung scheitert, wird sie zuverlässig freigegeben.
|
||
|
||
## 11.2 Node-Ausfall
|
||
|
||
- Heartbeat alle 10 Sekunden
|
||
- Node nach konfigurierbarem Timeout `UNREACHABLE`
|
||
- keine neuen Starts
|
||
- laufende Server als `UNKNOWN` markieren
|
||
- keine automatische parallele Zweitinstanz desselben Worlds starten
|
||
- Wiederanmeldung des Agents reconciliert Zustand
|
||
- Admin erhält Alarm
|
||
- optional Offline-Migration aus Backup nur als expliziter Adminvorgang
|
||
- Split-Brain verhindern
|
||
|
||
## 11.3 Wartungsmodus
|
||
|
||
- keine neuen Server auf Node
|
||
- optional laufende Server auslaufen lassen
|
||
- optional Stop zu Wartungszeit
|
||
- Migrationsassistent für gestoppte Server
|
||
- Fortschrittsanzeige
|
||
- Wartungsbanner für betroffene Benutzer
|
||
|
||
---
|
||
|
||
# 12. Port- und DNS-Verwaltung
|
||
|
||
Implementiere:
|
||
|
||
- Portpools pro Node und Protokoll
|
||
- TCP/UDP getrennt
|
||
- eindeutige transaktionale Reservierung
|
||
- Java-Standardport und alternative Ports
|
||
- Bedrock-UDP-Ports
|
||
- optionale Zusatzports für Voice Chat oder Geyser
|
||
- Tarifgrenzen für Zusatzports
|
||
- keine freie Wahl beliebiger Hostports durch Benutzer
|
||
- Freigabe beim Löschen
|
||
- Quarantänezeit vor Wiederverwendung optional
|
||
|
||
DNS:
|
||
|
||
- pro Server stabiler Slug
|
||
- `server-slug.play.example.net`
|
||
- DNS-SRV-Unterstützung für Java
|
||
- Provider-Abstraktion
|
||
- zunächst RFC2136 oder PowerDNS API
|
||
- später weitere DNS-Provider
|
||
- DNS-Jobs idempotent
|
||
- Status und Fehler im Adminbereich
|
||
|
||
---
|
||
|
||
# 13. Tarife, Credits und Abrechnung
|
||
|
||
Baue die Abrechnung modular. Der Plattformbetrieb muss auch ohne aktivierten Zahlungsanbieter möglich sein.
|
||
|
||
## 13.1 Tarife
|
||
|
||
Beispiel:
|
||
|
||
### Free
|
||
|
||
- begrenzter RAM
|
||
- begrenzte Disk
|
||
- Idle Shutdown
|
||
- Warteschlange
|
||
- begrenzte Backups
|
||
- begrenzte Laufzeit oder monatliche Credits
|
||
- keine garantierte Verfügbarkeit
|
||
|
||
### Starter
|
||
|
||
- mehr RAM und Disk
|
||
- höhere Queue-Priorität
|
||
- mehr Backups
|
||
- längere Idle-Zeit
|
||
- optionale Zusatzports
|
||
|
||
### Pro
|
||
|
||
- höhere Limits
|
||
- bevorzugte Nodes
|
||
- geplante Backups
|
||
- längere Aufbewahrung
|
||
- SFTP optional
|
||
- längere Laufzeit
|
||
|
||
## 13.2 Credits
|
||
|
||
Unterstütze ein transparentes Credit-System:
|
||
|
||
- Wallet
|
||
- Gutschriften
|
||
- Abbuchungen
|
||
- Ablauf optional
|
||
- niemals negative Credits ohne explizite Regel
|
||
- idempotente Metering-Jobs
|
||
- nachvollziehbares Ledger
|
||
- Korrekturbuchungen statt Löschen
|
||
- Verbrauch nach RAM-GB-Minuten
|
||
- optional CPU-Zeit
|
||
- Storage nach GB-Tagen
|
||
- Zusatzfeatures getrennt
|
||
- Rundungsregeln dokumentieren
|
||
|
||
## 13.3 Zahlungen
|
||
|
||
- Payment-Provider-Abstraktion
|
||
- Stripe als erster optionaler Provider
|
||
- PayPal später
|
||
- Webhooks signaturprüfen
|
||
- idempotent verarbeiten
|
||
- Rechnungsstatus
|
||
- Abonnementstatus
|
||
- Grace Period
|
||
- Suspendierung statt sofortiger Datenlöschung
|
||
- konfigurierbare Löschfrist
|
||
- keine Kartendaten selbst speichern
|
||
|
||
## 13.4 Werbung
|
||
|
||
Werbung ist kein Bestandteil des MVP. Bereite nur eine Consent-fähige Slot-Abstraktion vor. Keine Drittanbieter-Werbeskripte ohne separate Aktivierung und Datenschutzprüfung.
|
||
|
||
---
|
||
|
||
# 14. Administratorbereich
|
||
|
||
Erstelle einen strikt geschützten Adminbereich.
|
||
|
||
## 14.1 Dashboard
|
||
|
||
- aktive Benutzer
|
||
- aktive Server
|
||
- laufende Server
|
||
- Queue-Länge
|
||
- Node-Auslastung
|
||
- Fehlerquote
|
||
- Startdauer
|
||
- Backup-Erfolgsrate
|
||
- Storage-Verbrauch
|
||
- Umsatz und Credit-Verbrauch, falls aktiviert
|
||
- aktuelle Incidents
|
||
- Agent-Versionen
|
||
- ausstehende Updates
|
||
|
||
## 14.2 Nodes
|
||
|
||
- Node registrieren
|
||
- Enrollment Token einmalig anzeigen
|
||
- Zertifikat ausstellen und rotieren
|
||
- Heartbeats
|
||
- CPU, RAM, Disk, Netzwerk
|
||
- Containerübersicht
|
||
- Portpools
|
||
- Runtime-Version
|
||
- Wartungsmodus
|
||
- Drain
|
||
- Labels und Capabilities
|
||
- sichere Deaktivierung
|
||
- Löschung nur ohne aktive Zuordnungen
|
||
|
||
## 14.3 Benutzer
|
||
|
||
- suchen
|
||
- Status
|
||
- Rollen
|
||
- 2FA-Status
|
||
- Sessions widerrufen
|
||
- suspendieren
|
||
- entsperren
|
||
- E-Mail-Verifizierung zurücksetzen
|
||
- Datenexport auslösen
|
||
- Löschprozess starten
|
||
- Audit-Log
|
||
|
||
Administratoren dürfen keine Benutzerpasswörter sehen oder setzen. Passwort-Reset erfolgt über sicheren Reset-Flow.
|
||
|
||
## 14.4 Server
|
||
|
||
- globale Suche
|
||
- Zustand
|
||
- Besitzer
|
||
- Node
|
||
- Ressourcen
|
||
- Lifecycle-Aktionen
|
||
- Suspendierung
|
||
- Migration
|
||
- Backup
|
||
- Audit
|
||
- Fehlerdiagnose
|
||
- keine unprotokollierten Eingriffe
|
||
|
||
## 14.5 Jobs
|
||
|
||
- Queue
|
||
- Status
|
||
- Versuche
|
||
- Fehler
|
||
- Retry
|
||
- Abbrechen, wenn sicher
|
||
- Dead Letter
|
||
- Correlation-ID
|
||
- technische Details nur für berechtigte Rollen
|
||
|
||
## 14.6 Katalog
|
||
|
||
- Providerstatus
|
||
- letzte Synchronisation
|
||
- API-Limits
|
||
- Softwarebuilds
|
||
- Runtime-Images
|
||
- gesperrte oder zurückgezogene Versionen
|
||
- manuelle Resynchronisation
|
||
- Prüfsummenstatus
|
||
|
||
## 14.7 Abuse und Support
|
||
|
||
- Abuse Reports
|
||
- Support Tickets
|
||
- interne Notizen
|
||
- Status und Priorität
|
||
- Anhänge
|
||
- Verknüpfung zu Benutzer und Server
|
||
- Maßnahmen auditieren
|
||
- Server sperren
|
||
- Beweise und Logs nach definierter Retention
|
||
|
||
---
|
||
|
||
# 15. Benachrichtigungen
|
||
|
||
Kanäle:
|
||
|
||
- In-App
|
||
- E-Mail
|
||
- Webhook optional
|
||
- Discord Webhook optional
|
||
|
||
Ereignisse:
|
||
|
||
- Server startbereit
|
||
- Start fehlgeschlagen
|
||
- Server gestoppt
|
||
- Idle-Stop angekündigt
|
||
- Backup erfolgreich oder fehlgeschlagen
|
||
- Restore erfolgreich oder fehlgeschlagen
|
||
- Credits niedrig
|
||
- Abonnementproblem
|
||
- Einladung
|
||
- Node-Störung
|
||
- Wartung
|
||
- Sicherheitsereignis
|
||
- neue Anmeldung
|
||
- 2FA geändert
|
||
|
||
Benachrichtigungen müssen pro Typ und Kanal konfigurierbar sein.
|
||
|
||
---
|
||
|
||
# 16. Monitoring und Observability
|
||
|
||
Implementiere OpenTelemetry-kompatible Instrumentierung.
|
||
|
||
## 16.1 Metriken
|
||
|
||
API:
|
||
|
||
- Request-Dauer
|
||
- Request-Rate
|
||
- Fehlerquote
|
||
- Rate-Limit-Treffer
|
||
- DB-Pool
|
||
- Redis-Latenz
|
||
|
||
Worker:
|
||
|
||
- Queue-Länge
|
||
- Jobdauer
|
||
- Fehlversuche
|
||
- Dead-Letter-Anzahl
|
||
|
||
Agent:
|
||
|
||
- Heartbeat
|
||
- Containeranzahl
|
||
- CPU
|
||
- RAM
|
||
- Disk
|
||
- Netzwerk
|
||
- Docker-Fehler
|
||
- Startdauer
|
||
- Logstream-Verbindungen
|
||
|
||
Produktmetriken:
|
||
|
||
- Serverstarts
|
||
- Startfehler
|
||
- Queue-Wartezeit
|
||
- Provisionierungsdauer
|
||
- Backupdauer
|
||
- Restore-Dauer
|
||
- Idle Stops
|
||
- aktive Spieler, nur aggregiert und datenschutzkonform
|
||
- verbrauchte Credits
|
||
|
||
## 16.2 Logging
|
||
|
||
- strukturierte Logs
|
||
- keine Tokens oder Secrets
|
||
- Benutzer-ID nur, wenn nötig
|
||
- Server-ID
|
||
- Node-ID
|
||
- Correlation-ID
|
||
- Job-ID
|
||
- definierte Retention
|
||
- Loki-Konfiguration
|
||
- sensible Minecraft-Chatlogs standardmäßig nicht zentral dauerhaft speichern
|
||
|
||
## 16.3 Health Endpoints
|
||
|
||
- Liveness
|
||
- Readiness
|
||
- Dependency Health
|
||
- keine sensitiven Details öffentlich
|
||
|
||
---
|
||
|
||
# 17. API-Design
|
||
|
||
Beispielendpunkte:
|
||
|
||
```text
|
||
POST /api/v1/auth/register
|
||
POST /api/v1/auth/login
|
||
POST /api/v1/auth/logout
|
||
POST /api/v1/auth/2fa/setup
|
||
POST /api/v1/auth/2fa/verify
|
||
GET /api/v1/me
|
||
GET /api/v1/me/sessions
|
||
DELETE /api/v1/me/sessions/:id
|
||
|
||
GET /api/v1/servers
|
||
POST /api/v1/servers
|
||
GET /api/v1/servers/:id
|
||
PATCH /api/v1/servers/:id
|
||
DELETE /api/v1/servers/:id
|
||
|
||
POST /api/v1/servers/:id/start
|
||
POST /api/v1/servers/:id/stop
|
||
POST /api/v1/servers/:id/restart
|
||
POST /api/v1/servers/:id/kill
|
||
|
||
GET /api/v1/servers/:id/console/token
|
||
GET /api/v1/servers/:id/files
|
||
GET /api/v1/servers/:id/files/content
|
||
PUT /api/v1/servers/:id/files/content
|
||
POST /api/v1/servers/:id/files/upload
|
||
POST /api/v1/servers/:id/files/archive
|
||
POST /api/v1/servers/:id/files/unarchive
|
||
|
||
GET /api/v1/servers/:id/backups
|
||
POST /api/v1/servers/:id/backups
|
||
POST /api/v1/servers/:id/backups/:backupId/restore
|
||
DELETE /api/v1/servers/:id/backups/:backupId
|
||
|
||
GET /api/v1/catalog/software
|
||
GET /api/v1/catalog/projects
|
||
GET /api/v1/catalog/projects/:id/versions
|
||
POST /api/v1/servers/:id/addons
|
||
DELETE /api/v1/servers/:id/addons/:addonId
|
||
|
||
GET /api/v1/admin/nodes
|
||
POST /api/v1/admin/nodes
|
||
POST /api/v1/admin/nodes/:id/drain
|
||
POST /api/v1/admin/nodes/:id/certificates/rotate
|
||
GET /api/v1/admin/jobs
|
||
GET /api/v1/admin/audit
|
||
```
|
||
|
||
Verwende Pagination, Filter, Sortierung und konsistente Cursor-Pagination bei großen Listen.
|
||
|
||
---
|
||
|
||
# 18. Agent-Protokoll
|
||
|
||
Definiere versionierte Nachrichtentypen.
|
||
|
||
Beispiele Control Plane zu Agent:
|
||
|
||
```json
|
||
{
|
||
"protocolVersion": 1,
|
||
"messageId": "01...",
|
||
"type": "server.start",
|
||
"timestamp": "2026-01-01T00:00:00Z",
|
||
"payload": {
|
||
"serverId": "01...",
|
||
"desiredGeneration": 4
|
||
}
|
||
}
|
||
```
|
||
|
||
Weitere Befehle:
|
||
|
||
- `server.provision`
|
||
- `server.install`
|
||
- `server.start`
|
||
- `server.stop`
|
||
- `server.kill`
|
||
- `server.delete`
|
||
- `server.inspect`
|
||
- `server.command`
|
||
- `server.backup.prepare`
|
||
- `server.backup.release`
|
||
- `server.files.list`
|
||
- `server.files.read`
|
||
- `server.files.write`
|
||
- `server.files.upload.complete`
|
||
- `server.world.validate`
|
||
- `server.metrics.subscribe`
|
||
- `server.logs.subscribe`
|
||
|
||
Agent zu Control Plane:
|
||
|
||
- `agent.hello`
|
||
- `agent.heartbeat`
|
||
- `agent.inventory`
|
||
- `server.state`
|
||
- `server.metrics`
|
||
- `server.log`
|
||
- `server.operation.progress`
|
||
- `server.operation.completed`
|
||
- `server.operation.failed`
|
||
|
||
Jede Operation benötigt:
|
||
|
||
- Message-ID
|
||
- Correlation-ID
|
||
- Server-ID
|
||
- Generation
|
||
- Deadline
|
||
- Idempotency-Key
|
||
- Ergebniscode
|
||
- maschinenlesbaren Fehlercode
|
||
- benutzerfreundliche Kurzmeldung
|
||
|
||
---
|
||
|
||
# 19. Storage-Konzept
|
||
|
||
## 19.1 Aktive Serverdaten
|
||
|
||
Standard:
|
||
|
||
- lokaler NVMe-Storage auf Game-Node
|
||
- ein Verzeichnis oder ZFS-Dataset pro Server
|
||
- Quota pro Server
|
||
- Dateibesitz ausschließlich für Agent/Container-UID
|
||
- atomare Provisionierung über temporäres Verzeichnis und Rename
|
||
|
||
Optional:
|
||
|
||
- ZFS-Datasets und Snapshots
|
||
- Ceph RBD oder CephFS über Storage-Adapter
|
||
- keine harte Abhängigkeit im MVP
|
||
|
||
## 19.2 Backups
|
||
|
||
- S3-kompatibler Object Storage
|
||
- objektbezogene Metadaten in PostgreSQL
|
||
- SHA-256
|
||
- Multipart Upload
|
||
- serverseitige Verschlüsselung
|
||
- Lifecycle Policies
|
||
- Retention
|
||
- unvollständige Uploads bereinigen
|
||
- Backup gilt erst nach erfolgreicher Prüfsumme als verfügbar
|
||
|
||
## 19.3 Migration
|
||
|
||
Nur gestoppte Server im MVP:
|
||
|
||
1. Sicherheitsbackup oder Snapshot
|
||
2. Zielressourcen reservieren
|
||
3. Daten übertragen
|
||
4. Prüfsummen validieren
|
||
5. Ziel provisionieren
|
||
6. Allocation umschalten
|
||
7. DNS aktualisieren
|
||
8. Quellkopie nach Grace Period löschen
|
||
9. Rollback bei Fehler
|
||
|
||
Keine Live-Migration von Minecraft-Prozessen im MVP.
|
||
|
||
---
|
||
|
||
# 20. E-Mail
|
||
|
||
Implementiere SMTP-Konfiguration mit:
|
||
|
||
- TLS
|
||
- Templates in Deutsch und Englisch
|
||
- Vorschau im Entwicklungsmodus
|
||
- Retry
|
||
- Bounce-Status optional
|
||
- Absendername konfigurierbar
|
||
- Links ausschließlich mit kurzlebigen signierten Tokens
|
||
|
||
E-Mails:
|
||
|
||
- Verifizierung
|
||
- Passwort-Reset
|
||
- Einladung
|
||
- Backupfehler
|
||
- Credits niedrig
|
||
- Zahlungsproblem
|
||
- Sicherheitswarnung
|
||
- Accountlöschung
|
||
|
||
---
|
||
|
||
# 21. UI-Seiten
|
||
|
||
Öffentlich:
|
||
|
||
- Landingpage
|
||
- Funktionen
|
||
- Preise
|
||
- Status
|
||
- Dokumentation
|
||
- Login
|
||
- Registrierung
|
||
- Passwort vergessen
|
||
- Impressum
|
||
- Datenschutz
|
||
- Nutzungsbedingungen
|
||
|
||
Benutzerbereich:
|
||
|
||
- Dashboard
|
||
- Serverliste
|
||
- Server erstellen
|
||
- Serverübersicht
|
||
- Konsole
|
||
- Dateien
|
||
- Software
|
||
- Add-ons
|
||
- Welten
|
||
- Spieler
|
||
- Backups
|
||
- Zeitpläne
|
||
- Zugriffe
|
||
- Nutzung und Abrechnung
|
||
- Benachrichtigungen
|
||
- Profil
|
||
- Sicherheit
|
||
- Sessions
|
||
- API-Tokens optional später
|
||
|
||
Admin:
|
||
|
||
- Dashboard
|
||
- Benutzer
|
||
- Server
|
||
- Nodes
|
||
- Allocations
|
||
- Jobs
|
||
- Katalog
|
||
- Runtime-Images
|
||
- Tarife
|
||
- Zahlungen
|
||
- Credits
|
||
- Abuse
|
||
- Support
|
||
- Audit
|
||
- Feature Flags
|
||
- Systemeinstellungen
|
||
- Wartungen
|
||
|
||
---
|
||
|
||
# 22. Designvorgaben
|
||
|
||
Erstelle ein eigenständiges Design.
|
||
|
||
Eigenschaften:
|
||
|
||
- professionell
|
||
- technisch
|
||
- übersichtlich
|
||
- keine verspielte Kinderoptik
|
||
- schnelle Bedienbarkeit
|
||
- klare Zustandsfarben, aber niemals ausschließlich Farbe als Information
|
||
- gute mobile Nutzbarkeit
|
||
- reduzierte Animationen
|
||
- Skeleton States
|
||
- Empty States
|
||
- klare Fehlermeldungen
|
||
- Bestätigungsdialoge für destruktive Aktionen
|
||
- Fortschrittsanzeigen bei langen Operationen
|
||
- Toasts nur für kurzfristige Rückmeldung
|
||
- dauerhafte Fehler im Seitenkontext anzeigen
|
||
|
||
Alle Texte müssen i18n-fähig sein.
|
||
|
||
---
|
||
|
||
# 23. Entwicklungs- und Deploymentumgebung
|
||
|
||
## 23.1 Lokale Entwicklung
|
||
|
||
Erstelle `compose.dev.yml` mit:
|
||
|
||
- PostgreSQL
|
||
- Redis
|
||
- MinIO
|
||
- Mailpit
|
||
- API
|
||
- Worker
|
||
- Web
|
||
- optional lokalem Node Agent
|
||
- lokalem Docker-basiertem Game-Node-Profil
|
||
- Prometheus optional
|
||
|
||
Ein Kommando soll die Umgebung starten:
|
||
|
||
```bash
|
||
pnpm dev:infra
|
||
pnpm dev
|
||
```
|
||
|
||
Alternativ ein dokumentiertes Gesamtkommando.
|
||
|
||
## 23.2 Produktion
|
||
|
||
Erstelle:
|
||
|
||
- `compose.prod.yml`
|
||
- Traefik Labels
|
||
- externe Nutzung von `traefik-network`
|
||
- Healthchecks
|
||
- Restart Policies
|
||
- Ressourcenlimits für Control-Plane-Dienste
|
||
- separate interne Netzwerke
|
||
- Secret Files
|
||
- PostgreSQL- und Redis-Backupdokumentation
|
||
- Migrationskommando
|
||
- Rollbackdokumentation
|
||
|
||
## 23.3 Node Installation
|
||
|
||
Erstelle ein idempotentes Ansible-Playbook:
|
||
|
||
- Docker installieren
|
||
- cgroup v2 prüfen
|
||
- dedizierten Benutzer erstellen
|
||
- Datenverzeichnis erstellen
|
||
- Agent installieren
|
||
- systemd-Unit installieren
|
||
- Zertifikate und Token sicher ablegen
|
||
- Firewall konfigurieren
|
||
- notwendige Kernelparameter prüfen
|
||
- Logrotation
|
||
- Node registrieren
|
||
- Smoke Test
|
||
|
||
Keine Installation über unsichere `curl | sh`-Pipelines.
|
||
|
||
---
|
||
|
||
# 24. Konfiguration
|
||
|
||
Erstelle eine vollständige `.env.example`.
|
||
|
||
Mindestens:
|
||
|
||
```text
|
||
APP_NAME
|
||
APP_ENV
|
||
APP_URL
|
||
API_URL
|
||
TRUSTED_PROXY_COUNT
|
||
SESSION_SECRET
|
||
ENCRYPTION_KEY
|
||
DATABASE_URL
|
||
REDIS_URL
|
||
|
||
SMTP_HOST
|
||
SMTP_PORT
|
||
SMTP_USER
|
||
SMTP_PASSWORD
|
||
SMTP_FROM
|
||
SMTP_TLS
|
||
|
||
S3_ENDPOINT
|
||
S3_REGION
|
||
S3_BUCKET
|
||
S3_ACCESS_KEY
|
||
S3_SECRET_KEY
|
||
S3_FORCE_PATH_STYLE
|
||
|
||
TRAEFIK_NETWORK
|
||
GAME_BASE_DOMAIN
|
||
DNS_PROVIDER
|
||
RFC2136_SERVER
|
||
RFC2136_KEY_NAME
|
||
RFC2136_KEY_SECRET
|
||
|
||
NODE_CA_CERT
|
||
NODE_CA_KEY
|
||
NODE_AGENT_PUBLIC_URL
|
||
NODE_HEARTBEAT_TIMEOUT
|
||
|
||
MODRINTH_USER_AGENT
|
||
CURSEFORGE_API_KEY
|
||
|
||
STRIPE_SECRET_KEY
|
||
STRIPE_WEBHOOK_SECRET
|
||
|
||
OTEL_EXPORTER_OTLP_ENDPOINT
|
||
LOG_LEVEL
|
||
```
|
||
|
||
Validiere Konfiguration beim Start. Fehlende Pflichtwerte müssen einen klaren Fehler erzeugen.
|
||
|
||
---
|
||
|
||
# 25. Tests
|
||
|
||
## 25.1 Unit Tests
|
||
|
||
- State Machine
|
||
- Berechtigungen
|
||
- Scheduler-Scoring
|
||
- Quotas
|
||
- Credit-Ledger
|
||
- Pfadvalidierung
|
||
- Archive-Sicherheit
|
||
- Add-on-Kompatibilität
|
||
- Agent-Nachrichtenvalidierung
|
||
- idempotente Lifecycle-Operationen
|
||
|
||
## 25.2 Integration Tests
|
||
|
||
Mit Testcontainers:
|
||
|
||
- PostgreSQL
|
||
- Redis
|
||
- S3/MinIO
|
||
- API und Worker
|
||
- simuliertes Agent-Protokoll
|
||
|
||
Tests:
|
||
|
||
- Benutzer registriert sich und erstellt Server
|
||
- Server wird provisioniert
|
||
- Start und Stop
|
||
- doppelter Start erzeugt nur einen Job
|
||
- Node fällt während Start aus
|
||
- Backup und Restore
|
||
- Quota überschritten
|
||
- Credits erschöpft
|
||
- Zugriff eines fremden Benutzers wird verweigert
|
||
- Path Traversal wird blockiert
|
||
- manipulierte Agent-Nachricht wird verworfen
|
||
|
||
## 25.3 End-to-End
|
||
|
||
Playwright:
|
||
|
||
- Registrierung
|
||
- Login
|
||
- 2FA
|
||
- Serverassistent
|
||
- Lifecycle
|
||
- Konsole
|
||
- Dateibearbeitung
|
||
- Backup
|
||
- Einladung
|
||
- Admin-Nodeansicht
|
||
|
||
## 25.4 Go Tests
|
||
|
||
- Agent-Reconciliation
|
||
- Container-Spec-Erzeugung
|
||
- Pfadsicherheit
|
||
- Heartbeat
|
||
- Reconnect
|
||
- Command-Autorisierung
|
||
- Logstream-Backpressure
|
||
|
||
## 25.5 Sicherheitsprüfungen
|
||
|
||
- Dependency Audit
|
||
- Secret Scan
|
||
- Container Image Scan
|
||
- SAST
|
||
- keine kritischen Findings im CI
|
||
- dokumentierte Ausnahmen mit Ablaufdatum
|
||
|
||
---
|
||
|
||
# 26. CI/CD
|
||
|
||
Erstelle GitHub-Actions-Workflows oder eine providerneutrale CI-Struktur:
|
||
|
||
- Install
|
||
- Lint
|
||
- Typecheck
|
||
- Unit Tests
|
||
- Integration Tests
|
||
- Go Tests
|
||
- Build
|
||
- Container Build
|
||
- SBOM
|
||
- Image Scan
|
||
- Signierung optional
|
||
- Migration Dry Run
|
||
- E2E für Main Branch
|
||
- versionierte Releases
|
||
- Changelog
|
||
|
||
Container-Tags:
|
||
|
||
- Git SHA
|
||
- semantische Version
|
||
- niemals ausschließlich `latest`
|
||
|
||
---
|
||
|
||
# 27. MVP-Phasen
|
||
|
||
Halte diese Reihenfolge ein.
|
||
|
||
## Phase 0 – Repository und Grundlagen
|
||
|
||
- Monorepo
|
||
- Entwicklungsumgebung
|
||
- PostgreSQL, Redis, MinIO, Mailpit
|
||
- Basiskonfiguration
|
||
- Logging
|
||
- OpenAPI
|
||
- CI
|
||
- Dokumentationsstruktur
|
||
- Healthchecks
|
||
|
||
Abnahmekriterium: Alle Dienste starten lokal, Lint und Tests laufen.
|
||
|
||
## Phase 1 – Authentifizierung und Benutzerpanel
|
||
|
||
- Registrierung
|
||
- Verifizierung
|
||
- Login
|
||
- Sessions
|
||
- Passwort-Reset
|
||
- TOTP
|
||
- Basisdashboard
|
||
- Admin-Bootstrap
|
||
|
||
Abnahmekriterium: Vollständiger sicherer Loginflow mit Tests.
|
||
|
||
## Phase 2 – Single-Node Vertical Slice
|
||
|
||
- GameNode-Modell
|
||
- Node Enrollment
|
||
- Go Agent
|
||
- Heartbeat
|
||
- Server erstellen
|
||
- Allocation
|
||
- Provisionieren
|
||
- Start
|
||
- Stop
|
||
- Status
|
||
- einfache Metriken
|
||
- lokaler Minecraft-Testserver
|
||
|
||
Abnahmekriterium: Ein Benutzer erstellt im Web einen Server, startet ihn, verbindet sich mit Minecraft und stoppt ihn wieder.
|
||
|
||
## Phase 3 – Konsole, Dateien und Einstellungen
|
||
|
||
- Live-Konsole
|
||
- Befehle
|
||
- Dateimanager
|
||
- `server.properties`
|
||
- Spielerlisten
|
||
- Audit
|
||
|
||
Abnahmekriterium: Verwaltung vollständig über Webpanel ohne Hostzugriff.
|
||
|
||
## Phase 4 – Welten und Backups
|
||
|
||
- Upload
|
||
- Download
|
||
- Weltvalidierung
|
||
- S3-Backup
|
||
- Restore
|
||
- Retention
|
||
- geplante Backups
|
||
|
||
Abnahmekriterium: Welt kann gesichert, ersetzt und zuverlässig restauriert werden.
|
||
|
||
## Phase 5 – Software und Add-ons
|
||
|
||
- Softwarekatalog
|
||
- Versionen
|
||
- Modrinth
|
||
- Mods
|
||
- Plugins
|
||
- Modpacks
|
||
- Abhängigkeiten
|
||
- Update und Rollback
|
||
|
||
Abnahmekriterium: Paper-Plugin und Fabric-Mod lassen sich kompatibilitätsgeprüft installieren.
|
||
|
||
## Phase 6 – Multi-Node und Queue
|
||
|
||
- Scheduler
|
||
- Ressourcenreservierung
|
||
- Startqueue
|
||
- Drain
|
||
- Wartung
|
||
- Node-Ausfall-Reconciliation
|
||
- Offline-Migration
|
||
|
||
Abnahmekriterium: Server werden korrekt auf mindestens zwei Nodes verteilt.
|
||
|
||
## Phase 7 – Idle Shutdown und Free-Tier
|
||
|
||
- Spielererkennung
|
||
- Countdown
|
||
- Auto-Stop
|
||
- Quotas
|
||
- Credits
|
||
- Usage Metering
|
||
- Queue-Prioritäten
|
||
|
||
Abnahmekriterium: Leerer Free-Server stoppt zuverlässig und Verbrauch ist nachvollziehbar.
|
||
|
||
## Phase 8 – DNS und Join-to-Start
|
||
|
||
- Portpools
|
||
- DNS-SRV
|
||
- Edge Gateway
|
||
- Start bei Verbindungsversuch
|
||
- Schutz gegen Start-Spam
|
||
|
||
Abnahmekriterium: Feste Adresse startet einen gestoppten Server kontrolliert.
|
||
|
||
## Phase 9 – Abrechnung und Produktion
|
||
|
||
- Tarife
|
||
- Stripe optional
|
||
- Rechnungsstatus
|
||
- Suspendierung
|
||
- Monitoring
|
||
- Alerting
|
||
- Backups der Control Plane
|
||
- Ansible
|
||
- Hardening
|
||
- Betriebsdokumentation
|
||
|
||
Abnahmekriterium: dokumentierter produktiver Betrieb auf getrennter Control Plane und zwei Game-Nodes.
|
||
|
||
---
|
||
|
||
# 28. Definition of Done
|
||
|
||
Eine Funktion gilt nur als abgeschlossen, wenn:
|
||
|
||
- Backend implementiert
|
||
- Berechtigungen geprüft
|
||
- Eingaben validiert
|
||
- Fehlerfälle behandelt
|
||
- Audit-Events ergänzt, sofern relevant
|
||
- UI implementiert
|
||
- Lade-, Leer- und Fehlerzustände vorhanden
|
||
- Unit- oder Integrationstests vorhanden
|
||
- Dokumentation aktualisiert
|
||
- keine kritischen Sicherheitsprobleme offen
|
||
- keine Secrets eingecheckt
|
||
- Migrationen reproduzierbar
|
||
- Feature lokal testbar
|
||
- Logs und Metriken sinnvoll vorhanden
|
||
|
||
---
|
||
|
||
# 29. Betriebsdokumentation
|
||
|
||
Erstelle mindestens:
|
||
|
||
```text
|
||
docs/operations/installation.md
|
||
docs/operations/control-plane.md
|
||
docs/operations/game-node.md
|
||
docs/operations/traefik.md
|
||
docs/operations/dns.md
|
||
docs/operations/object-storage.md
|
||
docs/operations/backup-restore.md
|
||
docs/operations/disaster-recovery.md
|
||
docs/operations/upgrades.md
|
||
docs/operations/node-drain.md
|
||
docs/operations/server-migration.md
|
||
docs/operations/incident-response.md
|
||
docs/security/threat-model.md
|
||
docs/security/container-isolation.md
|
||
docs/security/secrets.md
|
||
docs/security/data-retention.md
|
||
```
|
||
|
||
Disaster-Recovery-Szenarien:
|
||
|
||
- Verlust der PostgreSQL-Datenbank
|
||
- Verlust von Redis
|
||
- Verlust eines Game-Nodes
|
||
- Verlust des Object Storage
|
||
- kompromittiertes Node-Zertifikat
|
||
- fehlerhafte Softwareversion
|
||
- unterbrochene Migration
|
||
- beschädigtes World-Backup
|
||
|
||
---
|
||
|
||
# 30. Threat Model
|
||
|
||
Erstelle frühzeitig ein Threat Model mit mindestens:
|
||
|
||
- bösartiger registrierter Benutzer
|
||
- kompromittierter Mod oder Plugin-Datei
|
||
- kompromittierter Benutzeraccount
|
||
- kompromittierter Node Agent
|
||
- kompromittierter Game-Container
|
||
- gestohlener Agent-Token
|
||
- Replay einer Lifecycle-Nachricht
|
||
- Path Traversal
|
||
- ZIP-Bomb
|
||
- Symlink-Angriff
|
||
- SSRF über Resource-Pack- oder Download-URLs
|
||
- interne Portscans
|
||
- Exfiltration von Secrets
|
||
- Queue-Flooding
|
||
- Start-Spam
|
||
- Backup-Manipulation
|
||
- Supply-Chain-Angriff
|
||
- manipulierte Runtime-Images
|
||
- DNS-Takeover
|
||
- WebSocket-Hijacking
|
||
- fehlerhafte Mandantentrennung
|
||
|
||
Dokumentiere Mitigations und Restrisiken.
|
||
|
||
---
|
||
|
||
# 31. Nicht im MVP
|
||
|
||
Diese Funktionen nicht vorziehen:
|
||
|
||
- allgemeines Multi-Game-Hosting
|
||
- Kubernetes
|
||
- Live-Migration laufender Minecraft-Prozesse
|
||
- Marketplace für kostenpflichtige Drittinhalte
|
||
- eigene DDoS-Mitigation
|
||
- generische Kundenshell
|
||
- freie Docker-Images
|
||
- beliebige Startbefehle
|
||
- Reseller-System
|
||
- White-Label-Mandanten
|
||
- Mobile App
|
||
- Bedrock Join-to-Start vor stabilem Java-Gateway
|
||
- Werbenetzwerke
|
||
- KI-basierte automatische Logreparatur
|
||
|
||
Architektur so gestalten, dass spätere Erweiterungen möglich bleiben.
|
||
|
||
---
|
||
|
||
|
||
# 32. Vollständige WHMCS-Integration
|
||
|
||
WHMCS ist im produktiven Betriebsmodus das kaufmännisch führende System. GameCloud ist das technisch führende System für Gameserver, Nodes, Allocations, Laufzeit, Backups, Ressourcen und Serverzustände.
|
||
|
||
Es darf keine direkte Manipulation der jeweils anderen Datenbank geben. Die Kopplung erfolgt ausschließlich über versionierte APIs, signierte Ereignisse, stabile externe IDs, Idempotency-Keys und regelmäßige Reconciliation.
|
||
|
||
## 32.1 Verantwortlichkeiten
|
||
|
||
WHMCS verwaltet:
|
||
|
||
- Kunden, Kontakte und Benutzerzugriffe
|
||
- Bestellungen
|
||
- Produkte und Produkt-Addons
|
||
- konfigurierbare Optionen
|
||
- Upgrades und Downgrades
|
||
- Rechnungen
|
||
- Zahlungen
|
||
- Steuern und Währungen
|
||
- Zahlungsanbieter
|
||
- Mahnungen und kaufmännische Sperren
|
||
- Kündigungsanfragen
|
||
- Vertragsstatus
|
||
- kaufmännische E-Mails
|
||
- Supporttickets, sofern WHMCS dafür genutzt wird
|
||
|
||
GameCloud verwaltet:
|
||
|
||
- technische Benutzeridentitäten
|
||
- Minecraft-Server
|
||
- Serverzustände und Lifecycle
|
||
- Nodes und Allocations
|
||
- CPU-, RAM-, Disk- und Portlimits
|
||
- Software, Versionen, Mods und Plugins
|
||
- Welten
|
||
- Backups und Restores
|
||
- technische Nutzungsmesswerte
|
||
- Startwarteschlangen
|
||
- technische Benachrichtigungen
|
||
- Audit-Ereignisse
|
||
- Abuse- und Sicherheitsstatus
|
||
|
||
Konfigurationsmodus:
|
||
|
||
```text
|
||
BILLING_PROVIDER=whmcs
|
||
```
|
||
|
||
In diesem Modus:
|
||
|
||
- werden Rechnungen, Zahlungen, Steuern und Abonnements ausschließlich in WHMCS verwaltet
|
||
- ist das interne GameCloud-Billing deaktiviert oder nur eine Read-only-Projektion
|
||
- darf das technische Credit-Ledger Messwerte führen, aber keine konkurrierenden Rechnungen erzeugen
|
||
- werden Tarif- und Vertragsänderungen aus WHMCS übernommen
|
||
- werden technische Abweichungen über Reconciliation erkannt
|
||
|
||
Alternativer Standalone-Modus:
|
||
|
||
```text
|
||
BILLING_PROVIDER=internal
|
||
```
|
||
|
||
Ein Wechsel des Billing-Providers benötigt ein dokumentiertes Migrationsverfahren.
|
||
|
||
## 32.2 Zu entwickelnde WHMCS-Module
|
||
|
||
Entwickle zwei getrennte Module.
|
||
|
||
### Provisioning-/Server-Modul
|
||
|
||
Installationspfad:
|
||
|
||
```text
|
||
/modules/servers/hexagamecloud/
|
||
```
|
||
|
||
Repository:
|
||
|
||
```text
|
||
integrations/whmcs/modules/servers/hexagamecloud/
|
||
hexagamecloud.php
|
||
hooks.php
|
||
lib/
|
||
ApiClient.php
|
||
ApiException.php
|
||
Authentication.php
|
||
CanonicalRequest.php
|
||
Configuration.php
|
||
Dto/
|
||
Idempotency.php
|
||
Logger.php
|
||
Mapping.php
|
||
ModuleResult.php
|
||
ServiceLink.php
|
||
Sso.php
|
||
Usage/
|
||
MetricsProvider.php
|
||
templates/
|
||
clientarea.tpl
|
||
error.tpl
|
||
lang/
|
||
english.php
|
||
german.php
|
||
```
|
||
|
||
### Addon-Modul
|
||
|
||
Installationspfad:
|
||
|
||
```text
|
||
/modules/addons/hexagamecloud/
|
||
```
|
||
|
||
Repository:
|
||
|
||
```text
|
||
integrations/whmcs/modules/addons/hexagamecloud/
|
||
hexagamecloud.php
|
||
hooks.php
|
||
lib/
|
||
ApiClient.php
|
||
Configuration.php
|
||
EventStore.php
|
||
HealthCheck.php
|
||
ProductSync.php
|
||
Reconciliation.php
|
||
SecretStore.php
|
||
Upgrade.php
|
||
templates/
|
||
dashboard.tpl
|
||
settings.tpl
|
||
products.tpl
|
||
mappings.tpl
|
||
services.tpl
|
||
jobs.tpl
|
||
reconciliation.tpl
|
||
lang/
|
||
english.php
|
||
german.php
|
||
```
|
||
|
||
Zusätzlich:
|
||
|
||
```text
|
||
integrations/whmcs/tests/
|
||
Unit/
|
||
Integration/
|
||
Contract/
|
||
Fixtures/
|
||
|
||
integrations/whmcs/packaging/
|
||
build-package.sh
|
||
manifest.json
|
||
checksums.txt
|
||
```
|
||
|
||
Der technische Modulname lautet immer `hexagamecloud`.
|
||
|
||
## 32.3 Qualitätsanforderungen für PHP
|
||
|
||
- `declare(strict_types=1);`
|
||
- Namespaces für Klassen unter `lib/`
|
||
- PSR-12
|
||
- Composer nur innerhalb des Moduls und ohne Konflikt mit WHMCS-Abhängigkeiten
|
||
- keine Änderung von WHMCS-Core-Dateien
|
||
- keine direkten Schreibzugriffe auf WHMCS-Kerntabellen
|
||
- Capsule ausschließlich für eigene Modultabellen oder unvermeidbare dokumentierte Read-only-Abfragen
|
||
- keine versteckte Geschäftslogik in Templates
|
||
- deutsche und englische Sprachdateien
|
||
- keine hartcodierten Produkt-, Options- oder Kunden-IDs
|
||
- keine hartcodierten URLs oder Secrets
|
||
- semantische Modulversion
|
||
- Upgrade-Routinen für eigene Tabellen
|
||
- reproduzierbares ZIP-Paket
|
||
- SHA-256-Prüfsummen
|
||
- Changelog
|
||
- Kompatibilitätsmatrix für WHMCS und PHP
|
||
- statische Analyse mit PHPStan oder Psalm
|
||
- PHPUnit-Tests
|
||
- Contract Tests gegen die GameCloud-API
|
||
- Modulcode darf bei nicht erreichbarer GameCloud keine Fatal Errors in WHMCS verursachen
|
||
|
||
Beachte, dass WHMCS-Provisioning-Module maximal 24 klassische Moduleinstellungen pro Produkt unterstützen. Globale API-Einstellungen und umfangreiche Mappings gehören deshalb in das Addon-Modul oder in die WHMCS-Serverkonfiguration, nicht in eine unkontrolliert große `ConfigOptions`-Liste.
|
||
|
||
## 32.4 Unterstützte Provisioning-Funktionen
|
||
|
||
Implementiere, soweit fachlich sinnvoll:
|
||
|
||
```php
|
||
hexagamecloud_MetaData()
|
||
hexagamecloud_ConfigOptions()
|
||
hexagamecloud_TestConnection()
|
||
|
||
hexagamecloud_CreateAccount()
|
||
hexagamecloud_SuspendAccount()
|
||
hexagamecloud_UnsuspendAccount()
|
||
hexagamecloud_TerminateAccount()
|
||
hexagamecloud_Renew()
|
||
hexagamecloud_ChangePackage()
|
||
|
||
hexagamecloud_ServiceSingleSignOn()
|
||
hexagamecloud_AdminSingleSignOn()
|
||
|
||
hexagamecloud_ClientArea()
|
||
hexagamecloud_ClientAreaCustomButtonArray()
|
||
hexagamecloud_AdminCustomButtonArray()
|
||
hexagamecloud_CustomActions()
|
||
|
||
hexagamecloud_AdminServicesTabFields()
|
||
hexagamecloud_AdminServicesTabFieldsSave()
|
||
|
||
hexagamecloud_ListAccounts()
|
||
hexagamecloud_UsageUpdate()
|
||
hexagamecloud_MetricProvider()
|
||
```
|
||
|
||
`ChangePassword` wird nur implementiert, wenn es eine echte fachliche Bedeutung gibt. Wird ausschließlich SSO verwendet, darf WHMCS kein separates GameCloud-Passwort erzeugen oder speichern.
|
||
|
||
Alle Lifecycle-Funktionen müssen:
|
||
|
||
1. Eingaben validieren.
|
||
2. WHMCS-Parameter in ein typisiertes internes DTO überführen.
|
||
3. einen stabilen Idempotency-Key erzeugen.
|
||
4. einen Timeout verwenden.
|
||
5. API-Antworten strikt validieren.
|
||
6. asynchrone Operationen korrekt abbilden.
|
||
7. eine Correlation-ID verwenden.
|
||
8. Secrets in Logs maskieren.
|
||
9. Wiederholungen sicher behandeln.
|
||
10. nur `success` zurückgeben, wenn der Auftrag dauerhaft angenommen oder abgeschlossen wurde.
|
||
11. bei Fehlern eine verständliche Meldung für WHMCS-Administratoren zurückgeben.
|
||
12. keine rohen Stacktraces oder API-Secrets im Clientbereich anzeigen.
|
||
|
||
## 32.5 Modul- und Produktkonfiguration
|
||
|
||
Globale Verbindungsdaten werden bevorzugt über einen WHMCS-Servereintrag oder das Addon-Modul konfiguriert:
|
||
|
||
- GameCloud API Base URL
|
||
- Integration ID
|
||
- API Secret
|
||
- optional mTLS-Clientzertifikat
|
||
- CA-Zertifikat oder Certificate Pin
|
||
- Timeout
|
||
- maximale Wiederholungen
|
||
- erlaubte Clock Skew
|
||
- SSO-Ziel-Origin
|
||
- Webhook Secret
|
||
- Logging-Level
|
||
- Test- oder Produktionsmodus
|
||
|
||
Pro WHMCS-Produkt werden innerhalb des 24-Felder-Limits nur notwendige Werte verwaltet:
|
||
|
||
- GameCloud Plan ID
|
||
- Standard-Edition
|
||
- Standard-Softwarefamilie
|
||
- Standard-Minecraft-Version
|
||
- Standard-Region oder Node-Pool
|
||
- RAM
|
||
- CPU-Gewichtung
|
||
- Disk
|
||
- maximale Spieler
|
||
- Backup-Profil
|
||
- Idle-Shutdown-Profil
|
||
- Queue-Priorität
|
||
- Always-on
|
||
- Usage Billing aktiviert
|
||
- Grace Period vor Löschung
|
||
- Terminierungsmodus
|
||
|
||
Verwende Loader-Funktionen für dynamische Werte:
|
||
|
||
- Pläne
|
||
- Regionen
|
||
- Softwarefamilien
|
||
- Versionen
|
||
- Node-Pools
|
||
- Backup-Profile
|
||
|
||
Bei API-Ausfall:
|
||
|
||
- keine bestehenden Werte überschreiben
|
||
- letzten gültigen Cache anzeigen
|
||
- Warnung mit Zeitstempel ausgeben
|
||
- Speichern mit unbekannter oder leerer Plan-ID verhindern
|
||
|
||
## 32.6 Produkt-, Options- und Addon-Mapping
|
||
|
||
Mappings dürfen nicht allein anhand sichtbarer Namen erfolgen, da diese übersetzt oder geändert werden können.
|
||
|
||
Das Addon-Modul verwaltet:
|
||
|
||
```text
|
||
WHMCS Product ID -> GameCloud Plan ID
|
||
WHMCS Configurable Option ID -> GameCloud Resource Key
|
||
WHMCS Option Value ID -> normalisierter GameCloud-Wert
|
||
WHMCS Product Addon ID -> GameCloud Feature Key
|
||
```
|
||
|
||
Beispiele:
|
||
|
||
```text
|
||
product_id=7 -> plan_id=starter-java
|
||
option_id=12,value_id=44 -> memoryMiB=4096
|
||
option_id=13,value_id=51 -> diskGiB=50
|
||
option_id=14,value_id=62 -> region=de-fra-1
|
||
addon_id=8 -> backupSlots+=5
|
||
addon_id=9 -> alwaysOn=true
|
||
```
|
||
|
||
Anforderungen:
|
||
|
||
- Mapping validieren
|
||
- Mapping versionieren
|
||
- Import und Export als JSON
|
||
- Dry Run
|
||
- Vorschau einer normalisierten Bestellung
|
||
- Warnung bei gelöschten Optionswerten
|
||
- Konflikte erkennen
|
||
- keine geratenen Fallbackwerte
|
||
- unbekannte Mappings blockieren die Provisionierung
|
||
- Fehler nennt WHMCS-Service-ID und problematische Option
|
||
- Reconciliation-Fall erzeugen
|
||
|
||
## 32.7 CreateAccount
|
||
|
||
`CreateAccount` erzeugt genau einen technischen GameCloud-Service.
|
||
|
||
Ablauf:
|
||
|
||
1. WHMCS-Service und Status prüfen.
|
||
2. Client ID, User ID, Service ID, Product ID und Order-Kontext erfassen.
|
||
3. Produkt, Configurable Options und Addons normalisieren.
|
||
4. Kundenverknüpfung anlegen oder laden.
|
||
5. GameCloud-Benutzer anlegen oder korrekt verknüpfen.
|
||
6. Provisionierungsanfrage an GameCloud senden.
|
||
7. externe Referenzen mitsenden:
|
||
- WHMCS Installation ID
|
||
- Client ID
|
||
- User ID
|
||
- Service ID
|
||
- Product ID
|
||
- Order ID, falls vorhanden
|
||
- Invoice ID, falls vorhanden
|
||
8. Idempotency-Key verwenden:
|
||
|
||
```text
|
||
whmcs:{installationId}:service:{serviceId}:create:{configurationGeneration}
|
||
```
|
||
|
||
9. GameCloud erzeugt Server und `WhmcsServiceLink` transaktional.
|
||
10. GameCloud Server ID in WHMCS als Service Property oder nicht kundenseitig änderbares Custom Field speichern.
|
||
11. keine Klartextpasswörter speichern.
|
||
12. bei erneuter Ausführung bestehenden Server erkennen.
|
||
13. keinen zweiten Server anlegen.
|
||
14. bei unklarem Timeout den Status per GET prüfen, bevor erneut provisioniert wird.
|
||
|
||
Eine Provisionierungsantwort enthält:
|
||
|
||
```json
|
||
{
|
||
"operationId": "01...",
|
||
"serviceId": "01...",
|
||
"serverId": "01...",
|
||
"status": "accepted",
|
||
"correlationId": "01..."
|
||
}
|
||
```
|
||
|
||
## 32.8 SuspendAccount
|
||
|
||
Suspendierung ist nicht identisch mit Stop.
|
||
|
||
Bei Suspendierung:
|
||
|
||
- laufenden Server kontrolliert stoppen
|
||
- Zustand `SUSPENDED` setzen
|
||
- neue Starts blockieren
|
||
- SSO auf Sperrseite umleiten oder verweigern
|
||
- API-Tokens für den Service widerrufen
|
||
- Welten und Backups nicht sofort löschen
|
||
- Shared-User-Zugriffe einfrieren
|
||
- Grund speichern:
|
||
- overdue
|
||
- manual
|
||
- fraud
|
||
- abuse
|
||
- security
|
||
- cancellation-pending
|
||
- WHMCS-Service-ID und Correlation-ID auditieren
|
||
- Grace Period starten, falls konfiguriert
|
||
|
||
Der Aufruf muss idempotent sein.
|
||
|
||
## 32.9 UnsuspendAccount
|
||
|
||
Bei Entsperrung:
|
||
|
||
- Sperrgrund prüfen
|
||
- kaufmännische Sperren automatisch aufhebbar machen
|
||
- Abuse-, Fraud- oder Security-Sperren nur bei expliziter Freigabe aufheben
|
||
- Tarif und Quotas erneut synchronisieren
|
||
- Server in `STOPPED` freigeben
|
||
- nicht automatisch starten
|
||
- SSO wieder aktivieren
|
||
- technische Tokens bei Bedarf neu ausstellen
|
||
- Audit-Ereignis erzeugen
|
||
|
||
## 32.10 TerminateAccount
|
||
|
||
Unterstütze zwei Modi.
|
||
|
||
### Soft Termination
|
||
|
||
- `TERMINATION_PENDING`
|
||
- Server stoppen
|
||
- Starts und SSO blockieren
|
||
- optionale Abschluss-Sicherung
|
||
- Daten bis zum Löschdatum aufbewahren
|
||
- Wiederherstellung durch Admin während Grace Period
|
||
- endgültige Löschung durch Worker
|
||
|
||
### Immediate Termination
|
||
|
||
- nur explizit konfigurierbar
|
||
- Server stoppen
|
||
- DNS entfernen
|
||
- Ports und Allocation freigeben
|
||
- aktive Serverdaten löschen
|
||
- Backup-Aufbewahrung separat nach Vertrag und Datenschutz behandeln
|
||
- Link tombstonen
|
||
- vollständiges Audit erzeugen
|
||
|
||
Doppelte Terminate-Aufrufe sind sicher. Eine bereits gelöschte Ressource gilt als erfolgreich terminiert.
|
||
|
||
## 32.11 Renew
|
||
|
||
`Renew` erzeugt niemals einen neuen Server.
|
||
|
||
Verwendung:
|
||
|
||
- Ablaufdatum aktualisieren
|
||
- neue monatliche Credits zuteilen
|
||
- neue Usage-Periode eröffnen
|
||
- zahlungsbedingt abgelaufenen Service freigeben
|
||
- Ledger-Eintrag mit Invoice ID anlegen
|
||
- Idempotency-Key anhand Rechnungs- oder Renewal-Referenz verwenden
|
||
|
||
Bei normalen wiederkehrenden Produkten ohne technisches Ablaufdatum darf die Funktion kontrolliert `success` zurückgeben.
|
||
|
||
## 32.12 ChangePackage
|
||
|
||
Ablauf:
|
||
|
||
1. aktuelle GameCloud-Konfiguration lesen
|
||
2. neue WHMCS-Konfiguration normalisieren
|
||
3. Diff erzeugen
|
||
4. Verfügbarkeit prüfen
|
||
5. Änderungsplan erzeugen
|
||
6. sichere Änderungen anwenden
|
||
7. Neustartbedarf markieren
|
||
8. Regionwechsel als Migration ausführen
|
||
9. Teilfehler zurückrollen oder Reconciliation markieren
|
||
|
||
Regeln:
|
||
|
||
- RAM-Erhöhung nur bei verfügbarer Kapazität
|
||
- Disk-Vergrößerung online oder kontrolliert
|
||
- Disk-Verkleinerung nur, wenn Nutzung und Storage-Technik dies zulassen
|
||
- Downgrade bei zu hoher Nutzung ablehnen
|
||
- Always-on und Queue-Priorität aktualisieren
|
||
- Backup-Retention sauber anpassen
|
||
- keine Welt- oder Softwareänderung als versteckter Tarifwechsel
|
||
- keine stille Abschaltung
|
||
- Status im WHMCS-Adminbereich anzeigen:
|
||
- applied
|
||
- restart-required
|
||
- migration-running
|
||
- rejected
|
||
- reconciliation-required
|
||
|
||
## 32.13 Produkt-Addons
|
||
|
||
Unterstützte Addons:
|
||
|
||
- zusätzlicher RAM
|
||
- zusätzlicher Diskplatz
|
||
- zusätzliche Backup-Slots
|
||
- längere Backup-Retention
|
||
- zusätzliche Ports
|
||
- Premium-Queue
|
||
- Always-on
|
||
- feste Proxy-Adresse
|
||
- Managed Updates
|
||
- Managed Modpack
|
||
- Support-Level
|
||
- zusätzlicher S3-Export
|
||
|
||
Addon-Aktivierung, Suspendierung, Reaktivierung und Terminierung wirken als Feature-Delta auf den bestehenden Server. Ein Addon darf keinen zweiten Server erzeugen.
|
||
|
||
## 32.14 Single Sign-On
|
||
|
||
Implementiere `ServiceSingleSignOn` und `AdminSingleSignOn`.
|
||
|
||
Flow:
|
||
|
||
1. WHMCS prüft den aktuell authentifizierten Benutzer.
|
||
2. Das Modul prüft den Zugriff auf den konkreten Service.
|
||
3. Das Modul fordert ein einmaliges GameCloud-SSO-Ticket an.
|
||
4. Ticketinhalt:
|
||
- GameCloud User ID
|
||
- WHMCS Installation ID
|
||
- WHMCS Client ID
|
||
- WHMCS User ID
|
||
- WHMCS Service ID
|
||
- GameCloud Server ID
|
||
- Rolle
|
||
- Zielpfad
|
||
- Issuer
|
||
- Audience
|
||
- Issued At
|
||
- Expiry
|
||
- Nonce
|
||
5. Gültigkeit maximal 60 Sekunden.
|
||
6. nur einmal nutzbar.
|
||
7. serverseitig nur gehasht speichern.
|
||
8. Redirect nur auf Allowlist-Origin.
|
||
9. keine beliebige `returnUrl`.
|
||
10. nach Einlösung normale sichere GameCloud-Session erzeugen.
|
||
11. Admin-SSO als sichtbare Support-/Impersonation-Session kennzeichnen.
|
||
12. Admin-Impersonation vollständig auditieren.
|
||
13. kein langfristiges Token in der URL.
|
||
|
||
WHMCS zeigt den Button `Server verwalten`.
|
||
|
||
## 32.15 WHMCS Client Area
|
||
|
||
Kompakte Ansicht:
|
||
|
||
- Servername
|
||
- Status
|
||
- Adresse und Port
|
||
- Edition
|
||
- Software und Version
|
||
- Tarif
|
||
- RAM und Disk
|
||
- aktuelle Spieler
|
||
- nächstes Abrechnungsdatum
|
||
- Suspendierungsstatus
|
||
- letzte Backups
|
||
- laufende Jobs
|
||
- Button zum GameCloud-Panel
|
||
|
||
Schnellaktionen:
|
||
|
||
- Start
|
||
- Stop
|
||
- Restart
|
||
- Backup erstellen
|
||
|
||
Sicherheitsanforderungen:
|
||
|
||
- CSRF-Schutz
|
||
- Servicebesitz prüfen
|
||
- aktiven WHMCS-Benutzer prüfen
|
||
- serverseitiger API-Aufruf
|
||
- keine GameCloud-Integration-Secrets im Browser
|
||
- Idempotency-Key
|
||
- lange Jobs nicht synchron blockieren
|
||
- verständliche Fehlerseite bei API-Ausfall
|
||
|
||
Der vollständige Dateimanager und die Konsole verbleiben im GameCloud-Panel.
|
||
|
||
## 32.16 Admin Services Tab
|
||
|
||
Zeige:
|
||
|
||
- GameCloud Server ID
|
||
- GameCloud User ID
|
||
- technischer Zustand
|
||
- gewünschter Zustand
|
||
- Node
|
||
- Allocation
|
||
- IP und Port
|
||
- Plan
|
||
- Ressourcen
|
||
- Disknutzung
|
||
- Spielerzahl
|
||
- letzte Statuszeit
|
||
- letzte Synchronisierung
|
||
- letzte Correlation-ID
|
||
- aktive Operationen
|
||
- Suspendierungsgrund
|
||
- geplantes Löschdatum
|
||
- Link zum GameCloud-Adminpanel
|
||
|
||
Adminaktionen:
|
||
|
||
- Status neu laden
|
||
- Start
|
||
- Stop
|
||
- Restart
|
||
- Backup
|
||
- Reconcile
|
||
- Ressourcen erneut anwenden
|
||
- Verknüpfung reparieren
|
||
- Migration auslösen
|
||
- SSO
|
||
|
||
Destruktive Aktionen benötigen Bestätigung und passende Adminrechte.
|
||
|
||
## 32.17 Addon-Modul: globale Verwaltung
|
||
|
||
### Dashboard
|
||
|
||
- API-Erreichbarkeit
|
||
- GameCloud-Version
|
||
- Modulversion
|
||
- letzte erfolgreiche Synchronisierung
|
||
- verknüpfte Kunden
|
||
- verknüpfte Services
|
||
- nicht verknüpfte WHMCS-Services
|
||
- verwaiste GameCloud-Server
|
||
- fehlgeschlagene Provisionierungen
|
||
- Reconciliation-Fälle
|
||
- Usage-Exportstatus
|
||
- Secret- oder Zertifikatsablauf
|
||
- letzte Fehler
|
||
|
||
### Einstellungen
|
||
|
||
- API URL
|
||
- Integration ID
|
||
- Secret oder mTLS
|
||
- Timeout
|
||
- SSO-Origin
|
||
- Webhook Secret
|
||
- Billing-Modus
|
||
- Grace Period
|
||
- Logging-Level
|
||
- Feature Flags
|
||
- Cron-Intervalle
|
||
|
||
Secrets verschlüsselt speichern und nach dem Speichern nicht erneut vollständig anzeigen.
|
||
|
||
### Produkt-Mappings
|
||
|
||
- WHMCS-Produkte
|
||
- GameCloud-Pläne
|
||
- Configurable Options
|
||
- Product Addons
|
||
- Validierung
|
||
- Vorschau
|
||
- Import und Export
|
||
- Dry Run
|
||
|
||
### Services
|
||
|
||
- Suche nach Client ID
|
||
- Service ID
|
||
- Server ID
|
||
- Status
|
||
- Tarifabweichung
|
||
- Ressourcenabweichung
|
||
- letzte Synchronisierung
|
||
- Reconcile
|
||
- Neuverknüpfung
|
||
- kontrollierter Import
|
||
|
||
### Jobs
|
||
|
||
- Operation
|
||
- Service ID
|
||
- Correlation-ID
|
||
- Dauer
|
||
- HTTP-Status
|
||
- Ergebnis
|
||
- Retry
|
||
- maskierte Metadaten
|
||
- keine Secrets
|
||
|
||
## 32.18 Eigene Modultabellen in WHMCS
|
||
|
||
Verwende Präfix `mod_hexagamecloud_`.
|
||
|
||
Mindestens:
|
||
|
||
```text
|
||
mod_hexagamecloud_installations
|
||
mod_hexagamecloud_client_links
|
||
mod_hexagamecloud_user_links
|
||
mod_hexagamecloud_service_links
|
||
mod_hexagamecloud_product_mappings
|
||
mod_hexagamecloud_option_mappings
|
||
mod_hexagamecloud_addon_mappings
|
||
mod_hexagamecloud_events
|
||
mod_hexagamecloud_operations
|
||
mod_hexagamecloud_sync_cursors
|
||
mod_hexagamecloud_reconciliation
|
||
mod_hexagamecloud_usage_exports
|
||
```
|
||
|
||
Speichere keine redundanten vollständigen Kundendatensätze. Halte nur IDs, technische Referenzen, Status, Hashes, Cursor und notwendige Diagnosemetadaten.
|
||
|
||
## 32.19 GameCloud Integration API
|
||
|
||
Erstelle einen eigenen API-Namespace:
|
||
|
||
```text
|
||
GET /api/v1/integrations/whmcs/health
|
||
GET /api/v1/integrations/whmcs/catalog/plans
|
||
GET /api/v1/integrations/whmcs/catalog/regions
|
||
GET /api/v1/integrations/whmcs/catalog/software
|
||
GET /api/v1/integrations/whmcs/catalog/versions
|
||
|
||
PUT /api/v1/integrations/whmcs/clients/:externalClientId
|
||
PUT /api/v1/integrations/whmcs/users/:externalUserId
|
||
|
||
POST /api/v1/integrations/whmcs/services
|
||
GET /api/v1/integrations/whmcs/services/:externalServiceId
|
||
PATCH /api/v1/integrations/whmcs/services/:externalServiceId
|
||
POST /api/v1/integrations/whmcs/services/:externalServiceId/suspend
|
||
POST /api/v1/integrations/whmcs/services/:externalServiceId/unsuspend
|
||
POST /api/v1/integrations/whmcs/services/:externalServiceId/terminate
|
||
POST /api/v1/integrations/whmcs/services/:externalServiceId/renew
|
||
POST /api/v1/integrations/whmcs/services/:externalServiceId/change-package
|
||
POST /api/v1/integrations/whmcs/services/:externalServiceId/reconcile
|
||
|
||
POST /api/v1/integrations/whmcs/services/:externalServiceId/sso
|
||
POST /api/v1/integrations/whmcs/services/:externalServiceId/actions/start
|
||
POST /api/v1/integrations/whmcs/services/:externalServiceId/actions/stop
|
||
POST /api/v1/integrations/whmcs/services/:externalServiceId/actions/restart
|
||
POST /api/v1/integrations/whmcs/services/:externalServiceId/actions/backup
|
||
|
||
GET /api/v1/integrations/whmcs/services/:externalServiceId/usage
|
||
GET /api/v1/integrations/whmcs/events
|
||
POST /api/v1/integrations/whmcs/events/ack
|
||
```
|
||
|
||
Verwende keine allgemeinen Super-Admin-Endpunkte für das Modul.
|
||
|
||
## 32.20 API-Authentifizierung
|
||
|
||
Bevorzugt:
|
||
|
||
1. mTLS
|
||
2. zusätzlich HMAC-signierte Requests
|
||
|
||
Header:
|
||
|
||
```text
|
||
X-HGC-Integration-ID
|
||
X-HGC-Timestamp
|
||
X-HGC-Nonce
|
||
X-HGC-Idempotency-Key
|
||
X-HGC-Signature
|
||
X-Correlation-ID
|
||
```
|
||
|
||
Kanonische Signaturbasis:
|
||
|
||
```text
|
||
HTTP_METHOD
|
||
REQUEST_PATH
|
||
CANONICAL_QUERY
|
||
SHA256_BODY
|
||
TIMESTAMP
|
||
NONCE
|
||
IDEMPOTENCY_KEY
|
||
```
|
||
|
||
Anforderungen:
|
||
|
||
- HMAC-SHA256 oder stärker
|
||
- konstanter Zeitvergleich
|
||
- Clock-Skew-Limit
|
||
- Nonce-Replay-Schutz
|
||
- Secret Rotation mit Überlappungsfenster
|
||
- getrennte Test- und Produktions-Credentials
|
||
- optionale IP-Allowlist
|
||
- Rate Limits pro Installation
|
||
- Authentifizierungsfehler auditieren
|
||
|
||
Scopes:
|
||
|
||
```text
|
||
catalog:read
|
||
client:write
|
||
service:read
|
||
service:provision
|
||
service:lifecycle
|
||
service:package
|
||
service:terminate
|
||
usage:read
|
||
sso:create
|
||
reconcile:run
|
||
events:read
|
||
```
|
||
|
||
## 32.21 Ereignisse und Hooks
|
||
|
||
Hooks nur verwenden, wenn Provisioning-Funktionen nicht ausreichen.
|
||
|
||
Mögliche Ereignisse:
|
||
|
||
- OrderPaid
|
||
- InvoicePaid
|
||
- InvoiceRefunded
|
||
- CancellationRequest
|
||
- Product Addon Activation
|
||
- Product Addon Suspension
|
||
- Product Addon Unsuspension
|
||
- Product Addon Termination
|
||
- Client Merge
|
||
- Client- oder Benutzeränderung
|
||
- täglicher Cronabschluss
|
||
- Modulaktivierung
|
||
- Moduldeaktivierung
|
||
|
||
Regeln:
|
||
|
||
- kein Hook darf doppelte Provisionierung erzeugen
|
||
- jedes Event persistent deduplizieren
|
||
- Event-Key aus Installation, Hookname und stabiler Objekt-ID
|
||
- lange Arbeit an GameCloud delegieren
|
||
- Cron nicht durch einen einzelnen Fehler abbrechen
|
||
- Retry und Dead-Letter
|
||
- Reihenfolge von Order-, Invoice- und Provisioning-Events testen
|
||
- Geschäftslogik nicht ausschließlich in Hooks verstecken
|
||
|
||
## 32.22 GameCloud-Ereignisse an WHMCS
|
||
|
||
Relevante Ereignisse:
|
||
|
||
- Provisionierung abgeschlossen
|
||
- Provisionierung fehlgeschlagen
|
||
- Paketänderung abgeschlossen
|
||
- Paketänderung fehlgeschlagen
|
||
- Migration abgeschlossen
|
||
- Server endgültig gelöscht
|
||
- Backup dauerhaft fehlgeschlagen
|
||
- Ressourcenlimit erreicht
|
||
- Usage-Periode abgeschlossen
|
||
- Reconciliation erforderlich
|
||
- Abuse- oder Security-Sperre
|
||
|
||
Sichere Standardvariante:
|
||
|
||
- Addon-Modul pollt GameCloud cursorbasiert
|
||
- mindestens einmalige Zustellung
|
||
- Deduplizierung über Event ID
|
||
- Cursor persistent speichern
|
||
- Ack erst nach erfolgreicher Verarbeitung
|
||
- Dead-Letter-Ansicht
|
||
|
||
Ein eingehender WHMCS-Webhook-Endpunkt ist optional und muss streng signaturgeprüft sein.
|
||
|
||
## 32.23 Usage Billing
|
||
|
||
Implementiere die WHMCS Usage-Metrics-Schnittstelle über `MetricProvider`.
|
||
|
||
Metriken:
|
||
|
||
```text
|
||
runtime_minutes
|
||
memory_gib_minutes
|
||
cpu_core_minutes
|
||
storage_gib_days
|
||
backup_storage_gib_days
|
||
egress_gib
|
||
extra_port_days
|
||
priority_queue_minutes
|
||
managed_service_units
|
||
```
|
||
|
||
Anforderungen:
|
||
|
||
- GameCloud aggregiert unveränderbare Rohmesswerte
|
||
- feste Abrechnungsfenster
|
||
- UTC intern
|
||
- identische Wiederholungsantworten
|
||
- Export mit Hash und Status
|
||
- keine stillen rückwirkenden Änderungen
|
||
- Korrekturen als Adjustment
|
||
- Preise ausschließlich in WHMCS
|
||
- Testmodus
|
||
- effiziente Batch-Abfrage
|
||
- `UsageUpdate` für klassische Disk-/Bandwidth-Werte
|
||
- `MetricProvider` für erweiterte Metriken
|
||
- exportierte Perioden auditieren
|
||
|
||
## 32.24 Kunden- und Benutzerzuordnung
|
||
|
||
WHMCS Client, WHMCS User und GameCloud User sind getrennte Objekte.
|
||
|
||
Regeln:
|
||
|
||
- ein Client kann mehrere WHMCS-Benutzer haben
|
||
- ein Benutzer kann Zugriff auf mehrere Kundenkonten besitzen
|
||
- SSO prüft den aktuellen WHMCS-Benutzer und den konkreten Service
|
||
- niemals nur anhand E-Mail verknüpfen
|
||
- Schlüssel:
|
||
- Installation ID
|
||
- Client ID
|
||
- User ID
|
||
- Service ID
|
||
- E-Mail ist nur Attribut
|
||
- Client-Merge migriert Links kontrolliert
|
||
- E-Mail-Änderung erzeugt keinen neuen GameCloud-Account
|
||
- entfernte WHMCS-Benutzer verlieren SSO-Zugriff
|
||
- GameCloud Shared Members benötigen kein WHMCS-Konto
|
||
|
||
## 32.25 Status-Mapping
|
||
|
||
```text
|
||
WHMCS Pending -> DRAFT oder PROVISIONING_PENDING
|
||
WHMCS Active -> STOPPED/RUNNING/STARTING/STOPPING
|
||
WHMCS Suspended -> SUSPENDED
|
||
WHMCS Terminated -> TERMINATION_PENDING/DELETED
|
||
WHMCS Cancelled -> abhängig von Kündigungsdatum
|
||
WHMCS Fraud -> SUSPENDED mit reason=fraud
|
||
```
|
||
|
||
Technische Zustände wie `ERROR`, `BACKING_UP`, `RESTORING` oder `MIGRATING` ändern den kaufmännischen WHMCS-Status nicht automatisch.
|
||
|
||
## 32.26 Reconciliation
|
||
|
||
Mindestens täglich und zusätzlich ereignisgesteuert.
|
||
|
||
Vergleiche:
|
||
|
||
- WHMCS Active, GameCloud fehlt
|
||
- WHMCS Suspended, GameCloud startbar
|
||
- WHMCS Terminated, GameCloud vorhanden
|
||
- GameCloud-Server ohne WHMCS-Link
|
||
- Tarifabweichung
|
||
- RAM-/Disk-Abweichung
|
||
- fehlende Addons
|
||
- doppelte Links
|
||
- Benutzerzuordnung
|
||
- Löschfrist
|
||
- Usage-Lücken
|
||
- fehlerhafte Port- oder DNS-Zuordnung
|
||
|
||
Klassifikation:
|
||
|
||
```text
|
||
INFO
|
||
WARNING
|
||
BLOCKING
|
||
DESTRUCTIVE
|
||
SECURITY
|
||
```
|
||
|
||
Automatische Reparatur nur bei eindeutig sicheren Fällen. Destruktive Reparaturen benötigen Dry Run und Adminbestätigung.
|
||
|
||
## 32.27 Kündigung, Refund und Chargeback
|
||
|
||
Kündigung:
|
||
|
||
- sofort oder Periodenende
|
||
- Löschdatum vormerken
|
||
- Start und SSO abhängig vom Vertragsstatus
|
||
- Widerruf bis zur erlaubten Frist
|
||
- Nutzer im Panel informieren
|
||
|
||
Refund:
|
||
|
||
- keine automatische Datenlöschung
|
||
- kaufmännische und technische Aktion trennen
|
||
|
||
Chargeback/Fraud:
|
||
|
||
- sofortige Suspendierung möglich
|
||
- keine irreversible automatische Löschung
|
||
- manuelle Prüfung
|
||
- Tokens widerrufen
|
||
- Abuse-Fall und Audit erzeugen
|
||
|
||
## 32.28 Logging und Datenschutz
|
||
|
||
Verwende WHMCS `logModuleCall`, aber maskiere:
|
||
|
||
- API Secrets
|
||
- Signaturen
|
||
- Passwörter
|
||
- Session-Tokens
|
||
- SSO-Tickets
|
||
- mTLS-Schlüssel
|
||
- personenbezogene Payload-Felder, soweit nicht notwendig
|
||
|
||
Speichere:
|
||
|
||
- Aktion
|
||
- Service ID
|
||
- Operation ID
|
||
- Correlation-ID
|
||
- HTTP-Status
|
||
- Dauer
|
||
- maschinenlesbaren Fehlercode
|
||
- gekürzte technische Meldung
|
||
|
||
Keine vollständigen Weltdaten, Konsolenlogs oder Chatnachrichten in WHMCS speichern.
|
||
|
||
## 32.29 Tests der WHMCS-Integration
|
||
|
||
Unit Tests:
|
||
|
||
- Normalisierung von Modulparametern
|
||
- Mapping von Optionen
|
||
- Signaturerstellung
|
||
- Signaturprüfung
|
||
- Idempotency-Key
|
||
- Secret-Maskierung
|
||
- Status-Mapping
|
||
- Usage-Rundung
|
||
- Reconciliation-Klassifikation
|
||
|
||
Contract Tests:
|
||
|
||
- CreateAccount
|
||
- SuspendAccount
|
||
- UnsuspendAccount
|
||
- TerminateAccount
|
||
- Renew
|
||
- ChangePackage
|
||
- SSO
|
||
- Usage
|
||
- Events
|
||
- API-Fehlerformate
|
||
|
||
Integration Tests:
|
||
|
||
- doppelter CreateAccount-Aufruf
|
||
- Timeout nach angenommener Provisionierung
|
||
- Suspend während Start
|
||
- Unsuspend bei Abuse-Sperre
|
||
- Downgrade unter reale Disknutzung
|
||
- Addon-Aktivierung und -Entfernung
|
||
- Client-Merge
|
||
- gelöschter Optionswert
|
||
- Secret Rotation
|
||
- Event-Deduplizierung
|
||
- verpasste Eventperiode und Cursor-Recovery
|
||
- Usage-Export zweimal abgerufen
|
||
- Reconciliation mit verwaistem Server
|
||
|
||
## 32.30 Deployment und Dokumentation
|
||
|
||
Erstelle:
|
||
|
||
```text
|
||
docs/integrations/whmcs/installation.md
|
||
docs/integrations/whmcs/configuration.md
|
||
docs/integrations/whmcs/products.md
|
||
docs/integrations/whmcs/configurable-options.md
|
||
docs/integrations/whmcs/addons.md
|
||
docs/integrations/whmcs/sso.md
|
||
docs/integrations/whmcs/usage-billing.md
|
||
docs/integrations/whmcs/reconciliation.md
|
||
docs/integrations/whmcs/security.md
|
||
docs/integrations/whmcs/upgrades.md
|
||
docs/integrations/whmcs/troubleshooting.md
|
||
```
|
||
|
||
Installation dokumentiert:
|
||
|
||
- Voraussetzungen
|
||
- Moduldateien kopieren
|
||
- Addon aktivieren
|
||
- Berechtigungen setzen
|
||
- GameCloud-Integration anlegen
|
||
- Secret oder Zertifikat hinterlegen
|
||
- Servereintrag konfigurieren
|
||
- Produkt zuweisen
|
||
- Mappings erstellen
|
||
- Test Connection
|
||
- Testbestellung
|
||
- Suspend/Unsuspend-Test
|
||
- SSO-Test
|
||
- Usage-Test
|
||
- Cron
|
||
- Backup
|
||
- Upgrade
|
||
- Rollback
|
||
|
||
## 32.31 WHMCS-Umsetzungsphasen
|
||
|
||
### WHMCS Phase A – Fundament
|
||
|
||
- API-Client
|
||
- Authentifizierung
|
||
- Modulstruktur
|
||
- Addon-Einstellungen
|
||
- Test Connection
|
||
- eigene Tabellen
|
||
- Logging
|
||
- Packaging
|
||
|
||
### WHMCS Phase B – Provisionierung
|
||
|
||
- CreateAccount
|
||
- Service Links
|
||
- Product Mapping
|
||
- Configurable Options
|
||
- Client Area Status
|
||
- Admin Services Tab
|
||
|
||
### WHMCS Phase C – Lifecycle
|
||
|
||
- Suspend
|
||
- Unsuspend
|
||
- Terminate
|
||
- Renew
|
||
- ChangePackage
|
||
- Addons
|
||
|
||
### WHMCS Phase D – SSO
|
||
|
||
- Service SSO
|
||
- Admin SSO
|
||
- Einmaltickets
|
||
- Impersonation Audit
|
||
- Allowlist Redirects
|
||
|
||
### WHMCS Phase E – Synchronisierung
|
||
|
||
- ListAccounts
|
||
- Reconciliation
|
||
- Cursor-Events
|
||
- Dead Letter
|
||
- Import bestehender Services
|
||
|
||
### WHMCS Phase F – Usage Billing
|
||
|
||
- MetricProvider
|
||
- UsageUpdate
|
||
- Perioden
|
||
- Exporte
|
||
- Adjustments
|
||
- Testmodus
|
||
|
||
Abnahmekriterium: Eine bezahlte WHMCS-Bestellung erzeugt genau einen GameCloud-Server. Sperrung, Entsperrung, Tarifwechsel, Kündigung, SSO, Addons und Usage Billing funktionieren reproduzierbar und idempotent.
|
||
|
||
## 32.32 Offizielle Referenzen für die Implementierung
|
||
|
||
Cursor soll bei der Implementierung die jeweils aktuelle offizielle WHMCS-Dokumentation prüfen. Relevante Ausgangspunkte:
|
||
|
||
- https://developers.whmcs.com/provisioning-modules/
|
||
- https://developers.whmcs.com/provisioning-modules/supported-functions/
|
||
- https://developers.whmcs.com/provisioning-modules/core-module-functions/
|
||
- https://developers.whmcs.com/provisioning-modules/config-options/
|
||
- https://developers.whmcs.com/provisioning-modules/loader-functions/
|
||
- https://developers.whmcs.com/provisioning-modules/single-sign-on/
|
||
- https://developers.whmcs.com/provisioning-modules/usage-metrics/
|
||
- https://developers.whmcs.com/provisioning-modules/service-properties/
|
||
- https://developers.whmcs.com/provisioning-modules/server-sync/
|
||
- https://developers.whmcs.com/provisioning-modules/module-logging/
|
||
- https://developers.whmcs.com/provisioning-modules/admin-services-tab/
|
||
- https://developers.whmcs.com/addon-modules/
|
||
- https://developers.whmcs.com/hooks-reference/
|
||
|
||
Implementiere nicht blind anhand veralteter Blogposts oder inoffizieller Beispiele.
|
||
|
||
---
|
||
|
||
# 33. Erste konkrete Aufgabe
|
||
|
||
|
||
Beginne jetzt mit **Phase 0**.
|
||
|
||
Erstelle nicht nur einen Plan, sondern lege die tatsächliche Repository-Struktur und funktionsfähige Dateien an.
|
||
|
||
Erwartetes erstes Ergebnis:
|
||
|
||
1. Monorepo mit allen Grundverzeichnissen
|
||
2. `pnpm-workspace.yaml`
|
||
3. Turborepo-Konfiguration
|
||
4. Next.js-Webanwendung
|
||
5. NestJS-Fastify-API
|
||
6. Worker-Grundgerüst
|
||
7. Go-Module für Agent und Gateway
|
||
8. PostgreSQL/Prisma-Grundschema
|
||
9. Redis- und MinIO-Konfiguration
|
||
10. `compose.dev.yml`
|
||
11. `.env.example`
|
||
12. Healthchecks
|
||
13. strukturiertes Logging
|
||
14. OpenAPI
|
||
15. Basis-CI
|
||
16. ADR für die gewählte Architektur
|
||
17. `docs/IMPLEMENTATION_STATUS.md`
|
||
18. README mit exakten Startbefehlen
|
||
19. erste Tests
|
||
20. erfolgreiche lokale Build-, Lint- und Testausführung
|
||
|
||
Wähle kompatible stabile Versionen und pinne sie nachvollziehbar. Verwende keine veralteten Beispielversionen aus Tutorials. Dokumentiere jede externe Abhängigkeit und deren Zweck.
|
||
|
||
Nach Phase 0 fahre nicht automatisch mit unkontrollierten Großänderungen fort. Präsentiere den abgeschlossenen Stand, die Testergebnisse und die nächste klar abgegrenzte Phase.
|