Velocity und Paper mit Docker Compose einrichten

Aufbau des Netzwerks

Velocity ist der einzige öffentliche Zugang zu deinem Minecraft-Netzwerk. Der Proxy meldet Java-Spieler an und leitet sie an einen oder mehrere Server weiter. Für den Einstieg brauchst du:

• einem itzg/mc-proxy-Container mit Velocity
• einem itzg/minecraft-server-Container mit Paper
• einem gemeinsamen Docker-Netzwerk
• ausschließlich Port 25565 am Proxy
• dauerhaften Ordnern für Proxy- und Serverdaten

Wenn du nur einen Server und keine Proxy-Plugins brauchst, bleibt der Java-Server-Konfigurator die einfachere Lösung. Ein Proxy schafft eine zusätzliche Sicherheitsgrenze, die vollständig konfiguriert werden muss.

Schritt 1: Compose-Grundlage erzeugen

Öffne den Minecraft-Proxy-Konfigurator, wähle VELOCITY und behalte 25565:25577 als öffentliche Portweiterleitung. Ergänze die erzeugte Datei um einen Paper-Server:

services:
  proxy:
    image: itzg/mc-proxy:latest
    restart: unless-stopped
    ports:
      - "25565:25577"
    environment:
      TYPE: VELOCITY
      MEMORY: 512m
    volumes:
      - ./proxy:/server
    networks:
      - minecraft
    stdin_open: true
    tty: true

  lobby:
    image: itzg/minecraft-server:java25
    restart: unless-stopped
    environment:
      EULA: "TRUE"
      TYPE: PAPER
      VERSION: "26.1.2"
      ONLINE_MODE: "FALSE"
    volumes:
      - ./lobby:/data
    networks:
      - minecraft

networks:
  minecraft: {}

lobby besitzt absichtlich keinen ports-Eintrag. Beide Services befinden sich im Netzwerk minecraft, deshalb erreicht der Proxy Paper unter lobby:25565.

Pinne eine getestete Minecraft-Version, statt die Beispielversion dauerhaft zu übernehmen. Beim Wechsel hilft der Guide zur richtigen Java-Version.

Schritt 2: Konfigurationsdateien erzeugen lassen

Lege die Ordner an, prüfe das aufgelöste Compose-Modell und starte beide Services:

mkdir -p proxy lobby
docker compose config
docker compose up -d
docker compose logs -f proxy lobby

Warte, bis Paper vollständig gestartet ist und die Datei proxy/velocity.toml angelegt wurde. Stoppe danach beide Container, bevor du die Weiterleitung einrichtest:

docker compose down

Deaktiviere die Online-Anmeldung am Paper-Server erst, wenn sein Port nicht mehr öffentlich erreichbar ist. Schließe den nächsten Schritt ab, bevor Spieler den Proxy nutzen.

Schritt 3: Paper als Backend registrieren

Öffne proxy/velocity.toml und trage den öffentlichen Port sowie den Paper-Server ein:

bind = "0.0.0.0:25577"
online-mode = true
player-info-forwarding-mode = "modern"
forwarding-secret-file = "forwarding.secret"

[servers]
lobby = "lobby:25565"
try = ["lobby"]

localhost würde im Proxy-Container auf den Proxy selbst zeigen. Der Compose-Servicename lobby bleibt dagegen auch nach einer neuen Container-IP stabil.

Velocity erzeugt proxy/forwarding.secret. Paper benötigt exakt denselben Wert. Schließe deshalb vor dem öffentlichen Start den Guide zu Velocity Modern Forwarding ab.

Schritt 4: Den gesamten Pfad prüfen

Starte den Verbund erneut:

docker compose up -d
docker compose ps
docker compose logs --tail=100 proxy lobby

Prüfe anschließend:

1. Beide Services bleiben Up, der Proxy wird healthy.
2. Velocity meldet keinen Forwarding- oder Backend-Fehler.
3. docker compose port proxy 25577 zeigt die öffentliche Portweiterleitung.
4. docker compose port lobby 25565 zeigt keinen Host-Port.
5. Ein Java-Client erreicht über Host-Port 25565 die Lobby.

Der Paper-Log muss die weitergeleitete Spieleridentität zeigen, nicht einen direkten unauthentifizierten Login.

Später ein weiteres Backend ergänzen

Füge beispielsweise einen Service survival zum selben Netzwerk hinzu und registriere ihn in Velocity:

[servers]
lobby = "lobby:25565"
survival = "survival:25565"
try = ["lobby"]

Jedes Backend erhält ein eigenes Datenverzeichnis. Teile niemals denselben Weltordner zwischen zwei laufenden Servern und wende dieselben Forwarding- und Isolationsregeln auf jeden Service an.

Fehlerbehebung

Nächste Schritte

• Richte Velocity Modern Forwarding für Paper ein.
• Nutze bei Verbindungsfehlern die Anleitung zur Backend-Verbindung.
• Ergänze Bedrock-Crossplay über Geyser und Floodgate auf Velocity.
• Sichere jedes Backend mit automatischen Backups.