Configurer BungeeCord : connecter ton serveur Minecraft en toute sécurité

BungeeCord relie plusieurs serveurs Minecraft Java sous une adresse commune. Le proxy authentifie le joueur et le redirige vers le lobby, le survie ou d'autres backends. Il n'héberge lui-même aucun monde. Un réseau minimal nécessite donc au moins deux processus ou instances d'hébergement distincts : un proxy BungeeCord et un backend Minecraft.

La règle de sécurité la plus importante : les backends tournent derrière BungeeCord en mode hors ligne. Ils ne doivent donc jamais être librement accessibles depuis Internet. ip_forward: true transmet l'identité, mais ne constitue pas un contrôle d'accès. Verrouille la protection pare-feu/réseau privé avant de considérer le réseau comme terminé.

À quoi ressemble un réseau BungeeCord

Minecraft Java Client
        |
        | adresse publique du proxy
        v
 BungeeCord (online_mode=true, ip_forward=true)
        |
        | uniquement le chemin proxy autorisé
        +---------------------+
        v                     v
 Lobby / Paper          Survival / Paper
 online-mode=false      online-mode=false
 bungeecord=true        bungeecord=true

Le proxy gère la connexion, l'adresse publique, le routage et les commandes proxy. Les backends stockent les mondes, les inventaires et les données des plugins Bukkit/Paper. BungeeCord ne synchronise pas ces données automatiquement. Des rangs, bannissements ou inventaires valables sur tout le réseau nécessitent des plugins adaptés et le plus souvent une base de données commune.

Quelle topologie choisir ?

La configuration de BungeeCord se ressemble dans toutes les variantes, mais pas le chemin réseau sécurisé. Décide de la topologie avant de saisir des adresses dans config.yml.

Proxy et backend sur le même nœud

Deux instances d'hébergement sur le même nœud restent des conteneurs distincts. Le proxy peut atteindre le backend via l'adresse interne prévue à cet effet ; une instance tierce sur le même bridge ne le doit pas. Ouvrir tout le sous-réseau Docker serait donc trop large. La protection doit rester liée à la source proxy concrète et se résoudre à nouveau après un redémarrage de conteneur.

Proxy et backend sur des nœuds différents

Ici, le chemin passe par le réseau des nœuds. Autorise sur le backend exactement la source du proxy concerné et le port TCP précis. N'ouvre pas par inadvertance l'UDP, une plage de ports ou l'intégralité de l'IP du nœud pour d'autres instances clientes. Vérifie le chemin positif depuis le proxy et le chemin négatif depuis une source indépendante dans la même fenêtre de temps.

Backend externe

Un backend en dehors de la plateforme d'hébergement nécessite une route que le proxy BungeeCord puisse atteindre. L'exploitant du système externe est responsable de son propre pare-feu. Un tunnel inverse ou un VPN peut assurer le transport, mais n'est sûr que si le backend reste lié localement et que seul le chemin proxy autorisé est transmis. Les textes produits ne doivent qualifier cette variante de sécurisée qu'après vérification du chemin positif et négatif pour la configuration concrète.

Plusieurs proxys

Plusieurs proxys pour la haute disponibilité constituent une conception à part entière. Chaque chemin source autorisé, la gestion commune des plugins/données et le traitement des sessions doivent être planifiés explicitement. Ne copie pas simplement une autre IP dans une liste blanche large. Ce guide décrit délibérément un proxy associé par chemin backend.

Prérequis et modèle de coûts

Tu as besoin de :

• une instance BungeeCord ;
• au moins un serveur Paper/Spigot séparé comme backend ;
• un port TCP unique par processus ;
• un chemin accessible du proxy vers le backend ;
• un pare-feu, un réseau privé ou un contrôle d'accès équivalent et vérifié ;
• une sauvegarde testée avant de transformer un serveur existant.

Sur game-serverhosting, BungeeCord est un logiciel serveur à part entière. Prévois le proxy et les backends comme des instances séparées. Si tu n'as pas encore d'instances, commence par la commande d'un serveur Minecraft. La base de code actuelle de BungeeCord compile avec Java 17 ; l'egg proposé fonctionne avec Java 21. Ne te fie pas à d'anciennes affirmations génériques comme « 512 Mo pour 500 joueurs » : les plugins, le taux de connexion, la compression et les attaques modifient considérablement les besoins.

Étape 1 : noter l'architecture et les ports

Donne à chaque instance un nom et un rôle. Un exemple simple :

127.0.0.1 ne fonctionne que si le proxy et le backend partagent le même espace de noms réseau. Deux conteneurs Pterodactyl sur le même hôte ne sont pas automatiquement reliés via loopback. Utilise exactement l'adresse backend que ton proxy peut atteindre, et n'ouvre donc jamais par précaution tout un sous-réseau de conteneurs.

Étape 2 : sauvegarder les serveurs existants

Avant toute modification du mode en ligne ou du forwarding, sauvegarde les mondes, playerdata, les bases de données de plugins et les fichiers de configuration. Effectue au moins un test de restauration. Lors du passage d'UUID hors ligne à en ligne, les joueurs peuvent apparaître comme de nouveaux comptes bien que leurs anciens fichiers existent toujours. Le guide sur le changement de version en toute sécurité explique le chemin de sauvegarde, de copie et de retour arrière que tu devrais aussi utiliser pour cette migration.

Étape 3 : démarrer le proxy et modifier config.yml

Démarre BungeeCord une fois puis arrête proprement le proxy. Cela génère un config.yml correspondant à la version installée. Tu trouveras la référence complète des champs dans config.yml de BungeeCord expliqué.

Un modèle minimal et raccourci ressemble à ceci :

online_mode: true
ip_forward: true
player_limit: -1

servers:
  lobby:
    address: <ADRESSE-LOBBY>:<PORT-LOBBY>
    motd: '&aLobby'
    restricted: false
  survival:
    address: <ADRESSE-SURVIVAL>:<PORT-SURVIVAL>
    motd: '&aSurvival'
    restricted: false

listeners:
  - host: 0.0.0.0:<PORT-PROXY>
    priorities:
      - lobby
      - survival
    force_default_server: true
    max_players: 100

max_players influence le nombre de places affiché. La limite dure globale est player_limit ; des valeurs de zéro ou moins signifient illimité. Les noms de backend sous priorities doivent correspondre exactement aux clés sous servers.

Étape 4 : configurer les backends pour le forwarding

Sur chaque backend Paper/Spigot :

# server.properties
online-mode=false

# spigot.yml
settings:
  bungeecord: true

Avec un Paper récent, vérifie aussi dans config/paper-global.yml :

proxies:
  bungee-cord:
    online-mode: true

Cette valeur Paper décrit le mode en ligne du proxy et doit y correspondre. Elle ne contredit pas le online-mode=false dans server.properties. Les quatre valeurs et les conséquences sur UUID/sauvegardes sont expliquées en détail dans Configurer l'IP Forwarding de BungeeCord en toute sécurité.

Étape 5 : sécuriser l'accès aux backends

Vient maintenant l'étape qui manque dans beaucoup d'anciens tutoriels. Autorise le port TCP du backend exclusivement depuis le proxy associé, ou lie-le à un réseau privé véritablement partagé. Une simple IP interne, restricted: true ou bungeecord: true ne constitue pas une preuve de sécurité.

Sur game-serverhosting, le chemin proxy autorisé pour les topologies BungeeCord prises en charge est déduit de l'instance proxy concrète par le gardien de backend actif. Si la source est absente ou arrêtée, le chemin reste en mode blocage uniquement. Pour un backend exploité en externe, tu dois configurer toi-même son pare-feu de sorte que seul le chemin proxy vérifié soit autorisé.

BungeeGuard peut fournir une protection par jeton supplémentaire sur l'hébergement mutualisé. Utilise au moins la version 1.4.0 ; les installations anciennes concernées doivent être mises à jour et le jeton doit être renouvelé. Le jeton n'a jamais sa place dans les tickets, captures d'écran ou journaux. BungeeGuard complète la protection réseau et ne rend pas automatiquement invisible une surface d'attaque accessible.

Étape 6 : ordre de démarrage et tests réels

Démarre d'abord les backends, puis le proxy. Vérifie plus d'un seul port ouvert :

1. Le processus proxy tourne et écoute sur l'allocation attribuée.
2. Le proxy atteint l'adresse du lobby en TCP.
3. Le ping Minecraft via l'adresse publique du proxy fonctionne.
4. Un vrai compte de test arrive dans le lobby et peut changer de serveur.
5. L'IP et l'UUID en ligne arrivent correctement au backend.
6. Un accès direct indépendant au port du backend échoue.

Seul le point 6 transforme un chemin de forwarding fonctionnel en résultat réellement sécurisé. Si la connexion échoue, suis l'arbre de diagnostic pour « Could not connect to a default or fallback server » sans ouvrir le pare-feu de manière générale pour autant.

Planifier le routage, le fallback et la maintenance

priorities n'est pas seulement une liste pour la première connexion. Elle détermine aussi les cibles que BungeeCord essaie successivement en cas de panne d'un serveur. Place en première position un petit backend fiable et compatible. Un serveur survie avec un modpack lourd est rarement le meilleur fallback technique.

forced_hosts peut diriger différents domaines vers différentes cibles de départ. Exemple : creative.example.net démarre sur creative, tandis que play.example.net commence dans le lobby. Les deux noms DNS pointent vers le même proxy. Teste chaque nom d'hôte séparément, car un fonctionnement par défaut ne dit rien sur une faute de frappe dans le mapping des hôtes forcés.

restricted: true est utile pour les serveurs de maintenance ou d'équipe. La permission associée bungeecord.server.<nom> doit être évaluée au niveau du proxy. Elle empêche un joueur normal de changer de serveur via BungeeCord, mais ne protège pas contre un accès TCP direct au backend.

Pour la maintenance, la procédure suivante est recommandée :

1. Retirer le serveur cible de la priorité utilisée publiquement ou le verrouiller via une permission.
2. Déplacer de façon contrôlée les joueurs connectés vers un backend sain.
3. Sauvegarder et maintenir le backend.
4. Vérifier le TCP proxy-vers-backend et effectuer un vrai test de connexion.
5. Ne rouvrir le routage qu'ensuite.

Un redémarrage du proxy déconnecte tous les joueurs connectés via celui-ci. Les mondes continuent de tourner sur les backends, mais le redémarrage reste une interruption visible et doit s'inscrire dans une fenêtre de maintenance.

Revue de sécurité avant la mise en service

Parcours cette limite une fois du point de vue d'un attaquant :

• Seul le proxy est-il documenté comme adresse Minecraft publique ?
• Chaque port backend est-il bloqué depuis un poste de travail indépendant ?
• Une autre instance sur le même nœud/bridge partagé peut-elle atteindre le port ?
• La source proxy actuelle est-elle réévaluée après un arrêt/redémarrage ?
• Un proxy arrêté ou non résoluble de manière univoque reste-t-il fail-closed ?
• Les jetons, les IP complètes et key.pem ont-ils été retirés des captures d'écran et des journaux de support ?
• Seul un petit groupe de personnes dispose-t-il de permissions comme /ip, /send, /alert et /end ?
• Tous les backends enregistrés sont-ils dignes de confiance ? Les backends peuvent influencer le réseau via le plugin messaging.

Si tu ne peux pas répondre à une question par un test ou une règle concrète, l'état est non vérifié, pas « probablement sûr ». C'est particulièrement important sur l'hébergement mutualisé : une adresse d'apparence interne ne garantit pas encore une séparation des locataires.

Sauvegardes, mises à jour et supervision

BungeeCord ne possède pas de monde, mais son état reste tout de même pertinent en cas de restauration. Sauvegarde avant les mises à jour :

• config.yml et modules.yml ;
• le dossier plugins/ du proxy avec ses configurations ;
• les bases de données de plugins locales ou externes de manière cohérente ;
• la version de build BungeeCord et de Java utilisée ;
• une documentation caviardée des noms de backend, des ports et des règles de protection.

Les mondes, playerdata et les données des plugins Bukkit/Paper sont sauvegardés séparément sur les backends. Une sauvegarde du proxy ne remplace pas une sauvegarde de monde. Après une restauration, vérifie pas seulement la présence des fichiers, mais aussi que la connexion au lobby, l'UUID, les permissions et le changement de serveur fonctionnent de nouveau correctement.

Pour une mise à jour, arrête le proxy proprement, remplace uniquement le JAR ou utilise l'installateur prévu à cet effet, et vérifie d'abord le journal de démarrage. Suivent ensuite le ping Minecraft, une vraie connexion, l'identité, le fallback et le chemin direct toujours bloqué. Garde le dernier JAR fonctionnel ainsi que la configuration correspondante prêts pour un retour arrière.

La supervision distingue au moins ces signaux :

Surveille en complément le tas mémoire/GC, les blocages de la boucle d'événements, les exceptions de plugins, les délais d'attente du backend et les taux de connexion inhabituels. Un indicateur vert du tableau de bord ne doit pas résumer plusieurs de ces états en un simple « en ligne ».

Éviter les erreurs de configuration courantes

• Port proxy et port backend inversés : les joueurs arrivent directement sur le backend en mode hors ligne, ou BungeeCord se connecte à lui-même.
• Domaine public utilisé comme adresse backend : le proxy se retrouve dans une boucle DNS/routage. Utilise l'adresse cible interne concrète.
• max_players lu comme limite dure : la liste des serveurs affiche la valeur, alors que player_limit peut rester illimité.
• Un seul test TCP effectué : le listener est ouvert, mais le lobby, le forwarding ou le protocole échouent.
• Pare-feu désactivé pour déboguer : la connexion positive fonctionne, pendant qu'un contournement d'identité reste ouvert en même temps.
• Plugin Bukkit installé sur le proxy : la plateforme ou les dépendances ne correspondent pas ; lis le descripteur et la page du projet.
• /greload après des modifications profondes : certaines parties de la configuration ou des plugins restent dans l'ancien état. Utilise un redémarrage complet.
• Sauvegarde sans test de restauration : seul un cas d'erreur révèle que la base de données, les mondes ou l'état des plugins n'ont pas été sauvegardés de manière cohérente.

Diriger le domaine et le SRV vers le proxy

Le DNS pointe toujours vers le proxy public. En cas de port Java différent, un enregistrement SRV _minecraft._tcp peut mapper le port. La cible SRV doit être un nom d'hôte, pas une IP. Les étapes précises A/CNAME/SRV se trouvent dans le guide Connecter ton propre domaine à ton serveur de jeu.

Les hôtes forcés (Forced Hosts) n'y changent rien : ils utilisent uniquement le nom d'hôte demandé par le client comme information de routage. survival.example.net pointe lui aussi d'abord vers le proxy ; c'est ensuite BungeeCord qui redirige en interne vers survival.

Bien répartir les plugins et les permissions

• Les plugins BungeeCord vont dans le dossier plugins/ du proxy.
• Les plugins Bukkit/Paper vont sur le backend concerné.
• Certains plugins réseau nécessitent des composants sur les deux niveaux.
• Les permissions proxy ne sont pas automatiquement présentes dans un plugin de permissions uniquement backend.
• Après des modifications de plugins, un redémarrage complet planifié est plus fiable que /greload.

N'utilise que des plugins provenant de sources dignes de confiance et vérifie la plateforme, la version, les dépendances et les indications de sécurité. Le guide des plugins montre le chemin dans le panel pour les plugins Paper/Spigot ; les plugins proxy doivent être explicitement identifiés comme compatibles BungeeCord.

Crossplay Bedrock avec Geyser

Dans un réseau BungeeCord, tu installes Geyser sur le proxy, pas sur chaque backend. Java utilise le TCP, le listener Bedrock l'UDP. Floodgate suffit sur le proxy, à condition que les plugins backend n'aient besoin ni de son API ni du support de skin supplémentaire. key.pem est un secret d'authentification.

La vérification des ports et des connexions reste distincte pour le TCP et l'UDP. Utilise le guide crossplay Geyser/Floodgate une fois que le chemin Java pur fonctionne de manière sécurisée.

BungeeCord ou Velocity ?

BungeeCord est encore activement développé en 2026. Waterfall, l'ancien fork de PaperMC, est en revanche en fin de vie. PaperMC recommande Velocity pour les nouveaux réseaux et signale lui-même que sa propre comparaison peut être biaisée en faveur de son propre produit.

Pour un réseau existant avec des plugins BungeeCord importants, BungeeCord peut être le choix présentant le moins de risques. Pour un nouveau réseau sur des versions Paper récentes, Velocity propose le Modern Forwarding avec un format secret protégé par MAC. Ne décide pas sur la base de chiffres de performance génériques, mais en fonction des versions, de l'API des plugins, du forwarding et de la migration. L'article BungeeCord vs Velocity 2026 contient la matrice de décision.

FAQ

BungeeCord est-il un serveur Minecraft ?

Non. BungeeCord est un proxy. Les mondes, chunks, mobs et modes de jeu tournent sur des backends séparés.

De combien de serveurs ai-je besoin ?

Au moins deux processus ou instances : le proxy et un backend. Pour un lobby plus un mode de jeu, trois instances sont recommandées.

Le proxy doit-il fonctionner en mode en ligne ?

Pour un réseau authentifié normal, oui : online_mode: true sur le proxy. Les backends utilisent online-mode=false, car le proxy a déjà authentifié.

ip_forward est-il sécurisé ?

C'est nécessaire pour les vraies IP et les UUID en ligne, mais ce n'est pas suffisant à lui seul. Le forwarding legacy ne possède pas de secret de signature spécifique au proxy. Le port du backend doit être protégé des sources non fiables.

Un redémarrage du proxy redémarre-t-il mes mondes ?

Non. Les backends continuent de tourner, mais les joueurs connectés via le proxy sont déconnectés.

Ai-je besoin d'un lobby ?

Pas obligatoirement. Au moins une cible accessible dans priorities est nécessaire ; un lobby dédié rend généralement le fallback et la maintenance plus clairs.

De quels ports BungeeCord a-t-il besoin ?

Le listener Java public utilise le TCP. Chaque backend nécessite un port TCP propre, accessible uniquement au proxy. Query et Geyser/Bedrock utilisent, une fois activés, des ports UDP séparés ; ne les ouvre pas si la fonction n'est pas utilisée.

Puis-je installer des plugins Paper sur BungeeCord ?

Non, pas de manière générale. Les plugins Paper/Bukkit vont sur les backends. Le proxy a besoin de plugins explicitement conçus pour BungeeCord. Les plugins réseau peuvent fournir deux composants séparés.

Pourquoi mon backend ne voit-il que l'IP du proxy ?

En général, ip_forward sur le proxy ou settings.bungeecord sur le backend est désactivé. Vérifie les deux côtés et redémarre complètement. Ne modifie les valeurs liées à l'UUID qu'après une sauvegarde.

Puis-je utiliser plusieurs domaines ?

Oui. Tous les domaines pointent vers le proxy. forced_hosts peut ensuite associer le nom d'hôte demandé à un backend de départ.

Le crossplay fonctionne-t-il automatiquement sur chaque backend ?

Geyser traduit le protocole Bedrock au niveau du proxy. Les backends doivent accepter la version de protocole Java émulée par Geyser ; en cas d'écart de version, une configuration ViaVersion délibérément vérifiée peut être nécessaire. L'accessibilité UDP est testée séparément du TCP Java.

Vérification finale

Le réseau n'est terminé que lorsque la vraie connexion via le proxy réussit et qu'une connexion directe indépendante vers le backend en mode hors ligne est bloquée. Documente les adresses et règles de manière caviardée, sauvegarde la configuration et les données de monde séparément, et planifie la prochaine revue technique avant l'échéance indiquée si BungeeCord, Java, BungeeGuard, Paper, Velocity ou Geyser publie une version pertinente.

Conserve également, pour d'éventuels futurs cas de support, la date et le fuseau horaire du test, les versions du proxy/backend et le premier message d'erreur concret. Masque à cette occasion les adresses IP des joueurs et supprime entièrement les secrets. Cela permet de comprendre a posteriori la différence entre une erreur de processus, de réseau, de protocole, d'identité ou de plugin, sans intégrer de données client sensibles dans une base de connaissances durable.

Sources primaires

• BungeeCord : Installation
• BungeeCord : Guide de configuration
• BungeeCord : IP Forwarding
• BungeeCord : dépôt et avertissement de sécurité
• Paper : configuration globale
• BungeeGuard : sécurité