Host-Agent – Referenz

Der Host-Agent (nexus-agent) ist ein eigenständiger Daemon, der auf einem Hostsystem (Bare-Metal, VM oder Container) läuft und dem Nexus Core die volle Kontrolle über die dort liegenden Minecraft-Server gibt: anlegen, starten, stoppen, Konsole streamen, Dateien verwalten, Backups, Welten. Er ist das Gegenstück zur Minecraft-Bridge — die Bridge verbindet einen laufenden Spielserver mit dem Panel, der Host-Agent verwaltet die Maschine, auf der Spielserver entstehen und leben.

Praktische Einrichtung: Host-Agent (Node) verbinden.

Status: Phase 1 (implementiert). Ein Node meldet Host-Metriken, verwaltet Server-Prozesse, streamt Konsolen und führt Datei-/Backup-/Welt-Operationen jailed im Server-Verzeichnis aus.

1. Architektur

┌────────────────────────────┐         WebSocket  /agent/ws        ┌─────────────────────────┐
│   Nexus Core               │ ◄──────────────────────────────────►│   Host-Agent (Node)     │
│                            │                                      │   nexus-agent JAR       │
│  AgentWsHandler            │   Agent→Core: handshake,             │                         │
│  AgentManager  (Sessions,  │     node.heartbeat, server.state,    │  NexusAgentClient       │
│   pending Request-Futures) │     console.line, *.result           │  HostMetrics            │
│  AgentRequests (ask/await) │                                      │  ProcessRunner          │
│  NodeController (REST)      │   Core→Agent: server.start/stop/…    │  FileManager            │
│                            │     console.write, file.*, backup.*, │  BackupManager          │
│  Node, AgentToken (JPA)    │     world.*                          │  WorldManager, Installer│
└────────────────────────────┘                                      └─────────────────────────┘
        ▲ REST /api/v1/nodes                                            spawnt & überwacht
        │ (Perm core.node.manage)                                       Minecraft-Prozesse
   ACP „Nodes"                                                          (paper/velocity JARs)

• WebSocket-Route: /agent/ws (getrennt von der Bridge unter /bridge/ws und dem Panel-WS unter /api/v1/ws).
• Verbindungsrichtung: Der Agent verbindet sich ausgehend zum Core (firewall-freundlich; der Host braucht keine offenen Ports).
• Korrelation: Datei-/Backup-/Welt-Befehle laufen als Request/Response über eine requestId; der Core wartet per CompletableFuture (Timeout 30 s). Heartbeats, Server-State und Konsolenzeilen sind unidirektional.

Komponenten Core-seitig

Komponenten Agent-seitig

2. Authentifizierung

Identisch zum Bridge-Muster: ein Einmal-Token wird beim ersten Handshake gegen einen dauerhaften Agent-Key getauscht.

Ablauf:

1. Admin erzeugt im ACP (Perm core.node.manage) einen Token → POST /api/v1/nodes/tokens. Der Klartext-Token wird genau einmal angezeigt.
2. Der Agent sendet handshake mit dem Token.
3. Der Core hasht (SHA-256) und prüft:
   • Hash == bestehender agentKeyHash → Re-Auth (kein neuer Key).
   • Hash == unbenutzter Token → Token als used markieren, neuen nxa_-Key erzeugen und in handshake.ok zurückgeben.
   • sonst → handshake.error mit Code NX-3101 (Token ungültig/verbraucht).
4. Der Agent persistiert den Key (agent.properties, POSIX 600) und nutzt ihn ab dem nächsten Start automatisch — der Token entfällt.

Sicherheit: Token und Key sind Credentials. In Produktion wss:// verwenden, sonst wandern sie im Klartext über die Leitung. Die Config-Datei wird auf Eigentümer-Lese-/Schreibrecht (600) beschränkt.

3. WebSocket-Protokoll

Frame-Format (JSON, in beide Richtungen):

{ "type": "message.type", "id": "<uuid des Senders>", "data": { /* … */ } }

3.1 Agent → Core

3.2 Core → Agent

3.3 Beispiel: kompletter Handshake-Verkehr

Agent → Core   {"type":"handshake","id":"4f…","data":{
                  "token":"nat_FxO2k_V9…","nodeName":"prod-1","version":"0.1.0"}}
Core  → Agent   {"type":"handshake.ok","id":"a1…","data":{
                  "nodeId":"7c9e…","coreVersion":"0.1.0","agentKey":"nxa_YWJj…"}}
Agent → Core   {"type":"node.heartbeat","id":"…","data":{
                  "cpuLoad":0.12,"ramUsedMb":4096,"ramTotalMb":16384,
                  "diskUsedGb":48,"diskTotalGb":200}}     // alle 10 s

3.4 Beispiel: Request/Response (Datei lesen)

Core  → Agent   {"type":"file.read","id":"…","data":{
                  "requestId":"req-91","root":"/srv/lobby","path":"server.properties"}}
Agent → Core   {"type":"file.result","id":"…","data":{
                  "requestId":"req-91","ok":true,"content":"server-port=25565\n…"}}

Schlägt die Operation fehl, antwortet der Agent {"requestId":"req-91","ok":false, "error":"…"}; AgentRequests.ask() übersetzt das in einen HTTP-Validierungsfehler.

4. REST-API (/api/v1/nodes)

Alle Endpunkte erfordern die Permission core.node.manage und werden auditiert.

Beispiel: Token erzeugen

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…", "name": "prod-1" }   (nur jetzt sichtbar!)

5. Konfiguration

agent.properties

Umgebungsvariablen (headless)

URL-Normalisierung (AgentSetup.deriveWsUrl): https://panel.example.com → wss://panel.example.com/agent/ws; ein Reverse-Proxy-Subpfad https://host/nexus → wss://host/nexus/agent/ws; vollständige ws(s)://…/agent/ws bleiben unverändert.

6. Betreiben

Die Agent-JAR (jubyte-nexus-agent-*.jar) gibt es im JuByte-Store-Konto unter Downloads.

# Interaktiver Erst-Setup (fragt ACP-Adresse, Node-Name, Token ab)
java -jar jubyte-nexus-agent-0.1.0.jar

# Headless (Env-Variablen vollständig)
export NEXUS_CORE_URL=https://panel.example.com
export NEXUS_AGENT_TOKEN=nat_…
export NEXUS_NODE_NAME=prod-1
java -jar jubyte-nexus-agent-0.1.0.jar

# Neu konfigurieren (gespeicherte Config verwerfen)
java -jar jubyte-nexus-agent-0.1.0.jar --reconfigure

# Eigener Config-Pfad
NEXUS_AGENT_CONFIG=/etc/jubyte/agent.properties java -jar jubyte-nexus-agent-0.1.0.jar

Beispiel: systemd-Service

# /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   # Logger „nexus-agent" → stderr

7. Entwickler-Beispiele

7.1 Core-seitig: einen Server starten

AgentManager.sendCommand() verschickt einen fire-and-forget-Befehl; der Agent meldet den Fortschritt asynchron über server.state.

@Service
public class ServerControlService {
    private final AgentManager agents;

    public void start(GameServer s) {
        boolean queued = agents.sendCommand(s.getNodeId(), "server.start", Map.of(
            "serverId", s.getId().toString(),
            "path",     s.getInstallPath(),
            "command",  s.getLaunchCommand()));
        if (!queued) throw NexusException.validation("Host-Agent offline");
        // Zustandswechsel kommen als server.state → game_servers.power_state
    }
}

7.2 Core-seitig: Datei lesen (Request/Response)

AgentRequests.ask() blockiert bis zur Antwort (oder Timeout) und wirft bei ok=false. Ideal hinter einem HTTP-Controller.

JsonNode res = agentRequests.ask(nodeId, "file.read", Map.of(
        "requestId", UUID.randomUUID().toString(),
        "root",      server.getInstallPath(),
        "path",      "server.properties"),
    30 /* Sekunden */);
String content = res.path("content").asText();

7.3 Eigener Agent-Client (anderes Sprach-Ökosystem)

Der Agent ist nur ein WebSocket-Client, der dem obigen Protokoll folgt — du kannst ihn in jeder Sprache nachbauen. Minimaler Node.js-Heartbeat-Loop:

import WebSocket from 'ws';
const ws = new WebSocket('wss://panel.example.com/agent/ws');
const send = (type, data) => ws.send(JSON.stringify({ type, id: crypto.randomUUID(), data }));

ws.on('open', () => send('handshake', { token: process.env.NAT, nodeName: 'edge-1', version: '0.1.0' }));
ws.on('message', (buf) => {
  const msg = JSON.parse(buf);
  if (msg.type === 'handshake.ok') {
    if (msg.data.agentKey) saveKey(msg.data.agentKey);        // Key persistieren!
    setInterval(() => send('node.heartbeat', {
      cpuLoad: os.loadavg()[0] / os.cpus().length,
      ramUsedMb: Math.round((os.totalmem() - os.freemem()) / 1e6),
      ramTotalMb: Math.round(os.totalmem() / 1e6),
      diskUsedGb: 0, diskTotalGb: 0,
    }), 10_000);
  }
  if (msg.type === 'server.start') { /* eigenen Prozess spawnen, server.state melden */ }
});

8. Resilienz & Lifecycle

Sicherheits-Guards der Datei-Operationen

• Path-Jailing: Jeder Pfad wird gegen den Server-Root normalisiert; !path.startsWith(base) wirft IllegalArgumentException. Kein ..-Ausbruch.
• Zip-Slip-Schutz: unarchive/restore überspringen Einträge außerhalb des Roots.
• Transfer-Limit: Up-/Download max 16 MB (MAX_TRANSFER).
• Root-Schutz: Der Server-Root selbst lässt sich nicht löschen oder archivieren; purge() verweigert leere Pfade, ., Dateisystem-Root und das Agent-CWD.

9. Datenbank

V39__nodes.sql legt nodes und agent_tokens an; V40__server_node_placement.sql erweitert game_servers um node_id, install_path, launch_command, power_state.

10. Fehlercodes

Siehe auch

• Host-Agent (Node) verbinden – Schritt-für-Schritt
• Bridge-Protokoll – das Schwester-Protokoll für laufende Spielserver
• HWID-Agent – client-seitiger Hardware-Fingerprint