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.
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,
curletjq - 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 :
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/backupsInstaller Velocity
Créez un script qui télécharge le dernier build stable et contrôle son empreinte. Il resservira pour les mises à jour :
sudo nano /opt/minecraft/velocity-update.sh#!/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 :
sudo chmod 755 /opt/minecraft/velocity-update.sh
sudo -u minecraft /opt/minecraft/velocity-update.sh 4.3.1La ligne velocity.jar.new: OK confirme que le fichier est intact.
Créez le service :
sudo nano /etc/systemd/system/velocity.service[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.targetCes options Java sont celles que recommande la documentation de Velocity. Démarrez le proxy une première fois pour générer sa configuration :
sudo systemctl daemon-reload
sudo systemctl start velocity.service
sudo journalctl -u velocity.service -n 30 --no-pagerAttendez 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 :
sudo systemctl stop velocity.service
sudo chmod 700 /opt/minecraft/velocity
sudo ls -l /opt/minecraft/velocityVous devez voir velocity.toml et forwarding.secret.
Configurer Velocity
sudo -u minecraft nano /opt/minecraft/velocity/velocity.tomlVérifiez ou modifiez ces lignes, au début du fichier :
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] :
[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 :
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.propertiesActivez ensuite le transfert moderne dans la configuration de Paper, avec le secret généré par Velocity :
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/configContrôlez le résultat sans afficher le secret :
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.ymlVous 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 :
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.txtCréez ses réglages, avec un monde plat et sans monstres :
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
EOFCréez son service :
sudo nano /etc/systemd/system/minecraft-lobby.service[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.targetTout démarrer
Démarrez les deux serveurs, puis suivez le premier démarrage du lobby jusqu'à la ligne Done :
sudo systemctl daemon-reload
sudo systemctl start minecraft.service
sudo systemctl enable --now minecraft-lobby.service
sudo journalctl -u minecraft-lobby.service -fQuittez le suivi avec Ctrl+C, puis démarrez le proxy :
sudo systemctl enable --now velocity.service
sudo journalctl -u velocity.service -n 30 --no-pagerVérifier que les ports internes sont fermés
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 :
sudo ufw status | grep -E '2556[67]'Depuis un autre ordinateur, testez ensuite les ports. Le premier doit répondre, le second doit échouer :
nc -zv -w 5 IP_SERVEUR 25565
nc -zv -w 5 IP_SERVEUR 25566Si 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 :
sudo ufw allow from IP_DU_PROXY to any port 25566 proto tcpOu avec iptables :
sudo iptables -A INPUT -p tcp -s IP_DU_PROXY --dport 25566 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 25566 -j DROPVérifier le résultat
Contrôlez d'abord les trois services :
systemctl is-active velocity.service minecraft.service minecraft-lobby.serviceConnectez-vous ensuite avec votre client Minecraft, à la même adresse qu'avant. Vous devez arriver dans le lobby. Tapez alors :
/server
/server survieLa 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 :
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 :
sudo chmod 700 /opt/minecraft/backupsAjoutez 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 :
tar -czf $BACKUP_DIR/world_proxy_$DATE.tar.gz -C /opt/minecraft velocity lobbyMettre à 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 :
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.serviceMettez ensuite à jour le serveur survie comme indiqué dans le guide Paper, puis copiez son fichier vers le lobby :
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.serviceRevenir en arrière
Pour retrouver un serveur seul sur le port 25565, sans perdre ce qui a été joué depuis :
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.serviceLes 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é :
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é.