Установка агента Tickwise

Tickwise — плагин с открытым кодом для мониторинга Minecraft-серверов на Paper, Purpur и Velocity. Он читает лог сервера, вырезает из него секреты и персональные данные и распознаёт известные проблемы по локальному подписанному пакету сигнатур. В облако агент начинает отправлять данные только после того, как вы явно привяжете сервер. Выполнять команды на сервере он не умеет.

Ниже — установка плагина на Paper и Velocity, привязка к Telegram-боту и что делать, если что-то пошло не так. Установка занимает пару минут на каждый сервер.

Требования

Плагин собран против paper-api 1.21.11 и velocity-api 3.5.1. На живых серверах все сочетания версий пока не проверялись.

Где взять плагин

Публичных релизов пока нет. Jar собирается из репозитория:

./gradlew :agent-paper:shadowJar :agent-velocity:shadowJar

В jar уже встроены подписанный пакет сигнатур и публичные ключи для проверки его подписи, так что локальная диагностика работает сразу после установки.

Установка на Paper и Purpur

1. Положите Tickwise-Paper-0.1.0.jar в папку plugins/.
2. Перезапустите сервер.
3. Проверьте консоль: агент должен сообщить о запуске.

Настройки лежат в plugins/Tickwise/config.yml, файл создаётся при первом запуске. После правки выполните /tickwise reload.

Роль сервера агент определяет сам: backend, если в config/paper-global.yml включён proxies.velocity.enabled или в spigot.yml стоит settings.bungeecord: true, иначе standalone.

Если агент не смог стартовать, он пишет в консоль Tickwise не запустился и отключается (сервер продолжает работу) и выключает только себя. Сервер продолжает работать.

Установка на Velocity

1. Положите Tickwise-Velocity-0.1.0.jar в plugins/ прокси.
2. Перезапустите прокси.
3. Настройки — в plugins/tickwise/config.toml. Команды reload на Velocity нет: после правки конфига перезапустите прокси.

Сеть Velocity и backend'ы

Чтобы облако склеивало сбой на прокси и его причину на backend'е в один инцидент:

• поставьте агент и на прокси, и на каждый backend;
• привяжите все серверы из одного Telegram-чата и в одну сеть (по умолчанию она называется default);
• имя backend'а в Tickwise должно совпадать с именем в секции [servers] файла velocity.toml. Задайте его в server.name или, если имя отличается, в server.proxy-alias.

server:
  name: "lobby"

Привязка к облаку и Telegram

До привязки агент ничего не отправляет. Привязку может запустить только консоль или игрок с правом tickwise.owner.

1. Укажите адрес облака в cloud.endpoint. Значение по умолчанию в шаблоне — заглушка, адрес нужно прописать явно. Разрешён только https://.

   cloud:
     endpoint: "https://<адрес облака>"
   

2. В консоли выполните tickwise link, при желании с именем сервера. Агент выдаст одноразовый код на 15 минут.

3. Отправьте код боту Tickwise в Telegram: /link КОД [имя-сервера] [сеть]. Это можно сделать в личном чате или в группе; в группе команду принимают только от администраторов. Бот покажет имя, платформу, версию и замаскированный IP агента — убедитесь, что это ваш сервер.

4. Подтвердите привязку в консоли.

Чат, из которого пришла первая /link, становится организацией: все серверы этого чата видят друг друга, а уведомления о падении сервера приходят в Telegram именно туда. Что умеет бот после привязки — на странице Telegram-бот.

Для Docker и автоматизации есть cloud.auto-link: true: привязка стартует сама через 5 секунд после запуска и печатает код в консоль. Подтвердить его в Telegram всё равно нужно.

Команды и права

Команда без аргументов выполняет status. Из консоли доступны все команды.

tickwise.admin по умолчанию есть у операторов. tickwise.owner не выдаётся никому, даже op, — назначьте его явно через плагин прав. На Velocity права выдаёт плагин прав.

Что работает без облака

Без привязки и при недоступном облаке агент продолжает:

• читать лог и распознавать известные проблемы по встроенному пакету сигнатур — найденное пишется в консоль;
• отвечать на status, diagnose и privacy;
• разбирать при старте новые crash report'ы и hs_err_pid*.log и замечать crash loop (три неудачных запуска за 30 минут).

Без облака не работают уведомления в Telegram, страница инцидента, склейка ошибок прокси и backend'ов и обновление пакета сигнатур. Если облако недоступно после привязки, данные копятся в очереди на диске (по умолчанию до 50 МБ) и уходят, когда связь вернётся.

Если что-то пошло не так

Первый шаг всегда один — tickwise status в консоли: команда показывает состояние облака, последнюю ошибку отправки и время следующей попытки.

Проблемы самой сети Velocity агент тоже распознаёт. Самые частые при настройке Velocity forwarding: рассогласован modern forwarding, не совпадает forwarding secret и backend недоступен для прокси. Полный список — в базе ошибок.

Отвязка и удаление

tickwise unlink в консоли удаляет токен с сервера и останавливает отправку; локальная диагностика продолжает работать. Облако об этом не узнаёт: сервер останется в списке бота со статусом «нет связи». Чтобы убрать сервер из Tickwise и отозвать его токен, откройте карточку сервера в боте и нажмите «🔌 Отвязать».

Неотправленные данные остаются в папке outbox/ и уйдут при следующей привязке. Если это не нужно, удалите outbox/ перед tickwise link.

Полное удаление:

1. tickwise unlink.
2. Остановите сервер или прокси.
3. Удалите jar из plugins/.
4. Удалите папку данных: plugins/Tickwise/ на Paper или plugins/tickwise/ на Velocity. В ней лежат токен, соль псевдонимизации, очередь и скачанные пакеты сигнатур.

Как агент обращается с данными, подробно описано на странице Безопасность.