Arhitectură
← Înapoi la indexul documentației
Minecraft Server Manager este o aplicație Node.js redată pe server, cu un singur proces. Gestionează
servere Minecraft care rulează ca containere Docker folosind imaginea
itzg/docker-minecraft-server, comunicând cu
daemonul Docker prin API-ul său (niciodată prin apelarea liniei de comandă docker).
Structura de execuție
Secțiune intitulată „Structura de execuție”- Express + Handlebars redau paginile pe partea serverului. Nu există SPA; JavaScript-ul browserului din
public/js/este o îmbunătățire progresivă scrisă manual. Un pas esbuild (pnpm run build:js) îl împachetează și îl minifyază înpublic/dist/js/; aplicația servește acel pachet atunci când este prezent și sursa brută în caz contrar, astfel încât o rulare de dezvoltare fără o compilare funcționează totuși. node:sqlite(integrat în Node; panoul necesită Node ≥ 24) este baza de date - sincronă, zero module native, mod WAL. Un mic program de rulare a migrațiilor versiificate aplicăsrc/db/migrations/*la pornire. Instrucțiunile pregătite sunt stocate în cache însrc/db/index.jsindexate după textul SQL.wstransportă fluxurile live de consolă și statistici. Ambele sunt brokerate: un singur flux ascendentdocker logs --follow(saudocker stats) per server, demuxat o dată și distribuit fiecărei tab-uri conectate, mai degrabă decât un flux ascendent per vizualizator. Brokerul de consolă păstrează un mic buffer de redare pentru tab-urile care se conectează târziu și elimină un abonat al cărui socket rămâne prea în urmă, mai degrabă decât să blocheze fluxul partajat.- dockerode este singura modalitate prin care aplicația comunică cu Docker. Endpoint-ul este detectat automat per platformă (pipe numit Windows vs. socket Unix).
- Toată starea persistentă se află sub un singur director (
$DATA_DIR, implicit./data). Copierea acelui director migrează întregul panou.
Stratificare
Secțiune intitulată „Stratificare”Dependențele curg într-o singură direcție:
┌─────────────────────────────┐ HTTP ───────▶│ web/routes/* (+ middleware)│ parsează și validează intrarea, modelează răspunsurile └──────────────┬──────────────┘ │ ┌──────────────▼──────────────┐ │ services/* │ logica domeniului (funcționalitățile reale) └───┬─────────┬─────────┬─────┘ │ │ │ ┌────────────▼──┐ ┌────▼────┐ ┌──▼──────────┐ │ docker/* │ │ db/* │ │ storage/* │ infrastructură └───────────────┘ └─────────┘ └─────────────┘web/routes/- un router per domeniu (players,worlds,crashes,blueprints,files, …).web/app.jsmontează cele de nivel superior (api.js, API-ul JSON de sesiune care deține și rutele serverului de bază și montează routerele de domeniu per server;index.js, paginile;auth,account,tasks, …). Routerele validează cu zod, apelează un serviciu și returnează JSON sau redau o vizualizare. Logica de afaceri nu aparține aici. Două routere sunt montate în zona publică, înainte derequireAuth:routes/status.js(pagini de stare HTML per server, opționale) șiroutes/apiV1.js(/api/v1, un API JSON numai pentru citire autentificat printr-un token Bearer emis de administrator dinservices/apiTokens.js, dezactivat dacă nu este activat în Setări; vezidocs/public-api.md).services/- inima aplicației. Fiecare serviciu deține un domeniu și poate depinde de infrastructură și de alte servicii.docker/- wrapper-e dockerode:connect(detectare endpoint + stare daemon),containers(creare/pornire/oprire/recreare cu mount-uri de legătură, limite de memorie/CPU și etichete),logs,stats,images,networks(descoperire rețea gazdă),hostPath(re-radacinează căile de legătură subDATA_DIR_HOST), și unwatchercare transformă evenimentele Docker în istoric + detectare blocări.db/- wrapper-ul SQLite și programul de rulare a migrațiilor.storage/- inițializarea./data, gardianul de căi (safeJoin, coloana vertebrală de siguranță a fișierelor) și indexatorul de dimensiuni în fundal + aplicarea cotelor.
Transversal:
config/- configurația de mediu plus catalogul de câmpuri: singura sursă de adevăr pentru setările serverului. Fiecare variabilă de mediu itzg este catalogată (etichetă, ajutor, tip, unitate, implicit, validare, secțiune, flag-uri de pericol). Expertul, formularele de setări și validarea zod sunt toate derivate din acesta, astfel încât expunerea unei noi setări este o modificare de date, nu o nouă conductă UI.events/-recordEvent()este singurul punct de intrare pentru jurnalul de istoric; evenimentele ciclului de viață capturează, de asemenea, fragmente de jurnal de container îndata/logs/<id>/events/.ws/- WebSockets autentificate pentru consolă + statistici (cookie de sesiune verificat la upgrade,Originverificat pentru a bloca deturnarea cross-site), brokerate per server (vezi “Structura de execuție”).logger.js+instrument.js-require('./logger')(label)returnează un logger Pino per modul; nivelul dinLOG_LEVEL,makeFailureThrottle()menține o buclă de fundal care eșuează persistent la o singură linie de jurnal plus o linie “recuperată”.src/utils/logSanitize.jscenzurează cheile cu format de credențiale și token-urile webhook din metadatele structurate;src/config/logLevel.jseste lista de permise de nivel partajată (păstrată separat pentru a evita un ciclu de require cuconfig).src/instrument.jseste o cusătură Sentry dormantă, încărcată prima însrc/server.js.src/web/middleware/requestLog.jsscrie o linie de jurnal de acces per cerere (sărind peste/healthzși fișierele statice). ESLint impuneno-consolesubsrc/**, cupreflight.js,instrument.js, șiconfig/index.jsexceptate (rulează înainte ca logger-ul să existe).- Limitarea ratei -
src/web/middleware/rateLimit.jsplaseazăexpress-rate-limitîn fața/api(RATE_LIMIT_API_PER_MIN, implicit 1200) și POST-urile de login / 2FA / setup (RATE_LIMIT_AUTH_PER_15MIN, implicit 100);0dezactivează un limitator. Indexează dupăreq.ip, deciTRUST_PROXYcontează în spatele unui proxy./api/v1are proprii limitatori: o limită per client-IP (de cinci ori bugetul per token) care rulează înainte ca token-ul să fie verificat, apoi un buget per token (RATE_LIMIT_PUBLIC_API_PER_MIN, implicit 120) indexat după ID-ul token-ului verificat. Un cont soft separat per cont însrc/web/middleware/auth.jsgestionează blocarea la login (per IP și global per cont, cu decădere). - Autorizare: două niveluri. Rolul global (
requireAuth→requireRole/requireWriteînsrc/web/middleware/auth.js) controlează acțiunile la nivel de panou și este implicit pe fiecare server. Permisiunile per server (src/services/permissions.js, nouă capabilități stocate ca listă JSON per(utilizator, server)înuser_server_permissions) rafinează implicitul pentru un server; fiecare rută/api/servers/:id, montare sub-router, pagină, WebSocket și listare la nivel de flotă trece prinsrc/web/middleware/serverAccess.js(serverScope, montat pe prefixul/servers/:idatât al API-ului, cât și al routerului de pagini, ascunde un server fărăviewca 404;requireCap(cap)numește capabilitatea necesară unei rute). Scrierile care își numesc serverul în corpul cererii (programări, extragere și instalare lume, export blueprint) sunt deschise pentru vizualizatori numai de cătrerequireWritepentru acel server, și fiecare astfel de rută verifică capabilitatea în sine.test/permissions-routes.test.jsparcurge stivele routerului live și eșuează dacă o rută de scriere, montare sau pagină cu scop de server nu are un gardian.
Comportamente cheie ale domeniului
Secțiune intitulată „Comportamente cheie ale domeniului”- Modpack-urile sunt întotdeauna fixate. Imaginea actualizează automat pack-urile nefixate la fiecare repornire, deci panoul rezolvă “latest” la un ID concret de versiune la momentul instalării și îl fixează. Actualizările sunt un flux explicit orchestrat (
updates/): previzualizare → backup pre-actualizare → oprire grațioasă → re-fixare → recreare → monitorizare stare → rollback printr-un clic. - Suprapunerea de moduri personalizate este gestionată de panou: modurile adăugate de utilizator ajung în biblioteca deduplicată și sunt legate fizic în server, astfel încât să supraviețuiască actualizărilor de pack. Dezactivarea este conștientă de clasă. Deoarece
biblioteca păstrează fiecare build pe care l-a descărcat, o actualizare înregistrează build-ul pe care l-a înlocuit
(
server_content.previous_*) și poate fi restaurată numai din fișiere locale. Dezactivarea unui mod de pack scrie variabila de mediu de excludere a pack-ului în schimb;packs.applyPacktransportă aceasta și restul ajustărilor pack-ului (PACK_TUNING_KEYS) peste o schimbare de versiune a aceluiași pack și o elimină când pack-ul se schimbă. - O actualizare a versiunii Minecraft trebuie câștigată.
services/compat.jsscanează modurile unui server - rezolvate din rândurile instalate de panou, apoi din manifestul pack-ului CurseForge, apoi prin hash-ul de conținut împotriva Modrinth/CurseForge - și construiește o matrice de suport (loader, versiune Minecraft) per proiect dinlatestFilesIndexesale CurseForge (200 de proiecte per cerere) și lista de versiuni per proiect a Modrinth (o cerere per proiect, ceea ce menține loader-ul și versiunea asociate). Verificatorul de actualizări oferă numai cea mai nouă versiune pe care o suportă FIECARE mod și nu oferă nimic deloc atunci când răspunsul nu poate fi stabilit: nicio scanare, o scanare pentru o versiune sau un loader diferit, una care nu s-a terminat niciodată, sau un jar pe care niciun registru nu îl recunoaște. Scanările sunt numai manuale, iar progresul și rezultatele parțiale ale acestora se află înversion_compat(nu înservices/tasks.jsdin memorie), astfel încât o reîmprospătare sau o repornire a panoului continuă în loc să se blocheze pe un spinner;reconcileScans()marchează scanările abandonate de o oprire la următoarea pornire. - Versiunea loader-ului de moduri este o fixare, ca totul.
services/loaderPin.jscitește build-ul instalat din manifestul de instalare al imaginii (.forge-manifest.jsonși similare) și scrie fixarea: variabila itzg a loader-ului pe un server simplu (FORGE_VERSION, …), sauCF_MOD_LOADER_VERSIONpe un pack CurseForge Forge sau Fabric, care suprascrie versiunea declarată de pack. Instalatorul CurseForge al imaginii ignoră acea suprascriere pentru NeoForge, iar pack-urile Modrinth și FTB nu au niciuna, deci loader-ul lor urmează pack-ul.packs.applyPackelimină toate variabileleCF_la o actualizare sau rollback de pack, care elimină o suprascriere odată cu restul. Un build tipizat este verificat mai întâi împotriva listei complete a registrului (services/loaderVersions.js; cel al Forge provine din metadatele sale maven, care omite numerele; o ratare este re-verificată o dată împotriva registrului în sine), apoi modificarea este backup → fixare (peste mediul așa cum este după backup) → reconstruire. - Porturile sunt alocate dintr-un schemă de bază (joc de la
PORT_GAME_STARTîn sus, RCON = joc +PORT_RCON_OFFSET, Bedrock de laPORT_BEDROCK_START), sondate pentru disponibilitate și rezervate în baza de date. “Ocupat” este uniunea tuturor revendicărilor fiecărui server (porturi live, plus o pereche în așteptare mai jos), fiecare port gazdă pe care îl publică orice container Docker (containers.publishedHostPorts: legături live ale containerelor în rulare plus cele configurate ale fiecărui container oprit, deoarece o sondă de legare a sistemului de operare din interiorul propriului container al panoului vede numai spațiul de rețea al acelui container), și sonda sistemului de operare. Partea Docker este stocată în cache timp de 3 secunde și limitată: o listă care nu răspunde în 2,5 secunde elimină numai partea Docker, iar o inspecție lentă costă numai porturile acelui container. Crearea serverelor șiservers.changeGamePortaleg porturi printr-un singur lanț de serializare care acoperă numai alegerea și revendicarea sa (scrierea rândului pentru o creare, rezervarea în memorie pentru o modificare de port); selectorul de port al BlueMap și suprascrierile de port suplimentar nu sunt incluse și nu consultă Docker. O modificare de port pe un server existent (servers.changeGamePort, sub blocarea de operare a serverului) este aplicată imediat, deoarece Docker repară legăturile de port la crearea containerului: noua pereche (RCON întotdeauna joc +PORT_RCON_OFFSET) este verificată și rezervată în memorie (ports.reserve, atât perechea veche, cât și cea nouă, onorată de fiecare altă alegere) sub blocarea de port. Este refuzată (409PENDING_CHANGES) cât timp alte setări așteaptă o reconstruire, deci reconstruiește numai un container care a rulat deja, pe un port nou; și un server în rulare este modificat numai când cererea spunerestart: true(altfel 409NEEDS_CONFIRM). Imaginea este trasă și numele containerului personalizat este verificat înainte ca orice să fie atins. Un server în rulare este oprit; apoi noua pereche este scrisă cupending_recreate = 1(astfel încât o blocare a panoului de acolo lasă un “rebuild pending” onest), containerul este eliminat, reconstruit pe noua pereche și pornit. Dacă orice pas după oprire eșuează,putBackOnOldPortscrie perechea veche înapoi, reconstruiește (și repornește, dacă era în rulare) pe ea și înregistrează ce pas a eșuat; istoricul și alertele spun dacă chiar și asta a eșuat, ceea ce lasă serverul oprit până când cineva îl pornește. Capabilitateasettingseste suficientă, inclusiv serverul în rulare. Non-administratorii pot alege numai de laPORT_GAME_STARTîn sus. (Coloaneleport_*_pendingdin migrarea 029 aparțin unui design anterior, nelansat și sunt neutilizate; 031 le șterge.) O coliziune de blocare răspunde cu 409 șicode: 'BUSY', pe care apelatorii care reîncearcă o verifică mai degrabă decât formularea. O repornire automată la blocare (watcher.restartAfterCrash) și o backup programată sau pornire (scheduler.runTaskWithRetry) care găsesc serverul ocupat cu o altă acțiune încearcă din nou la fiecare 20 s / 60 s timp de până la 30 de minute, iar o actualizare sau rollback de pack reîncearcă pașii săi blocați în același mod (opLock.retryWhileBusy); o repornire la blocare sau o pornire programată în așteptare renunță odată ce cineva a oprit, a oprit sau a pornit serverul de atunci (events.lifecycleActionSince), iar repornirea la blocare, de asemenea, când repornirea automată este dezactivată sau serverul a dispărut. Repornirile programate, opririle și comenzile nu sunt reîncercate, iar o programare a cărei ultimă rulare încă așteaptă omite următoarea sa declanșare. - Cotele de disc sunt aplicate de panou deoarece Docker nu poate limita utilizarea mount-urilor de legătură: indexatorul stochează în cache dimensiunile per director, iar operațiunile de creștere a discului sunt controlate de acestea.
- Secretele (parole RCON, chei API, secrete TOTP, URL-ul webhook Discord) sunt criptate în repaus cu AES-256-GCM folosind o cheie dedicată aleatorie la
$DATA_DIR/.secret-key(mod0600, generată automat). Este independentă deSESSION_SECRET; o cheie derivată dinSESSION_SECRETeste păstrată ca o rezervă numai pentru decriptare pentru valorile scrise înainte ca cheia dedicată să existe, iarsrc/services/secretsMigration.jsre-criptează acelea sub cheia dedicată o dată la pornire. Un.secret-keycare există dar nu poate fi parsat este o eroare gravă la pornire (nu este niciodată regenerat silențios peste cel existent). Blueprint-urile elimină toate secretele la export. server.propertieseste deținut de panou, dar umbrit de mediu. Imaginea itzg reafirmă fiecare proprietate bazată pe mediu la fiecare pornire (OVERRIDE_SERVER_PROPERTIESimplicit true), deci o valoare pe care panoul o editează direct - Controale Lume PvP/dificultate, comutatorul whitelist, editorul de fișiere - ar fi anulată silențios la următoarea pornire, cu excepția cazului în care variabila de mediu corespunzătoare este eliminată și containerul recreat. Fiecare scriere directă de proprietate trece prinwriteServerProperties()(fișier complet) sausetServerProperty()(o singură cheie) însrc/services/servers.js, care rescriu atomic fișierul, elimină variabila de mediu din spatele fiecărei chei modificate (prin atributulprop:pe câmpurile catalogului, verificat în teste împotriva definițiilor proprii ale imaginii pentru proprietăți) și marcheazăpending_recreate. Dificultatea este scrisă atât în fișier, cât și trimisă prin RCON, deoarece un server dedicat reaplică proprietateadifficultyla fiecare pornire. Minecraft în sine salveazăserver.propertiesdin valorile sale la pornire lawhitelist on/off, ceea ce ar anula modificările făcute în timp ce serverul rulează, deci comutatorul whitelist în rulare salvează mai întâi fișierul și îl rescrie cu numaiwhite-listmodificat. Variabilele de mediu rămân complet configurabile la creare (expertul le redă și se aplică o dată); ele doar desprind fixarea la prima editare a panoului a proprietății subiacente. MOTD are același contract: o editare directă a fișieruluimotdo dezactivează, deci ultima scriere câștigă.
Formate de date și de transmisie
Secțiune intitulată „Formate de date și de transmisie”data/panel.db- baza de date SQLite. Salvare zilnică prinVACUUM INTOcătredata/backups/_panel/(ultimele 14 păstrate);PRAGMA integrity_checkrulează la pornire.data/.session-secret- secretul automat generat pentru semnarea cookie-urilor, creat la prima rulare dacăSESSION_SECRETeste n setat. Ștergerea acestuia rotește secretul (ceea ce invalidează sesiunile).data/.secret-key- cheia dedicată de 32 de octeți pentru criptarea în repaus (mod0600), creată automat la prima rulare. Independent deSESSION_SECRET; ștergerea acestuia face ca orice credențial stocat să fie indecriptabil, deci aparține backup-urilor dvs.- Blueprint-uri (
.mcserver.zip) - un fișier zip cu unmanifest.jsoncare descrie configurația, resursele, referința pack-ului fixat, manifestul de suprapunere (URL-uri sursă + sha256), fișiere de configurare alese și, opțional, o lume. Importul re-descarcă și verifică hash-ul fiecărui mod și atribuie porturi noi. - Containere Docker create de panou sunt numite și etichetate astfel încât watcher-ul să le poată găsi; panoul deține ciclul lor de viață complet.
Secvența de pornire
Secțiune intitulată „Secvența de pornire”require('./instrument')(cusătura Sentry) înainte de orice altceva, apoirequire('./preflight')pentru a eșua clar la o versiune Node neacceptată.- Încărcare configurație; asigurare/generare
.session-secretși.secret-key. ensureDataRoot()- creează structura./data, ștergetmp/.- Rulează migrațiile DB, apoi
PRAGMA integrity_check(loghează zgomotos, indicădata/backups/_panella eșec). - Re-criptează orice secrete moștenite cu cheia
SESSION_SECRETsub.secret-key(secretsMigration). - Importă cheile API din mediu o dată (
apiKeys.importFromEnvOnce()), fixează orice server care încă poartă un selector de modpack nefixat (packPins.pinUnpinnedServers()), marchează scanările de compatibilitate a versiunilor lăsate în rulare de un proces anterior ca fiind întrerupte (compat.reconcileScans()), apoi populează blueprint-uri de pornire (protejat). - Pornește serverul HTTP + WS. Pe o legătură expusă, afișează PIN-ul
/setupde la prima rulare. - Instalează gardianul de execuție post-pornire (prinde erorile neprinse;
MSM_EXIT_ON_FATAL=1îl face să iasă brusc pentru implementări supravegheate). - Pornește serviciile de fundal: broker WS, indexator stocare, watcher-e blocări + inventar, planificator,
punte evenimente Discord, watcher-ul de contact chatbot și timer-ul zilnic de întreținere (curăță rânduri vechi de analize, transcrieri chatbot, istoric evenimente (365 zile) și rânduri cache API, apoi salvează
panel.db). - Inițializează Docker în fundal. Interfața utilizator este complet utilizabilă în timp ce daemonul este oprit;
funcționalitățile Docker se activează când devine accesibil. Odată conectat,
refreshStatuses({ boot })reconciliază stările din cache, emite un eveniment unicoffline-after-restartpentru un server care era pornit înainte ca panoul să repornească și nu va fi repornit, iar bucla de pornire pornește servereleauto_startplus recuperează servereleauto_restartgăsite blocate în timpul întreruperii (respectând backoff-ul de buclă de blocare).
Ordinea instrumentare-înainte-de-preflight este un compromis deliberat: permite ca o viitoare cablare Sentry să patch-uiască runtime-ul mai întâi, cu prețul unui mesaj puțin mai puțin prietenos pe un Node cu adevărat vechi.
Conducta de compilare
Secțiune intitulată „Conducta de compilare”pnpm run build = build:css (Tailwind → public/css/app.css) + build:js (esbuild →
public/dist/js/, ESM cu împărțirea codului). postinstall rulează numai CSS. public/css/app.css
și public/dist/ sunt artefacte de compilare ignorate de git; etapa de compilare Dockerfile rulează complet
pnpm run build și copiază public/ în imaginea de execuție. Fișierele statice sunt servite
immutable/cache lung pentru fișierele cu amprentă, cache scurt pentru CSS/JS și no-cache pentru HTML și
/api.