FR

Serveurs de jeux

Comment relier plusieurs serveurs Minecraft avec Velocity

Reliez plusieurs serveurs Paper derrière le proxy Velocity sur un VPS ou un serveur dédié Linux : transfert sécurisé des joueurs, ports internes fermés et retour arrière.

10 min de lecture, mis à jour le 18 novembre 2026

Sur cette page

Vos valeurs

Renseignez-les une fois, les commandes du guide se mettent à jour.

Velocity est un proxy Minecraft : les joueurs se connectent à une seule adresse, puis passent d'un serveur à l'autre sans se déconnecter. Ce guide place votre serveur existant derrière Velocity et lui ajoute un serveur lobby, sur la même machine.

Il prolonge les guides Créer un serveur Minecraft et Installer et mettre à jour des plugins sur Paper. Il réutilise l'utilisateur minecraft, le dossier /opt/minecraft/server, le service minecraft.service et la commande mc-console.

À la fin de ce guide, vous aurez :

  • Velocity à l'écoute sur le port public 25565, donc la même adresse pour vos joueurs
  • deux serveurs Paper joignables uniquement depuis la machine
  • un transfert sécurisé de l'identité des joueurs, avec leurs UUID et leurs inventaires conservés

Prérequis

  • Un serveur sous Paper, installé avec les deux guides cités ci-dessus, avec Java 25, curl et jq
  • Un accès SSH avec un utilisateur disposant de sudo
  • Environ 2 Go de mémoire libre en plus de votre serveur actuel : 1 Go pour Velocity et jusqu'à 1 Go pour le lobby
  • Assez d'espace disque pour une copie complète du dossier du serveur

Velocity, BungeeCord ou Waterfall ?

Velocity BungeeCord Waterfall
Projet PaperMC, développement actif SpigotMC, le proxy historique PaperMC, fin de vie
Transfert sécurisé de l'identité Oui, signé par un secret Non Non
Plugins API Velocity API BungeeCord API BungeeCord

PaperMC recommande Velocity plutôt que BungeeCord et Waterfall, et ne maintient plus Waterfall.

BungeeCord reste un choix défendable dans un seul cas : un plugin de proxy indispensable qui n'existe pas pour Velocity, car Velocity ne charge pas les plugins BungeeCord. Son transfert d'identité n'étant pas signé, la fermeture des ports internes décrite plus bas y est encore plus importante.

Comprendre l'installation cible

Service Nom dans Velocity Dossier Adresse d'écoute Joignable depuis
velocity.service /opt/minecraft/velocity 0.0.0.0:25565 Internet
minecraft.service survie /opt/minecraft/server 127.0.0.1:25566 La machine seulement
minecraft-lobby.service lobby /opt/minecraft/lobby 127.0.0.1:25567 La machine seulement

Sauvegarder le serveur

Arrêtez le serveur, puis créez une archive complète. Il reste arrêté jusqu'à la fin de la configuration, car Velocity va reprendre le port 25565 :

Terminal
sudo systemctl stop minecraft.service
sudo mkdir -p /opt/minecraft/backups
sudo tar -czf /opt/minecraft/backups/avant-velocity-$(date +%F-%H%M).tar.gz -C /opt/minecraft server
sudo ls -lh /opt/minecraft/backups

Installer Velocity

Créez un script qui télécharge le dernier build stable et contrôle son empreinte. Il resservira pour les mises à jour :

Terminal
sudo nano /opt/minecraft/velocity-update.sh
Terminal
#!/bin/bash
# Télécharge le dernier build stable de Velocity et remplace velocity.jar
set -euo pipefail

VERSION="${1:?Indiquez la version de Velocity, par exemple 4.3.1}"
UA="mon-serveur-minecraft/1.0 (https://votre-domaine.com)"
API="https://fill.papermc.io/v3/projects/velocity/versions/$VERSION/builds"

mkdir -p /opt/minecraft/velocity
cd /opt/minecraft/velocity

BUILD=$(curl -fsSL -H "User-Agent: $UA" "$API" | jq -c 'map(select(.channel == "STABLE")) | .[0]')
if [ "$BUILD" = "null" ]; then
    echo "Aucun build stable trouvé pour Velocity $VERSION." >&2
    exit 1
fi

URL=$(echo "$BUILD" | jq -r '.downloads."server:default".url')
SHA256=$(echo "$BUILD" | jq -r '.downloads."server:default".checksums.sha256')

curl -fL -H "User-Agent: $UA" -o velocity.jar.new "$URL"
echo "$SHA256  velocity.jar.new" | sha256sum -c -

if [ -f velocity.jar ]; then
    mv velocity.jar velocity.jar.old
fi
mv velocity.jar.new velocity.jar
echo "Velocity $VERSION, build $(echo "$BUILD" | jq -r '.id'), est en place."

Dans la ligne UA, remplacez votre-domaine.com par l'adresse de votre site ou un moyen de vous contacter. Lancez ensuite le script :

Terminal
sudo chmod 755 /opt/minecraft/velocity-update.sh
sudo -u minecraft /opt/minecraft/velocity-update.sh 4.3.1

La ligne velocity.jar.new: OK confirme que le fichier est intact.

Créez le service :

Terminal
sudo nano /etc/systemd/system/velocity.service
Configuration
[Unit]
Description=Proxy Minecraft Velocity
After=network.target

[Service]
User=minecraft
WorkingDirectory=/opt/minecraft/velocity
ExecStart=/usr/bin/java -Xms1G -Xmx1G -XX:+UseG1GC -XX:G1HeapRegionSize=4M -XX:+UnlockExperimentalVMOptions -XX:+ParallelRefProcEnabled -XX:+AlwaysPreTouch -XX:MaxInlineLevel=15 -jar /opt/minecraft/velocity/velocity.jar
SuccessExitStatus=130 143
Restart=on-failure
RestartSec=20
StandardInput=null

[Install]
WantedBy=multi-user.target

Ces options Java sont celles que recommande la documentation de Velocity. Démarrez le proxy une première fois pour générer sa configuration :

Terminal
sudo systemctl daemon-reload
sudo systemctl start velocity.service
sudo journalctl -u velocity.service -n 30 --no-pager

Attendez la ligne Done. L'avertissement Player info forwarding is disabled! est normal à ce stade. Arrêtez ensuite le proxy et protégez son dossier, qui contient le secret :

Terminal
sudo systemctl stop velocity.service
sudo chmod 700 /opt/minecraft/velocity
sudo ls -l /opt/minecraft/velocity

Vous devez voir velocity.toml et forwarding.secret.

Configurer Velocity

Terminal
sudo -u minecraft nano /opt/minecraft/velocity/velocity.toml

Vérifiez ou modifiez ces lignes, au début du fichier :

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

Remplacez ensuite tout le contenu des sections [servers] et [forced-hosts] :

toml
[servers]
lobby = "127.0.0.1:25567"
survie = "127.0.0.1:25566"

try = [
    "lobby",
    "survie"
]

[forced-hosts]

try donne l'ordre des serveurs tentés à la connexion, ou quand un joueur est expulsé d'un serveur. La section [forced-hosts] reste vide : les exemples livrés visent des serveurs factions et minigames qui n'existent pas chez vous, et Velocity refuserait de démarrer.

Raccorder le serveur existant

Faites écouter le serveur sur la boucle locale, sur son nouveau port, et confiez l'authentification au proxy :

Terminal
sudo -u minecraft sed -i \
    -e 's/^server-ip=.*/server-ip=127.0.0.1/' \
    -e 's/^server-port=.*/server-port=25566/' \
    -e 's/^online-mode=.*/online-mode=false/' \
    /opt/minecraft/server/server.properties
sudo grep -E '^(server-ip|server-port|online-mode)=' /opt/minecraft/server/server.properties

Activez ensuite le transfert moderne dans la configuration de Paper, avec le secret généré par Velocity :

Terminal
SECRET=$(sudo cat /opt/minecraft/velocity/forwarding.secret)
sudo -u minecraft sed -i "/^  velocity:/,/^ \{0,2\}[a-z]/{s/^    enabled: .*/    enabled: true/;s/^    online-mode: .*/    online-mode: true/;s/^    secret: .*/    secret: '$SECRET'/;}" /opt/minecraft/server/config/paper-global.yml
unset SECRET
sudo chmod 700 /opt/minecraft/server/config

Contrôlez le résultat sans afficher le secret :

Terminal
sudo grep -A3 '^  velocity:' /opt/minecraft/server/config/paper-global.yml | sed 's/secret: .*/secret: (masqué)/'
sudo grep -qF "$(sudo cat /opt/minecraft/velocity/forwarding.secret)" /opt/minecraft/server/config/paper-global.yml && echo "Secret identique" || echo "Secret différent"
sudo grep 'bungeecord:' /opt/minecraft/server/spigot.yml

Vous devez obtenir enabled: true, online-mode: true, Secret identique et bungeecord: false. Ce dernier réglage doit rester à false avec le transfert moderne.

Créer le serveur lobby

Le lobby reprend le même server.jar et la même configuration globale de Paper :

Terminal
sudo -u minecraft mkdir -p /opt/minecraft/lobby/config
sudo chmod 700 /opt/minecraft/lobby/config
sudo -u minecraft cp /opt/minecraft/server/server.jar /opt/minecraft/lobby/
sudo -u minecraft cp /opt/minecraft/server/config/paper-global.yml /opt/minecraft/lobby/config/
echo "eula=true" | sudo -u minecraft tee /opt/minecraft/lobby/eula.txt

Créez ses réglages, avec un monde plat et sans monstres :

Terminal
sudo -u minecraft tee /opt/minecraft/lobby/server.properties > /dev/null <<'EOF'
server-ip=127.0.0.1
server-port=25567
online-mode=false
motd=Lobby
max-players=50
level-type=minecraft\:flat
generate-structures=false
gamemode=adventure
force-gamemode=true
difficulty=peaceful
allow-nether=false
view-distance=6
simulation-distance=4
EOF

Créez son service :

Terminal
sudo nano /etc/systemd/system/minecraft-lobby.service
Configuration
[Unit]
Description=Minecraft Lobby Server
After=network.target

[Service]
User=minecraft
WorkingDirectory=/opt/minecraft/lobby
ExecStart=/usr/bin/java -Xms512M -Xmx1G -jar /opt/minecraft/lobby/server.jar nogui
ExecStop=/bin/kill -SIGINT $MAINPID
SuccessExitStatus=130 143
TimeoutStopSec=180
Restart=on-failure
RestartSec=20
StandardInput=null

[Install]
WantedBy=multi-user.target

Tout démarrer

Démarrez les deux serveurs, puis suivez le premier démarrage du lobby jusqu'à la ligne Done :

Terminal
sudo systemctl daemon-reload
sudo systemctl start minecraft.service
sudo systemctl enable --now minecraft-lobby.service
sudo journalctl -u minecraft-lobby.service -f

Quittez le suivi avec Ctrl+C, puis démarrez le proxy :

Terminal
sudo systemctl enable --now velocity.service
sudo journalctl -u velocity.service -n 30 --no-pager

Vérifier que les ports internes sont fermés

Terminal
sudo ss -ltnp | grep -E ':(25565|25566|25567)\b'

Le port 25565 doit écouter sur toutes les adresses. Les ports 25566 et 25567 doivent afficher 127.0.0.1 ou [::ffff:127.0.0.1], jamais 0.0.0.0, * ou [::].

Le pare-feu ne change pas : seul le port 25565 reste ouvert. Avec UFW, cette commande ne doit rien afficher :

Terminal
sudo ufw status | grep -E '2556[67]'

Depuis un autre ordinateur, testez ensuite les ports. Le premier doit répondre, le second doit échouer :

Terminal
nc -zv -w 5 IP_SERVEUR 25565
nc -zv -w 5 IP_SERVEUR 25566

Si un serveur est sur une autre machine

La boucle locale ne fonctionne que sur une seule machine. Sur une seconde machine, faites écouter le serveur sur une adresse privée, idéalement celle d'un tunnel WireGuard, indiquez cette adresse dans velocity.toml, puis n'autorisez que le proxy. Sur cette seconde machine, avec UFW :

Terminal
sudo ufw allow from IP_DU_PROXY to any port 25566 proto tcp

Ou avec iptables :

Terminal
sudo iptables -A INPUT -p tcp -s IP_DU_PROXY --dport 25566 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 25566 -j DROP

Vérifier le résultat

Contrôlez d'abord les trois services :

Terminal
systemctl is-active velocity.service minecraft.service minecraft-lobby.service

Connectez-vous ensuite avec votre client Minecraft, à la même adresse qu'avant. Vous devez arriver dans le lobby. Tapez alors :

Texte
/server
/server survie

La première commande liste les serveurs, la seconde vous transfère sans déconnexion. Vos constructions et votre inventaire doivent être là. Contrôlez enfin ce que le serveur a reçu :

Terminal
sudo journalctl -u minecraft.service --since "10 minutes ago" --no-pager | grep -E 'UUID of player|logged in with entity id'

Vous devez voir votre adresse IP publique, et non 127.0.0.1. Le troisième bloc de l'UUID doit commencer par 4, signe d'un compte authentifié.

Plugins et proxy

Les plugins Paper restent dans le dossier plugins de chaque serveur. Velocity possède ses propres plugins, à placer dans /opt/minecraft/velocity/plugins, puis à charger en redémarrant le proxy.

Si vous utilisez Geyser et Floodgate, leur installation change derrière un proxy : suivez la documentation de Floodgate pour Velocity.

Sauvegarder le proxy et le lobby

Le script backup.sh du guide de base ne couvre pas ces dossiers. Protégez d'abord le dossier des archives, car elles contiendront le secret :

Terminal
sudo chmod 700 /opt/minecraft/backups

Ajoutez ensuite cette ligne à /opt/minecraft/backup.sh, après la ligne tar existante. Le préfixe world_ permet au nettoyage automatique du script de la prendre en compte :

Terminal
tar -czf $BACKUP_DIR/world_proxy_$DATE.tar.gz -C /opt/minecraft velocity lobby

Mettre à jour

Quand une nouvelle version de Minecraft sort, mettez à jour Velocity avant les serveurs, pour qu'il accepte les nouveaux clients. Les joueurs sont déconnectés pendant l'opération :

Terminal
sudo systemctl stop velocity.service
sudo tar -czf /opt/minecraft/backups/velocity-$(date +%F-%H%M).tar.gz -C /opt/minecraft velocity
sudo -u minecraft /opt/minecraft/velocity-update.sh 4.3.1
sudo systemctl start velocity.service

Mettez ensuite à jour le serveur survie comme indiqué dans le guide Paper, puis copiez son fichier vers le lobby :

Terminal
sudo systemctl stop minecraft-lobby.service
sudo tar -czf /opt/minecraft/backups/lobby-$(date +%F-%H%M).tar.gz -C /opt/minecraft lobby
sudo -u minecraft cp /opt/minecraft/server/server.jar /opt/minecraft/lobby/server.jar
sudo systemctl start minecraft-lobby.service

Revenir en arrière

Pour retrouver un serveur seul sur le port 25565, sans perdre ce qui a été joué depuis :

Terminal
sudo systemctl disable --now velocity.service minecraft-lobby.service
sudo systemctl stop minecraft.service
sudo -u minecraft sed -i \
    -e 's/^server-ip=.*/server-ip=/' \
    -e 's/^server-port=.*/server-port=25565/' \
    -e 's/^online-mode=.*/online-mode=true/' \
    /opt/minecraft/server/server.properties
sudo -u minecraft sed -i "/^  velocity:/,/^ \{0,2\}[a-z]/{s/^    enabled: .*/    enabled: false/;s/^    secret: .*/    secret: ''/;}" /opt/minecraft/server/config/paper-global.yml
sudo systemctl start minecraft.service

Les dossiers velocity et lobby restent en place. En cas de problème plus grave, restaurez l'archive avant-velocity-… comme décrit dans la section Revenir à la sauvegarde du guide Paper.

En cas de problème

Commencez par les journaux du proxy et du serveur concerné :

Terminal
sudo journalctl -u velocity.service -n 100 --no-pager
sudo journalctl -u minecraft.service -n 100 --no-pager
sudo journalctl -u minecraft-lobby.service -n 100 --no-pager

« Unable to connect you to lobby. Please try again later. »

Velocity n'arrive pas à joindre ce serveur. Vérifiez qu'il est démarré et qu'il a fini de charger, puis que le port de velocity.toml correspond à server-port. La commande ss ci-dessus montre les ports réellement ouverts.

« There are no available servers to connect you to. »

Aucun serveur de la liste try n'a accepté le joueur. Contrôlez cette liste et démarrez au moins l'un de ces serveurs.

« Your server did not send a forwarding request to the proxy »

Le transfert moderne n'est pas actif sur le serveur Paper. Vérifiez enabled: true dans config/paper-global.yml, puis redémarrez-le. Si son journal affiche Velocity is enabled, but no secret key was specified, le secret est vide : reprenez la section Raccorder le serveur existant.

« Unable to verify player details »

Le secret de Paper ne correspond pas à forwarding.secret. Relancez la commande de copie du secret sur le serveur concerné, puis redémarrez-le. Pour le lobby, utilisez le chemin /opt/minecraft/lobby/config/paper-global.yml.

« This server requires you to connect with Velocity. »

Le joueur atteint le serveur Paper sans passer par le proxy, ou Velocity n'utilise pas le mode modern. Vérifiez player-info-forwarding-mode et l'adresse utilisée par le joueur. S'il a pu joindre 25566 depuis Internet, refermez ce port immédiatement.

« This server is only compatible with Minecraft 1.13 and above. »

Le transfert moderne refuse les clients antérieurs à 1.13. Ces joueurs doivent passer à une version plus récente.

Velocity ne démarre pas

Message dans le journal Cause Solution
Can't bind to …:25565 Le port est déjà pris, souvent par un serveur Minecraft Vérifiez server-port et utilisez sudo ss -ltnp
Server 'factions' for forced host '…' does not exist Un exemple reste dans [forced-hosts] Videz la section
Fallback server … is not registered in your configuration! Un nom de try est absent de [servers] Corrigez le nom
You don't have a forwarding secret set Le fichier du secret est vide ou introuvable Vérifiez forwarding.secret
UnsupportedClassVersionError Java est trop ancien Installez Java 25

« FAILED TO BIND TO PORT » sur un serveur Paper

Deux services utilisent le même port. Vérifiez server-port dans chaque server.properties : 25566 pour survie, 25567 pour le lobby.

Les joueurs ont perdu leur inventaire

Le serveur leur a attribué un autre UUID, en général parce que le transfert n'était pas actif ou que proxies.velocity.online-mode ne correspond pas à online-mode de Velocity. Arrêtez le serveur, corrigez ces réglages et redémarrez : les données d'origine restent dans le monde, sous l'ancien UUID.

Pour aller plus loin, consultez la documentation officielle de Velocity, notamment ses pages sur le transfert des joueurs et la sécurité.