Skip to main content
Version: Next

QMWeb

Публичный сайт в стилистике Minecraft: лендинг, регистрация, вход и личный кабинет. Использует тот же QMServer, что и QMAdmin; отличие в том, что у пользователя нет админских прав в API.

Исходники и релизы: QMWeb на GitHub — README / README_EN, CHANGELOG / CHANGELOG_EN, install.sh, ghcr.io/<owner>/qmweb.

Для публичных запросов к части эндпоинтов на QMServer должна быть включена интеграция QMWeb (QMAdmin → Интеграции). Иначе, например, GET /settings/referral и GET /settings/inventory-sync возвращают 404; POST /inventory (QXSync) на QMServer принимается только при QMWeb и модуле Minecraft. При 404 с текстом в detail об отключённой интеграции интерфейс показывает понятное сообщение. Если выключены обе интеграции (и QMLauncher, и QMWeb), публичный GET /servers может отдавать пустой список — см. QMServer — интеграции.

Технологии​

  • React 19, React Router 7, TypeScript, Vite 7
  • ESLint + Prettier
  • Шрифты в духе minecraft.net: Noto Sans, Minecraft Ten, Minecraft Seven (см. public/fonts/)

Функции для пользователя​

  • Главная страница
  • Регистрация и вход (JWT от QMServer; в Cloud при включённой интеграции Removed auth stack — также вход через Removed auth stack, см. ниже)
  • Личный кабинет / дашборд
  • Профиль (PATCH /auth/profile, привязка Ely.by через редиректы API)
  • Список серверов (GET /servers) — публичный список включённых профилей с онлайном
  • Контент с API: новости (GET /news), при необходимости публичные настройки (например GET /settings/inventory-sync, skin-providers, MSA для лаунчера — по мере того, как фронтенд их использует)
  • Скины: отображение через URL API и/или GET /skins/proxy для обхода CORS в браузере

Администрирование серверов, модов и генерация секретных ключей выполняется в QMAdmin, не на публичном сайте.

Домен​

web.qx-dev.ru

Дизайн​

  • Тёмная тема, зелёные акценты
  • Адаптивная вёрстка

Шрифты (обновление)​

npm install @mojang/web-theme-bootstrap --save-dev
cp node_modules/@mojang/web-theme-bootstrap/assets/fonts/*.woff2 node_modules/@mojang/web-theme-bootstrap/assets/fonts/*.woff node_modules/@mojang/web-theme-bootstrap/assets/fonts/*.ttf public/fonts/
npm uninstall @mojang/web-theme-bootstrap

Сборка​

cd QMWeb
npm install   # или npm ci
npm run build

Продакшен: сборка подтягивает данные предметов/локалей, затем tsc и vite build (минификация, dist/). В Dockerfile — npm ci, NODE_ENV=production только на шаге npm run build.

CI, образ GHCR и релизы статики​

В репозитории QMWeb (или в монорепозитории — .github/workflows/build-qmweb-image.yml) на push в main публикуется образ ghcr.io/<owner>/qmweb (linux/amd64, теги latest, digest по коммиту). GitHub Release со статикой qmweb-*-dist.tar.gz и .sha256 создаётся только при push git-тега vX.Y.Z (строгий semver, без суффиксов).

При сборке задаются QMSERVER_API_URL и VITE_LAUNCHER_DOWNLOAD_URL (как в Docker).

Скрипт install.sh​

Отдельный сервер под Linux x86_64: install.sh (raw) — --native (статика в /opt/qmweb/html, nginx из deploy/nginx/qmweb-site.conf) или --docker (образ GHCR, по умолчанию ~/qmweb). Переменные QMWEB_*, GITHUB_TOKEN для приватных репозиториев — см. install.sh --help.

curl -fsSL https://raw.githubusercontent.com/mindevis/QMWeb/main/install.sh | sudo bash -s -- --native
curl -fsSL https://raw.githubusercontent.com/mindevis/QMWeb/main/install.sh | bash -s -- --docker

Сообщения коммитов​

В репозитории QMWeb: commit-template.txt (Conventional Commits), как у QMServer / QMAdmin — git config commit.template commit-template.txt.

Переменные окружения​

Задаются в .env для локальной сборки или как build-arg / ENV в Dockerfile (см. .env.example в репозитории QMWeb). В Vite включено envPrefix: ['VITE_', 'QMSERVER_']: в бандл попадают и QMSERVER_API_URL, и переменные с префиксом VITE_.

ПеременнаяОписание
QMSERVER_API_URLБазовый URL QMServer API (вшивается при сборке), обычно .../api/v1
VITE_LAUNCHER_DOWNLOAD_URL(Необязательно) путь или URL к установщику лаунчера для кнопок на сайте; по умолчанию относительный путь под статикой
VITE_ADMIN_URL(Необязательно) ссылка «Админка» в шапке; по умолчанию продакшен-домен админки
VITE_LEGACY_ENV_(Cloud, PKCE) Точный redirect_uri для OAuth2 Removed auth stack; по умолчанию https://<origin>/login. Должен входить в LEGACY_ENV_ на QMServer.

См. также: Развёртывание (Ely.by redirect на ELY_FRONTEND_REDIRECT указывает на этот сайт после OAuth).

Вход через Removed auth stack (Cloud)​

При включённой интеграции Removed auth stack на QMServer:

  1. Прямой вход — кнопка вызывает POST /api/v1/modules/legacy-auth/auth/login; токен сохраняется как сессия QMWeb (тот же механизм, что обычный логин).
  2. OAuth2 PKCE (рекомендуется при отключённом пароле QMServer для учётки) — страница /login/legacy-auth: после ввода учётных данных Removed auth stack браузер переходит по redirect_url с QMServer, затем callback на /login с ?code= и ?state=, обмен кода на JWT и редирект в личный кабинет.

Эндпоинты и переменные LEGACY_ENV_*: см. QMServer — Removed auth stack OAuth2 PKCE. Публичный портал Removed auth stack (отдельный сервис в стеке): https://auth.qx-dev.ru — см. Развёртывание.