Pterohost docs

Whitelist: белый список игроков на сервере Minecraft

Настройка whitelist на сервере Minecraft: команды /whitelist, файл whitelist.json, enforce-whitelist, BungeeCord и плагины для расширенного вайтлиста.

Кратко: включите whitelist командой /whitelist on, добавляйте игроков через /whitelist add НикИгрока и перезагружайте список командой /whitelist reload. Файл whitelist.json хранится в корне сервера и редактируется вручную при необходимости.

Whitelist: белый список игроков на сервере Minecraft

Whitelist - это механизм, который пускает на сервер только тех игроков, чьи ники (или UUID) явно указаны в списке. Он незаменим для приватных проектов, выделенных серверов для друзей, закрытых бета-тестов и SMP-сообществ, где не нужны случайные гости. В 2026 году большинство администраторов совмещают встроенный ванильный whitelist с плагинами - это даёт гибкость: временные слоты, интеграция с Discord, автовайтлист по заявке. В этой статье разберём полную цепочку: от базовой команды до тонкостей с UUID в оффлайн-режиме и проксях BungeeCord/Velocity.

Pterohost - игровой хостинг Minecraft с NVMe-дисками, DDoS-защитой и поддержкой 24/7. Промокод 4START даёт -20% на первый заказ. Заказать Minecraft хостинг

Включение whitelist: server.properties

Первый шаг - активация белого списка на уровне конфигурации. Откройте файл server.properties в корне сервера и найдите две строки:

white-list=true
enforce-whitelist=true
  • white-list=true - включает проверку при подключении. Игрок не в списке получает сообщение “You are not whitelisted on this server”.
  • enforce-whitelist=true (появился в 1.17.1) - кикает уже онлайн игроков, которых нет в whitelist, немедленно при /whitelist reload. Если false - уже подключённые остаются до следующего выхода.

После правки server.properties нужен перезапуск. В панели Pterodactyl это кнопка Restart.

Проверка текущего состояния

В консоли или от имени оператора в игре:

/whitelist status

Ответ сервера укажет: Whitelist is currently turned on или off.

Команды /whitelist: полный список

Все команды работают как в консоли сервера (без слеша в консоли Pterodactyl), так и в игре при наличии прав оператора (уровень 3 и выше).

КомандаЧто делает
/whitelist onВключить фильтрацию
/whitelist offВыключить (список сохраняется)
/whitelist add <ник>Добавить игрока
/whitelist remove <ник>Удалить игрока
/whitelist listПоказать всех добавленных
/whitelist reloadПеречитать whitelist.json с диска

Примеры:

whitelist add Steve
whitelist add Alex
whitelist remove Griefer2026
whitelist list

Команда reload нужна, если вы редактировали whitelist.json вручную - без неё сервер не подхватит изменения в файле.

Файл whitelist.json: структура и ручное редактирование

Белый список хранится в whitelist.json в корне сервера. Пример файла:

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

Каждая запись - объект с двумя полями: uuid и name. Оба поля обязательны.

Ручное добавление через JSON

  1. Остановите сервер (или используйте reload после правки).
  2. Откройте whitelist.json текстовым редактором.
  3. Добавьте запись в конец массива - перед последней ].
  4. Сохраните файл.
  5. В консоли выполните whitelist reload (если сервер запущен).

Следите за корректностью JSON: запятые между объектами, отсутствие запятой после последнего элемента.

Онлайн-режим vs оффлайн-режим: проблема UUID

Это самый частый источник путаницы с whitelist.

Онлайн-режим (online-mode=true)

Сервер обращается к серверам Mojang при добавлении игрока. Команда /whitelist add НикИгрока автоматически получает реальный UUID из базы Mojang и записывает его в файл. UUID в онлайн-режиме - постоянный идентификатор учётной записи, не зависящий от смены ника.

Если игрок сменил ник - UUID остался прежним, значит запись в whitelist остаётся действующей. Но поле name в JSON устареет. Это косметическая проблема: авторизация работает по UUID.

Оффлайн-режим (online-mode=false)

В этом режиме UUID генерируется локально по формуле из версии 3 UUID (namespace + ник). Это означает:

  • UUID жёстко привязан к написанию ника. Если игрок зайдёт с ником Steve - UUID один. Если с steve (строчная) - совсем другой UUID.
  • При добавлении через /whitelist add Ник сервер сгенерирует UUID на основе точного регистра ника.
  • Ник в whitelist.json и ник при входе должны совпадать до символа, включая регистр.

Для оффлайн-сервера рекомендуется вести whitelist.json аккуратно и при проблемах проверять регистр ника.

Получение UUID вручную

Для онлайн-аккаунта UUID можно узнать через API:

https://api.mojang.com/users/profiles/minecraft/<НикИгрока>

Пример ответа:

{"id":"069a79f444e94726a5befca90e38aaf5","name":"Notch"}

UUID в файле пишется с дефисами: 069a79f4-44e9-4726-a5be-fca90e38aaf5.

Whitelist на BungeeCord и Velocity

В прокси-схемах игроки подключаются не напрямую к бэкэнду, а через BungeeCord или Velocity. Это меняет логику whitelist.

BungeeCord

По умолчанию BungeeCord не имеет встроенного whitelist - только ip-whitelist в config.yml для IP-адресов. Whitelist игроков реализуется на уровне бэкэнд-серверов.

Рекомендованная схема:

  1. В config.yml BungeeCord убедитесь, что online-mode: true.
  2. На каждом бэкэнд-сервере поставьте bungeecord: true в spigot.yml и online-mode=false в server.properties (BungeeCord передаёт UUID из Mojang).
  3. Включите whitelist на главном лобби-сервере - именно он первым принимает игрока. Остальные бэкэнды можно не ограничивать (или ограничить аналогично).
  4. Для защиты от прямого подключения в обход BungeeCord - закройте порты бэкэндов файрволлом или используйте плагин BungeeGuard.

Плагины whitelist уровня BungeeCord - например BungeeWhitelist - позволяют управлять списком централизованно и применять его ко всем бэкэндам сразу.

Velocity

Velocity - современный прокси с нативной поддержкой whitelist через плагины. Стандартного механизма в ядре нет, но плагины Whitelist for Velocity или VelocityWhitelist решают задачу:

/whitelist add НикИгрока
/whitelist remove НикИгрока
/whitelist reload

Установка как обычный Velocity-плагин: скачать .jar, положить в /plugins/, перезапустить прокси.

Важно: при использовании Velocity в forwarding-режиме modern UUID всегда берётся от Mojang (онлайн-режим), что устраняет проблему UUID из оффлайна.

Плагины для расширенного whitelist

Ванильный whitelist прост, но не умеет: давать временный доступ, принимать заявки, отправлять уведомления в Discord, ограничивать по группам. Для этого нужны плагины.

WhitelistPlus (Paper/Spigot)

Популярный плагин с открытым исходным кодом. Возможности:

  • Временные слоты: добавить игрока на N дней/часов.
  • Система заявок: игрок пишет /apply, администратор одобряет.
  • Discord Webhook: уведомление при новой заявке.
  • Кастомное сообщение при отказе в подключении.

Установка:

plugins/WhitelistPlus.jar

Основные команды:

/wl add <игрок>
/wl remove <игрок>
/wl temp add <игрок> <время>   # например 7d, 12h
/wl list
/wl reload

Файл конфига plugins/WhitelistPlus/config.yml - там настраиваются сообщения, webhook и лимит заявок.

EasyWhitelist

Более легковесный вариант. Команды аналогичны ванильным, добавляет:

  • Возможность задавать разрешённые IP для игрока (IP-lock).
  • Лог попыток входа незарегистрированных игроков.
  • Команда /ew check <ник> - проверить, есть ли игрок в списке.

LuckPerms + контекстный доступ

LuckPerms сам по себе не является whitelist-плагином, но позволяет ограничить доступ к серверу через группы и контексты. Это нестандартное использование, но оно работает в сложных мультисерверных сетях, где уже используется LuckPerms.

Выбор плагина

ЗадачаПлагин
Простой закрытый серверВанильный whitelist
Временные слоты, заявкиWhitelistPlus
IP-lock + логEasyWhitelist
Централизованно на BungeeCordBungeeWhitelist
VelocityWhitelist for Velocity

Частые ошибки и их решение

Ошибка 1: whitelist включён, но пропускает всех

Причина - white-list=false в server.properties. Проверьте файл и перезапустите. Команда /whitelist on не меняет server.properties постоянно - после перезапуска приоритет у файла конфигурации.

Решение:

white-list=true

Перезапуск обязателен.

Ошибка 2: игрок добавлен, но не может войти

Возможные причины:

  • Несовпадение регистра в оффлайн-режиме. Проверьте точное написание ника в whitelist.json.
  • UUID в файле некорректный или скопирован без дефисов. UUID в JSON должен быть в формате xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.
  • Плагин auth (например AuthMe) блокирует вход независимо от whitelist. Проверьте лог сервера - сообщение об ошибке укажет источник.

Ошибка 3: /whitelist reload не применяет изменения из файла

Убедитесь, что JSON синтаксически корректен. Неверная запятая или отсутствие кавычки ломает разбор, и сервер молча продолжает использовать старый список. Проверить JSON:

python3 -m json.tool whitelist.json

Если файл невалиден - вывод покажет ошибку с номером строки.

Ошибка 4: enforce-whitelist не кикает онлайн игроков

Убедитесь, что enforce-whitelist=true в server.properties и что сервер был перезапущен после изменения. Параметр читается при старте, не на лету. После корректной настройки команда /whitelist reload будет кикать незарегистрированных игроков немедленно.

Ошибка 5: после смены ника игрок не может войти

В онлайн-режиме - это не проблема (UUID не меняется). В оффлайн-режиме - нужно удалить старую запись и добавить новую с новым ником:

whitelist remove СтарыйНик
whitelist add НовыйНик

Автоматизация whitelist через RCON

Если вы управляете сервером программно (боты, веб-панели), можно отправлять команды whitelist через RCON - протокол удалённого управления.

Включение RCON в server.properties:

enable-rcon=true
rcon.port=25575
rcon.password=ваш_пароль

Пример с утилитой mcrcon:

mcrcon -H 127.0.0.1 -P 25575 -p ваш_пароль "whitelist add НовыйИгрок"

Это позволяет автоматически добавлять игроков из внешних систем - например, при оплате подписки или одобрении заявки в Discord.

Python-скрипт для массового добавления из файла со списком ников:

import subprocess

with open("new_players.txt") as f:
    for line in f:
        nick = line.strip()
        if nick:
            subprocess.run([
                "mcrcon", "-H", "127.0.0.1",
                "-P", "25575", "-p", "ваш_пароль",
                f"whitelist add {nick}"
            ])
            print(f"Added: {nick}")

Скрипт проходит по списку и добавляет каждого игрока по одному. После завершения выполните whitelist reload для применения изменений.

Whitelist и безопасность сервера

Whitelist - это первый рубеж защиты, но не единственный. Грамотная конфигурация включает несколько уровней.

Файрволл для бэкэнд-серверов

В прокси-схемах (BungeeCord/Velocity) бэкэнд-серверы должны быть недоступны напрямую из интернета. Даже с включённым whitelist прямое подключение к бэкэнду в обход прокси может создать проблему, если online-mode=false на бэкэнде. Закрывайте порты бэкэндов файрволлом:

# На сервере с iptables - закрыть порт 25566 для всех, кроме localhost
iptables -A INPUT -p tcp --dport 25566 ! -s 127.0.0.1 -j DROP

Whitelist + двухфакторная авторизация

На оффлайн-серверах whitelist не защищает от кражи ника - любой может зайти под чужим именем, если знает, кто в списке. Решение - плагин авторизации (AuthMe Reloaded, LoginSecurity). Whitelist фильтрует по имени, AuthMe требует пароль.

Совместное использование:

  1. Whitelist пропускает только известные ники.
  2. AuthMe требует пароль для входа от имени ника.
  3. Двойная защита существенно снижает риск.

Ротация whitelist

На серверах с регулярной сменой состава (сезонные SMP, турниры) рекомендуется периодически чистить whitelist.json от неактивных игроков. Это не только безопасность, но и порядок - список не разрастается до нескольких сотен записей.

Простой bash-скрипт для резервной копии и очистки:

# Сохранить текущий список
cp whitelist.json whitelist_backup_$(date +%Y%m%d).json

# Очистить список (оставить пустой массив)
echo "[]" > whitelist.json

После очистки выполните whitelist reload и начните добавлять только актуальных игроков.

Логирование попыток входа

Ванильный сервер логирует отклонённые попытки в logs/latest.log. Строка выглядит примерно так:

[INFO]: Disconnecting com.mojang.authlib.GameProfile@... (/:PORT): You are not whitelisted on this server

Плагины EasyWhitelist и WhitelistPlus ведут отдельный лог попыток - это удобнее для анализа.

Связанные материалы

Настройка whitelist тесно связана с другими параметрами сервера. Подробнее о ключевых настройках читайте в статье server.properties: полный разбор параметров. Управление правами операторов и уровни доступа описаны в руководстве /op команда: как назначить оператора. Если вы расширяете возможности сервера плагинами - обратитесь к нашему обзору лучших плагинов для сервера Minecraft.

Заключение

Whitelist в Minecraft - один из самых простых и надёжных инструментов безопасности. Ванильный механизм покрывает большинство задач: команды /whitelist on/off/add/remove/list/reload и файл whitelist.json работают стабильно с версии 1.7 и не требуют сторонних зависимостей. Для оффлайн-серверов главное - следить за точным регистром ников, для онлайн-режима всё проще: UUID привязан к аккаунту Mojang. В прокси-схемах BungeeCord/Velocity используйте отдельные плагины или настраивайте whitelist на бэкэнд-серверах. Если нужны временные слоты, заявки или Discord-уведомления - WhitelistPlus или EasyWhitelist решат задачу без лишней сложности.

Pterohost - хостинг Minecraft-серверов с NVMe-дисками, автоматическим резервным копированием и DDoS-защитой. Промокод 4START даёт -20% на первый заказ. Заказать Minecraft хостинг