Whitelist na serwerze Minecraft

Czym jest whitelist

Whitelist (ang. lista dozwolonych) to mechanizm dostępny w każdym serwerze Vanilla, Paper, Spigot i ich pochodnych, który pozwala administratorowi wskazać konkretnych graczy mogących się połączyć. Każdy, kto nie figuruje na liście, zobaczy komunikat: You are not whitelisted on this server! i połączenie zostanie odrzucone jeszcze przed załadowaniem świata.

Whitelist jest niezależna od systemu banów — możesz mieć gracza zarówno na whiteliście, jak i na ban liście. W takim przypadku ban ma pierwszeństwo i gracz nie dołączy. Whitelist jest też niezależna od uprawnień operatora: gracz może być OP-em, ale jeśli zostanie usunięty z whitelist, przy włączonej liście nie wejdzie na serwer.

Kiedy warto korzystać z whitelist? Przede wszystkim na serwerach prywatnych dla znajomych, serwerach SMP (Survival Multiplayer) z zamkniętą społecznością, podczas testów nowych wersji lub konfiguracji, gdy chcesz zapobiec przypadkowym wejściom nieznajomych oraz na serwerach dla streamerów z ich widzami.

Włączanie whitelist — server.properties

Whitelist włącza się w pliku server.properties, który znajdziesz w głównym katalogu serwera. Otwórz go dowolnym edytorem tekstowym i znajdź linię:

white-list=false

Zmień wartość na true:

white-list=true

Zapisz plik i uruchom serwer ponownie. Od tej chwili whitelist jest aktywna. Jeśli lista jest pusta i nie ma żadnych graczy w whitelist.json, nikt — nawet operatorzy — nie będzie mógł dołączyć (chyba że są wpisani na listę).

Zamiast edytować plik ręcznie i restartować serwer, możesz użyć komendy konsolowej, która działa natychmiastowo:

/whitelist on

Ta komenda włącza whitelist w czasie rzeczywistym bez potrzeby restartu i automatycznie aktualizuje wartość w server.properties.

Opcja enforce-whitelist dostępna od Minecraft 1.17 jest szczególnie przydatna, gdy chcesz mieć pewność, że żaden gracz — niezależnie od uprawnień — nie obejdzie listy.

Komendy whitelist

Pełny zestaw komend whitelist jest dostępny z konsoli serwera (bez ukośnika) lub dla graczy z uprawnieniami operatora (z ukośnikiem). Wymagany poziom uprawnień to OP level 3.

/whitelist add

Dodaje gracza do whitelist. Gracz nie musi być aktualnie połączony z serwerem — wystarczy podać jego nick.

/whitelist add NazwaGracza

Po dodaniu gracz może natychmiast dołączyć — nie jest wymagany restart ani przeładowanie. Serwer automatycznie zapisuje wpis do pliku whitelist.json.

/whitelist remove

Usuwa gracza z whitelist. Jeśli gracz jest aktualnie połączony, zostanie wyrzucony dopiero przy następnym połączeniu (lub natychmiast, jeśli masz włączone enforce-whitelist=true i użyjesz /whitelist reload).

/whitelist remove NazwaGracza

/whitelist list

Wyświetla wszystkich graczy aktualnie wpisanych na whitelistę. Przy dużych listach wynik jest paginowany w konsoli.

/whitelist list

/whitelist on i /whitelist off

Włącza lub wyłącza whitelist w czasie rzeczywistym. Odpowiednik ręcznej edycji server.properties, ale bez restartu.

/whitelist on
/whitelist off

/whitelist reload

Przeładowuje plik whitelist.json z dysku. Przydatne, gdy ręcznie edytujesz plik JSON bez użycia komend — po edycji wywołaj reload, żeby zmiany weszły w życie. Przy enforce-whitelist=true wyrzuca z serwera graczy, których usunąłeś z listy.

/whitelist reload

Plik whitelist.json

Wszystkie wpisy whitelist są przechowywane w pliku whitelist.json w głównym katalogu serwera. Format jest prosty — tablica obiektów JSON, każdy z dwoma polami: uuid i name.

[
  {
    "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
    "name": "Notch"
  },
  {
    "uuid": "853c80ef-3c37-49fd-aa49-938b674adae6",
    "name": "Dinnerbone"
  }
]

Pole uuid to unikalny identyfikator konta Mojang. Na serwerach premium jest pobierany automatycznie przez serwer z API Mojang podczas dodawania gracza komendą. Na serwerach offline-mode UUID jest generowany lokalnie na podstawie nicku.

Możesz edytować plik ręcznie — na przykład gdy musisz dodać wielu graczy naraz. Po edycji pamiętaj o wywołaniu /whitelist reload lub restarcie serwera. Jeśli plik jest niepoprawny składniowo (brakujący przecinek, niezamknięty nawias), serwer może nie załadować whitelist i potraktować ją jako pustą.

Waliduj JSON przed wgraniem na serwer — możesz użyć narzędzia online jak jsonlint.com lub wbudowanego walidatora w edytorze kodu (VS Code, Notepad++). Błąd składni w whitelist.json nie spowoduje restartu serwera, ale po cichu wyczyści listę, wpuszczając lub blokując wszystkich w zależności od ustawień.

Masowe dodawanie graczy

Jeśli chcesz dodać dziesiątki graczy naraz, najwygodniej jest przygotować plik JSON ręcznie. UUID każdego gracza możesz pobrać z https://api.mojang.com/users/profiles/minecraft/NazwaGracza — endpoint zwraca obiekt z polami id (UUID bez myślników) i name. UUID w pliku whitelist musi mieć myślniki (format standardowy: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).

Whitelist na serwerach offline-mode

Serwery w trybie online-mode=false (popularnie zwane cracked lub nieoficjalnymi) nie weryfikują kont przez serwery Mojang. To wpływa na działanie whitelist w istotny sposób.

Na serwerze premium UUID gracza jest stały i powiązany z kontem Mojang — zmiana nicku nie wpływa na UUID. Na serwerze offline-mode UUID jest obliczany lokalnie ze wzoru: UUID.nameUUIDFromBytes("OfflinePlayer:" + nick). Oznacza to:

• Zmiana nicku = utrata dostępu. Gracz zmienił nick? Jego offline UUID jest inny. Trzeba go ponownie dodać do whitelist pod nowym nickiem i usunąć stary wpis.
• Ten sam nick na różnych serwerach = ten sam UUID. W przeciwieństwie do premium, gdzie UUID jest unikalny globalnie.
• Podszywanie się. Na serwerze offline-mode gracz może wpisać dowolny nick, w tym nick kogoś na whiteliście. Whitelist sama w sobie nie chroni przed tym problemem — potrzebujesz pluginu do autoryzacji (AuthMe, nLogin) jako warstwy dodatkowej.

Whitelist na BungeeCord i Velocity

Przy serwerach działających za proxy (BungeeCord, Waterfall, Velocity) standardowa whitelist na serwerach backendowych jest niewystarczająca jako jedyne zabezpieczenie. Gracz może ominąć proxy i połączyć się bezpośrednio z backendem, jeśli zna jego adres IP i port.

Dlaczego natywna whitelist backendów nie wystarczy

Wyobraź sobie serwer lobby na porcie 25566 i serwer survival na porcie 25567, oba schowane za BungeeCord na porcie 25565. Jeśli porty backendów są dostępne publicznie (błąd konfiguracyjny, ale częsty), gracz może połączyć się bezpośrednio na port 25567, omijając wszelką logikę proxy — w tym whitelist ustawioną w BungeeCord.

Prawidłowa konfiguracja

Pierwszym krokiem jest zablokowanie portów backendów na firewallu — powinny być dostępne wyłącznie dla loopback (127.0.0.1) lub sieci lokalnej, nigdy z zewnątrz. Następnie możesz skonfigurować whitelist na poziomie proxy:

• BungeeCord/Waterfall: Plugin BungeeWhitelist lub BungeeGuard zarządza listą na poziomie proxy, zanim gracz trafi do jakiegokolwiek backendu.
• Velocity: Plugin Velocity Whitelist lub obsługa przez LuckPerms — gracz bez odpowiedniego uprawnienia jest odrzucany na etapie połączenia z proxy.
• LuckPerms (oba proxy): Możesz zdefiniować uprawnienie np. server.whitelist.allowed i wymagać go od wszystkich graczy. Brak uprawnienia = kick z komunikatem.

Whitelist per-serwer w sieci proxy

Jeśli chcesz, żeby różne serwery w sieci (lobby, survival, minigry) miały osobne listy dopuszczonych graczy, zamiast jednej globalnej — użyj pluginu obsługującego whitelist per-serwer, np. MultiWhitelist dla BungeeCord. Pozwala to prowadzić otwarty lobby dla wszystkich, ale zamknięty survival wyłącznie dla wybranych.

Automatyzacja — pluginy i boty Discord

Ręczne dodawanie graczy komendą działa świetnie dla małych serwerów. Przy większych projektach lub serwerach streamera, gdzie setki graczy chcą dostępu, warto zautomatyzować proces.

Pluginy whitelist z formularzem

Pluginy takie jak EasyWhitelist, WhitelistPlus czy Whitelistify dodają panel webowy lub system wniosków w grze. Gracz wypełnia formularz podając swój nick, admin zatwierdza wniosek jednym kliknięciem lub system automatycznie dodaje gracza po weryfikacji konta.

Bot Discord z integracją whitelist

Najbardziej popularne rozwiązanie na serwerach społecznościowych to bot Discord zarządzający whitelist. Gracz wpisuje na kanale Discord komendę np. !whitelist NazwaGracza, bot weryfikuje nick przez Mojang API, sprawdza warunki (rola na Discordzie, czas na serwerze) i automatycznie dodaje gracza przez RCON lub REST API.

Popularne boty Discord z taką funkcją to Minecord, MCWhitelistBot oraz własne boty oparte na bibliotekach discord.js lub discord.py z modułem RCON. RCON (Remote Console) to protokół pozwalający na zdalne wykonywanie komend serwera — włącz go w server.properties:

enable-rcon=true
rcon.password=TwojeBezpiecznHaslo
rcon.port=25575

EssentialsX i zarządzanie graczami

Jeśli używasz EssentialsX, masz dostęp do rozbudowanego systemu uprawnień i grup, który może uzupełniać whitelist. EssentialsX nie zarządza natywną whitelist Minecrafta, ale pozwala tworzyć własne grupy dostępu i warunki dołączenia przez integrację z LuckPerms.

Automatyczne whitelist przez weryfikację Discord

Zaawansowany przepływ wygląda tak: gracz dołącza do Discorda serwera → przechodzi weryfikację (captcha, wiek, akceptacja regulaminu) → bot automatycznie przydziela rolę → rola triggeruje webhook lub skrypt → nick gracza trafia do whitelist.json przez RCON. Cały proces może być w pełni bezobsługowy.

Whitelist a ban list — różnice

Whitelist i ban list to dwa osobne mechanizmy kontroli dostępu, które działają niezależnie i w różnych celach. Często są mylone przez początkujących administratorów.

Whitelist — lista dozwolonych

Whitelist to lista graczy, którym wolno wejść na serwer. Logika jest ekskluzywna: jeśli jesteś na liście — wejdziesz; jeśli nie ma Cię na liście — nie wejdziesz. Whitelist jest domyślnie wyłączona — włączona whitelist z pustą listą blokuje wszystkich.

Ban list — lista zablokowanych

Ban list to lista graczy, którym nie wolno wejść na serwer. Logika jest odwrotna: serwer jest otwarty dla wszystkich, a ban blokuje konkretne osoby. Plik to banned-players.json (bany po nicku/UUID) i banned-ips.json (bany IP). Komendy: /ban NazwaGracza, /ban-ip AdresIP, /pardon NazwaGracza.

Kiedy używać czego

• Whitelist: serwer prywatny, zamknięta grupa znajomych, SMP dla konkretnej społeczności, serwer w fazie budowy lub testów
• Ban: serwer publiczny, blokowanie konkretnych toksycznych graczy, zabezpieczenie przed graczem po incydencie
• Oba jednocześnie: możliwe, ale rzadko potrzebne. Ban ma pierwszeństwo — gracz zbanowany i wpisany na whitelist nie wejdzie.

Jeśli prowadzisz serwer publiczny i chcesz zablokować kilku graczy — używaj bana. Jeśli serwer ma być dostępny wyłącznie dla wybranych — whitelist jest właściwym narzędziem. Nie używaj whitelist zamiast bana do karania graczy — jest do tego osobny system.

Porady praktyczne

Zrób backup whitelist.json przed dużymi zmianami

Przed ręczną edycją pliku lub masowym czyszczeniem listy skopiuj whitelist.json w bezpieczne miejsce. Błąd składni JSON lub przypadkowe usunięcie może wyczyścić całą listę — wtedy backup pozwoli ją odtworzyć bez kontaktowania się z każdym graczem osobno.

Utrzymuj spójność nicków i UUID

Na serwerze premium gracze mogą zmieniać nicki przez konto Mojang. Serwer Vanilla identyfikuje ich po UUID, więc zmiana nicku nie blokuje dostępu — whitelist.json automatycznie aktualizuje nick przy następnym połączeniu. Jednak w starszych wersjach Spigota lub przy ręcznej edycji pliku upewnij się, że UUID jest zawsze poprawny.

Whitelist nie zastępuje hasła RCON

Jeśli włączyłeś RCON do automatyzacji, ustaw silne hasło i zablokuj port RCON (domyślnie 25575) na firewallu dla zewnętrznych połączeń. Dostęp do RCON = pełna kontrola nad serwerem, w tym możliwość modyfikacji whitelist bez autentykacji.

Informuj graczy o procedurze

Jeśli prowadzisz serwer z whitelist, umieść wyraźną informację na stronie lub Discordzie: jak złożyć wniosek o dostęp, ile trwa rozpatrzenie, jakie warunki trzeba spełnić. Brak informacji prowadzi do frustracji i wielu identycznych wiadomości prywatnych do administracji.

Regularny przegląd listy

Co kilka miesięcy przejrzyj whitelist i usuń nieaktywnych graczy, którzy nie logowali się od dawna. Mniejsza lista to lepsza przejrzystość i mniejsze ryzyko, że gracz z dostępem „odziedziczy" konto od kogoś, kto dawno przestał grać. Aktywność graczy możesz sprawdzić w logach serwera lub przez plugin statystyk.

Obsługa sytuacji awaryjnych

Jeśli musisz szybko zamknąć serwer dla wszystkich nowych graczy (atak, exploitowanie buga), szybciej jest użyć /whitelist on niż konfigurować firewall. Istniejący gracze online pozostają połączeni — tylko nowe połączenia będą odrzucane.

Powiązane strony

• Jak stworzyć serwer Minecraft — kompletny poradnik
• Komendy na serwerze Minecraft — lista dla adminów i graczy
• EssentialsX — niezbędny plugin dla każdego serwera
• Lista serwerów Minecraft — znajdź serwer dla siebie