Configurer un proxy Velocity pour Minecraft

Velocity est un proxy Minecraft performant qui répartit les joueurs entre plusieurs serveurs (lobby, survival, mini-jeux, etc.). Il supporte le modern forwarding (1.7–1.21+), ce qui évite de mettre online-mode=false sur les backends. Ce guide décrit l’installation, la configuration de velocity.toml, des backends et du secret de forwarding.

Prérequis

• Java 17+ (ou 21 selon les versions)
• Accès aux fichiers du proxy et des serveurs backend (votre panel ou SSH)
• Au moins 2 serveurs : un pour Velocity (entrée des joueurs) et un ou plusieurs backends (lobby, jeux, etc.)

Rôle de Velocity

• Les joueurs se connectent à Velocity (ex. port 25565).
• Velocity les envoie vers un backend (lobby, etc.) selon les règles (try, forced-hosts).
• Modern forwarding : Velocity envoie les infos de compte (UUID, pseudo) aux backends ; les backends restent en online-mode=true (recommandé).

Installation

1. Télécharger velocity.jar depuis papermc.io ou velocitypowered.com.
2. Créer un dossier dédié, y placer velocity.jar.
3. Premier lancement :
   java -Xms512M -Xmx512M -jar velocity.jar
   Cela génère velocity.toml, forwarding.secret (ou la section dans le toml), et le dossier plugins/.

Configuration : velocity.toml

bind

bind = "0.0.0.0:25565"

Port d’écoute du proxy (25565 par défaut). À ouvrir dans le pare-feu et chez l’hébergeur.

[servers]

Définir les backends et l’ordre de tentative (try) :

[servers]
lobby = "127.0.0.1:25566"
survival = "127.0.0.1:25567"

[servers.try]
- lobby
- survival

Les joueurs essayeront lobby en premier, puis survival si lobby est down. Adapter les IP et ports aux machines réelles (même VPS ou autres).

[forwarding]

Mode modern (recommandé) :

[forwarding]
mode = "modern"

Générer un secret (32 bytes, base64) :

openssl rand -base64 32

Dans velocity.toml :

[forwarding]
mode = "modern"
secret = "LE_SECRET_GENERE_ICI"

Ce secret devra être configuré identique dans chaque backend (Paper, Spigot) — voir ci-dessous.

[messages], [query], [advanced]

• messages : messages de kick, de maintenance, etc.
• query : désactiver si inutile.
• advanced : compression, compression-seuil, etc. ; valeurs par défaut souvent suffisantes.

Configuration des backends (Paper / Spigot)

online-mode

Avec modern forwarding, laissez online-mode=true sur les backends. Velocity envoie les infos signées ; le backend les valide.

Paper : proxies.velocity

Dans config/paper-global.yml (ou spigot.yml selon la version) ou config/paper-world-defaults.yml, selon la doc de Paper :

proxies:
  velocity:
    enabled: true
    online-mode: true
    secret: "LE_MEME_SECRET_QUE_DANS_VELOCITY"

(Le nom exact et l’emplacement peuvent varier : config/paper-global.yml ou config/paper-defaults.yml → section proxies.velocity.)

Spigot : BungeeCord

Si le backend est en Spigot (sans Paper), activer BungeeCord et renseigner le secret si Spigot le supporte ; sinon, pour une config type BungeeCord, il faut souvent bungeecord: true et online-mode=false. Avec Velocity, privilégier Paper et modern forwarding pour garder online-mode=true.

Port des backends

Les backends ne doivent pas être exposés sur le port public. Ils écoutent en localhost (127.0.0.1) ou sur une IP privée. Seul Velocity (25565) est exposé. Dans server.properties des backends : server-port=25566, 25567, etc.

Plugins utiles sur Velocity

• LuckPerms (Velocity) : permissions globales.
• LibertyBans : bannissements partagés.
• VelocityTab : liste de joueurs, tab.

Ordre de démarrage

1. Démarrer les backends (lobby, survival, etc.).
2. Démarrer Velocity.

À l’arrêt : Velocity d’abord, puis les backends.

Dépannage

Bonnes pratiques

• Ne pas exposer les ports des backends (25566, 25567, …) sur Internet.
• Utiliser un secret fort et unique, régénéré si compromis.
• Pour un alternative BungeeCord : bungeecord-setup ; pour les mods sur les backends : mods-minecraft ; pour ViaVersion : setup-viaversion.

Ressources

• Velocity – Documentation
• Paper – Configuration Velocity

Cet article s’inscrit dans notre série de guides hébergement et gaming. Pour un serveur sur-mesure, contact.