QMClient

Агент на Linux (x86_64 только), который ставится на выделенный хост (VPS, железо). Сканирует подкаталоги в рабочем каталоге из учётной записи «выделенный сервер» в QMServer и отправляет результат по HTTP в API — без SSH.

Установка только нативная (статический бинарник + systemd). Образа Docker и поставки в контейнер нет: агенту нужны прямой доступ к каталогам на машине и управление процессами (скан, supervise).

См. также: QMAdmin (панель), QMServer (маршруты /agent/... и /admin/dedicated-servers).

Назначение

• Раз в заданный интервал (или после загрузки) выполняется скан work_dir и POST отчёта на QMServer.
• QMServer сопоставляет найденные папки с профилями игровых серверов по IP + порт и полям dedicated_server_id / data_subdir. Если имя папки под work_dir — валидный UUID, совпадающий с полем uuid профиля в QMServer, сопоставление идёт по нему (удобно, когда на одном IP несколько JVM с одним портом). UUID профиля соответствует каталогу данных этой установки на хосте (подкаталог в work_dir).
• Управление запуском скана: systemd (qmclient.service — oneshot, qmclient.timer — периодически и после boot).
• Сервис qmclient-supervise.service (в релизе) ставится и включается автоматически вместе с таймером и сканом; это длинный цикл опроса QMServer: команды запуск / остановка / перезапуск Minecraft через run.sh и лог в панель. Вручную: qmclient -supervise. Подробнее ниже и QMServer (маршруты supervisor).

Версия и сборка

Версия задаётся при линковке (-ldflags "-X main.version=…"), в том числе в CI. Команда:

qmclient -version

Статическая сборка: CGO_ENABLED=0, один исполняемый файл на архитектуру.

Установка и артефакты

В репозитории QMClient по тегу v* CI публикует GitHub Release: статический qmclient-linux-amd64, архив, install.sh, unit-файлы qmclient.service, qmclient.timer, qmclient-supervise.service, контрольные суммы. При собственном зеркале достаточно отдавать те же имена файлов по HTTPS.

Админ в QMAdmin получает одну готовую команду: curl …/install.sh | bash -s -- с --dedicated-id, --envelope; --api-url не подставляется, если собранная панель указывает на тот же базовый URL API, что и константа по умолчанию (https://api.qx-dev.ru/api/v1 — см. QMSERVER_API_URL при сборке QMAdmin и QMCLIENT_DEFAULT_PUBLIC_API_BASE в qmclient-install.ts). Свой API: --api-url или QMSERVER_URL на хосте. Установка от root, без вставки sudo в однострочник. Нужен systemd.

• Флаг --with-supervise в скрипте устарел: supervise-юнит подключается всегда, если соответствующий unit-файл есть в поставке (systemctl enable --now выполняет установка и обновление).

URL скрипта в однострочнике собирается в QMAdmin из src/lib/qmclient-install.ts (по умолчанию — шаблоны github.com/.../releases/...; при необходимости переопределите VITE_QMCLIENT_GITHUB_REPO и VITE_QMCLIENT_RELEASE_TAG под свой хостинг).

Краткий README в репозитории агента ведёт на эту страницу; детали — ниже и в соседних разделах QMDocs.

Обновление исполняемого файла и unit-файлов

После первой установки файл /opt/qmclient/qmclient.conf не нужно пересоздавать для обновления агента.

• На хосте (root): qmclient -upgrade — скачивает исполняемый файл и юниты с настроенного источника (по умолчанию GitHub Releases API для github.com, если QMCLIENT_GITHUB_REPO указывает на репозиторий там), затем daemon-reload, systemctl enable --now для qmclient.timer и qmclient-supervise.service (если файл есть), плюс разовый запуск скана (qmclient.service).
• Опционально фиксированная версия: qmclient -upgrade -upgrade-tag qmclient/v1.0.0 (или другой тег в вашей схеме именования).
• Репозиторий и тег по умолчанию читаются из /opt/qmclient/qmclient.conf: QMCLIENT_GITHUB_REPO, QMCLIENT_RELEASE_TAG (если не заданы — значения по умолчанию из установки, часто mindevis/QMClient и latest).
• Через скрипт: curl -fsSL …/install.sh | bash -s -- --upgrade (опционально --tag).

В QMAdmin на странице выделенного хоста (при подключённом агенте) дублируются готовые команды для копирования.

Режим supervise (Minecraft и очередь задач)

Только Linux x86_64. Агент в цикле вызывает GET …/agent/dedicated-servers/:id/supervisor, получает список задач и для каждой выполняет действие, затем POST …/supervisor/tasks/:id/result.

Minecraft: start / stop / restart

В каталоге инстанса (как в профиле QMServer: work_dir + data_subdir) должен быть исполняемый run.sh.

• Запуск: qmclient -supervise с теми же параметрами, что и для скана (-api, -dedicated-id, -envelope) или через переменные из /opt/qmclient/qmclient.conf (типичный ExecStart в qmclient-supervise.service).
• Интервал опроса API: -supervise-interval (секунды) или QMCLIENT_SUPERVISE_INTERVAL (не меньше 2).
• Процесс: run.sh стартует в новой сессии (setsid); stdout/stderr пишутся в <instance>/.qmclient/console.log, PID лидера сессии — <instance>/.qmclient/minecraft.pid. Остановка идёт сигналами группе процессов (SIGTERM, при необходимости SIGKILL).
• QMAdmin ставит в очередь команды start / stop / restart для профилей Minecraft. Хвост лога отправляется POST …/supervisor/console (пока в панели включён опрос лога).

Прочие действия в той же очереди

action	Назначение
install_cs16	SteamCMD: установка HLDS + cstrike в каталог инстанса (под work_dir).
provision_mc	Создание/проверка каталога Minecraft (server.properties и т.д.).
remove_instance	Остановка отслеживаемого JVM-процесса по .qmclient/minecraft.pid (если есть), удаление дерева каталога инстанса (data_subdir). Не трогает общий SteamCMD, кроме случая, когда в задаче выставлен флаг remove_steamcmd — тогда после удаления инстанса удаляется work_dir/SteamCMD (если каталога нет, шаг считается успешным).

Задачи remove_instance ставит QMServer при удалении профиля из админки с опцией «удалить с хоста»; запись профиля в БД к этому моменту может быть уже удалена — путь инстанса передаётся в задаче снимком (instance_subdir).

Скан по таймеру и supervise — независимые процессы: timer продолжает вызывать одноразовый qmclient без -supervise.

Эвристики сканирования (кратко)

• minecraft — наличие server.properties, порт из server-port= (по умолчанию 25565).
• goldsrc (в т.ч. CS 1.6) — каталоги/файлы вроде cstrike, hlds_run и т.п.
• unknown — остальное; порт может быть неизвестен до ручной привязки в панели.

Переменные в /opt/qmclient/qmclient.conf

Переменная	Назначение
QMSERVER_URL	База API, например https://api.example/api/v1
DEDICATED_SERVER_ID	Id выделенного сервера в QMAdmin
AGENT_TOKEN_ENVELOPE	Base64-конверт из QMAdmin; QMClient расшифровывает при запуске (единственный поддерживаемый способ)

Опционально:

Переменная	Назначение
WORK_DIR	Переопределить каталог сканирования (-work-dir)
QMCLIENT_SUPERVISE_INTERVAL	Интервал опроса supervise в секундах
QMCLIENT_GITHUB_REPO	owner/repo для -upgrade и скрипта --upgrade (форк)
QMCLIENT_RELEASE_TAG	Тег релиза вместо latest при обновлении (latest или qmclient/v…)

Репозиторий

QMClient — отдельный Git-репозиторий; workflow релиза: .github/workflows/release-qmclient.yml (теги v*).