Arkitektur
Minecraft Server Manager är en fristående, server-renderad Node.js-applikation. Den hanterar
Minecraft-servrar som körs som Docker-containrar med hjälp av
itzg/docker-minecraft-server-imagen, och kommunicerar
med Docker-demonen via dess API (aldrig genom att köra docker CLI via skalet).
Körtidsstruktur
Section titled “Körtidsstruktur”- Express + Handlebars renderar sidor på serversidan. Det finns ingen SPA; webbläsarens JS i
public/js/är handskriven progressiv förbättring. Ett esbuild-steg (pnpm run build:js) paketerar och minifierar det tillpublic/dist/js/; appen serverar det paketet när det finns och den råa källkoden annars, så en utvecklingskörning utan byggnation fungerar fortfarande. node:sqlite(inbyggt i Node; panelen kräver Node ≥ 24) är databasen – synkron, noll externa moduler, WAL-läge. En liten versionshanterad migrationskörning tillämparsrc/db/migrations/*vid uppstart. Förberedda satser cachas isrc/db/index.jsmed SQL-texten som nyckel.wshanterar live-konsol- och statistikströmmarna. Båda är förmedlade: en uppströmsdocker logs --follow(ellerdocker stats) per server, demuxad en gång och distribuerad till varje ansluten flik, snarare än en uppströms per tittare. Konsolförmedlaren behåller en liten återspelningsbuffert för sent anslutna flikar och släpper en prenumerant vars socket hamnar för långt efter, snarare än att sakta ner den delade strömmen.dockerodeär det enda sättet appen pratar med Docker. Ändpunkten upptäcks automatiskt per plattform (Windows namngiven pipe vs. unix socket).- All persistent data finns under en enda katalog (
$DATA_DIR, standard./data). Att kopiera den katalogen migrerar hela panelen.
Lagerindelning
Section titled “Lagerindelning”Beroenden flödar i en riktning:
┌─────────────────────────────┐ HTTP ───────▶│ web/routes/* (+ middleware)│ parsar & validerar input, formar svar └──────────────┬──────────────┘ │ ┌──────────────▼──────────────┐ │ services/* │ domänlogik (de faktiska funktionerna) └───┬─────────┬─────────┬─────┘ │ │ │ ┌────────────▼──┐ ┌────▼────┐ ┌──▼──────────┐ │ docker/* │ │ db/* │ │ storage/* │ infrastruktur └───────────────┘ └─────────┘ └─────────────┘web/routes/- en router per domän (players,worlds,crashes,blueprints,files, …).web/app.jsmonterar de översta nivåerna (api.js, sessionens JSON API som också innehåller kärnserver-routerna och monterar domänrouterna per server;index.js, sidorna;auth,account,tasks, …). Routrar validerar med zod, anropar en tjänst och returnerar JSON eller renderar en vy. Affärslogik hör inte hemma här. Två routrar monteras i offentliga zonen, förerequireAuth:routes/status.js(valfri HTML-status per server) ochroutes/apiV1.js(/api/v1, ett skrivskyddat JSON API autentiserat av en administratörsgenererad Bearer-token frånservices/apiTokens.js, avstängt om det inte är aktiverat i Inställningar; sedocs/public-api.md).services/- hjärtat i appen. Varje tjänst äger en domän och kan bero på infrastruktur och på andra tjänster.docker/- dockerode-inpackningar:connect(ändpunktsdetektering + demonhälsa),containers(skapa/starta/stoppa/återskapa med bind-mounts, minnes-/CPU-gränser och etiketter),logs,stats,images,networks(upptäckt av värdnätverk),hostPath(rotar om bind-vägar underDATA_DIR_HOST), och enwatchersom omvandlar Docker-händelser till historik + kraschdetektering.db/- SQLite-inpackningen och migrationskörningen.storage/-./data-bootstrappen, väktaren för sökvägar (safeJoin, ryggraden för filsäkerhet), och bakgrundsindexeraren + kvothanteringen.
Övergripande:
config/- miljökonfiguration plus katalogkatalogen: den enda sanningskällan för serverinställningar. Varje itzg-miljövariabel är katalogiserad (etikett, hjälp, typ, enhet, standard, validering, sektion, faroetiketter). Guiden, inställningsformulären och zod-valideringen härleds alla från den, så att exponera en ny inställning är en dataändring, inte ny UI-dragning.events/-recordEvent()är den enda ingångspunkten för historikloggen; livscykelhändelser fångar också utdrag från containerloggar tilldata/logs/<id>/events/.ws/- autentiserade WebSockets för konsol + statistik (sessionscookie verifierad vid uppgradering,Originkontrollerad för att blockera cross-site hijacking), förmedlad per server (se “Körtidsstruktur”).logger.js+instrument.js-require('./logger')(label)returnerar en per-modul Pino-logger; nivå frånLOG_LEVEL,makeFailureThrottle()håller en ihållande misslyckad bakgrundsslinga till en loggrad plus en “återställd” rad.src/utils/logSanitize.jsredigerar nycklar med format för autentiseringsuppgifter och webhook-token från den strukturerade metadatan;src/config/logLevel.jsär den delade nivås tillåtna lista (hålls separat för att undvika en kravcykel medconfig).src/instrument.jsär en vilande Sentry-söm, laddad först isrc/server.js.src/web/middleware/requestLog.jsskriver en åtkomstloggrad per begäran (hoppar över/healthzoch statiska tillgångar). ESLint tvingarno-consoleundersrc/**, medpreflight.js,instrument.js, ochconfig/index.jsundantagna (de körs innan loggern finns).- Rate limiting -
src/web/middleware/rateLimit.jsplacerarexpress-rate-limitframför/api(RATE_LIMIT_API_PER_MIN, standard 1200) och inloggnings- / 2FA- / inställnings-POST-begäranden (RATE_LIMIT_AUTH_PER_15MIN, standard 100);0inaktiverar en begränsare. Den nycklar påreq.ip, såTRUST_PROXYär viktigt bakom en proxy./api/v1har sina egna begränsare: ett tak per klient-IP (fem gånger budgeten per token) som körs innan token verifieras, sedan en budget per token (RATE_LIMIT_PUBLIC_API_PER_MIN, standard 120) nycklad på den verifierade tokenens ID. En separat mjuk räknare per konto isrc/web/middleware/auth.jshanterar inloggningslåsningen (per IP och globalt för kontot, avtagande). - Auktorisering: två lager. Den globala rollen (
requireAuth→requireRole/requireWriteisrc/web/middleware/auth.js) styr panelomfattande åtgärder och är standard för varje server. Behörigheter per server (src/services/permissions.js, nio kapaciteter lagrade som en JSON-lista per(användare, server)iuser_server_permissions) förfinar standarden för en server; varje/api/servers/:id-rutt, sub-router-montering, sida, WebSocket och flottomfattande listning går igenomsrc/web/middleware/serverAccess.js(serverScope, monterad på prefixet/servers/:idför både API:et och sidroutern, döljer en server utanviewsom en 404;requireCap(cap)namnger kapaciteten en rutt behöver). Skrivningar som namnger sin server i kroppen (scheman, världsextraktion och installation, blueprint-export) öppnas för tittare avrequireWriteendast för den servern, och varje sådan rutt kontrollerar kapaciteten själv.test/permissions-routes.test.jsgår igenom de levande routerstackarna och misslyckas om en server-omfattande skrivrutt, montering eller sida saknar en grind.
Viktiga domänbeteenden
Section titled “Viktiga domänbeteenden”- Modpacks är alltid fastlåsta. Imagen uppgraderar automatiskt olåsta paket vid varje omstart, så panelen löser “senaste” till ett konkret versions-ID vid installation och låser det. Uppgraderingar är ett explicit orkestrerat flöde (
updates/): förhandsgranskning → säkerhetskopiering före uppdatering → graciös stopp → om-låsning → återskapande → hälsomonitor → återställning med ett klick. - Överlagringen för anpassade moddar hanteras av panelen: användartillagda moddar hamnar i det deduplicerade biblioteket och länkas hårt in i servern så att de överlever paketuppdateringar. Inaktivering är klassmedveten. Eftersom biblioteket behåller varje nedladdad byggnation, registrerar en uppdatering den ersatta byggnationen
(
server_content.previous_*) och kan återställas från lokala filer ensam. Att inaktivera en paketmod skriver paketets exkluderingsmiljövariabel istället;packs.applyPackhanterar det och resten av paketinställningarna (PACK_TUNING_KEYS) över en versionsändring av samma paket, och tar bort det när paketet ändras. - En uppgradering av Minecraft-versionen måste förtjänas.
services/compat.jsskannar serverns moddar – lösta från panelinstallerade rader, sedan CurseForge-paketmanifestet, sedan efter innehållshash mot Modrinth/CurseForge – och bygger en (laddare, Minecraft-version) supportmatris per projekt ur CurseForgeslatestFilesIndexes(200 projekt per begäran) och Modrinths versionslista per projekt (en begäran per projekt, vilket är vad som håller laddare och version ihopkopplade). Uppdateringskontrollern erbjuder endast den nyaste versionen SOM VARJE mod stöder, och erbjuder ingenting alls när svaret inte kan fastställas: ingen skanning, en skanning för en annan version eller laddare, en som aldrig avslutades, eller en jar som ingen av registren känner igen. Skanningar är endast manuella, och deras framsteg och partiella resultat finns iversion_compat(inte i minnesbaseradeservices/tasks.js), så en uppdatering eller en panelomstart fortsätter istället för att hänga på en spinner;reconcileScans()markerar skanningar som föräldralösa vid en avstängning vid nästa uppstart. - Modladdarens version är en fastlåsning, som allt annat.
services/loaderPin.jsläser den installerade byggnationen från imagen egen installationsmanifest (.forge-manifest.jsonoch liknande) och skriver fastlåsningen: laddarens itzg-variabel på en vanlig server (FORGE_VERSION, …), ellerCF_MOD_LOADER_VERSIONpå ett Forge- eller Fabric CurseForge-paket, vilket åsidosätter den version paketet deklarerar. Imagen CurseForge-installatör ignorerar det åsidosättandet för NeoForge, och Modrinth- och FTB-paket har ingen, så deras laddare följer paketet.packs.applyPacktar bort allaCF_-variabler vid en paketuppdatering eller återställning, vilket tar bort ett åsidosättande med resten. En typad byggnation kontrolleras mot registrets fullständiga lista först (services/loaderVersions.js; Forges kommer från dess maven-metadata, som hoppar över nummer; en miss kontrolleras igen en gång mot registret självt), sedan är ändringen säkerhetskopiering → fastlåsning (över miljön som den är efter säkerhetskopieringen) → återbyggnad. - Portar allokeras från ett bas-schema (spel från
PORT_GAME_STARToch uppåt, RCON = spel +PORT_RCON_OFFSET, Bedrock frånPORT_BEDROCK_START), provas för tillgänglighet och reserveras i databasen. “Upptaget” är unionen av varje servers anspråk (live-portar, plus ett väntande par nedan), varje värdport som en Docker-container publicerar (containers.publishedHostPorts: körande containrars live-bindningar plus varje stoppad containers konfigurerade, eftersom en OS-bind-provning från insidan av panelens egen container bara ser den containerns nätverksnamnrymd), och OS-provet. Docker-delen cachas i 3 s och begränsas: en lista som inte svarar på 2,5 s släpper bara Docker-delen, och en långsam inspektion kostar bara den containerns portar. Server-skapelser ochservers.changeGamePortväljer portar genom en serialiseringskedja som bara täcker valet och dess anspråk (radskrivningen för en skapelse, minnesreservationen för en portändring); BlueMaps portväljare och de extra port-åsidosättningarna är inte med i den och konsulterar inte Docker. En portändring på en befintlig server (servers.changeGamePort, under serverns op-lås) tillämpas omedelbart, eftersom Docker fixar portbindningar vid container-skapande: det nya paret (RCON alltid spel +PORT_RCON_OFFSET) kontrolleras och reserveras i minnet (ports.reserve, både det gamla och det nya paret, respekteras av varje annat val) under port-låset. Det vägras (409PENDING_CHANGES) medan andra inställningar väntar på en återbyggnad, så det återbygger bara en container som redan körts, på en ny port; och en körande server ändras bara när begäran sägerrestart: true(annars 409NEEDS_CONFIRM). Imagen dras och ett anpassat containernamn kontrolleras innan något vidrörs. En körande server stoppas; sedan skrivs det nya paret medpending_recreate = 1(så en panelkrasch därifrån lämnar en ärlig “återbyggnad väntar”), containern tas bort, återbyggs på det nya paret och startas. Om något steg efter stoppet misslyckas, skriverputBackOnOldPorttillbaka det gamla paret, återbygger (och startar om, om den kördes) på det och registrerar vilket steg som misslyckades; historik och varningar säger om även det misslyckades, vilket lämnar servern stoppad tills någon startar den.settings-kapaciteten räcker, inklusive körande server. Icke-administratörer får bara välja frånPORT_GAME_STARToch uppåt. (Kolumnernaport_*_pendingfrån migration 029 tillhör en tidigare, ej släppt design och används inte; 031 rensar dem.) En låskollision svarar 409 medcode: 'BUSY', vilket de anropande anroparen nedan kontrollerar snarare än formuleringen. En automatisk omstart vid krasch (watcher.restartAfterCrash) och en schemalagd säkerhetskopiering eller start (scheduler.runTaskWithRetry) som hittar servern upptagen med en annan åtgärd försöker igen var 20:e sekund / 60:e sekund i upp till 30 minuter, och en paketuppdatering eller återställning försöker sina låsta steg på samma sätt (opLock.retryWhileBusy); en kraschomstart eller en väntande schemalagd start ger upp när någon har stoppat, dödat eller startat servern sedan dess (events.lifecycleActionSince), och kraschomstarten också när automatisk omstart är avstängd eller servern är borta. Schemalagda omstarter, stopp och kommandon försöks inte igen, och ett schema vars sista körning fortfarande väntar hoppar över sin nästa avfyrning. - Disk-kvoter upprätthålls av panelen eftersom Docker inte kan begränsa användningen av bind-mounts: indexeraren cachar storlekar per katalog och disk-växande operationer begränsas av dem.
- Hemligheter (RCON-lösenord, API-nycklar, TOTP-hemligheter, Discord webhook-URL) krypteras vid vila med AES-256-GCM med en dedikerad slumpmässig nyckel vid
$DATA_DIR/.secret-key(läge0600, automatiskt genererad). Den är oberoende avSESSION_SECRET; en nyckel härledd frånSESSION_SECRETbehålls som en fallback endast för dekryptering för värden som skrivits innan den dedikerade nyckeln fanns, ochsrc/services/secretsMigration.jskrypterar om dessa under den dedikerade nyckeln en gång vid uppstart. En.secret-keysom finns men inte kan parsas är ett allvarligt uppstartsfel (den genereras aldrig tyst över den). Blueprints tar bort alla hemligheter vid export. server.propertiesägs av panelen men skuggas av miljövariabler. itzg-imagen återhävdar varje miljöbaserad egenskap vid varje start (OVERRIDE_SERVER_PROPERTIESstandard true), så ett värde som panelen redigerar direkt – Världskontroller PvP/svårighetsgrad, vitlistningsväxeln, Filredigeraren – skulle tyst återställas vid nästa start om inte motsvarande miljövariabel tas bort och containern återskapas. Varje direkt egenskapsskrivning går viawriteServerProperties()(hela filen) ellersetServerProperty()(en nyckel) isrc/services/servers.js, som atomärt skriver om filen, avmarkerar miljövariabeln bakom varje ändrad nyckel (via attributetprop:på katalogfält, kontrollerat i tester mot imagen egna egendefinitioner), och flaggarpending_recreate. Svårighetsgrad skrivs till filen såväl som skickas över RCON, eftersom en dedikerad server återanvänderdifficulty-egenskapen vid varje uppstart. Minecraft självt sparar om server.properties från sina startvärden vidwhitelist on/off, vilket skulle ångra redigeringar gjorda medan servern körs, så den körande vitlistningsväxeln ögonblicksbildar filen först och skriver tillbaka den med endastwhite-liständrad. Miljövariablerna förblir fullt konfigurerbara vid skapandet (guiden renderar dem och de tillämpas en gång); de låser upp sig först första gången panelen redigerar den underliggande egenskapen. MOTD har samma kontrakt: en direkt redigering avmotd-filen avmarkerar den, så den sista skrivningen vinner.
Data- och trådformat
Section titled “Data- och trådformat”data/panel.db- SQLite-databasen. Ögonblicksbildas dagligen viaVACUUM INTOtilldata/backups/_panel/(senaste 14 behålls);PRAGMA integrity_checkkörs vid uppstart.data/.session-secret- den automatiskt genererade hemligheten för sessionscookies, skapad vid första körningen omSESSION_SECRETär odefinierad. Att ta bort den roterar hemligheten (vilket ogiltigförklarar sessioner).data/.secret-key- den dedikerade 32-byte krypteringsnyckeln vid vila (läge0600), automatiskt skapad vid första körningen. Oberoende avSESSION_SECRET; att ta bort den gör varje lagrad autentiseringsuppgift okrypterbar, så den hör hemma med dina säkerhetskopior.- Blueprints (
.mcserver.zip) - en zip med enmanifest.jsonsom beskriver konfiguration, resurser, den fastlåsta paketreferensen, överlagringsmanifestet (käll-URL:er + sha256), valda konfigurationsfiler och eventuellt en värld. Import laddar ner och hash-verifierar varje mod och tilldelar nya portar. - Docker-containrar som skapas av panelen namnges och märks så att vakten kan hitta dem; panelen äger deras fulla livscykel.
Uppstartssekvens
Section titled “Uppstartssekvens”require('./instrument')(Sentry-sömmen) före allt annat, sedanrequire('./preflight')för att tydligt misslyckas vid en inkompatibel Node-version.- Ladda konfiguration; säkerställ/generera
.session-secretoch.secret-key. ensureDataRoot()- skapa./data-layouten, rensatmp/.- Kör DB-migrationer, sedan
PRAGMA integrity_check(loggar högt, pekar pådata/backups/_panelvid fel). - Kryptera om eventuella äldre
SESSION_SECRET-nyckelbaserade hemligheter under.secret-key(secretsMigration). - Importera API-nycklar från miljön en gång (
apiKeys.importFromEnvOnce()), lås eventuell server som fortfarande bär en olåst modpack-väljare (packPins.pinUnpinnedServers()), markera versionskompatibilitetsskanningar som lämnats igång av en tidigare process som avbrutna (compat.reconcileScans()), sedan fröa start-blueprints (skyddad). - Starta HTTP + WS-servern. Vid en exponerad bindning, skriv ut den första körningens
/setupPIN-kod. - Installera körtidsskyddet efter uppstart (fångar okontrollerade fel;
MSM_EXIT_ON_FATAL=1gör att den avslutas hårt för övervakade distributioner). - Starta bakgrundstjänster: WS-förmedlare, lagringsindexerare, krasch- och inventarievakter, schemaläggare,
Discord-händelsebrygga, chattbot-utåtriktad vakt, och dagliga underhållstimern (rensa gamla
analysrader, chattbot-transkriptioner, händelsehistorik (365 dagar) och API-cache-rader, sedan ögonblicksbilda
panel.db). - Initiera Docker i bakgrunden. Gränssnittet är fullt användbart medan demonen är nere;
Docker-funktioner tänds när den blir nåbar. När ansluten,
refreshStatuses({ boot })synkroniserar cachade statusar, skickar en engångshändelseoffline-after-restartför en server som var igång innan panelen startades om och inte kommer att startas om, och uppstartsloopen startarauto_start-servrar plus återställerauto_restart-servrar som hittats kraschade under avbrottet (respekterar krasch-loop-backoff).
Ordningen instrument-före-preflight är en medveten kompromiss: den låter en framtida Sentry-koppling lappa körningen först, till priset av ett något mindre vänligt meddelande vid en verkligt gammal Node.
Byggpipeline
Section titled “Byggpipeline”pnpm run build = build:css (Tailwind → public/css/app.css) + build:js (esbuild →
public/dist/js/, ESM med koddelning). postinstall kör endast CSS. public/css/app.css
och public/dist/ är gitignorerade byggartefakter; Dockerfile-byggstadiet kör hela
pnpm run build och kopierar public/ in i körningsimagen. Statiska tillgångar serveras
med immutable/lång cache för fingerprintade filer, kort cache för CSS/JS, och no-cache för HTML och
/api.