Architettura
← Indietro all’indice della documentazione
Minecraft Server Manager è un’applicazione Node.js renderizzata lato server, a processo singolo. Gestisce
server Minecraft in esecuzione come container Docker utilizzando l’immagine
itzg/docker-minecraft-server, comunicando con il
demone Docker tramite la sua API (mai tramite shell docker CLI).
Struttura di runtime
Sezione intitolata “Struttura di runtime”- Express + Handlebars renderizzano le pagine lato server. Non c’è SPA; il JS del browser in
public/js/è un miglioramento progressivo scritto a mano. Un passaggio esbuild (pnpm run build:js) lo impacchetta e minimizza inpublic/dist/js/; l’app serve quel bundle quando è presente e la sorgente raw altrimenti, quindi un’esecuzione di sviluppo senza build funziona comunque. node:sqlite(integrato in Node; il pannello richiede Node ≥ 24) è il database - sincrono, zero moduli nativi, modalità WAL. Un piccolo runner di migrazioni versionate applicasrc/db/migrations/*all’avvio. Le istruzioni preparate sono memorizzate nella cache insrc/db/index.jscon chiave basata sul testo SQL.wsgestisce i flussi live di console e statistiche. Entrambi sono brokerati: un upstreamdocker logs --follow(odocker stats) per server, demuxato una volta e distribuito a ogni scheda connessa, piuttosto che un upstream per visualizzatore. Il broker della console mantiene un piccolo buffer di replay per le schede che si uniscono in ritardo e scarta un sottoscrittore il cui socket va troppo indietro piuttosto che bloccare il flusso condiviso.- dockerode è l’unico modo in cui l’app comunica con Docker. L’endpoint viene rilevato automaticamente per piattaforma (named pipe Windows vs. socket Unix).
- Tutto lo stato persistente vive sotto una directory (
$DATA_DIR, predefinito./data). Copiare quella directory migra l’intero pannello.
Struttura a livelli
Sezione intitolata “Struttura a livelli”Le dipendenze fluiscono in una sola direzione:
┌─────────────────────────────┐ HTTP ───────▶│ web/routes/* (+ middleware)│ analizza e valida l'input, modella le risposte └──────────────┬──────────────┘ │ ┌──────────────▼──────────────┐ │ services/* │ logica di dominio (le funzionalità effettive) └───┬─────────┬─────────┬─────┘ │ │ │ ┌────────────▼──┐ ┌────▼────┐ ┌──▼──────────┐ │ docker/* │ │ db/* │ │ storage/* │ infrastruttura └───────────────┘ └─────────┘ └─────────────┘web/routes/- un router per dominio (players,worlds,crashes,blueprints,files, …).web/app.jsmonta quelli di primo livello (api.js, l’API JSON di sessione che contiene anche le rotte principali del server e monta i router di dominio per server;index.js, le pagine;auth,account,tasks, …). I router validano con zod, chiamano un servizio e restituiscono JSON o renderizzano una vista. La logica di business non appartiene qui. Due router sono montati nella zona pubblica, prima direquireAuth:routes/status.js(pagine di stato per server opzionali) eroutes/apiV1.js(/api/v1, un’API JSON di sola lettura autenticata da un token Bearer emesso dall’admin daservices/apiTokens.js, disattivata se non abilitata nelle Impostazioni; vedidocs/public-api.md).services/- il cuore dell’app. Ogni servizio possiede un dominio e può dipendere dall’infrastruttura e da altri servizi.docker/- wrapper dockerode:connect(rilevamento endpoint + stato daemon),containers(crea/avvia/ferma/ricrea con bind mount, limiti di memoria/CPU ed etichette),logs,stats,images,networks(scoperta rete host),hostPath(ri-radica i percorsi di bind sottoDATA_DIR_HOST), e unwatcherche trasforma gli eventi Docker in cronologia + rilevamento crash.db/- il wrapper SQLite e il runner di migrazioni.storage/- il bootstrap di./data, il guardiano dei percorsi (safeJoin, la spina dorsale di sicurezza dei file), e l’indicizzatore di dimensioni in background + applicazione delle quote.
Trasversale:
config/- configurazione dell’ambiente più il catalogo dei campi: l’unica fonte di verità per le impostazioni del server. Ogni variabile d’ambiente itzg è catalogata (etichetta, aiuto, tipo, unità, predefinito, validazione, sezione, flag di pericolo). La procedura guidata, i moduli delle impostazioni e la validazione zod sono tutti derivati da esso, quindi esporre una nuova impostazione è una modifica dei dati, non una nuova infrastruttura UI.events/-recordEvent()è l’unico punto di ingresso per il log della cronologia; gli eventi del ciclo di vita catturano anche estratti di log del container indata/logs/<id>/events/.ws/- WebSockets autenticati per console + statistiche (cookie di sessione verificato all’upgrade,Origincontrollato per bloccare dirottamenti cross-site), brokerati per server (vedi “Struttura di runtime”).logger.js+instrument.js-require('./logger')(label)restituisce un logger Pino per modulo; livello daLOG_LEVEL,makeFailureThrottle()mantiene un loop in background persistentemente fallimentare a una riga di log più una riga “recuperata”.src/utils/logSanitize.jsredige chiavi a forma di credenziale e token webhook dai metadati strutturati;src/config/logLevel.jsè la whitelist di livello condivisa (tenuta separata per evitare un ciclo di require conconfig).src/instrument.jsè una porta Sentry dormiente, caricata per prima insrc/server.js.src/web/middleware/requestLog.jsscrive una riga di access-log per richiesta (saltando/healthze asset statici). ESLint imponeno-consolesottosrc/**, conpreflight.js,instrument.js, econfig/index.jsesentati (eseguiti prima che il logger esista).- Limitazione della frequenza -
src/web/middleware/rateLimit.jsinserisceexpress-rate-limitdavanti a/api(RATE_LIMIT_API_PER_MIN, predefinito 1200) e i POST di login / 2FA / setup (RATE_LIMIT_AUTH_PER_15MIN, predefinito 100);0disabilita un limiter. Si basa sureq.ip, quindiTRUST_PROXYè importante dietro un proxy./api/v1ha i suoi limiter: un limite per IP client (cinque volte il budget per token) che viene eseguito prima che il token venga verificato, quindi un budget per token (RATE_LIMIT_PUBLIC_API_PER_MIN, predefinito 120) basato sull’ID del token verificato. Un contatore soft separato per account insrc/web/middleware/auth.jsgestisce il blocco del login (per IP e globale per account, in decadimento). - Autorizzazione: due livelli. Il ruolo globale (
requireAuth→requireRole/requireWriteinsrc/web/middleware/auth.js) blocca le azioni a livello di pannello ed è il predefinito su ogni server. Le autorizzazioni per server (src/services/permissions.js, nove capacità memorizzate come elenco JSON per(utente, server)inuser_server_permissions) affinano il predefinito per un server; ogni rotta/api/servers/:id, montaggio di sottorouter, pagina, WebSocket e elenco a livello di flotta passa attraversosrc/web/middleware/serverAccess.js(serverScope, montato sul prefisso/servers/:idsia dell’API che del router di pagine, nasconde un server senzaviewcome 404;requireCap(cap)nomina la capacità richiesta da una rotta). Le scritture che nominano il loro server nel corpo (pianificazioni, estrazione e installazione del mondo, esportazione blueprint) sono aperte agli spettatori solo darequireWriteper quel server, e ogni rotta di questo tipo controlla essa stessa la capacità.test/permissions-routes.test.jsattraversa gli stack del router live e fallisce se una rotta di scrittura con ambito server, un montaggio o una pagina non ha un gate.
Comportamenti chiave del dominio
Sezione intitolata “Comportamenti chiave del dominio”- I Modpack sono sempre bloccati. L’immagine aggiorna automaticamente i pack non bloccati ad ogni riavvio, quindi il pannello risolve “latest” in un ID di versione concreto al momento dell’installazione e lo blocca. Gli aggiornamenti sono un flusso esplicito orchestrato (
updates/): anteprima → backup pre-aggiornamento → arresto grazioso → ri-blocco → ricreazione → monitoraggio integrità → rollback con un clic. - L’overlay di mod personalizzato è gestito dal pannello: le mod aggiunte dall’utente atterrano nella libreria deduplicata e vengono collegate in modo rigido al server in modo che sopravvivano agli aggiornamenti del pack. La disabilitazione è consapevole della classe. Poiché la libreria conserva ogni build scaricata, un aggiornamento registra la build che ha sostituito (
server_content.previous_*) e può essere ripristinata dai soli file locali. La disabilitazione di una mod del pack scrive invece la variabile d’ambiente di esclusione del pack;packs.applyPacktrasporta quella e il resto della configurazione del pack (PACK_TUNING_KEYS) attraverso una modifica di versione dello stesso pack, e la elimina quando il pack cambia. - Un aggiornamento della versione di Minecraft deve essere guadagnato.
services/compat.jsscansiona le mod di un server - risolte dalle righe installate dal pannello, quindi dal manifest del pack CurseForge, quindi per hash del contenuto rispetto a Modrinth/CurseForge - e costruisce una matrice di supporto (loader, versione Minecraft) per progetto dallelatestFilesIndexesdi CurseForge (200 progetti per richiesta) e dall’elenco delle versioni per progetto di Modrinth (una richiesta per progetto, che è ciò che mantiene accoppiati loader e versione). Il checker di aggiornamento offre solo la versione più recente supportata da OGNI mod, e non offre nulla quando la risposta non può essere stabilita: nessuna scansione, una scansione per una versione o loader diversa, una che non è mai stata completata, o un jar che nessun registro riconosce. Le scansioni sono solo manuali, e il loro progresso e i risultati parziali vivono inversion_compat(non inservices/tasks.jsin memoria), quindi un aggiornamento o un riavvio del pannello riprende invece di bloccarsi su un indicatore;reconcileScans()contrassegna le scansioni orfane da uno spegnimento al successivo avvio. - La versione del mod loader è un pin, come tutto il resto.
services/loaderPin.jslegge la build installata dal manifest di installazione dell’immagine stessa (.forge-manifest.jsone simili) e scrive il pin: la variabile itzg del loader su un server normale (FORGE_VERSION, …), oCF_MOD_LOADER_VERSIONsu un pack CurseForge Forge o Fabric, che sovrascrive la versione dichiarata dal pack. L’installer CurseForge dell’immagine ignora tale sovrascrittura per NeoForge, e i pack Modrinth e FTB non ne hanno, quindi il loro loader segue il pack.packs.applyPackrimuove tutte le variabiliCF_durante un aggiornamento o rollback del pack, che elimina una sovrascrittura con il resto. Una build tipizzata viene controllata prima rispetto all’elenco completo del registro (services/loaderVersions.js; quello di Forge proviene dai suoi metadati maven, che saltano i numeri; una mancata corrispondenza viene ricontrollata una volta rispetto al registro stesso), quindi la modifica viene sottoposta a backup → pin (sopra l’env così com’è dopo il backup) → ricostruzione. - Le porte vengono allocate da uno schema di base (gioco da
PORT_GAME_STARTin su, RCON = gioco +PORT_RCON_OFFSET, Bedrock daPORT_BEDROCK_START), sondate per disponibilità e riservate nel DB. “Occupato” è l’unione di tutte le rivendicazioni di ogni server (porte live, più una coppia in sospeso sotto), ogni porta host che qualsiasi container Docker pubblica (containers.publishedHostPorts: binding live dei container in esecuzione più quelli configurati di ogni container fermato, perché una sonda di bind del sistema operativo dall’interno del container del pannello vede solo lo spazio di rete di quel container), e la sonda del sistema operativo. La parte Docker è memorizzata nella cache per 3 secondi e limitata: un elenco che non risponde in 2,5 secondi scarta solo la parte Docker, e un ispezione lenta costa solo le porte di quel container. La creazione del server eservers.changeGamePortscelgono le porte attraverso una catena di serializzazione che copre solo la scelta e la sua rivendicazione (la scrittura della riga per una creazione, la prenotazione in memoria per una modifica della porta); il selettore di porte di BlueMap e le sovrascritture di porte aggiuntive non sono inclusi e non consultano Docker. Una modifica della porta su un server esistente (servers.changeGamePort, sotto il blocco op del server) viene applicata immediatamente, perché Docker corregge i binding delle porte alla creazione del container: la nuova coppia (RCON sempre gioco +PORT_RCON_OFFSET) viene controllata e riservata in memoria (ports.reserve, sia la vecchia che la nuova coppia, onorate da ogni altra scelta) sotto il blocco della porta. Viene rifiutata (409PENDING_CHANGES) mentre altre impostazioni attendono una ricostruzione, quindi ricostruisce solo un container che è già stato eseguito, su una nuova porta; e un server in esecuzione viene modificato solo quando la richiesta dicerestart: true(altrimenti 409NEEDS_CONFIRM). L’immagine viene scaricata e viene controllato un nome di container personalizzato prima che venga toccato qualcosa. Un server in esecuzione viene fermato; quindi la nuova coppia viene scritta conpending_recreate = 1(quindi un crash del pannello da lì lascia un onesto “ricostruzione in sospeso”), il container rimosso, ricostruito sulla nuova coppia e avviato. Se un passaggio dopo l’arresto fallisce,putBackOnOldPortriscrive la vecchia coppia, ricostruisce (e riavvia, se era in esecuzione) su di essa e registra quale passaggio è fallito; la cronologia e gli avvisi indicano se anche quello è fallito, il che lascia il server fermo finché qualcuno non lo avvia. La capacitàsettingsè sufficiente, incluso il server in esecuzione. I non amministratori possono scegliere solo daPORT_GAME_STARTin su. (Le colonneport_*_pendingdella migrazione 029 appartengono a un design precedente, non rilasciato, e non vengono utilizzate; 031 le cancella.) Una collisione di blocco risponde con 409 ecode: 'BUSY', che i chiamanti che ritentano controllano piuttosto che la dicitura. Un riavvio automatico in caso di crash (watcher.restartAfterCrash) e un backup o avvio pianificato (scheduler.runTaskWithRetry) che trovano il server occupato da un’altra azione tentano di nuovo ogni 20 s / 60 s per un massimo di 30 minuti, e un aggiornamento o rollback del pack ritenta i suoi passaggi bloccati allo stesso modo (opLock.retryWhileBusy); un riavvio in caso di crash o un avvio pianificato in attesa si arrendono una volta che qualcuno ha fermato, ucciso o avviato il server da allora (events.lifecycleActionSince), e il riavvio in caso di crash anche quando il riavvio automatico è disattivato o il server è scomparso. Riavvii, arresti e comandi pianificati non vengono ritentati, e una pianificazione la cui ultima esecuzione è ancora in attesa salta il suo prossimo avvio. - Le quote disco sono applicate dal pannello perché Docker non può limitare l’utilizzo dei bind-mount: l’indicizzatore memorizza nella cache le dimensioni per directory e le operazioni di crescita del disco sono bloccate su di esse.
- I segreti (password RCON, chiavi API, segreti TOTP, URL webhook Discord) sono crittografati a riposo con AES-256-GCM utilizzando una chiave casuale dedicata in
$DATA_DIR/.secret-key(modalità0600, generata automaticamente). È indipendente daSESSION_SECRET; una chiave derivata daSESSION_SECRETviene mantenuta come fallback solo per decrittazione per i valori scritti prima che la chiave dedicata esistesse, esrc/services/secretsMigration.jsli ricrittografa sotto la chiave dedicata una volta all’avvio. Un.secret-keyesistente ma non analizzabile è un errore di avvio grave (non viene mai rigenerato silenziosamente). I blueprint eliminano tutti i segreti all’esportazione. server.propertiesè di proprietà del pannello ma ombreggiato dall’ambiente. L’immagine itzg riafferma ogni proprietà basata sull’ambiente ad ogni avvio (OVERRIDE_SERVER_PROPERTIESpredefinito true), quindi un valore che il pannello modifica direttamente - PvP/difficoltà dei Controlli Mondo, l’interruttore whitelist, l’editor File - verrebbe silenziosamente ripristinato al prossimo avvio a meno che la variabile d’ambiente corrispondente non venga rimossa e il container ricreato. Ogni scrittura diretta di proprietà passa attraversowriteServerProperties()(intero file) osetServerProperty()(una chiave) insrc/services/servers.js, che riscrivono atomicamente il file, deselezionano la variabile d’ambiente dietro ogni chiave modificata (tramite l’attributoprop:sui campi del catalogo, controllato nei test rispetto alle definizioni delle proprietà dell’immagine stessa), e contrassegnanopending_recreate. La difficoltà viene scritta nel file e inviata tramite RCON, perché un server dedicato riapplica la proprietàdifficultyad ogni avvio. Minecraft stesso risalva server.properties dai suoi valori all’avvio alla modifica diwhitelist on/off, il che annullerebbe le modifiche apportate mentre il server è in esecuzione, quindi l’interruttore whitelist in esecuzione esegue uno snapshot del file prima e lo riscrive con modificato solowhite-list. L’ambiente le variabili rimangono completamente configurabili alla creazione (la procedura guidata le renderizza e si applicano una volta); si “sganciano” solo la prima volta che il pannello modifica la proprietà sottostante. MOTD ha lo stesso contratto: una modifica diretta del filemotdla deseleziona, quindi vince l’ultima scrittura.
Formati dati e di trasmissione
Sezione intitolata “Formati dati e di trasmissione”data/panel.db- il database SQLite. Snapshot giornaliero tramiteVACUUM INTOadata/backups/_panel/(mantenuti gli ultimi 14);PRAGMA integrity_checkviene eseguito all’avvio.data/.session-secret- il segreto di firma dei cookie generato automaticamente, creato al primo avvio seSESSION_SECRETnon è impostato. Eliminarlo ruota il segreto (il che invalida le sessioni).data/.secret-key- la chiave di crittografia dedicata a riposo da 32 byte (modalità0600), creata automaticamente al primo avvio. Indipendente daSESSION_SECRET; eliminarla rende ogni credenziale memorizzata indecifrabile, quindi appartiene ai tuoi backup.- Blueprint (
.mcserver.zip) - uno zip con unmanifest.jsonche descrive la configurazione, le risorse, il riferimento al pack bloccato, il manifest dell’overlay (URL sorgente + sha256), i file di configurazione scelti e opzionalmente un mondo. L’importazione ri-scarica e verifica tramite hash ogni mod e assegna nuove porte. - Container Docker creati dal pannello sono nominati ed etichettati in modo che il watcher possa trovarli; il pannello possiede il loro intero ciclo di vita.
Sequenza di avvio
Sezione intitolata “Sequenza di avvio”require('./instrument')(la porta Sentry) prima di tutto, poirequire('./preflight')per fallire chiaramente su una versione Node non supportata.- Carica la configurazione; assicurati/genera
.session-secrete.secret-key. ensureDataRoot()- crea la struttura./data, puliscitmp/.- Esegui le migrazioni DB, poi
PRAGMA integrity_check(registra rumorosamente, punta adata/backups/_panelin caso di fallimento). - Ricrittografa eventuali segreti legacy con chiave
SESSION_SECRETsotto.secret-key(secretsMigration). - Importa le chiavi API dall’ambiente una volta (
apiKeys.importFromEnvOnce()), blocca qualsiasi server che porta ancora un selettore di modpack non bloccato (packPins.pinUnpinnedServers()), contrassegna le scansioni di compatibilità versione lasciate in esecuzione da un processo precedente come interrotte (compat.reconcileScans()), quindi popola i blueprint iniziali (protetti). - Avvia il server HTTP + WS. Su un bind esposto, stampa il PIN
/setupdella prima esecuzione. - Installa la guardia di runtime post-avvio (cattura guasti non gestiti;
MSM_EXIT_ON_FATAL=1lo fa uscire forzatamente per distribuzioni supervisionate). - Avvia i servizi in background: broker WS, indicizzatore di storage, watcher di crash + inventario, scheduler,
ponte eventi Discord, watcher di outreach chatbot e il timer di manutenzione giornaliero (pulisce vecchie righe di analytics, trascrizioni chatbot, cronologia eventi (365 giorni) e righe della cache API, quindi esegue lo snapshot di
panel.db). - Inizializza Docker in background. L’interfaccia utente è completamente utilizzabile mentre il demone è spento;
le funzionalità Docker si attivano quando diventa raggiungibile. Una volta connesso,
refreshStatuses({ boot })riconcilia gli stati memorizzati nella cache, emette un evento una tantumoffline-after-restartper un server che era attivo prima che il pannello si riavviasse e non verrà ripristinato, e il loop di avvio avvia i serverauto_startpiù recupera i serverauto_restarttrovati in crash durante l’interruzione (rispettando il backoff del loop di crash).
L’ordine instrument-before-preflight è un compromesso deliberato: consente a un futuro wiring Sentry di patchare il runtime per primo, al costo di un messaggio leggermente meno amichevole su un Node veramente antico.
Pipeline di build
Sezione intitolata “Pipeline di build”pnpm run build = build:css (Tailwind → public/css/app.css) + build:js (esbuild →
public/dist/js/, ESM con code-splitting). postinstall esegue solo CSS. public/css/app.css
e public/dist/ sono artefatti di build ignorati da git; la fase di build del Dockerfile esegue il completo
pnpm run build e copia public/ nell’immagine di runtime. Gli asset statici vengono serviti
immutable/long-cache per i file con fingerprint, short-cache per CSS/JS, e no-cache per HTML e
/api.