Beilin Entry Control

Описание на английском

Beilin Entry Control — серверный мод для Fabric, созданный для серверов участников Beiyue.

Этот мод проверяет доступ игроков через взаимодействие с API Beiyue (beiyue.us). Игрокам без разрешения или с активными ограничениями будет отказано во входе.

Возможности

• Единый контроль доступа через API Beiyue
• Обновления банов и разрешений в реальном времени через WebSocket
• Никаких постоянных побочных эффектов (все операции только в памяти, без изменений других модов или файлов игры)

Требования

• Доступ к серверу участника Beiyue
• Сервер Fabric с установленным Fabric API
• Действующий ключ API, предоставленный Beiyue

Этот проект в первую очередь предназначен для китайских пользователей.

Beilin Entry Control（北约统一入服控制系统）

Серверный мод для Fabric, идущий в комплекте с Beilin Entry Control, предназначен для серверов участников Бэйюэ. Этот мод проверяет права игроков и подтверждает право входа на серверы Бэйюэ через связь с beiyue.us.

Этот проект также включает дополнительный мод Beilin Data Portability. Если вам нужна функция экспорта данных построек, смотрите отдельно Beilin Data Portability.

Обзор возможностей

• Единый контроль входа
  При входе игрока на сервер мод отправляет запрос на проверку прав к beiyue.us. Если игроку не выдано право входа на серверы Бэйюэ или действует один/несколько запретов, сервер откажет во входе.

• Мгновенное действие межсерверных запретов
  Мод постоянно синхронизирует состояние через WebSocket. Даже если игрок уже вошёл на сервер, при изменении прав связанные ограничения вступят в силу немедленно.

• Обеспечение высокой доступности сети
  Система использует архитектуру с основным и резервным узлами для стабильной синхронизации состояния. При сбое основного пути WebSocket мод автоматически переключится на резервный путь; если основной и резервный пути одновременно недоступны, сервер признает синхронизацию недействительной и принудительно очистит сервер, чтобы запрет вступал в силу сразу после выдачи.

• Без постоянных побочных эффектов

  • Вся логика работает только в памяти;
  • Читается только собственный файл конфигурации этого мода;
  • Конфигурации других модов или Minecraft не изменяются;
  • После удаления этого мода сервер немедленно вернётся к ванильной логике.

Предварительные условия

Перед установкой и использованием этого мода убедитесь, что выполнены следующие условия:

• Статус сервера участника Бэйюэ
  Этот мод доступен только для серверов участников Бэйюэ, для серверов, не являющихся участниками, поддержка пока не предоставляется.

• Серверная среда Minecraft
  Сервер должен работать на сервере Fabric с правильно установленным Fabric API, чтобы мод мог нормально загружаться и работать.

• Получение учётных данных API
  Этому моду требуются действующие учётные данные API. Запросите у Narek специальный apiKey и добавьте его в файл конфигурации сервера согласно инструкции по настройке.

Шаги установки

1. Разверните сервер Fabric

   • Используйте официальный Fabric Installer для развёртывания сервера Fabric.

2. Поместите файл мода

   • Поместите .jar файл этого мода в папку mods в корневом каталоге сервера.

3. Первый запуск сервера

   • Запустите сервер один раз, чтобы мод завершил инициализацию;
   • При этом в каталоге config будет создан файл конфигурации beilin-entry-control.json.

4. Остановите сервер

   • Завершите процесс сервера, чтобы отредактировать файл конфигурации.

Описание конфигурации

Путь к файлу конфигурации: config/beilin-entry-control.json

Пример содержимого (только пример, фактически ориентируйтесь на созданный файл):

{
  "apiKey": "YOUR_API_KEY_HERE",
  "baseHost": "beiyue.us",
  "wsBackupDnsHost": "saas.wiki-beilin.org",
  "wsPrimaryProbeIntervalSec": 10,
  "useHttps": true,
  "useWss": true
}

• apiKey（обязательно）

  • Ключ API, полученный по запросу у Narek;
  • При первом создании это значение-заполнитель "YOUR_API_KEY_HERE", обязательно замените его;
  • Если он отсутствует или пуст, мод посчитает конфигурацию недействительной и откажется работать.

• baseHost

  • Имя хоста для связи с API;
  • Значение по умолчанию — "beiyue.us";
  • Изменять нужно только в особых средах (например, внутренняя сеть, тестовая среда).

• wsBackupDnsHost

  • DNS-имя хоста, используемое резервным путём WebSocket;
  • Значение по умолчанию — "saas.wiki-beilin.org";
  • Изменять нужно только в особых средах (например, внутренняя сеть, тестовая среда).

• wsPrimaryProbeIntervalSec

  • Интервал в секундах для проверки восстановления основного пути, когда WebSocket находится на резервном пути;
  • Значение по умолчанию — 10;
  • Обычно изменять не нужно.

• useHttps

  • Использовать ли доступ к HTTP API через https://;
  • Изменять нужно только в особых средах (например, внутренняя сеть, тестовая среда).

• useWss

  • Использовать ли WebSocket через wss://;
  • Изменять нужно только в особых средах (например, внутренняя сеть, тестовая среда).

После внесения изменений сохраните файл конфигурации и перезапустите сервер.

Настройка белого списка сервера

Этот мод не изменяет никакие ванильные или Fabric настройки белого списка, администратору сервера нужно вручную настроить политику белого списка:

• Если вы хотите управлять входом только через Beilin Entry Control:

  • Установите white-list в false в server.properties;
  • Или отключите ванильный белый список привычным вам способом;
  • Фактическое право входа определяется beiyue.us.

• Если всё ещё нужно использовать вместе с ванильным белым списком:

  • Можно также оставить белый список включённым;
  • В этом случае для входа нужно одновременно выполнить два условия: «иметь действующее право входа на серверы Бэйюэ» и «находиться в белом списке сервера».

Сосуществование с дополнительным модом Portability

Beilin Data Portability — дополнительный мод этого проекта, предназначенный для переносимого экспорта данных построек. Он повторно использует учётные данные API и канал push-уведомлений WebSocket Beilin Entry Control, но не заменяет логику контроля входа.

• Если нужен только единый контроль входа, достаточно установить только Beilin Entry Control.
• Если нужна функция экспорта построек, установите одновременно Beilin Entry Control и Beilin Data Portability.
• О конфигурации, хранении индексов, процессе экспорта и командах обслуживания Portability смотрите в Beilin Data Portability.

Обновление и удаление

• Обновление мода

  • Остановите сервер;
  • Замените старую версию .jar в каталоге mods на новую;
  • Сохраните прежний config/beilin-entry-control.json, обычно изменять его не нужно;
  • Перезапустите сервер.

• Удаление мода

  • Остановите сервер;
  • Удалите .jar файл этого мода из каталога mods;
  • Перезапустите сервер;
  • После этого сервер вернётся к ванильной логике входа и больше не будет обращаться к API beiyue.us.

提示：如不再使用本模组，可根据需要手动删除 config/beilin-entry-control.json，这不会影响其他配置或存档。若服务器同时安装了 Beilin Data Portability，请一并参考 Beilin Data Portability 中的移除说明。

安全性与透明度说明

• 本模组仅在内存中处理入服逻辑与事件，不主动写入任何数据文件。
• 不会修改其他模组或 Minecraft 的配置文件，也不会改动世界存档结构。
• 所有与 beiyue.us 的通信仅围绕入服控制、状态同步和导出任务推送相关接口进行。
• 本模组会为 Beilin Data Portability 转发导出任务推送，但不会自行记录建筑数据或生成导出文件。

如有任何其他疑问，请联系 Narek。