Filed для Minecraft: REST API для управления файлами сервера
Filed — это мощный и гибкий плагин для PaperMC, который превращает ваш игровой сервер в управляемый файловый хаб. Он предоставляет REST API для чтения, создания, удаления и изменения файлов прямо на сервере Minecraft. Благодаря строгой аутентификации по токену и белому списку разрешённых путей, вы получаете безопасный доступ к конфигурациям, логам и другим данным без необходимости заходить на сервер по SSH или FTP. Плагин совместим с актуальными версиями Minecraft 1.20.x и 1.21.x, работая на Paper и его форках.
Как работает Filed
Filed запускает встроенный HTTP-сервер внутри процесса Minecraft. Вы можете отправлять запросы к конечным точкам API, чтобы читать содержимое файлов, создавать новые, перезаписывать существующие или удалять их. Все операции строго ограничены белым списком, который вы задаёте в конфигурации. Плагин нормализует пути, блокирует символические ссылки, выходящие за пределы корня сервера, и проверяет каждый запрос на соответствие разрешённым файлам и директориям. Это исключает возможность чтения чувствительных данных, таких как базы данных или системные файлы.
Установка Filed на PaperMC
Процесс установки прост и не требует дополнительных библиотек. Скачайте JAR-файл плагина и поместите его в папку plugins/ вашего сервера. После перезапуска PaperMC Filed сгенерирует конфигурационный файл plugins/Filed/config.yml. Если вы предпочитаете автоматизированные решения, лаунчер foxygame.net позволяет добавить Filed в сборку сервера в один клик, автоматически подбирая совместимую версию плагина под ваше ядро.
Настройка конфигурации
Файл config.yml содержит три ключевых параметра:
- port — HTTP-порт, на котором будет работать API (по умолчанию 9847).
- maximum_allowed_file_size — максимальный размер файла в байтах, который можно прочитать или записать. Защищает от перегрузки памяти.
- auth_token_file — путь к файлу с хешированными токенами (обычно
tokens.json). - allowed — секция, где перечисляются разрешённые файлы (
files) и директории (directories). Пути указываются относительно корня сервера.
Пример разрешённых путей:
server.properties— доступ к основному конфигу сервера.world/stats— директория со статистикой игроков.plugins/SomePlugin/config.yml— конфиг другого плагина.
Генерация токенов доступа
Для аутентификации используется Bearer-токен. Сгенерируйте его прямо в игре или через консоль сервера командой /filed generate <имя>. Для выполнения команды требуются права оператора. Токен отображается однократно — сохраните его сразу, так как восстановить его невозможно. В файле tokens.json хранятся только SHA-256 хеши токенов, что обеспечивает безопасность даже при компрометации файловой системы.
API-эндпоинты и примеры запросов
Все запросы к API должны содержать заголовок Authorization: Bearer <ваш_токен>. Базовый URL: http://адрес_сервера:порт.
Чтение файлов и директорий
GET /files?path=<путь>&content=<true|false>
Если путь указывает на файл, возвращается JSON с полями type: "file", path и content. Для директории ответ содержит type: "directory" и массив files с объектами файлов внутри этой директории (без рекурсивного обхода). Параметр content=false позволяет получить только метаданные без содержимого, экономя трафик.
Запись и создание файлов
PUT /files?path=<путь>
Тело запроса должно содержать новый контент файла в формате text/plain. Родительская директория обязана существовать. Плагин создаст файл, если его нет, или перезапишет существующий. В ответе вернётся записанное содержимое. Запись в директории запрещена — только в файлы.
Удаление файлов
DELETE /files?path=<путь>
Удаляет указанный файл и возвращает его последнее содержимое. Директории удалять нельзя. Если файл не существует, вернётся ошибка 404.
Проверка работоспособности
GET /health
Этот эндпоинт не требует авторизации. Возвращает {"message": "ok"}, если API запущен и готов принимать запросы. Удобно использовать для мониторинга.
Обработка ошибок
Filed возвращает понятные JSON-ошибки с кодом и описанием:
- unauthorized (401) — отсутствует или неверный токен.
- forbidden (403) — путь не входит в белый список или обнаружен выход через симлинк.
- not_found (404) — запрашиваемый файл не существует.
- invalid_path (400) — некорректный формат пути.
- is_directory (400) — попытка записать или удалить директорию.
- parent_not_found (400) — родительская директория не существует (при создании файла).
- too_large (413) — размер файла превышает лимит, заданный в конфигурации.
Безопасность и ограничения
Filed спроектирован с учётом потенциальных угроз. Все пути нормализуются, а попытки обхода через `..` блокируются. Символические ссылки, ведущие за пределы корневой директории сервера, отвергаются. Токены хешируются алгоритмом SHA-256, поэтому даже при чтении файла tokens.json злоумышленник не получит исходные ключи. Лимит на размер файла предотвращает атаки, направленные на исчерпание памяти. Белый список путей гарантирует, что API никогда не получит доступ к файлам, не указанным явно в конфигурации, таким как ops.json или usercache.json.
Практическое применение
С помощью Filed вы можете автоматизировать управление сервером: веб-панель может читать server.properties для отображения текущих настроек, бот в Discord — выгружать статистику из world/stats, а система резервного копирования — забирать только разрешённые файлы. Плагин идеально вписывается в экосистему PaperMC и не требует модификации клиента. Для тех, кто собирает сервер с нуля, лаунчер foxygame.net предлагает каталог дополнений, где Filed доступен к установке вместе с другими популярными плагинами, автоматически разрешая зависимости и подбирая версию ядра.
Заключение
Filed — это элегантное решение для администраторов, которым нужен программный доступ к файлам сервера Minecraft без компромиссов в безопасности. Чёткий белый список, токен-аутентификация и интуитивный REST API делают его незаменимым инструментом для интеграции с внешними сервисами. Установите плагин на свой PaperMC сервер, настройте разрешённые пути и начните управлять файлами через HTTP уже сегодня.