Whitelist не работает: диагностика

MAATRIX GAMES

Добавил друга в whitelist, а сервер его не пускает — или того хуже, whitelist вроде включён, а заходит кто попало. Это одна из тех проблем, где причина почти всегда банальная, но найти её с наскока сложно, потому что вариантов сразу несколько: не тот параметр, не тот UUID, не перечитанный файл. Разберём по шагам, где именно чаще всего ломается whitelist и как это проверить, не гадая.

white-list=false: самая частая причина

Первое, что стоит проверить, даже если кажется, что «я точно включал» — сам параметр в server.properties, в корне сервера:

white-list=true

Если тут стоит false, сервер полностью игнорирует содержимое whitelist.json, каким бы полным и правильным оно ни было. Это самая частая причина, с которой приходят в поддержку: человек аккуратно добавил всех через /whitelist add, всё выглядит нормально в файле — а параметр включения где-то по пути слетел или вообще не был выставлен изначально, если сервер настраивали руками, а не через команду.

Проверить быстро:

grep white-list server.properties

Если строки нет вообще — допиши её вручную и перезапусти сервер (параметры из server.properties читаются при старте, «на лету» этот конкретный флаг не подхватывается через reload, в отличие от самого списка). Если сервер уже запущен и лезть в конфиг неохота — включить можно прямо из консоли или RCON:

/whitelist on

Эта команда действует немедленно и заодно сама выставляет white-list=true в файле, так что после неё можно не перезапускать сервер отдельно ради конфига. Базовую настройку с нуля — что такое whitelist и зачем он нужен — можно посмотреть в статье whitelist: как настроить доступ на сервер, здесь я исхожу из того, что whitelist уже когда-то настраивался, но что-то пошло не так.

Неверный ник или UUID в whitelist.json

Вторая по частоте причина — запись в списке технически есть, но она не соответствует тому, кто реально подключается. whitelist.json выглядит так:

[
  {
    "uuid": "069a79f4-44e9-4726-a5be-fca90e38aec5",
    "name": "Notch"
  }
]

Ключевое поле здесь — uuid, а не name. Сервер сверяет подключение именно по UUID, ник — вторичное поле, которое обновляется само при следующем входе. Отсюда две типичные ошибки:

• Опечатка в нике при ручном добавлении через /whitelist add ИмяИгрока. Ники в Minecraft чувствительны к регистру только косметически, но сама опечатка (лишняя буква, перепутанные символы) приведёт к тому, что команда либо не найдёт аккаунт вообще, либо привяжет UUID не того игрока, если ник случайно совпал с чужим.
• Ручная правка файла с произвольным или устаревшим UUID. Если кто-то скопировал UUID из старого бэкапа, с другого сервера или просто ошибся при копировании из сервиса проверки UUID — запись в файле есть, но она ни на кого не указывает или указывает не на того человека.

Проверить UUID конкретного игрока можно через любой сторонний сервис проверки Mojang-аккаунтов по нику (в поиске — «minecraft uuid lookup»), либо довериться серверу: если он в онлайн-режиме, команда /whitelist add Ник сама обратится к серверам авторизации Mojang и подставит правильный UUID — ручной ввод UUID в этом случае вообще не нужен и только повышает риск опечатки.

online-mode true/false: почему UUID не совпадают

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

online-mode=true

Он определяет, проверяет ли сервер клиентов через авторизацию Mojang/Microsoft. От него напрямую зависит, откуда берётся UUID:

• online-mode=true (лицензионный режим). UUID — настоящий, привязанный к аккаунту, выдаётся серверами авторизации. Он одинаковый на любом сервере, где играет этот же аккаунт.
• online-mode=false (офлайн-режим). UUID генерируется локально самим сервером на основе одного только ника (детерминированная функция от строки имени). Это значит, что офлайн-UUID для ника «Notch» на одном сервере будет совпадать с офлайн-UUID того же ника на другом офлайн-сервере — но категорически не совпадёт с настоящим лицензионным UUID того же аккаунта.

Проблема возникает, когда whitelist заполняли одним способом, а сервер работает в другом режиме — например, кто-то добавил игроков через сторонний сервис проверки лицензионных UUID, а сервер при этом в online-mode=false. Игрок подключается, сервер генерирует ему офлайн-UUID по нику, сверяет с whitelist — и не находит совпадения, потому что там лежит лицензионный UUID того же человека.

Решение: если сервер офлайн, добавляй игроков строго через /whitelist add Ник, пока сервер запущен именно в офлайн-режиме — тогда UUID в файле будет сгенерирован тем же алгоритмом, что и при реальном подключении, и они совпадут. Смешивать режимы (сначала играли в online-mode true, потом переключились на false, оставив старый whitelist) — гарантированный способ получить массовые отказы у половины списка.

Файл поправили, а сервер не заметил: нужен reload

Третья по частоте причина — файл whitelist.json отредактирован руками (например, скопирован большой список при переезде с другого сервера), но сервер продолжает работать со старой версией списка, загруженной в память при старте.

Minecraft-сервер не следит за файлом whitelist.json в реальном времени — он читает его один раз при запуске и держит в памяти. Любая ручная правка файла напрямую (через SFTP, файловый менеджер панели, текстовый редактор) не применяется автоматически. Нужно либо перезапустить сервер целиком, либо, что быстрее и не требует даунтайма, выполнить команду:

/whitelist reload

Она перечитывает файл с диска и подхватывает изменения без рестарта. Это же касается ситуации наоборот — если whitelist правили через команды /whitelist add/remove на одном инстансе, а потом файл синхронизировался куда-то ещё (например, при работе через панель с несколькими нодами) — на другом инстансе тоже нужен reload, чтобы файл в памяти совпал с файлом на диске.

Отдельно стоит проверять валидность JSON после ручной правки: лишняя запятая после последнего элемента массива или незакрытая фигурная скобка уронит парсинг всего файла при старте или reload, и тогда список вообще не загрузится — часто без явной ошибки в чате, только в логе сервера. Если после reload что-то пошло не так и сервер ведёт себя странно — как искать причину в логе, разобрано в статье логи и краш-репорты: как читать и искать причину.

Диагностика через консоль: /whitelist list и логи

Прежде чем гадать, что не так, всегда полезно посмотреть, что сервер реально считает загруженным списком, а не что лежит в файле на диске — это не всегда одно и то же, особенно если недавно правили конфиг вручную.

/whitelist list

Команда выводит в консоли (или в чате, если выполняется от игрока с правами оператора) реальный список ников, которые сервер держит в памяти прямо сейчас. Если игрока там нет — значит либо он не добавлен, либо файл не перечитан после правки, либо запись битая и не распарсилась.

Дальше стоит подключиться к серверу через SSH или консоль панели и проверить сам файл:

cat whitelist.json

Сравни вывод команды /whitelist list с содержимым файла на диске. Если они расходятся — почти наверняка не хватает /whitelist reload. Если игрока нет вообще нигде — значит проблема на шаге добавления (опечатка, не тот режим online-mode). Если файл не парсится (пустой список после reload, хотя строки в нём видны) — ищи синтаксическую ошибку JSON, самый быстрый способ — прогнать содержимое через любой онлайн-валидатор JSON или python3 -m json.tool whitelist.json, которая сразу укажет на битую строку.

Для удалённой диагностики без прямого доступа к консоли удобен RCON — команды выше выполняются точно так же через него, что особенно полезно, если нужно проверить сервер не заходя в саму игру. Подключение и базовые команды RCON разобраны в статье RCON: подключение и основные команды.

Пошаговый чек-лист: от простого к сложному

Если непонятно, с чего начинать — вот порядок, который экономит время, потому что идёт от самых частых причин к самым редким:

1. Проверь white-list=true в server.properties (grep white-list server.properties).
2. Выполни /whitelist list и сравни с тем, кого ожидаешь там увидеть.
3. Если игрока нет — добавь заново командой /whitelist add Ник, не редактируя файл руками.
4. Если правил whitelist.json вручную — выполни /whitelist reload или перезапусти сервер.
5. Проверь online-mode в server.properties — совпадает ли режим с тем, в каком добавлялся игрок.
6. Проверь валидность JSON, если после reload список выглядит пустым или урезанным.
7. Убедись, что нет опечатки в нике — самый надёжный способ обойти это: добавлять по нику через команду, а не копировать UUID руками.

Таблица для быстрой сверки симптома и вероятной причины:

Частые вопросы