Архітектура
← Назад до індексу документації
Minecraft Server Manager — це однопроцесна, серверно-відрендерена Node.js програма. Вона керує
серверами Minecraft, які працюють як Docker-контейнери, використовуючи образ
itzg/docker-minecraft-server, взаємодіючи з
Docker daemon через його API (ніколи не викликаючи docker CLI).
Структура виконання
Section titled “Структура виконання”- 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) для кожного проекту зlatestFilesIndexesCurseForge (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, як стара, так і нова пара, враховуються кожним іншим вибором) під блокуванням порту. Вона відхиляється (409PENDING_CHANGES), поки інші налаштування чекають на перезбірку, тому вона завжди перезбирає контейнер, який вже працював, на новому порту; а запущений сервер змінюється лише тоді, коли запит вказуєrestart: true(інакше 409NEEDS_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 “Послідовність завантаження”require('./instrument')(шов Sentry) перед усім іншим, потімrequire('./preflight')для чіткого повідомлення про помилку при непідтримуваній версії Node.- Завантаження конфігурації; забезпечення/генерація
.session-secretта.secret-key. ensureDataRoot()— створення структури./data, очищенняtmp/.- Виконання міграцій БД, потім
PRAGMA integrity_check(гучно логує, вказує наdata/backups/_panelу разі збою). - Перешифрування будь-яких застарілих секретів, ключованих
SESSION_SECRET, під.secret-key(secretsMigration). - Імпорт ключів API з середовища один раз (
apiKeys.importFromEnvOnce()), закріплення будь-якого сервера, який все ще має незакріплений селектор модпаку (packPins.pinUnpinnedServers()), позначення сканувань сумісності версій, що залишилися запущеними від попереднього процесу, як перерваних (compat.reconcileScans()), потім заповнення початкових креслень (захищено). - Запуск сервера HTTP + WS. При відкритому прив’язуванні вивести PIN-код першого запуску
/setup. - Встановлення захисту середовища виконання після завантаження (перехоплює незловлені збої;
MSM_EXIT_ON_FATAL=1змушує жорстко вийти для керованих розгортань). - Запуск фонових сервісів: брокер WS, індексатор сховища, спостерігачі збоїв + інвентарю, планувальник,
міст подій Discord, спостерігач за вихідними даними чат-бота та щоденний таймер обслуговування (очищення старих рядків аналітики, транскриптів чат-бота, історії подій (365 днів) та рядків кешу API, потім створення знімка
panel.db). - Ініціалізація Docker у фоновому режимі. Інтерфейс повністю функціональний, поки демон недоступний;
функції Docker активуються, коли він стає доступним. Після підключення
refreshStatuses({ boot })узгоджує кешовані статуси, генерує одноразову подіюoffline-after-restartдля сервера, який був увімкнений до перезапуску панелі і не буде відновлений, і цикл завантаження запускає сервериauto_startплюс відновлює сервериauto_restart, знайдені збитими під час збою (з урахуванням затримки циклу збоїв).
Порядок інструментування перед перевіркою — це свідомий компроміс: він дозволяє майбутньому патчу Sentry спочатку виправити середовище виконання, за рахунок трохи менш дружнього повідомлення про справді старий Node.
Конвеєр збірки
Section titled “Конвеєр збірки”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.