REST API Palworld: включение и управление сервером

Как включить REST API Palworld на порту 8212: RESTAPIEnabled, Basic-аутентификация, таблица эндпоинтов с примерами curl, разбор /metrics и интеграция с Prometheus.

Официальный REST API Palworld появился в обновлении v0.3.1 и закрыл давнюю боль администраторов: до него единственным способом управления сервером был RCON, неудобный для мониторинга и интеграций. Теперь сервер поднимает HTTP-эндпоинт на порту 8212, отдаёт метрики производительности, список игроков и настройки в JSON, а команды управления принимает обычными POST-запросами. Это гайд по включению REST API, аутентификации, полному списку эндпоинтов с примерами curl и интеграции с Prometheus. Установку сервера и базовую настройку PalWorldSettings.ini здесь не дублируем - если сервер ещё не поднят, начните с установки Palworld dedicated server.

Что такое REST API Palworld и зачем он нужен

REST API - это HTTP-интерфейс управления, встроенный в серверный билд Palworld (App ID 2394010). В отличие от RCON, который работает по бинарному протоколу Source RCON, REST принимает и отдаёт данные в формате JSON по HTTP. Это даёт три практических преимущества:

• Мониторинг из коробки. Эндпоинт /v1/api/metrics отдаёт serverfps, uptime и онлайн - метрики, которых у RCON просто нет.
• Лёгкая интеграция. Любой язык, любая система мониторинга умеет ходить в HTTP. Не нужен специальный RCON-клиент.
• Читаемые ответы. JSON парсится штатными средствами, тогда как RCON возвращает плоский текст, который приходится разбирать регулярками.

API слушает отдельный порт (8212 TCP по умолчанию) и работает параллельно с игровым портом 8211 UDP и RCON на 25575 TCP. Все три канала независимы.

Включение REST API в PalWorldSettings.ini

REST API выключен по умолчанию. Включается он в Pal/Saved/Config/LinuxServer/PalWorldSettings.ini внутри строки OptionSettings=(...). Нужны четыре параметра:

[/Script/Pal.PalGameWorldSettings]
OptionSettings=(...,AdminPassword="strong-admin-pass",bUseAuth=True,RESTAPIEnabled=True,RESTAPIPort=8212,...)

Разберём каждый:

Ключевой нюанс: REST API не запустится с пустым AdminPassword. Если оставить пароль пустым, при старте сервер выведет в лог предупреждение и API останется выключенным даже при RESTAPIEnabled=True. Пароль обязателен, и он же становится паролем Basic Auth. Полный разбор остальных параметров конфига - в отдельной статье про настройки Palworld, здесь мы фокусируемся только на API.

После правки конфига сервер нужно перезапустить:

sudo systemctl restart palworld

Проверить, что порт слушается:

ss -tlnp | grep 8212

Если строка есть - API поднялся. Если нет, смотрите лог journalctl -u palworld | grep -i rest.

Аутентификация: HTTP Basic Auth

Все запросы к REST API требуют HTTP Basic Authentication. Логин фиксированный - admin, пароль равен AdminPassword из конфига. В curl это флаг -u:

curl -s -u admin:strong-admin-pass http://127.0.0.1:8212/v1/api/info

Под капотом это заголовок Authorization: Basic <base64(admin:пароль)>. Если передать неверный пароль или не передать заголовок вовсе, API вернёт 401 Unauthorized. Три частые причины 401:

1. В конфиге не выставлен bUseAuth=True.
2. Пароль в запросе не совпадает с AdminPassword.
3. Сервер не перезапущен после правки конфига - работает старый пароль.

Логин всегда admin - его сменить нельзя.

Таблица эндпоинтов

API делится на две группы: GET-эндпоинты для чтения состояния и POST-эндпоинты для управляющих действий. Базовый префикс у всех - /v1/api.

GET-эндпоинты: чтение состояния

/v1/api/info

Самый лёгкий запрос, годится как health-check:

curl -s -u admin:strong-admin-pass http://127.0.0.1:8212/v1/api/info

Ответ:

{
  "version": "v0.3.11",
  "servername": "Pterohost Palworld Server",
  "description": "PvE, friendly"
}

/v1/api/players

Список всех, кто сейчас онлайн. Именно отсюда берут userId для кика и бана:

curl -s -u admin:strong-admin-pass http://127.0.0.1:8212/v1/api/players

{
  "players": [
    {
      "name": "Alice",
      "playerId": "00000000000000000000000000000001",
      "userId": "steam_76561198000000000",
      "ip": "203.0.113.5",
      "ping": 42.5,
      "location_x": -12500.0,
      "location_y": 3400.0,
      "level": 27
    }
  ]
}

Поле userId в формате steam_<SteamID64> - это идентификатор для управляющих команд.

/v1/api/settings

Возвращает все активные настройки мира в JSON. Удобно для аудита - можно сверить, что применился нужный конфиг, не парся .ini вручную:

curl -s -u admin:strong-admin-pass http://127.0.0.1:8212/v1/api/settings | jq .

/v1/api/metrics

Ключевой эндпоинт для мониторинга. Разберём подробно ниже.

POST-эндпоинты: управление

POST-запросы принимают тело в JSON и требуют заголовок Content-Type: application/json.

Announce (broadcast)

Отправить сообщение в игровой чат всем:

curl -s -u admin:strong-admin-pass \
  -H "Content-Type: application/json" \
  -X POST http://127.0.0.1:8212/v1/api/announce \
  -d '{"message":"Рестарт сервера через 5 минут"}'

В отличие от RCON, где пробелы приходится заменять подчёркиваниями, REST принимает нормальный текст с пробелами и кириллицей.

Kick и Ban

# Кик
curl -s -u admin:strong-admin-pass \
  -H "Content-Type: application/json" \
  -X POST http://127.0.0.1:8212/v1/api/kick \
  -d '{"userid":"steam_76561198000000000","message":"AFK too long"}'

# Бан
curl -s -u admin:strong-admin-pass \
  -H "Content-Type: application/json" \
  -X POST http://127.0.0.1:8212/v1/api/ban \
  -d '{"userid":"steam_76561198000000000","message":"Griefing"}'

# Снять бан
curl -s -u admin:strong-admin-pass \
  -H "Content-Type: application/json" \
  -X POST http://127.0.0.1:8212/v1/api/unban \
  -d '{"userid":"steam_76561198000000000"}'

userid берётся из ответа /v1/api/players.

Save, Shutdown, Stop

# Сохранить мир
curl -s -u admin:strong-admin-pass \
  -X POST http://127.0.0.1:8212/v1/api/save

# Плановый шатдаун через 60 секунд с сообщением
curl -s -u admin:strong-admin-pass \
  -H "Content-Type: application/json" \
  -X POST http://127.0.0.1:8212/v1/api/shutdown \
  -d '{"waittime":60,"message":"Плановый рестарт"}'

# Немедленная остановка без таймера
curl -s -u admin:strong-admin-pass \
  -X POST http://127.0.0.1:8212/v1/api/stop

Разница между shutdown и stop: shutdown даёт таймер waittime и рассылает сообщение (сервер успевает сохраниться), stop вырубает процесс сразу. На проде почти всегда нужен shutdown с предварительным save.

Pterohost - хостинг Palworld на NVMe с DDoS-защитой и открытым REST API из панели. Промокод 4START даёт -20% на первый заказ. Арендовать Palworld сервер

Разбор /metrics для мониторинга

/v1/api/metrics - главная причина, по которой стоит включать REST API. Он отдаёт то, что нельзя достать из RCON:

curl -s -u admin:strong-admin-pass http://127.0.0.1:8212/v1/api/metrics

{
  "serverfps": 58,
  "currentplayernum": 12,
  "serverframetime": 17.24,
  "maxplayernum": 32,
  "uptime": 84213,
  "days": 47
}

Что означают поля:

Главная метрика - serverfps. Движок целится в 60 тиков в секунду. Пока значение держится около 55-60, всё хорошо. Просадка до 30-40 при высоком онлайне или множестве активных баз - сигнал, что пора оптимизировать. Что именно тюнить при просадке fps, разбираем в статьях про оптимизацию Palworld и починку лагов сервера.

Интеграция с Prometheus

REST API отдаёт JSON, а Prometheus ждёт свой текстовый формат экспозиции. Мостом служит небольшой скрипт-экспортёр. Простейший вариант - опрашивать /metrics по cron и класть значения в файл для node_exporter textfile collector:

#!/bin/bash
# /home/palworld/pal_exporter.sh
AUTH="admin:strong-admin-pass"
URL="http://127.0.0.1:8212/v1/api/metrics"
OUT="/var/lib/node_exporter/textfile/palworld.prom"

JSON=$(curl -s -u "$AUTH" "$URL")
FPS=$(echo "$JSON" | jq .serverfps)
PLAYERS=$(echo "$JSON" | jq .currentplayernum)
UPTIME=$(echo "$JSON" | jq .uptime)
FRAMETIME=$(echo "$JSON" | jq .serverframetime)

cat > "$OUT.tmp" <<EOF
# HELP palworld_server_fps Server tick rate
# TYPE palworld_server_fps gauge
palworld_server_fps $FPS
# HELP palworld_players_online Current player count
# TYPE palworld_players_online gauge
palworld_players_online $PLAYERS
# HELP palworld_uptime_seconds Server process uptime
# TYPE palworld_uptime_seconds counter
palworld_uptime_seconds $UPTIME
# HELP palworld_frametime_ms Server frame time
# TYPE palworld_frametime_ms gauge
palworld_frametime_ms $FRAMETIME
EOF

mv "$OUT.tmp" "$OUT"

Запись во временный файл с последующим mv - атомарная подмена, чтобы Prometheus не прочитал полупустой файл. Ставим в cron с частотой раз в 15 секунд через отдельный таймер или простой цикл:

# systemd timer или простой watch-цикл
*/1 * * * * /home/palworld/pal_exporter.sh

Для минутного шага хватит cron; если нужна секундная гранулярность - оформите скрипт как systemd-сервис с циклом sleep 15. После этого в Prometheus появятся метрики palworld_server_fps, palworld_players_online и остальные, а в Grafana можно строить графики и вешать алерт на palworld_server_fps < 30.

Если полноценный Prometheus не нужен, достаточно однострочного health-check для алертинга в Telegram или на почту:

FPS=$(curl -s -u admin:pass http://127.0.0.1:8212/v1/api/metrics | jq .serverfps)
if [ "$FPS" -lt 30 ]; then
  echo "Palworld FPS упал до $FPS" | mail -s "ALERT" admin@example.com
fi

REST API против RCON: когда что использовать

Оба интерфейса управляют одним сервером, но заточены под разные задачи.

Практический вывод:

• Мониторинг, дашборды, автоматические алерты, интеграции с внешними панелями - REST API. Только у него есть /metrics, и JSON парсится тривиально.
• Быстрые ручные команды из терминала, легаси-инструменты, привычка - RCON остаётся рабочим вариантом. Полный список RCON-команд с примерами - в гайде по RCON Palworld.

На практике их держат вместе: RCON для оперативного управления руками, REST для непрерывного мониторинга скриптами. Оба используют один и тот же AdminPassword, так что настраиваются одной правкой конфига.

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

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

• Держите API на localhost. Не открывайте 8212 в firewall наружу. Ходите через SSH-туннель: ssh -L 8212:127.0.0.1:8212 user@server.
• Если API нужен извне - ставьте перед ним nginx с TLS и дополнительной авторизацией, а не публикуйте голый HTTP. Basic Auth без шифрования передаёт пароль почти в открытом виде (base64).
• Сильный AdminPassword. Он же пароль RCON и REST - брутфорс по HTTP делается быстро.
• Отдельный порт под фильтром. На хостинге с L3/L4 DDoS-защитой панельные порты закрыты от флуда, но 8212 всё равно стоит держать доступным только для доверенных IP.

Firewall при локальном доступе выглядит так - порт наружу не открываем совсем:

ufw allow 8211/udp        # игровой порт, нужен всем
ufw allow 25575/tcp from 10.0.0.0/24   # RCON только из внутренней сети
# 8212 не открываем - ходим через SSH-туннель
ufw reload

Pterohost - готовый Palworld-хостинг с DDoS-защитой, автобэкапами и REST API прямо из панели управления. Промокод 4START даёт -20% на первый заказ. Заказать Palworld сервер

Часто задаваемые вопросы

На каком порту работает REST API Palworld?

По умолчанию 8212 TCP, значение задаётся параметром RESTAPIPort в PalWorldSettings.ini. Порт отдельный от игрового (8211 UDP) и RCON (25575 TCP). Открывать его наружу не обязательно - безопаснее держать API на localhost и ходить через SSH-туннель или reverse-proxy.

Как аутентифицироваться в REST API Palworld?

Используется HTTP Basic Auth с логином admin и паролем из параметра AdminPassword. В curl это флаг -u admin:пароль. Обязательно должны быть выставлены bUseAuth=True и непустой AdminPassword, иначе API вернёт ошибку авторизации или не запустится.

Чем REST API отличается от RCON в Palworld?

RCON - бинарный протокол Source RCON на 25575 TCP для команд управления. REST API - HTTP/JSON на 8212 TCP, удобнее для мониторинга и интеграций. У REST есть эндпоинт /metrics с serverfps и uptime, которого нет в RCON. Для скриптовой автоматизации и дашбордов берите REST, для быстрых ручных команд - RCON.

Как снять метрики производительности через REST API?

GET-запрос на /v1/api/metrics возвращает JSON с полями serverfps, uptime (секунды), days (игровые сутки), currentplayernum и maxplayernum. serverfps ниже 30 означает перегрузку сервера. Эти значения удобно скармливать в Prometheus через простой скрипт-экспортёр.

Почему REST API Palworld возвращает 401 Unauthorized?

Причины: не передан заголовок Basic Auth, неверный AdminPassword, либо в конфиге не выставлен bUseAuth=True. Проверьте, что логин именно admin, пароль совпадает с AdminPassword в PalWorldSettings.ini, и что сервер перезапущен после правки конфига.