Architektura
Minecraft Server Manager je jednoprocesová, serverově renderovaná Node.js aplikace. Spravuje
Minecraft servery běžící jako Docker kontejnery pomocí obrazu
itzg/docker-minecraft-server, komunikuje s Docker
daemonem přes jeho API (nikdy nevolejte docker CLI).
Architektura za běhu
Sekce “Architektura za běhu”- Express + Handlebars renderují stránky na straně serveru. Nejedná se o SPA; prohlížečový JS v
public/js/je ručně psané progresivní vylepšení. Krok esbuild (pnpm run build:js) jej spojí a zmenší dopublic/dist/js/; aplikace obsluhuje tento balíček, když je přítomen, a syrový zdroj jinak, takže vývojový běh bez sestavení stále funguje. node:sqlite(vestavěný v Node; panel vyžaduje Node ≥ 24) je databáze - synchronní, bez nativních modulů, režim WAL. Malý verzovaný runner migrací aplikujesrc/db/migrations/*při startu. Připravené příkazy jsou cachovány vsrc/db/index.jss klíčem podle textu SQL.wspřenáší živé streamy konzole a statistik. Oba jsou zprostředkované: jeden upstreamdocker logs --follow(nebodocker stats) na server, jednou demuxovaný a rozeslaný do každé připojené karty, spíše než jeden upstream na prohlížeče. Broker konzole udržuje malou vyrovnávací paměť pro pozdní připojení a zahodí odběratele, jehož soket zaostává příliš daleko, místo aby zpomalil sdílený stream.- dockerode je jediný způsob, jak aplikace komunikuje s Dockerem. Koncový bod je automaticky detekován podle platformy (pojmenovaná pipe ve Windows vs. unixový soket).
- Veškerý trvalý stav žije pod jedním adresářem (
$DATA_DIR, výchozí./data). Kopírování tohoto adresáře migruje celý panel.
Vrstvení
Sekce “Vrstvení”Závislosti tečou jedním směrem:
┌─────────────────────────────┐ HTTP ───────▶│ web/routes/* (+ middleware)│ parsuje a validuje vstup, tvaruje odpovědi └──────────────┬──────────────┘ │ ┌──────────────▼──────────────┐ │ services/* │ doménová logika (skutečné funkce) └───┬─────────┬─────────┬─────┘ │ │ │ ┌────────────▼──┐ ┌────▼────┐ ┌──▼──────────┐ │ docker/* │ │ db/* │ │ storage/* │ infrastruktura └───────────────┘ └─────────┘ └─────────────┘web/routes/- jeden router na doménu (players,worlds,crashes,blueprints,files, …).web/app.jspřipojuje ty nejvyšší úrovně (api.js, JSON API pro relace, které také drží hlavní serverové routy a připojuje doménové routy pro jednotlivé servery;index.js, stránky;auth,account,tasks, …). Routy validují pomocí zod, volají službu a vracejí JSON nebo renderují pohled. Obchodní logika sem nepatří. Dva routry jsou připojeny v veřejné zóně, předrequireAuth:routes/status.js(volitelné HTML stavové stránky pro jednotlivé servery) aroutes/apiV1.js(/api/v1, JSON API pouze pro čtení ověřené administrátorem vydaným Bearer tokenem zservices/apiTokens.js, vypnuté, pokud není povoleno v Nastavení; vizdocs/public-api.md).services/- srdce aplikace. Každá služba vlastní jednu doménu a může záviset na infrastruktuře a na jiných službách.docker/- obaly pro dockerode:connect(detekce koncového bodu + stav daemonu),containers(vytváření/spouštění/zastavování/re-vytváření s bind mounty, limity paměti/CPU a štítky),logs,stats,images,networks(objevování hostitelské sítě),hostPath(přesměrování bind cest podDATA_DIR_HOST) awatcher, který převádí události Dockeru na historii + detekci pádů.db/- obal SQLite a runner migrací.storage/- bootstrap./data, strážce cest (safeJoin, páteř bezpečnosti souborů) a indexátor velikosti na pozadí + vynucování kvót.
Průřezové:
config/- konfigurace prostředí plus katalog polí: jediný zdroj pravdy pro nastavení serveru. Každá itzg proměnná prostředí je katalogizována (štítky, nápověda, typ, jednotka, výchozí, validace, sekce, příznaky nebezpečí). Průvodce, formuláře nastavení a validace zod jsou všechny odvozeny z něj, takže zpřístupnění nového nastavení je změna dat, nikoli nové potrubí UI.events/-recordEvent()je jediný vstupní bod pro log historie; události životního cyklu také zachycují úryvky logů kontejneru dodata/logs/<id>/events/.ws/- ověřené WebSockety pro konzoli + statistiky (ověření cookie relace při upgradu, kontrolaOriginpro zablokování útoků přes weby), zprostředkované na server (viz “Architektura za běhu”).logger.js+instrument.js-require('./logger')(label)vrací modulární Pino logger; úroveň zLOG_LEVEL,makeFailureThrottle()udržuje trvale selhávající smyčku na pozadí na jeden řádek logu plus řádek “obnoveno”.src/utils/logSanitize.jsodstraňuje klíče ve tvaru pověření a tokeny webhooků ze strukturovaných metadat;src/config/logLevel.jsje sdílený povolený seznam úrovní (držený odděleně, aby se zabránilo cyklu vyžadování sconfig).src/instrument.jsje neaktivní šev Sentry, načtený první vsrc/server.js.src/web/middleware/requestLog.jszapisuje jeden řádek access-logu na požadavek (vynechává/healthza statická aktiva). ESLint vynucujeno-consolepodsrc/**, spreflight.js,instrument.jsaconfig/index.jsjako výjimkami (běží před existencí loggeru).- Omezení rychlosti -
src/web/middleware/rateLimit.jsumisťujeexpress-rate-limitpřed/api(RATE_LIMIT_API_PER_MIN, výchozí 1200) a přihlašovací / 2FA / nastavovací POSTy (RATE_LIMIT_AUTH_PER_15MIN, výchozí 100);0omezovač vypne. Klíčuje nareq.ip, takžeTRUST_PROXYje důležité za proxy./api/v1má své vlastní omezovače: limit na klienta IP (pětinásobek rozpočtu na token), který běží před ověřením tokenu, pak rozpočet na token (RATE_LIMIT_PUBLIC_API_PER_MIN, výchozí 120) s klíčem podle ID ověřeného tokenu. Samostatný měkký čítač na účet vsrc/web/middleware/auth.jszpracovává uzamčení přihlášení (na IP a globálně na účet, rozpadající se). - Autorizace: dvě vrstvy. Globální role (
requireAuth→requireRole/requireWritevsrc/web/middleware/auth.js) řídí akce v celém panelu a je výchozí na každém serveru. Oprávnění na server (src/services/permissions.js, devět schopností uložených jako JSON seznam na(uživatel, server)vuser_server_permissions) zpřesňuje tuto výchozí hodnotu pro jeden server; každý směrovač/api/servers/:id, připojený podsměrovač, stránka, WebSocket a seznam napříč flotilou procházísrc/web/middleware/serverAccess.js(serverScope, připojený na prefix/servers/:idjak API, tak směrovače stránek, skrývá server bezviewjako 404;requireCap(cap)pojmenovává schopnost, kterou požadavek potřebuje). Zápisy, které pojmenovávají svůj server v těle (plány, extrakce a instalace světa, export blueprintů), jsou otevřeny pro prohlížeče pouze pomocírequireWritepro daný server, a každý takový požadavek sám kontroluje schopnost.test/permissions-routes.test.jsprochází živé zásobníky směrovačů a selže, pokud zápisový požadavek, připojení nebo stránka vázaná na server nemá bránu.
Klíčové chování domény
Sekce “Klíčové chování domény”- Modpacky jsou vždy připnuté. Obraz automaticky upgraduje nepřipnuté balíčky při každém restartu, takže
panel při instalaci vyřeší “nejnovější” na konkrétní ID verze a připne jej. Upgrady jsou explicitní orchestrace
(
updates/): náhled → záloha před aktualizací → plynulé zastavení → re-pin → re-vytvoření → monitor stavu → vrácení jedním kliknutím. - Překryvná vrstva vlastních modů je spravována panelem: uživatelem přidané mody přistanou do deduplikované knihovny a
jsou pevně propojeny se serverem, takže přežijí aktualizace balíčku. Zakázání je třídně uvědomělé. Protože
knihovna uchovává každou sestavu, kterou stáhla, aktualizace zaznamená sestavu, kterou nahradila
(
server_content.previous_*) a lze ji vrátit pouze z lokálních souborů. Zakázání modu balíčku zapíše proměnnou prostředí pro vyloučení balíčku místo toho;packs.applyPackpřenáší tuto a zbytek ladění balíčku (PACK_TUNING_KEYS) přes změnu verze stejného balíčku a zahodí ji při změně balíčku. - Upgrade verze Minecraftu musí být zasloužený.
services/compat.jsprohledá mody serveru - vyřešené z řádků nainstalovaných panelem, pak z manifestu balíčku CurseForge, pak podle hashe obsahu proti Modrinth/CurseForge - a sestaví matici podpory (loader, verze Minecraftu) na projekt zlatestFilesIndexesCurseForge (200 projektů na požadavek) a seznam verzí Modrinth na projekt (jeden požadavek na projekt, což udržuje loader a verzi spárované). Kontrolka aktualizací nabízí pouze nejnovější verzi, kterou PODPORUJE KAŽDÝ mod, a nenabízí nic, když odpověď nelze stanovit: žádné skenování, skenování pro jinou verzi nebo loader, které nikdy neskončilo, nebo jar, který žádný registr nerozpozná. Skenování je pouze manuální a jeho průběh a částečné výsledky žijí vversion_compat(nikoli v pamětiservices/tasks.js), takže obnovení nebo restart panelu pokračuje místo zobrazení spinneru;reconcileScans()označuje skeny opuštěné vypnutím při příštím spuštění. - Verze mod loaderu je připnutí, jako všechno ostatní.
services/loaderPin.jsčte nainstalovanou sestavu z vlastního manifestu instalace obrazu (.forge-manifest.jsona podobně) a zapisuje připnutí: itzg proměnnou loaderu na běžném serveru (FORGE_VERSION, …), neboCF_MOD_LOADER_VERSIONna balíčku CurseForge Forge nebo Fabric, což přepíše verzi deklarovanou balíčkem. Instalátor CurseForge obrazu ignoruje toto přepínání pro NeoForge a balíčky Modrinth a FTB žádné nemají, takže jejich loader následuje balíček.packs.applyPackodstraní všechnyCF_proměnné při aktualizaci nebo vrácení balíčku, což spolu se zbytkem zahodí přepínání. Typovaná sestava je nejprve zkontrolována proti úplnému seznamu registru (services/loaderVersions.js; Forge pochází z jeho maven metadat, která přeskočí čísla; chybějící se znovu zkontroluje jednou proti samotnému registru), pak změna je záloha → připnutí (přes env, jak je po záloze) → přestavba. - Porty jsou alokovány ze základního schématu (hra od
PORT_GAME_STARTnahoru, RCON = hra +PORT_RCON_OFFSET, Bedrock odPORT_BEDROCK_START), testovány na dostupnost a rezervovány v databázi. “Obsazeno” je sjednocení všech nároků serveru (živé porty, plus čekající pár níže), každý hostitelský port, který jakýkoli Docker kontejner publikuje (containers.publishedHostPorts: živá propojení běžících kontejnerů plus nakonfigurovaná u každého zastaveného kontejneru, protože test bind portu zevnitř vlastního kontejneru panelu vidí pouze síťový prostor tohoto kontejneru) a test OS. Část Dockeru je cachována po dobu 3 sekund a omezena: seznam, který neodpoví za 2,5 sekundy, zahodí pouze část Dockeru a pomalá inspekce stojí pouze porty tohoto kontejneru. Vytváření serverů aservers.changeGamePortvybírají porty prostřednictvím jednoho řetězce serializace, který pokrývá pouze výběr a jeho nárok (zápis řádku pro vytvoření, rezervace v paměti pro změnu portu); BlueMapův výběr portů a přepínání dodatečných portů nejsou v něm a ne konzultují Docker. Změna portu na existujícím serveru (servers.changeGamePort, pod zámkem operací serveru) je aplikována najednou, protože Docker opravuje propojení portů při vytváření kontejneru: nový pár (RCON vždy hra +PORT_RCON_OFFSET) je zkontrolován a rezervován v paměti (ports.reserve, jak starý, tak nový pár, respektovaný každým jiným výběrem) pod zámkem portu. Je odmítnuto (409PENDING_CHANGES), zatímco ostatní nastavení čekají na přestavbu, takže přestavuje pouze kontejner, který již běžel, na novém portu; a běžící server je změněn pouze tehdy, když požadavek říkárestart: true(jinak 409NEEDS_CONFIRM). Obraz je stažen a název vlastního kontejneru je zkontrolován před jakýmkoli dotykem. Běžící server je zastaven; pak je nový pár zapsán spending_recreate = 1(takže pád panelu odtud zanechá poctivou “přestavbu čekající”), kontejner je odstraněn, přestavěn na novém páru a spuštěn. Pokud jakýkoli krok po zastavení selže,putBackOnOldPortzapíše starý pár zpět, přestaví (a restartuje, pokud běžel) na něm a zaznamená, který krok selhal; historie a upozornění říkají, zda selhalo i to, což zanechá server zastavený, dokud jej někdo nestartuje. Schopnostsettingsje dostatečná, včetně běžícího serveru. Neadministrátoři mohou vybírat pouze zPORT_GAME_STARTnahoru. (Sloupceport_*_pendingz migrace 029 patří k dřívějšímu, nevydanému designu a jsou nepoužité; 031 je vymaže.) Kolize zámku odpovídá 409 scode: 'BUSY', což opakující se volající níže kontrolují spíše než text. Automatický restart po pádu (watcher.restartAfterCrash) a naplánovaná záloha nebo start (scheduler.runTaskWithRetry), které zjistí, že server je zaneprázdněn jinou akcí, se pokoušejí znovu každých 20 s / 60 s po dobu až 30 minut, a aktualizace nebo vrácení balíčku opakuje své uzamčené kroky stejným způsobem (opLock.retryWhileBusy); restart po pádu nebo čekající naplánovaný start se vzdá, jakmile někdo server od té doby zastavil, zabil nebo spustil (events.lifecycleActionSince), a restart po pádu také, když je automatický restart vypnutý nebo server neexistuje. Naplánované restarty, zastavení a příkazy se neopakují a plán, jehož poslední běh stále čeká, přeskočí své další spuštění. - Diskové kvóty jsou vynucovány panelem, protože Docker nemůže omezit použití bind-mountů: indexátor cachuje velikosti adresářů a operace růstu disku jsou na nich blokovány.
- Tajné klíče (hesla RCON, API klíče, TOTP tajné klíče, URL Discord webhooku) jsou šifrovány v klidu pomocí AES-256-GCM s dedikovaným náhodným klíčem na
$DATA_DIR/.secret-key(režim0600, automaticky generovaný). Je nezávislý naSESSION_SECRET; klíč odvozený zSESSION_SECRETje uchováván jako záložní možnost pouze pro dešifrování pro hodnoty zapsané před existencí dedikovaného klíče asrc/services/secretsMigration.jsje při startu znovu šifruje pod dedikovaným klíčem..secret-key, který existuje, ale nelze jej analyzovat, je tvrdá chyba při startu (nikdy není tiše přegenerován). Blueprinty odstraňují všechna tajná data při exportu. server.propertiesje vlastněn panelem, ale stínován proměnnými prostředí. itzg obraz znovu potvrzuje každou vlastnost založenou na prostředí při každém startu (OVERRIDE_SERVER_PROPERTIESvýchozí hodnota je true), takže hodnota, kterou panel upravuje přímo - Ovládání světa PvP/obtížnost, přepínač whitelistu, editor souborů - by byla tiše vrácena při příštím startu, pokud by odpovídající proměnná prostředí nebyla odstraněna a kontejner znovu vytvořen. Každý přímý zápis vlastnosti procházíwriteServerProperties()(celý soubor) nebosetServerProperty()(jeden klíč) vsrc/services/servers.js, které atomicky přepisují soubor, odstraní proměnnou prostředí za každým změněným klíčem (přes atributprop:v polích katalogu, kontrolováno v testech proti definicím vlastností samotného obrazu) a označípending_recreate. Obtížnost je zapsána do souboru i poslána přes RCON, protože dedikovaný server znovu aplikuje vlastnostdifficultypři každém spuštění. Samotný Minecraft znovu ukládá server.properties ze svých hodnot při spuštění při zapnutí/vypnutíwhitelist, což by zrušilo úpravy provedené během běhu serveru, takže běžící přepínač whitelistu nejprve uloží soubor a zapíše jej zpět se změněným pouzewhite-list. Proměnné prostředí zůstávají plně konfigurovatelné při vytváření (průvodce je vykreslí a aplikují se jednou); odepnou se pouze při prvním úpravě panelu podkladové vlastnosti. MOTD má stejnou smlouvu: přímá úprava souborumotdji odepne, takže platí poslední zápis.
Datové a přenosové formáty
Sekce “Datové a přenosové formáty”data/panel.db- databáze SQLite. Denně zálohováno pomocíVACUUM INTOdodata/backups/_panel/(nejnovějších 14 uchováno);PRAGMA integrity_checkběží při startu.data/.session-secret- automaticky generovaný tajný klíč pro podepisování cookies, vytvořený při prvním spuštění, pokud jeSESSION_SECRETnenastaven. Jeho smazání otočí tajný klíč (což zneplatní relace).data/.secret-key- dedikovaný 32bajtový klíč pro šifrování v klidu (režim0600), automaticky vytvořený při prvním spuštění. Nezávislý naSESSION_SECRET; jeho smazání učiní každý uložený údaj nečitelným, takže patří k vašim zálohám.- Blueprinty (
.mcserver.zip) - zip smanifest.jsonpopisujícím konfiguraci, zdroje, připnutý odkaz na balíček, manifest překryvné vrstvy (zdrojové URL + sha256), vybrané konfigurační soubory a volitelně svět. Import znovu stáhne a ověří hash každého modu a přiřadí nové porty. - Docker kontejnery vytvořené panelem jsou pojmenovány a označeny štítky, aby je watcher mohl najít; panel vlastní jejich plný životní cyklus.
Sekvence spouštění
Sekce “Sekvence spouštění”require('./instrument')(švu Sentry) před čímkoli jiným, pakrequire('./preflight')pro jasné selhání při nepodporované verzi Node.- Načtení konfigurace; zajištění/generování
.session-secreta.secret-key. ensureDataRoot()- vytvoření rozložení./data, vymazánítmp/.- Spuštění migrací databáze, pak
PRAGMA integrity_check(hlasitě loguje, ukazuje nadata/backups/_panelpři selhání). - Znovu zašifrování všech starých tajných klíčů pod
SESSION_SECRETpod.secret-key(secretsMigration). - Jednorázový import API klíčů z prostředí (
apiKeys.importFromEnvOnce()), připnutí všech serverů stále nesoucích nepřipnutý výběr modpacku (packPins.pinUnpinnedServers()), označení skenů kompatibility verzí ponechaných běžících předchozím procesem jako přerušené (compat.reconcileScans()), pak naplnění počátečních blueprintů (chráněno). - Spuštění HTTP + WS serveru. Na vystaveném bindu vytiskne PIN pro první spuštění
/setup. - Instalace strážce běhového prostředí po spuštění (zachytává nezachycené chyby;
MSM_EXIT_ON_FATAL=1způsobí tvrdé ukončení pro spravovaná nasazení). - Spuštění služeb na pozadí: WS broker, indexátor úložiště, watchery pádů + inventáře, plánovač,
most událostí Discord, watcher pro oslovení chatbotů a denní časovač údržby (pročištění starých
řádků analytiky, přepisů chatbotů, historie událostí (365 dní) a řádků cache API, pak snapshot
panel.db). - Inicializace Dockeru na pozadí. UI je plně použitelné, zatímco daemon je dole;
funkce Dockeru se rozsvítí, jakmile se stane dosažitelným. Po připojení
refreshStatuses({ boot })synchronizuje cachované stavy, emituje jednorázovou událostoffline-after-restartpro server, který byl zapnutý před restartem panelu a nebude obnoven, a smyčka spouštění spustí serveryauto_startplus obnoví serveryauto_restartnalezené jako padlé během výpadku (s ohledem na zpětný útlum pádů).
Pořadí instrument-před-preflight je záměrný kompromis: umožňuje budoucímu drátování Sentry opravit runtime jako první, za cenu mírně méně přátelské zprávy na skutečně staré verzi Node.
Sestavovací pipeline
Sekce “Sestavovací pipeline”pnpm run build = build:css (Tailwind → public/css/app.css) + build:js (esbuild →
public/dist/js/, ESM s rozdělením kódu). postinstall spouští pouze CSS. public/css/app.css
a public/dist/ jsou artefakty sestavení ignorované v gitu; fáze sestavení Dockerfile spouští plný
pnpm run build a kopíruje public/ do runtime obrazu. Statická aktiva jsou obsluhována
immutable/dlouhá cache pro soubory s otiskem prstu, krátká cache pro CSS/JS a no-cache pro HTML a
/api.