← Dokumentation

Cloud-Netzwerk anbinden (CloudNet & Co.)

Das Cloud-Modul zeigt die Live-Topologie eines dynamischen Netzwerks (CloudNet, eigene Orchestrierung) im ACP unter Cloud: Tasks/Gruppen und ihre laufenden Services mit Spielerzahlen und Online-Status. Nexus orchestriert nicht selbst – ein schlanker Connector meldet die laufenden Services per HTTP.

CloudNet 4: offizieller Connector (empfohlen)

Für CloudNet 4 gibt es ein fertiges Node-Modul (nexus-cloudnet-connector, Download-Button im ACP unter Cloud → CloudNet anbinden; Version folgt dem Update-Kanal aus /license):

  1. Jar in den modules-Ordner des CloudNet-Nodes legen, Node neu starten.

  2. Im ACP report.token setzen (Module → cloud).

  3. modules/JuByteNexus-Connector/config.json ausfüllen und Modul neu laden:

    {
  "nexusUrl": "https://panel.example.com",
  "token": "<report.token>",
  "connector": "cloudnet-1",
  "reportIntervalSeconds": 10,
  "includeProxies": true
}

Das Modul meldet alle Services (Spielerzahlen via CloudNet-Bridge-Properties) im Takt an das Panel, führt die im ACP ausgelösten START/STOP-Befehle über die CloudNet-Driver-API aus (Server hinzufügen → „Neuen Server über die Cloud erstellen" bzw. Cloud → Service → „Stoppen") und quittiert sie mit dem nächsten Heartbeat. Es nutzt nur die stabile Driver-API (gebaut gegen 4.0.0-RC10, Java 21) und lädt auch ohne Bridge-Modul – dann fehlen lediglich die Spielerzahlen.

Alle anderen Clouds nutzen dieselbe generische Report-API:

1. Token setzen

ACP → Module → cloud → Einstellungen: report.token auf ein zufälliges Secret setzen (leer = alle Reports werden abgelehnt). Optional:

  • service.ttl-seconds (Default 30) – innerhalb dieser Zeit gilt ein Service als online.
  • prune.after-seconds (Default 600) – länger stille Services werden aus der Topologie entfernt.

2. Services melden (Heartbeat)

Der Connector schickt im Takt (z. B. alle 5–10 s) die vollständige aktuelle Service-Liste:

POST /api/v1/modules/cloud/report
X-Cloud-Token: <report.token>
Content-Type: application/json

{
  "connector": "cloudnet-eu",
  "services": [
    { "name": "Lobby-1", "task": "Lobby", "state": "RUNNING",
      "host": "10.0.0.5", "port": 25565, "playersOnline": 12, "maxPlayers": 100 },
    { "name": "BedWars-3", "task": "BedWars", "state": "RUNNING",
      "host": "10.0.0.9", "port": 25571, "playersOnline": 8, "maxPlayers": 16 }
  ]
}

Antwort: { "applied": 2 }. Services werden per connector+name aktualisiert (Upsert); was nicht mehr gemeldet wird, läuft über die TTL aus und wird vom Prune-Job entfernt. Der Endpoint authentifiziert ausschließlich über X-Cloud-Token (constant-time geprüft) – kein Nexus-Login nötig.

CloudNet-Beispiel

Ein kleines CloudNet-Modul (oder ein externes Skript, das die CloudNet-REST/Node-API abfragt) sammelt ServiceInfoSnapshots, mappt task → task, name → name, onlinePlayers/maxPlayers und postet sie an den Endpoint oben. Da der Vertrag bewusst generisch ist, lässt sich genauso Pterodactyl, ein Docker-Swarm oder eine Eigenbau-Cloud anbinden.

3. Befehle entgegennehmen (Server erstellen & stoppen)

Die Antwort auf jeden POST /report enthält die für diesen Connector ausstehenden Befehle:

{
  "applied": 2,
  "commands": [
    { "id": "…", "action": "START", "task": "BedWars", "amount": 2 },
    { "id": "…", "action": "STOP", "serviceName": "Lobby-3", "task": "Lobby" }
  ]
}

Der Connector führt sie auf der Cloud aus (Service starten bzw. stoppen) und meldet die erledigten IDs beim nächsten Heartbeat zurück – derselbe /report-Call, kein Extra-Endpoint:

{ "connector": "cloudnet-eu", "services": [ … ], "ackedCommandIds": ["…", "…"] }

Ausgelöst werden die Befehle im ACP (beides erfordert cloud.manage):

  • Server → Server hinzufügen → „Neuen Server über die Cloud erstellen" – Connector, Task und Anzahl wählen → START.
  • Cloud → Service → „Stoppen" → STOP für genau diesen Service.

Der neu gestartete Service erscheint automatisch beim nächsten Heartbeat in der Topologie; gestoppte laufen über die TTL aus.

4. Im ACP ansehen

Unter Cloud erscheinen Kennzahlen (Connectoren, Services online, Spieler, Tasks), pro Task eine Auslastungs-Karte und eine Live-Tabelle aller Services (Auto-Refresh alle 10 s). Mit der Permission cloud.manage lässt sich ein hängengebliebener Geister-Service manuell entfernen; cloud.view genügt zum Ansehen.