Host-Agent (Node) verbinden

So machst du eine Maschine zu einem Node, auf dem der Nexus Core Minecraft-Server anlegen, starten und verwalten kann. Hintergrund & vollständiges Protokoll: Host-Agent-Referenz.

Abgrenzung: Der Host-Agent verwaltet die Maschine (Prozesse, Dateien, Backups). Die Minecraft-Bridge verbindet einen laufenden Spielserver mit dem Panel. Ein typischer Node läuft beides: der Agent legt den Server an, das Bridge-Plugin verbindet ihn anschließend.

Voraussetzungen

• Ein laufender Nexus Core, erreichbar per https:///wss://.
• Java 21+ auf dem Host.
• Berechtigung core.node.manage im ACP.

1. Agent-JAR bereitstellen

Die Agent-JAR (jubyte-nexus-agent-*.jar) bekommst du im JuByte-Store-Konto unter Downloads. Lege sie auf den Host, z. B. nach /opt/nexus-agent/.

2. Pairing-Token erzeugen

ACP → Nodes → Node hinzufügen → Token erzeugen (oder per API):

curl -X POST https://panel.example.com/api/v1/nodes/tokens \
  -H "Authorization: Bearer <admin-jwt>" \
  -H "Content-Type: application/json" \
  -d '{"name":"prod-1"}'
# → { "token": "nat_FxO2k_V9…" }

Der Klartext-Token wird genau einmal angezeigt. Er legitimiert genau einen Handshake; danach erhält der Node automatisch einen dauerhaften Agent-Key.

3. Agent einrichten

Variante A – interaktiv (erstes Mal)

java -jar /opt/nexus-agent/jubyte-nexus-agent-0.1.0.jar

Der Assistent fragt:

1. ACP-Adresse – z. B. https://panel.example.com (wird zu wss://panel.example.com/agent/ws normalisiert; Reverse-Proxy-Subpfade wie https://host/nexus funktionieren).
2. Node-Name – eindeutig, z. B. prod-1.
3. Pairing-Token – der nat_…-Wert aus Schritt 2.

Nach erfolgreichem Pairing speichert der Agent agent.properties (POSIX 600) inkl. des dauerhaften Keys. Künftige Starts verbinden sich ohne erneute Eingabe.

Variante B – headless (Env-Variablen)

export NEXUS_CORE_URL=https://panel.example.com
export NEXUS_AGENT_TOKEN=nat_FxO2k_V9…
export NEXUS_NODE_NAME=prod-1
java -jar /opt/nexus-agent/jubyte-nexus-agent-0.1.0.jar

Die Werte werden beim ersten Start in die Config-Datei übernommen.

4. Als Dienst betreiben (empfohlen)

# /etc/systemd/system/nexus-agent.service
[Unit]
Description=JuByteNexus Host-Agent
After=network-online.target

[Service]
Type=simple
User=nexus
WorkingDirectory=/opt/nexus-agent
Environment=NEXUS_AGENT_CONFIG=/opt/nexus-agent/agent.properties
ExecStart=/usr/bin/java -jar /opt/nexus-agent/jubyte-nexus-agent-0.1.0.jar
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl enable --now nexus-agent
sudo journalctl -u nexus-agent -f

5. Verifizieren

• Im ACP erscheint der Node online mit CPU/RAM/Disk-Metriken (Heartbeat alle 10 s).
• GET /api/v1/nodes listet ihn mit Live-Status und Version.
• Lege testweise einen Server auf dem Node an → der Agent provisioniert ihn (EULA, server.properties, Paper-JAR) und meldet den Zustand über server.state.

6. Server auf dem Node anlegen (Ablauf)

1. Im ACP einen Server dem Node zuweisen → Core sendet server.install (Software, Version, Port, Bridge-Token).
2. Der Agent lädt das Paper-JAR (PaperMC-API), schreibt eula.txt/server.properties und – falls verfügbar – das Bridge-Plugin nach plugins/.
3. server.start startet den Prozess; die Konsole streamt live ins ACP (console.line).
4. Das vorkonfigurierte Bridge-Plugin verbindet den Spielserver zusätzlich übers Bridge-Protokoll.

Fehlerbehebung

Sicherheit: In Produktion wss:// (TLS) verwenden — Token und Agent-Key werden sonst im Klartext übertragen. Die Config-Datei wird auf 600 beschränkt.