smueller/HexaHost-GameCloud
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
HexaHost-GameCloud/HexaHost_GameCloud_Cursor_Masterprompt.md
smueller e37ea87b35
Some checks failed
CI / Go — node-agent tests (push) Has been cancelled
Details
CI / Go — edge-gateway build (push) Has been cancelled
Details
CI / Node — lint, typecheck, test, build (push) Has been cancelled
Details
initial commit
2026-06-26 10:45:08 +02:00

71 KiB
Raw Permalink Blame History

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

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:

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:

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:

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:

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

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:

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:

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:

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:

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:

/modules/servers/hexagamecloud/

Repository:

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:

/modules/addons/hexagamecloud/

Repository:

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:

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:

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:

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:

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:
whmcs:{installationId}:service:{serviceId}:create:{configurationGeneration}
  1. GameCloud erzeugt Server und WhmcsServiceLink transaktional.
  2. GameCloud Server ID in WHMCS als Service Property oder nicht kundenseitig änderbares Custom Field speichern.
  3. keine Klartextpasswörter speichern.
  4. bei erneuter Ausführung bestehenden Server erkennen.
  5. keinen zweiten Server anlegen.
  6. bei unklarem Timeout den Status per GET prüfen, bevor erneut provisioniert wird.

Eine Provisionierungsantwort enthält:

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

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:

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:

X-HGC-Integration-ID
X-HGC-Timestamp
X-HGC-Nonce
X-HGC-Idempotency-Key
X-HGC-Signature
X-Correlation-ID

Kanonische Signaturbasis:

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:

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:

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

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:

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:

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:

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.

Reference in New Issue View Git Blame Copy Permalink