Введение

QM Project — платформа для игровой инфраструктуры: лаунчер (в т.ч. для Minecraft), единый REST API, админка, публичный сайт, агент QMClient на выделенных Linux-хостах и эта документация. Из QMAdmin ведётся учёт выделенных хостов, скан каталогов, при необходимости управление процессом Minecraft (run.sh) и логом через QMClient supervise, обновление исполняемого файла агента; в разработке — возможности на базе SteamCMD для установки и обновления игр.

Компоненты и связи

QMLauncher, QMWeb и QMAdmin ходят в один QMServer (/api/v1); QMServer работает с MySQL. В QMAdmin включают модули и интеграции (QMLauncher, QMWeb). Это влияет на доступность части API — см. QMServer. Отдельный мод/плагин (QXSync, coming soon) отправляет снимки инвентаря в QMServer при включённом модуле Minecraft и интеграции QMWeb — см. Синхронизация инвентаря.

Компонент	Назначение
QMLauncher	GUI-лаунчер (Wails), только нативно на ПК (без Docker): инстансы, моды, Microsoft-вход, опрос QMServer; релиз Linux amd64 с GitHub по тегу v* — см. QMLauncher
QMServer	Единый REST API (/api/v1), JWT, игровые аккаунты, скины, новости, настройки, модпаки на стороне сервера; только Linux x86_64; репозиторий QMServer. Установка: install.sh — см. QMServer. QXSync принимает инвентарь только при модуле Minecraft и интеграции QMWeb (см. inventory-sync)
QMAdmin	Панель для администраторов: пользователи облака, игровые и выделенные серверы, моды, новости, ключи (CurseForge, inventory sync), Ely.by. Сборка: QMSERVER_API_URL — см. переменные; install.sh, ghcr.io/<owner>/qmadmin
QMClient	Агент на Linux на выделенном хосте (только нативно: бинарник + systemd, без Docker): периодический скан work_dir, опционально --supervise (запуск/стоп/run.sh, лог в QMAdmin), qmclient --upgrade; установка из QMAdmin — см. QMClient
QMWeb	Публичный сайт и личный кабинет: те же учётные записи и API QMServer. Сборка: QMSERVER_API_URL, VITE_* — см. переменные; install.sh, ghcr.io/<owner>/qmweb
QMDocs	Статический сайт (Docusaurus 3): документация открыта; кнопка «Войти» в шапке ведёт на /login (QMServer, заголовок X-QM-Client: qmdocs). Страница /licensing (выпуск токена Pro на площадке с QMSERVER_LICENSE_ISSUER_SEED) доступна только is_super_admin. Активация у клиента — QMAdmin → Лицензия Pro и QMSERVER_LICENSE_PUBLIC_KEY. Сборка: npm run build в QMDocs

Публичный API по продакшену обычно доступен по https://api.qx-dev.ru (см. Развёртывание).

Монорепозиторий Git

Корень qm-project — отдельный Git-репозиторий. Каталоги QMAdmin, QMClient, QMDocs, QMLauncher, QMServer, QMWeb, QMDeploy подключены как субмодули (список и URL — .gitmodules). QMServer может быть приватным: для git submodule update нужен SSH и ключ в ssh-agent (ssh-add -l, проверка GitHub: ssh -T [email protected]).

git clone --recurse-submodules <URL-вашего-qm-project>
git submodule update --init --recursive

Подтянуть субмодули до последних коммитов на удалённых ветках (меняет указатели в суперрепозитории): git submodule update --remote --merge. Коммиты делайте в каталоге субмодуля, затем в корне закоммитьте обновлённый указатель субмодуля.

Каталог QXMods/ в корне не отслеживается (.gitignore).

Быстрый старт (монорепозиторий)

# В .env или .env.cloud задайте GHCR_OWNER (владелец ghcr.io — см. .env.example)
make build-all    # QMLauncher + docker compose pull qmserver (образ qmserver:latest)
make run-all      # up qmserver + зависимости из docker-compose.yaml
# облачный стек: make run-qmserver-cloud (compose docker-compose.cloud.yaml)
make deploy       # прод: rsync + сборка/запуск (QMServer из ghcr.io)

Окружения и порты продакшена — в Развёртывание.

Ссылки на окружения

Сервис	Домен (пример)
QMServer (API, Swagger)	api.qx-dev.ru
QMAdmin	admin.qx-dev.ru
QMWeb	web.qx-dev.ru
Документация	qm.qx-dev.ru