BungeeCord — proxy do sieci serwerów Minecraft

Czym jest BungeeCord

BungeeCord to serwer proxy dla Minecraft stworzony przez md_5 i zespół SpigotMC. Jego główne zadanie jest proste: stać między klientem gracza a wieloma serwerami backendowymi i zarządzać tym, do którego z nich gracz jest w danej chwili podłączony.

Bez proxy każdy tryb gry wymaga osobnego adresu IP lub portu. Gracze muszą rozłączać się i wpisywać nowy adres, żeby przełączyć się z survivalu na skyblock. Z BungeeCord sieć prezentuje się dla graczy jako jeden serwer — dołączają do huba (serwer wejściowy) i komendami lub portalami przechodzą do innych trybów.

BungeeCord obsługuje do kilku tysięcy graczy jednocześnie (zależy od sprzętu i konfiguracji) i jest od lat fundamentem największych polskich i światowych sieci Minecraft. Hypixel, Mineplex, CubeCraft — wszystkie zbudowane na tej samej koncepcji proxy.

Projekt jest open-source i dostępny na GitHubie SpigotMC. Oficjalne bugi i forki (Waterfall, Velocity) są aktywnie rozwijane, choć sam BungeeCord jest już stosunkowo dojrzałym projektem.

Jak działa proxy

Architektura sieci BungeeCord składa się z trzech warstw:

1. Proxy (BungeeCord) — publiczny węzeł wejściowy, dostępny dla graczy przez internet. Nasłuchuje na porcie 25565 (lub innym). Nie uruchamia żadnego świata Minecraft — jego jedyną rolą jest przekazywanie połączeń.
2. Serwery backendowe — właściwe serwery Minecraft (Paper, Spigot, Fabric), każdy na osobnym porcie (np. 25566, 25567, 25568). Nie są bezpośrednio dostępne z zewnątrz — firewall blokuje ich porty dla wszystkich IP poza hostem proxy.
3. Hub (lobby) — jeden z serwerów backendowych, wyznaczony jako serwer startowy. Każdy gracz ląduje tu po zalogowaniu. Stąd może przejść do innych trybów.

Kiedy gracz łączy się z siecią, BungeeCord przyjmuje połączenie, autentykuje je z serwerami Mojang (tryb online) i kieruje gracza na domyślny serwer. Gdy gracz wpisuje /server survival, proxy przenosi jego sesję na serwer survival — gracz widzi ekran ładowania, ale nie traci połączenia z siecią.

Proxy przekazuje również prawdziwy adres IP gracza do backendu przez mechanizm ip_forward — bez tego pluginy zarządzające graczami (np. LuckPerms) nie wiedziałyby, kto jest kim.

Instalacja BungeeCord

BungeeCord to plik JAR uruchamiany tak samo jak każdy serwer Minecraft. Potrzebujesz Javy 17 lub nowszej.

Krok 1: Pobierz BungeeCord

Oficjalny build pobierzesz z ci.md-5.net (Jenkins md_5). Pobierz najnowszy BungeeCord.jar. Alternatywnie rozważ od razu Waterfall — fork z poprawkami wydajności.

Krok 2: Pierwsza konfiguracja

Uruchom proxy raz, żeby wygenerowało pliki konfiguracyjne:

java -Xms512M -Xmx512M -jar BungeeCord.jar

Po uruchomieniu w katalogu pojawi się config.yml, modules.yml i folder plugins/. Zatrzymaj proxy (end w konsoli) i przejdź do edycji konfiguracji.

Krok 3: Przygotuj serwery backendowe

Każdy serwer backend musi mieć wyłączony tryb online (online-mode: false w server.properties) i włączony bungeecord: true w spigot.yml. Tryb offline jest bezpieczny, bo autoryzacja odbywa się na poziomie proxy. BungeeCord przekazuje informację o autoryzacji do backendu przez ip_forward.

Konfiguracja config.yml

Plik config.yml to centrum sterowania całą siecią. Oto najważniejsze sekcje:

Definicja serwerów

servers:
  hub:
    motd: '&1Lobby'
    address: localhost:25566
    restricted: false
  survival:
    motd: '&2Survival'
    address: localhost:25567
    restricted: false
  skyblock:
    motd: '&aSkyBlock'
    address: localhost:25568
    restricted: false

Każdy wpis w sekcji servers to jeden backend. Klucz (np. hub, survival) to nazwa używana przez graczy w komendzie /server. Adres może być lokalny (localhost:port) lub zdalny (ip:port) jeśli serwery działają na osobnych maszynach.

Pole restricted: true sprawia, że do serwera mogą przejść tylko gracze z uprawnieniem bungeecord.server.<nazwa>. Przydatne do serwerów administracyjnych lub przestrzeni tworzenia.

Listeners

listeners:
- query_port: 25577
  motd: '&1Serwer Minecraft'
  tab_list: GLOBAL_PING
  query_enabled: false
  proxy_protocol: false
  forced_hosts:
    pvp.example.com: pvp
    skyblock.example.com: skyblock
  ping_passthrough: false
  priorities:
  - hub
  - survival
  bind_local_address: true
  host: 0.0.0.0:25565
  max_players: 500
  tab_size: 60
  force_default_server: false
  online_mode: true

Kluczowe pola w listenerze:

• host — adres i port, na którym nasłuchuje proxy. 0.0.0.0:25565 przyjmuje połączenia ze wszystkich interfejsów sieciowych.
• priorities — lista serwerów w kolejności próbowania przy łączeniu. Jeśli hub jest offline, BungeeCord spróbuje następnego.
• online_mode — zawsze true na proxy. Autentykacja z Mojang odbywa się tutaj, a nie na backendach.
• max_players — maksymalna liczba graczy w całej sieci.
• forced_hosts — przekierowuje graczy łączących się przez konkretną domenę od razu na wskazany serwer (pomijając hub).

Pozostałe opcje globalne

ip_forward: true
network_compression_threshold: 256
connection_throttle: 4000
connection_throttle_limit: 3
timeout: 30000
player_limit: -1
permissions:
  default:
  - bungeecord.command.server
  - bungeecord.command.list
  admin:
  - bungeecord.command.alert
  - bungeecord.command.end
  - bungeecord.command.ip
  - bungeecord.command.reload

ip_forward: true to jedno z najważniejszych ustawień — omówiono je szczegółowo w sekcji bezpieczeństwa. connection_throttle limituje, jak często ten sam IP może próbować połączyć się z siecią (ochrona przed flood).

Łączenie serwerów

Po skonfigurowaniu config.yml i uruchomieniu wszystkich backendów gracze mogą przełączać się między trybami na kilka sposobów:

Komenda /server

Domyślna komenda BungeeCord. Gracz wpisuje /server survival, żeby przejść do serwera o nazwie survival. Bez argumentów wyświetla listę dostępnych serwerów z liczbą graczy.

Pluginy portalu

Na hubie możesz postawić portale lub przyciski, które teleportują gracza do innego serwera. Pluginy takie jak BungeePortals lub własne rozwiązania oparte na BungeeCord API obsługują tę funkcję. Gracz wchodzi w portal i w ciągu sekundy trafia na inny backend.

Komendy pluginów

Wiele pluginów lobby (Limbo, LobbyAPI, Skript z BungeeBridge) dodaje własne menu serwerów z GUI. Gracze widzą wizualny selector trybu z ikoną, liczbą graczy i statusem serwera.

BungeeCord API

Jeśli piszesz własny plugin, możesz przenieść gracza kodem:

// Po stronie backendu (Spigot/Paper)
ByteArrayDataOutput out = ByteStreams.newDataOutput();
out.writeUTF("Connect");
out.writeUTF("survival");
player.sendPluginMessage(plugin, "BungeeCord", out.toByteArray());

Plugin musi zarejestrować kanał BungeeCord przy starcie. To najczystsza metoda automatycznego przekierowywania graczy po spełnieniu warunków (np. po ukończeniu tutorialu).

Pluginy BungeeCord

BungeeCord ma własne API i ekosystem pluginów — nie są to te same pliki JAR co dla Spigot/Paper. Instalujesz je w folderze plugins/ obok proxy JAR.

BungeeTabListPlus

Jeden z najpopularniejszych pluginów BungeeCord. Pozwala w pełni skonfigurować TAB listę graczy — osobne listy dla każdego serwera, globalne, dynamiczne placeholdery, niestandardowe nagłówki i stopki. Na sieci z wieloma serwerami TAB bez tego pluginu pokazuje tylko graczy z aktualnego backendu.

LuckPerms (tryb proxy)

LuckPerms może działać na BungeeCord jako centralny system uprawnień dla całej sieci. Uprawnienia przyznane przez proxy są synchronizowane z backendami przez wspólną bazę danych (MySQL, MariaDB, PostgreSQL). Jeden zestaw ról dla całej sieci zamiast osobnej konfiguracji na każdym backendzie.

Geyser-BungeeCord

Geyser to plugin/proxy pozwalający graczom Bedrock Edition łączyć się z serwerami Java Edition. Wersja BungeeCord instaluje się bezpośrednio na proxy, co jest bardziej efektywne niż oddzielna instancja Geyser. Gracze mobile i konsolowi widzą Twoją sieć tak samo jak gracze Java.

BungeeGuard

Wtyczka bezpieczeństwa weryfikująca, że połączenia do backendów faktycznie przychodzą przez BungeeCord. Proxy wstrzykuje do handshake'u tajny token, backend akceptuje tylko połączenia z tym tokenem. Alternatywa dla czystego firewalla — przydatna gdy nie możesz zablokować portów na poziomie systemu (hosting współdzielony).

ViaVersion / ViaBackwards na proxy

Jeśli zainstalowane na BungeeCord, te pluginy pozwalają graczom różnych wersji klienta łączyć się z siecią. ViaVersion obsługuje nowsze klientów na starszym serwerze, ViaBackwards odwrotnie. Instalacja na proxy zamiast na każdym backendzie osobno to duże uproszczenie administracji.

AntiVPN / AntiBot

Pluginy takie jak AntiVPN sprawdzają, czy gracz nie korzysta z VPN lub proxy, a AntiBot wykrywa i blokuje ataki botów na etapie połączenia z siecią — zanim dotrą do backendów.

ip_forward i bezpieczeństwo

To najważniejsza sekcja dla każdego, kto stawia sieć BungeeCord. Błędy tutaj prowadzą do poważnych luk bezpieczeństwa.

Dlaczego ip_forward jest konieczny

Gdy gracz łączy się przez proxy, backend widzi jego połączenie jako przychodzące z adresu IP serwera proxy (np. 127.0.0.1), a nie od rzeczywistego gracza. To problem dla pluginów IP ban, geolokalizacji i logowania. Z ip_forward: true w BungeeCord oraz bungeecord: true w spigot.yml backendu, proxy wstrzykuje prawdziwy IP i UUID gracza do handshake'a połączenia.

Krytyczne zabezpieczenie: firewall

Gdy backend akceptuje dane z handshake'a bez weryfikacji źródła, każdy mógłby połączyć się bezpośrednio z backendem i podać fałszywy IP lub UUID — co w praktyce oznacza możliwość podszywania się pod dowolnego gracza.

Obowiązkowa konfiguracja firewalla (przykład iptables):

# Zablokuj dostęp do portów backendów z zewnątrz
iptables -A INPUT -p tcp --dport 25566 -s 127.0.0.1 -j ACCEPT
iptables -A INPUT -p tcp --dport 25566 -j DROP
iptables -A INPUT -p tcp --dport 25567 -s 127.0.0.1 -j ACCEPT
iptables -A INPUT -p tcp --dport 25567 -j DROP
# Zostaw otwarty tylko port proxy
iptables -A INPUT -p tcp --dport 25565 -j ACCEPT

Jeśli backendy są na osobnych maszynach, zamień 127.0.0.1 na prywatny IP serwera proxy. Ogólna zasada: porty backendów muszą być dostępne wyłącznie dla serwera proxy.

forced_hosts a bezpieczeństwo

Sekcja forced_hosts w listenerze pozwala kierować graczy łączących się przez konkretną domenę od razu na wybrany serwer. To wygodne dla serwisów dedykowanych pod subdomenę, ale ważne jest używanie jej świadomie — nieprawidłowa konfiguracja może pozwolić graczom ominąć hub i jego systemy autoryzacji (np. AuthMe).

Limit połączeń

Dwie opcje w config.yml chronią przed atakami:

• connection_throttle: 4000 — minimalny czas (ms) między połączeniami z tego samego IP
• connection_throttle_limit: 3 — liczba prób przed tymczasowym zablokowaniem IP

Dla sieci publicznych warto ustawić throttle na 2000–3000ms. Zbyt agresywne ustawienia mogą blokować graczy z NAT (wielu graczy za jednym IP).

Waterfall — fork od PaperMC

Waterfall to fork BungeeCord rozwijany przez zespół PaperMC. Jest drop-in replacementem — instalujesz go dokładnie tak samo jak BungeeCord, używasz tych samych pluginów i tej samej konfiguracji.

Co Waterfall dodaje do BungeeCord

• Poprawki wydajności — lepsze zarządzanie pamięcią i sieciowe przy dużej liczbie graczy
• Rozszerzony API — więcej możliwości dla developerów pluginów
• Aktywniejszy cykl poprawek — Waterfall szybciej reaguje na exploity i bugi Minecrafta niż oryginalny BungeeCord
• Wbudowane zabezpieczenia — część poprawek bezpieczeństwa trafia do Waterfall zanim pojawi się w upstream BungeeCord
• Lepsza kompatybilność z Paper — jeśli backendy to Paper, Waterfall+Paper to sprawdzona kombinacja

Pobierzesz go z papermc.io/downloads/waterfall. Migracja z BungeeCord to podmiana JAR — nic więcej.

Velocity jako alternatywa

Velocity to nowoczesny proxy stworzony przez ten sam zespół co Paper i Waterfall. To nie jest fork BungeeCord — to projekt pisany od zera z inną architekturą i innym API.

Dlaczego Velocity jest lepsze dla nowych sieci

• Modern forwarding — zamiast ip_forward (które wymaga firewalla), Velocity używa kryptograficznie podpisanego tokenu. Backend akceptuje tylko połączenia z prawidłowym podpisem. Bezpieczniejsze i prostsze w konfiguracji.
• Wydajność — Velocity jest napisane wydajniej niż BungeeCord. Przy dużej liczbie graczy różnica jest zauważalna.
• Aktywny rozwój — PaperMC aktywnie dodaje nowe funkcje do Velocity, Waterfall jest w maintenance-only
• Natywne wsparcie Paper/Folia — optymalnie skrojone pod stos PaperMC

Kiedy zostać przy BungeeCord/Waterfall

BungeeCord pozostaje dobrym wyborem gdy:

• Masz istniejącą sieć z pluginami pisanymi pod BungeeCord API — migracja pluginów na Velocity API wymaga przepisania kodu
• Korzystasz z pluginów, które nie mają wersji dla Velocity
• Twoi gracze używają starszych klientów nieobsługiwanych przez Velocity

W każdym innym przypadku — jeśli zaczynasz nowy projekt — zacznij od Velocity.

Porady dla administratorów

Hub zawsze dostępny

Hub to serwer, do którego trafia gracz gdy backend jest offline lub gdy wykonuje się komenda /hub. Trzymaj hub możliwie lekkim — żadnych ciężkich pluginów, minimalna liczba graczy, żadnych światów do ładowania poza samym lobby. Hub powinien startować w 5 sekund. Rozważ Limbo (ultra-lekki serwer lobby) jako backend huba zamiast pełnego Spigota.

Restart bez disconnectów

BungeeCord pozwala na restart backendów bez rozłączania graczy — proxy utrzymuje sesję. Gracz widzi ekran reconnect lub jest automatycznie przekierowany na hub, gdy jego serwer restartuje. Używaj tego świadomie: ustaw w pluginie restartującym automatyczne przeniesienie graczy na hub przed restartem.

Monitoring i alerty

Dodaj plugin do monitorowania statusu backendów (np. przez webhook na Discord). BungeeCord zapisuje do logów informacje o rozłączeniach serwerów. Znając stan sieci w czasie rzeczywistym możesz reagować zanim gracze zaczną pisać na czacie, że coś nie działa.

Ujednolicona baza danych

Jeśli gracze mogą przenosić się między serwerami, baza danych musi być wspólna. LuckPerms, EssentialsX Economy, AuthMe — wszystkie muszą pisać do tej samej bazy MySQL/MariaDB. Bez tego gracz zalogowany na survival nie będzie miał uprawnień na skyblock.

Testuj na staging przed produkcją

Zmiana konfiguracji proxy lub instalacja nowego pluginu może rozłączyć wszystkich graczy. Trzymaj osobną, identyczną instancję sieci na staging (może być na tym samym serwerze, inny port). Testuj tam każdą zmianę przed wdrożeniem na produkcję.

Logi i rotacja

BungeeCord produkuje obszerne logi. Skonfiguruj logrotate lub użyj opcji -Dbungeecord.log.file=false jeśli masz zewnętrzny system logowania. Na sieci z tysiącami graczy logi potrafią zajmować gigabajty dziennie.

Powiązane strony

• Velocity — nowoczesne proxy dla sieci Minecraft
• Jak stworzyć serwer Minecraft — kompletny poradnik
• Paper vs Spigot — który silnik wybrać?
• Katalog pluginów Minecraft
• Serwery Minecraft — lista i typy