Velocity erreicht Paper nicht: Docker-Verbindung prüfen

Zuerst die Art des Fehlers bestimmen

„Velocity erreicht das Backend nicht“ kann vier unterschiedliche Ursachen haben:

1. Der Backend-Container ist gestoppt oder startet ständig neu.
2. Der Proxy kann den Backend-Namen nicht auflösen oder dorthin routen.
3. Unter dem Zielport lauscht noch kein fertiger Paper-Server.
4. TCP funktioniert, aber die Spielerweiterleitung weist den Login ab.

Ein Forwarding-Secret repariert keine UnknownHostException. Ebenso sollte ein fehlendes Docker-Netzwerk niemals durch einen öffentlichen Backend-Port umgangen werden.

Schritt 1: Ersten aussagekräftigen Fehler sichern

Erfasse Zustand und begrenzte Logs, bevor du mehrfach neu startest:

docker compose ps -a
docker compose logs --tail=200 proxy lobby
docker inspect "$(docker compose ps -q lobby)" --format 'status={{.State.Status}} exit={{.State.ExitCode}} oom={{.State.OOMKilled}} health={{if .State.Health}}{{.State.Health.Status}}{{else}}none{{end}}'

Ersetze lobby, falls dein Service anders heißt. Wenn Paper beendet wird, löse zuerst diesen Fehler. Die Anleitung zu ständigen Container-Neustarts hilft bei EULA-, Java-, Rechte-, Speicher- und Konfigurationsproblemen.

Schritt 2: Adresse in velocity.toml prüfen

Bei diesem Compose-Modell:

services:
  proxy:
    networks: [minecraft]
  lobby:
    networks: [minecraft]
networks:
  minecraft: {}

verwendet Velocity:

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

Typische Fehlkonfigurationen:

• localhost:25565 zeigt in den Proxy-Container zurück.
• Eine feste Container-IP ändert sich bei Neuerstellung.
• Eine Portweiterleitung zum Host wie 25566 ist für Verbindungen innerhalb von Compose nicht nötig.
• Die öffentliche Domain verlässt Docker unnötig.

Der Servicename ist die stabile Referenz im Compose-Netzwerk. Stütze die Verbindung nicht auf container_name oder eine momentane IP.

Schritt 3: Netzwerkzugehörigkeit vergleichen

Prüfe Modell und laufende Container:

docker compose config
docker inspect "$(docker compose ps -q proxy)" --format '{{json .NetworkSettings.Networks}}'
docker inspect "$(docker compose ps -q lobby)" --format '{{json .NetworkSettings.Networks}}'

Beide Container benötigen mindestens ein gemeinsames Netzwerk. Zwei getrennte Compose-Projekte erhalten unterschiedliche implizite default-Netzwerke, auch wenn ihre YAML-Dateien ähnlich aussehen.

Für getrennte Projekte kannst du einmalig ein gemeinsames Netzwerk anlegen:

docker network create minecraft-proxy

In beiden Compose-Dateien wird es anschließend referenziert:

networks:
  minecraft:
    external: true
    name: minecraft-proxy

Hänge Proxy und Backends an minecraft und erstelle die Container neu. Das veraltete Feld links ersetzt keine korrekte gemeinsame Netzwerkzugehörigkeit.

Schritt 4: Aus dem Proxy-Netzwerk testen

Führe den entscheidenden Test direkt im Velocity-Container aus. itzg/mc-proxy enthält dafür das Werkzeug mc-monitor:

docker compose exec proxy mc-monitor status --host lobby --port 25565

Bewerte das Ergebnis zusammen mit dem Paper-Log:

• Name nicht auflösbar: Servicename oder gemeinsames Netzwerk falsch.
• Connection refused: Name stimmt, aber Paper lauscht nicht auf 25565.
• Timeout: Route oder Firewall verwirft Pakete.
• Status erfolgreich: Netzwerk und Minecraft-Statusabfrage funktionieren; prüfe Forwarding und Loginregeln.

Ein Test nur vom Docker-Host reicht nicht. Vom Proxy-Container kann die Verbindung anders verlaufen.

Schritt 5: Startbereitschaft von Paper bestätigen

Betrachte den aktuellen Startversuch:

docker compose logs --since=10m lobby

Suche in den Logs nach der Meldung, dass Paper vollständig gestartet ist, und prüfe Adresse sowie Port. Geeignete Standardwerte für Container in server.properties sind:

server-ip=
server-port=25565

Ein leeres server-ip lässt Paper auf den Container-Interfaces lauschen. Eine Host-IP, die im Container nicht existiert, kann den Start verhindern.

Schritt 6: Routing von Forwarding trennen

Wenn mc-monitor Paper erreicht, aber Spieler weiterhin gekickt werden, vergleiche:

• player-info-forwarding-mode = "modern" in velocity.toml
• proxies.velocity.enabled: true in paper-global.yml
• identische Forwarding-Secrets
• übereinstimmenden Proxy-Online-Mode
• deaktiviertes Bungee-Legacy-Forwarding

Die exakte Konfiguration steht im Modern-Forwarding-Guide. Ändere jeweils nur eine Schicht und wiederhole denselben Login-Test.

Symptome zuordnen

Reparatur verifizieren

docker compose ps
docker compose exec proxy mc-monitor status --host lobby --port 25565
docker compose port lobby 25565

Der Statuscheck muss erfolgreich sein; der letzte Befehl darf keinen Host-Port zeigen. Verbinde dich anschließend über Velocity und bestätige die korrekte Spieleridentität im Backend.

Nächste Schritte

• Kehre zum vollständigen Velocity-Compose-Aufbau zurück.
• Sichere den funktionierenden Pfad mit Modern Forwarding.
• Bei instabilem Paper hilft die Anleitung zu ständigen Container-Neustarts.