Перейти к содержимому

Архитектура

← Назад к оглавлению документации

Minecraft Server Manager — это однопроцессное, рендерируемое на стороне сервера приложение Node.js. Оно управляет серверами Minecraft, работающими как Docker-контейнеры, используя образ itzg/docker-minecraft-server, взаимодействуя с Docker daemon через его API (никогда путем вызова docker CLI).

  • Express + Handlebars рендерят страницы на стороне сервера. SPA отсутствует; JavaScript браузера в public/js/ является написанным вручную прогрессивным улучшением. Шаг esbuild (pnpm run build:js) собирает и минифицирует его в public/dist/js/; приложение обслуживает этот бандл при его наличии, а исходный код в противном случае, так что разработка без сборки также работает.
  • node:sqlite (встроен в Node; панель требует Node ≥ 24) — это база данных; синхронная, без нативных модулей, в режиме WAL. Небольшой менеджер версионированных миграций применяет src/db/migrations/* при загрузке. Подготовленные выражения кэшируются в src/db/index.js по текстовому ключу SQL.
  • ws обеспечивает потоки живой консоли и статистики. Оба брокеруются: один исходящий поток docker logs --follow (или docker stats) на сервер, демультиплексируемый один раз и рассылаемый на каждую подключенную вкладку, вместо одного исходящего потока на каждого зрителя. Брокер консоли хранит небольшой буфер повтора для поздно присоединившихся вкладок и отключает подписчика, чей сокет отстает слишком сильно, вместо того чтобы замедлять общий поток.
  • dockerode — единственный способ взаимодействия приложения с Docker. Конечная точка определяется автоматически для каждой платформы (именованный канал Windows против Unix-сокет).
  • Все постоянное состояние хранится в одной директории ($DATA_DIR, по умолчанию ./data). Копирование этой директории мигрирует всю панель.

Зависимости текут в одном направлении:

┌─────────────────────────────┐
HTTP ───────▶│ web/routes/* (+ middleware)│ парсинг и валидация ввода, формирование ответов
└──────────────┬──────────────┘
│
┌──────────────▼──────────────┐
│ services/* │ логика предметной области (реальные функции)
└───┬─────────┬─────────┬─────┘
│ │ │
┌────────────▼──┐ ┌────▼────┐ ┌──▼──────────┐
│ docker/* │ │ db/* │ │ storage/* │ инфраструктура
└───────────────┘ └─────────┘ └─────────────┘
  • web/routes/ — по одному маршрутизатору на домен (players, worlds, crashes, blueprints, files, …). web/app.js монтирует верхнеуровневые маршрутизаторы (api.js, JSON API сессии, который также содержит основные маршруты сервера и монтирует доменные маршрутизаторы для каждого сервера; index.js, страницы; auth, account, tasks, …). Маршрутизаторы валидируют с помощью zod, вызывают сервис и возвращают JSON или рендерят представление. Бизнес-логика здесь не должна находиться. Два маршрутизатора монтируются в общей зоне, перед requireAuth: routes/status.js (опциональные HTML-страницы статуса для каждого сервера) и routes/apiV1.js (/api/v1, JSON API только для чтения, аутентифицированный токеном Bearer, выданным администратором из services/apiTokens.js, отключен по умолчанию; см. docs/public-api.md).
  • services/ — сердце приложения. Каждый сервис отвечает за одну предметную область и может зависеть от инфраструктуры и других сервисов.
  • docker/ — обертки dockerode: connect (определение конечной точки + состояние демона), containers (создание/запуск/остановка/пересоздание с bind mounts, ограничениями памяти/CPU и метками), logs, stats, images, networks (обнаружение сетевых подключений хоста), hostPath (перенаправление bind путей под DATA_DIR_HOST) и watcher, который преобразует события Docker в историю + обнаружение сбоев.
  • db/ — обертка SQLite и менеджер миграций.
  • storage/ — начальная загрузка ./data, защита путей (safeJoin, основа безопасности файлов) и фоновый индексатор размеров + контроль квот.

Сквозные аспекты:

  • config/ — конфигурация окружения плюс каталог полей: единственный источник истины для настроек сервера. Каждая переменная окружения itzg каталогизирована (метка, справка, тип, единица измерения, значение по умолчанию, валидация, раздел, флаги опасности). Мастер настройки, формы настроек и валидация zod выводятся из него, поэтому добавление новой настройки — это изменение данных, а не новая инфраструктура пользовательского интерфейса.
  • events/ — recordEvent() — единственная точка входа для журнала истории; события жизненного цикла также захватывают фрагменты логов контейнера в data/logs/<id>/events/.
  • ws/ — аутентифицированные WebSockets консоли + статистики (проверка cookie сессии при обновлении, проверка Origin для блокировки межсайтовых атак), брокеруемые на сервер (см. “Структура во время выполнения”).
  • logger.js + instrument.js — require('./logger')(label) возвращает Pino логгер для каждого модуля; уровень из LOG_LEVEL, makeFailureThrottle() поддерживает постоянно сбоящий фоновый цикл до одной строки лога плюс строку “восстановлено”. src/utils/logSanitize.js удаляет из структурированных метаданных ключи, похожие на учетные данные, и токены веб-хуков; src/config/logLevel.js — общий список допустимых уровней (вынесен отдельно, чтобы избежать цикла зависимостей с config). src/instrument.js — неактивный шов Sentry, загружаемый первым в src/server.js. src/web/middleware/requestLog.js записывает одну строку access-лога для каждого запроса (пропуская /healthz и статические файлы). ESLint принудительно применяет no-console в src/**, с исключениями для preflight.js, instrument.js и config/index.js (они выполняются до существования логгера).
  • Ограничение скорости — src/web/middleware/rateLimit.js помещает express-rate-limit перед /api (RATE_LIMIT_API_PER_MIN, по умолчанию 1200) и POST-запросами входа / 2FA / настройки (RATE_LIMIT_AUTH_PER_15MIN, по умолчанию 100); 0 отключает ограничитель. Он использует req.ip в качестве ключа, поэтому TRUST_PROXY имеет значение при работе за прокси. /api/v1 имеет свои собственные ограничители: ограничение на клиента (в пять раз больше бюджета на токен), которое выполняется до проверки токена, затем бюджет на токен (RATE_LIMIT_PUBLIC_API_PER_MIN, по умолчанию 120) с ключом по идентификатору проверенного токена. Отдельный мягкий счетчик на аккаунт в src/web/middleware/auth.js обрабатывает блокировку входа (по IP и глобально по аккаунту, с затуханием).
  • Авторизация: два уровня. Глобальная роль (requireAuth → requireRole / requireWrite в src/web/middleware/auth.js) контролирует действия по всей панели и является значением по умолчанию для каждого сервера. Разрешения для каждого сервера (src/services/permissions.js, девять возможностей, хранящихся в виде JSON-списка для каждого (пользователь, сервер) в user_server_permissions) уточняют это значение по умолчанию для одного сервера; каждый маршрут /api/servers/:id, монтирование подмаршрутизатора, страница, WebSocket и список по всему флоту проходят через src/web/middleware/serverAccess.js (serverScope, смонтированный на префиксе /servers/:id как API, так и маршрутизатора страниц, скрывает сервер без view как 404; requireCap(cap) называет возможность, необходимую маршруту). Записи, которые называют свой сервер в теле запроса (расписания, извлечение и установка мира, экспорт чертежей), открыты для зрителей только requireWrite для этого сервера, и каждый такой маршрут сам проверяет возможность. test/permissions-routes.test.js обходит стеки живых маршрутизаторов и выдает ошибку, если маршрут записи, монтирование или страница, связанные с сервером, не имеют ограничения.
  • Модпаки всегда закреплены. Образ автоматически обновляет незакрепленные пакеты при каждом перезапуске, поэтому панель разрешает “latest” в конкретный идентификатор версии во время установки и закрепляет его. Обновления — это явный оркестрованный поток (updates/): предварительный просмотр → резервное копирование перед обновлением → плавное завершение → перепривязка → пересоздание → монитор работоспособности → откат в один клик.
  • Оверлей пользовательских модов управляется панелью: добавленные пользователем моды попадают в дедуплицированную библиотеку и жестко связаны с сервером, поэтому они переживают обновления пакетов. Отключение зависит от класса. Поскольку библиотека хранит каждую загруженную сборку, обновление записывает замененную сборку (server_content.previous_*) и может быть восстановлено только из локальных файлов. Отключение мода пакета записывает переменную окружения исключения пакета вместо этого; packs.applyPack передает это и остальную часть настройки пакета (PACK_TUNING_KEYS) при изменении версии того же пакета и удаляет ее при изменении пакета.
  • Обновление версии Minecraft должно быть заслужено. services/compat.js сканирует моды сервера — разрешенные из строк, установленных панелью, затем манифеста пакета CurseForge, затем по хэшу содержимого против Modrinth/CurseForge — и строит матрицу поддержки (загрузчик, версия Minecraft) для каждого проекта из latestFilesIndexes CurseForge (200 проектов на запрос) и списка версий Modrinth для каждого проекта (один запрос на проект, что и сохраняет пару загрузчик-версия). Проверка обновлений предлагает только самую новую версию, которую поддерживают ВСЕ моды, и ничего не предлагает вообще, когда ответ не может быть установлен: нет сканирования, сканирование для другой версии или загрузчика, которое никогда не завершилось, или jar, который ни один реестр не распознает. Сканирование выполняется только вручную, и его прогресс и частичные результаты хранятся в version_compat (а не в services/tasks.js в памяти), поэтому обновление или перезапуск панели возобновляет работу вместо зависания на индикаторе; reconcileScans() помечает сканирования, оставшиеся без владельца после выключения, при следующей загрузке.
  • Версия загрузчика модов — это закрепление, как и все остальное. services/loaderPin.js считывает установленную сборку из собственного манифеста установки образа (.forge-manifest.json и аналогичные) и записывает закрепление: переменную itzg загрузчика на обычном сервере (FORGE_VERSION, …), или CF_MOD_LOADER_VERSION на пакете CurseForge Forge или Fabric, который переопределяет версию, указанную в пакете. Установщик CurseForge образа игнорирует это переопределение для NeoForge, а пакеты Modrinth и FTB не имеют его, поэтому их загрузчик следует за пакетом. packs.applyPack удаляет все переменные CF_ при обновлении или откате пакета, что удаляет переопределение вместе с остальным. Типизированная сборка сначала проверяется по полному списку реестра (services/loaderVersions.js; Forge берется из его метаданных maven, которые пропускают числа; пропущенный элемент проверяется еще раз против самого реестра), затем изменение проходит через резервное копирование → закрепление (над переменной окружения после резервного копирования) → пересборку.
  • Порты выделяются из базовой схемы (игра от PORT_GAME_START и выше, RCON = игра + PORT_RCON_OFFSET, Bedrock от PORT_BEDROCK_START), проверяются на доступность и резервируются в БД. “Занято” — это объединение всех претензий каждого сервера (активные порты плюс ожидающая пара ниже), всех портов хоста, которые публикует любой Docker-контейнер (containers.publishedHostPorts: активные привязки запущенных контейнеров плюс настроенные для каждого остановленного контейнера, поскольку проверка привязки ОС изнутри собственного контейнера панели видит только сетевое пространство имен этого контейнера) и проверка ОС. Часть Docker кэшируется в течение 3 секунд и ограничена: список, который не отвечает в течение 2,5 секунд, отбрасывает только часть Docker, а медленный инспектирование стоит только портов этого контейнера. Создание сервера и servers.changeGamePort выбирают порты через одну цепочку сериализации, которая охватывает только выбор и его резервирование (запись строки для создания, резервирование в памяти для изменения порта); выбор портов BlueMap и переопределения дополнительных портов не входят в нее и не обращаются к Docker. Изменение порта на существующем сервере (servers.changeGamePort, под блокировкой оператора сервера) применяется сразу, поскольку Docker исправляет привязки портов при создании контейнера: новая пара (RCON всегда игра + PORT_RCON_OFFSET) проверяется и резервируется в памяти (ports.reserve, как старая, так и новая пара, учитываются при каждом другом выборе) под блокировкой порта. Она отклоняется (409 PENDING_CHANGES), пока другие настройки ожидают пересборки, поэтому она пересобирает только контейнер, который уже работал, на новом порту; и работающий сервер изменяется только тогда, когда запрос указывает restart: true (иначе 409 NEEDS_CONFIRM). Образ скачивается и проверяется имя пользовательского контейнера перед тем, как что-либо будет затронуто. Работающий сервер останавливается; затем новая пара записывается с pending_recreate = 1 (так что сбой панели после этого оставляет честное “пересборка ожидается”), контейнер удаляется, пересобирается на новой паре и запускается. Если какой-либо шаг после остановки завершается сбоем, putBackOnOldPort записывает старую пару обратно, пересобирает (и перезапускает, если он работал) на ней и записывает, какой шаг завершился сбоем; история и оповещения сообщают, если даже это завершилось сбоем, что оставляет сервер остановленным до тех пор, пока кто-нибудь его не запустит. Возможность settings достаточна, включая работающий сервер. Неадминистраторы могут выбирать только из диапазона PORT_GAME_START и выше. (Столбцы port_*_pending из миграции 029 относятся к более раннему, невыпущенному дизайну и не используются; 031 очищает их.) Столкновение блокировок отвечает 409 с code: 'BUSY', который проверяют повторно вызывающие ниже, а не текст. Автоматический перезапуск при сбое (watcher.restartAfterCrash) и запланированное резервное копирование или запуск (scheduler.runTaskWithRetry), которые обнаруживают, что сервер занят другим действием, пытаются снова каждые 20 с / 60 с до 30 минут, а обновление или откат пакета повторяет свои заблокированные шаги тем же образом (opLock.retryWhileBusy); перезапуск при сбое или ожидающий запланированный запуск прекращает работу, как только кто-то остановил, убил или запустил сервер с момента последнего действия (events.lifecycleActionSince), а перезапуск при сбое также прекращает работу, когда автоперезапуск отключен или сервер отсутствует. Запланированные перезапуски, остановки и команды не повторяются, а расписание, чей последний запуск все еще ожидает, пропускает свое следующее срабатывание.
  • Квоты диска принудительно применяются панелью, поскольку Docker не может ограничить использование bind-mount: индексатор кэширует размеры каталогов, а операции роста диска зависят от них.
  • Секреты (пароли RCON, ключи API, секреты TOTP, URL веб-хука Discord) шифруются при хранении с помощью AES-256-GCM с использованием выделенного случайного ключа в $DATA_DIR/.secret-key (режим 0600, автогенерируется). Он независим от SESSION_SECRET; ключ, производный от SESSION_SECRET, сохраняется как резервная копия только для расшифровки для значений, записанных до существования выделенного ключа, и src/services/secretsMigration.js повторно шифрует их под выделенным ключом один раз при загрузке. Существующий, но нераспарсиваемый .secret-key является критической ошибкой при загрузке (он никогда не регенерируется молча поверх существующего). Чертежи удаляют все секреты при экспорте.
  • server.properties принадлежит панели, но теневой переменными окружения. Образ itzg повторно применяет каждое свойство, основанное на переменной окружения, при каждом запуске (OVERRIDE_SERVER_PROPERTIES по умолчанию true), поэтому значение, которое панель редактирует напрямую — PvP/сложность в World Controls, переключатель списка разрешенных, редактор файлов — будет молча отменено при следующем запуске, если соответствующая переменная окружения не будет удалена и контейнер не будет пересоздан. Каждая прямая запись свойства проходит через writeServerProperties() (весь файл) или setServerProperty() (один ключ) в src/services/servers.js, которые атомарно перезаписывают файл, снимают переменную окружения для каждого измененного ключа (через атрибут prop: в полях каталога, проверяется в тестах против собственных определений свойств образа) и помечают pending_recreate. Сложность записывается как в файл, так и отправляется через RCON, потому что выделенный сервер повторно применяет свойство difficulty при каждой загрузке. Сам Minecraft повторно сохраняет server.properties из своих значений при загрузке при включении/выключении whitelist, что отменит изменения, сделанные во время работы сервера, поэтому работающий переключатель списка разрешенных сохраняет снимок файла первым и перезаписывает его, изменив только white-list. Переменные окружения остаются полностью настраиваемыми при создании (мастер настройки отображает их, и они применяются один раз); они открепляются только при первом редактировании панелью соответствующего свойства. MOTD имеет тот же контракт: прямое редактирование файла motd снимает его, поэтому последнее изменение имеет приоритет.
  • data/panel.db — база данных SQLite. Ежедневно создается снимок через VACUUM INTO в data/backups/_panel/ (сохраняется 14 последних); PRAGMA integrity_check выполняется при загрузке.
  • data/.session-secret — автоматически сгенерированный секрет для подписи cookie, создается при первом запуске, если SESSION_SECRET не установлен. Удаление этого файла меняет секрет (что аннулирует сессии).
  • data/.secret-key — выделенный 32-байтный ключ шифрования при хранении (режим 0600), автоматически создается при первом запуске. Независим от SESSION_SECRET; его удаление делает все сохраненные учетные данные нерасшифровываемыми, поэтому он должен храниться вместе с вашими резервными копиями.
  • Чертежи (.mcserver.zip) — zip-архив с manifest.json, описывающим конфигурацию, ресурсы, закрепленную ссылку на пакет, манифест оверлея (URL-адреса источников + sha256), выбранные файлы конфигурации и, опционально, мир. Импорт повторно загружает и проверяет хэш каждого мода и назначает новые порты.
  • Docker-контейнеры, созданные панелью, имеют имена и метки, чтобы наблюдатель мог их найти; панель контролирует их полный жизненный цикл.
  1. require('./instrument') (шов Sentry) прежде всего, затем require('./preflight') для четкого сообщения об ошибке при неподдерживаемой версии Node.
  2. Загрузка конфигурации; обеспечение/генерация .session-secret и .secret-key.
  3. ensureDataRoot() — создание структуры ./data, очистка tmp/.
  4. Выполнение миграций БД, затем PRAGMA integrity_check (громко логирует, указывает на data/backups/_panel в случае сбоя).
  5. Повторное шифрование устаревших секретов, зашифрованных ключом SESSION_SECRET, под .secret-key (secretsMigration).
  6. Единовременный импорт ключей API из окружения (apiKeys.importFromEnvOnce()), закрепление любого сервера, который все еще использует незакрепленный селектор модпака (packPins.pinUnpinnedServers()), пометка сканирований совместимости версий, оставленных запущенными предыдущим процессом, как прерванные (compat.reconcileScans()), затем заполнение начальных чертежей (защищено).
  7. Запуск HTTP + WS сервера. При открытом бинде выводит PIN-код /setup для первого запуска.
  8. Установка защитного механизма среды выполнения после загрузки (перехватывает необработанные ошибки; MSM_EXIT_ON_FATAL=1 обеспечивает жесткий выход для управляемых развертываний).
  9. Запуск фоновых служб: брокер WS, индексатор хранилища, наблюдатели за сбоями + инвентарем, планировщик, мост событий Discord, наблюдатель за исходящими сообщениями чат-бота и ежедневный таймер обслуживания (удаление старых строк аналитики, стенограмм чат-бота, истории событий (365 дней) и строк кэша API, затем создание снимка panel.db).
  10. Инициализация Docker в фоновом режиме. Интерфейс полностью функционален, пока демон недоступен; функции Docker активируются, когда он становится доступен. После подключения refreshStatuses({ boot }) согласует кэшированные статусы, выдает однократное событие offline-after-restart для сервера, который был запущен до перезапуска панели и не будет запущен снова, и цикл загрузки запускает серверы auto_start, а также восстанавливает серверы auto_restart, найденные сбойными во время простоя (с учетом задержки цикла сбоев).

Порядок instrument-before-preflight — это сознательный компромисс: он позволяет будущему исправлению Sentry сначала исправить среду выполнения, за счет немного менее дружелюбного сообщения при очень старой версии Node.

pnpm run build = build:css (Tailwind → public/css/app.css) + build:js (esbuild → public/dist/js/, ESM с разделением кода). postinstall выполняет только CSS. public/css/app.css и public/dist/ являются артефактами сборки, игнорируемыми git; этап сборки Dockerfile выполняет полный pnpm run build и копирует public/ в образ среды выполнения. Статические файлы обслуживаются с immutable/длительным кэшированием для файлов с отпечатками, коротким кэшированием для CSS/JS и no-cache для HTML и /api.