MCRestAPI

MCRestAPI

Мод для Fabric, который предоставляет REST API и поток событий в реальном времени (SSE) для мониторинга и управления выделенными серверами Minecraft. Построен на встроенном HTTP-сервере JDK без внешних зависимостей. Доступен для Minecraft 1.21.11 и 26.1+ — скачайте файл, подходящий вашей версии.

Возможности

• REST API для мониторинга сервера (TPS, MSPT, память, CPU, количество игроков, свойства сервера)
• Поток Server-Sent Events (SSE) в реальном времени для чата, входов, выходов, смертей и игровых сообщений
• Полные данные об игроках: здоровье, еда, позиция, измерение, пинг, игровой режим, статус OP, URL головы со скином
• Данные о мире: сид, время, погода, сложность, количество сущностей, загруженные чанки, статистика по измерениям
• Удалённое выполнение команд через API
• Встроенная админ-панель (одностраничное веб-приложение) для мониторинга и управления
• Встроенный Swagger UI со спецификацией OpenAPI 3.1.0
• Мультиключевая аутентификация с гранулярными правами
• Мастер-ключ для административных операций
• Настройка CORS с белым списком источников
• API-ключи хешируются с помощью PBKDF2-SHA256 (никогда не хранятся в открытом виде)
• Ноль внешних зависимостей (используется встроенный HTTP-сервер JDK)
• Виртуальные потоки для лёгкой конкурентности
• Только для серверной стороны (не работает на клиентах)

Требования

Каждый релиз на Modrinth помечен поддерживаемой версией Minecraft — устанавливайте тот, что соответствует вашему серверу.

Установка

1. Скачайте последний mcrestapi-x.x.x.jar с этой страницы или из GitHub Releases
2. Поместите JAR-файл в папку mods/ вашего Fabric-сервера
3. Запустите сервер
4. При первом запуске мод создаёт файл конфигурации config/mcrestapi.json и выводит мастер-ключ и ключ API по умолчанию в консоль сервера. Сохраните оба ключа сразу — позже их получить не удастся.
5. API доступен по адресу http://localhost:8080 по умолчанию
6. Админ-панель находится по адресу http://localhost:8080/admin

Конфигурация

Файл конфигурации расположен по пути config/mcrestapi.json и создаётся автоматически при первом запуске.

Хеши API-ключей хранятся с использованием PBKDF2-SHA256. Исходные значения ключей показываются только один раз при создании.

Аутентификация

Все эндпоинты API (кроме публичных) требуют Bearer-токен в заголовке Authorization:

Authorization: Bearer mcsapi_xxxxxxxxxxxxxxxx

**Мастер-ключ** создаётся при первом запуске и даёт доступ к админским эндпоинтам (`/api/admin/*`) и панели управления (`/admin`). Также у него есть права-джокеры на все эндпоинты данных.

### Отключение аутентификации

Если обратный прокси уже занимается аутентификацией (basic auth, OIDC/forward-auth и т. п.), установи `auth.enabled` в `false` в конфиге:

```json
{ "auth": { "enabled": false } }

Это отключает всю аутентификацию, включая админские эндпоинты — обратный прокси становится единственной границей доверия. Делай так только если мод слушает 127.0.0.1 за прокси, который контролирует доступ. Мод пишет предупреждение при запуске (громче, если адрес привязки не loopback). Переключить можно и на лету из панели управления (Settings → Require API Key), перезапуск не нужен.

Права

Эндпоинты API

Базовый URL: `http://:(по умолчанию:http://localhost:8080`)

Подробные примеры запросов и ответов смотри во встроенном Swagger UI по адресу /api/docs.

Публичные (аутентификация не требуется)

Эндпоинты данных

Админские эндпоинты (требуется мастер-ключ)

Поток событий SSE

Подключитесь к /api/events/stream для получения событий сервера в реальном времени. События отправляются в стандартном формате SSE. Каждые 30 секунд отправляется keepalive-пинг.

Типы событий: chat, command, join, leave, death, game

Для SSE-подключений из браузера передавайте API-ключ через query-параметр ?auth=, так как EventSource не поддерживает кастомные заголовки.

CORS

CORS отключён по умолчанию. Когда он включён, CORS-заголовки получают только источники из белого списка. Настраивается через админ-панель или эндпоинты /api/admin/cors.

CORS обеспечивает защиту только в контексте браузера. Он не заменяет аутентификацию по API-ключу.

Админ-панель

Встроенная веб-панель по адресу /admin (требуется мастер-ключ).

Страницы: Dashboard (статистика сервера), Players, World, Chat (живой поток SSE), Console (выполнение команд), Keys, CORS, Settings.

Безопасность

• Адрес привязки по умолчанию — 127.0.0.1 (только localhost)
• API-ключи хешируются с помощью PBKDF2-SHA256 со случайной солью
• Мастер-ключ хранится отдельно от API-ключей
• Для удалённого доступа используйте обратный прокси (nginx, Caddy) с HTTPS/TLS
• Создавайте API-ключи с минимальными правами, необходимыми для каждого случая использования
• Отключайте аутентификацию только при привязке к 127.0.0.1 за доверенным обратным прокси, который обеспечивает аутентификацию