Перейти до вмісту

Архітектура

← Назад до індексу документації

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 (створення/запуск/зупинка/перестворення з прив’язками, обмеженнями пам’яті/CPU та мітками), logs, stats, images, networks (виявлення мережі хоста), hostPath (переприв’язка шляхів до DATA_DIR_HOST), та watcher, який перетворює події Docker на історію + виявлення збоїв.
  • db/ — обгортка SQLite та механізм міграцій.
  • storage/ — завантаження ./data, захист шляхів (safeJoin, основа безпеки файлів) та фоновий індексатор розмірів + контроль квот.

Перехресні аспекти:

  • config/ — конфігурація середовища плюс каталог полів: єдине джерело істини для налаштувань сервера. Кожна змінна середовища itzg каталогізована (мітка, довідка, тип, одиниця виміру, значення за замовчуванням, валідація, розділ, прапори небезпеки). Майстер налаштування, форми налаштувань та валідація zod виводяться з нього, тому додавання нового налаштування — це зміна даних, а не нова логіка інтерфейсу.
  • events/ — recordEvent() — єдина точка входу для журналу історії; події життєвого циклу також захоплюють фрагменти журналів контейнерів до data/logs/<id>/events/.
  • ws/ — автентифіковані WebSocket для консолі та статистики (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 записує один рядок журналу доступу на запит (пропускаючи /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 має власні обмежувачі: обмеження на клієнта IP (вп’ятеро більше бюджету на токен), яке виконується до перевірки токена, потім бюджет на токен (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) у 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 проходить по стеках живих маршрутизаторів і видає помилку, якщо маршрут запису, змонтований або сторінка, що залежить від сервера, не має воріт.

Ключові поведінки домену

Section titled “Ключові поведінки домену”
  • Модпаки завжди закріплені. Образ автоматично оновлює незакріплені паки при кожному перезапуску, тому панель розпізнає “останню” версію як конкретний ідентифікатор версії під час встановлення та закріплює її. Оновлення — це явний оркестрований потік (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 не може обмежити використання прив’язаних файлів: індексатор кешує розміри каталогів, а операції збільшення диска обмежуються ними.
  • Секрети (паролі 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/складність елементів керування світом, перемикач білого списку, редактор файлів — буде мовчки скасовано при наступному запуску, якщо відповідна змінна середовища не буде видалена, а контейнер перестворений. Кожен прямий запис властивості проходить через writeServerProperties() (весь файл) або setServerProperty() (один ключ) у src/services/servers.js, які атомарно перезаписують файл, знімають змінну середовища за кожним зміненим ключем (через атрибут prop: у полях каталогу, перевірений у тестах проти власних визначень властивостей образу) та позначають pending_recreate. Складність записується як у файл, так і надсилається через RCON, оскільки виділений сервер повторно застосовує властивість difficulty при кожному завантаженні. Сам Minecraft повторно зберігає server.properties зі своїх значень під час завантаження при увімкненні/вимкненні whitelist, що скасує редагування, зроблені під час роботи сервера, тому перемикач білого списку, що працює, спочатку створює знімок файлу і записує його назад, змінивши лише white-list. Змінні середовища залишаються повністю конфігурованими під час створення (майстер відображає їх, і вони застосовуються один раз); вони розкріплюються лише при першому редагуванні панеллю відповідної властивості. MOTD має той самий контракт: пряме редагування файлу motd знімає його, тому останній запис виграє.

Формати даних та передачі

Section titled “Формати даних та передачі”
  • 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-контейнери, створені панеллю, іменовані та марковані, щоб спостерігач міг їх знайти; панель володіє їх повним життєвим циклом.

Послідовність завантаження

Section titled “Послідовність завантаження”
  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, знайдені збитими під час збою (з урахуванням затримки циклу збоїв).

Порядок інструментування перед перевіркою — це свідомий компроміс: він дозволяє майбутньому патчу 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.