Введение

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

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

QMLauncher, QMWeb и QMAdmin ходят в один QMServer (/api/v1); QMServer работает с MySQL. В QMAdmin включают модули (в Cloud — в т.ч. биллинг; во Free — без QMBilling) и интеграции (QMLauncher, QMWeb; в QMServer Cloud ещё Removed auth stack как встроенный OAuth). Это влияет на доступность части 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; репозитории QMServerFree (публичный) и QMServerCloud (приватный, premium-маршруты). Установка с релизов GitHub: install.sh для Cloud и Free. QXSync принимает инвентарь только при модуле Minecraft и интеграции QMWeb (см. inventory-sync)
QMAdmin	Панель для администраторов: пользователи облака, игровые и выделенные серверы, моды, новости, ключи (CurseForge, inventory sync), Ely.by. Сборка: QMSERVER_API_URL — см. переменные; установка с релизов и Docker — 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): описание архитектуры и эндпоинтов; сборка — npm run build в каталоге QMDocs

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

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

Корень qm-project — отдельный Git-репозиторий. Каталоги QMAdmin, QMClient, QMDocs, QMLauncher, QMServerCloud, QMServerFree, QMWeb подключены как субмодули (список и URL — .gitmodules). QMServerCloud обычно приватный: для 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-free)
make run-all      # up qmserver (Free) + зависимости из docker-compose.yaml
# облачный стек: make build-qmserver-cloud && make run-qmserver-cloud (образ qmserver с ghcr.io)
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