Architektura
← Powrót do spisu dokumentacji
Minecraft Server Manager to aplikacja Node.js renderowana po stronie serwera, działająca w jednym procesie. Zarządza serwerami Minecraft uruchomionymi jako kontenery Docker przy użyciu obrazu itzg/docker-minecraft-server, komunikując się z demonem Docker przez jego API (nigdy przez wywoływanie docker CLI).
Kształt wykonania
Dział zatytułowany „Kształt wykonania”- Express + Handlebars renderują strony po stronie serwera. Nie ma SPA; JavaScript przeglądarki w
public/js/to ręcznie napisane ulepszenie progresywne. Krok esbuild (pnpm run build:js) łączy i minimalizuje go dopublic/dist/js/; aplikacja serwuje ten pakiet, gdy jest obecny, a surowe źródło w przeciwnym razie, więc uruchomienie w trybie deweloperskim bez budowania nadal działa. node:sqlite(wbudowany w Node; panel wymaga Node ≥ 24) to baza danych – synchroniczna, bez modułów natywnych, w trybie WAL. Mały runner migracji wersjonowanych stosujesrc/db/migrations/*przy starcie. Przygotowane instrukcje są buforowane wsrc/db/index.jsz kluczem opartym na tekście SQL.wsobsługuje strumienie konsoli i statystyk na żywo. Oba są pośredniczone: jeden strumień nadrzędnydocker logs --follow(lubdocker stats) na serwer, zdemultipleksowany raz i rozsyłany do każdej podłączonej karty, zamiast jednego strumienia nadrzędnego na widza. Pośrednik konsoli przechowuje mały bufor powtórek dla późno dołączających kart i usuwa subskrybenta, którego gniazdo zbyt mocno się opóźnia, zamiast spowalniać współdzielony strumień.- dockerode to jedyny sposób, w jaki aplikacja komunikuje się z Dockerem. Punkt końcowy jest automatycznie wykrywany dla każdej platformy (nazwana rura w systemie Windows vs. gniazdo uniksowe).
- Cały stan trwały znajduje się w jednym katalogu (
$DATA_DIR, domyślnie./data). Skopiowanie tego katalogu migruje cały panel.
Warstwowanie
Dział zatytułowany „Warstwowanie”Zależności płyną w jednym kierunku:
┌─────────────────────────────┐ HTTP ───────▶│ web/routes/* (+ middleware)│ parsowanie i walidacja danych wejściowych, kształtowanie odpowiedzi └──────────────┬──────────────┘ │ ┌──────────────▼──────────────┐ │ services/* │ logika domenowa (rzeczywiste funkcje) └───┬─────────┬─────────┬─────┘ │ │ │ ┌────────────▼──┐ ┌────▼────┐ ┌──▼──────────┐ │ docker/* │ │ db/* │ │ storage/* │ infrastruktura └───────────────┘ └─────────┘ └─────────────┘web/routes/- jeden router na domenę (players,worlds,crashes,blueprints,files, …).web/app.jsmontuje te najwyższego poziomu (api.js, JSON API sesji, które również zawiera podstawowe trasy serwera i montuje routery domenowe dla poszczególnych serwerów;index.js, strony;auth,account,tasks, …). Routery walidują za pomocą zod, wywołują usługę i zwracają JSON lub renderują widok. Logika biznesowa nie należy tutaj. Dwa routery są zamontowane w strefie publicznej, przedrequireAuth:routes/status.js(strony statusu serwera HTML z opcją wyboru) iroutes/apiV1.js(/api/v1, JSON API tylko do odczytu uwierzytelniane przez token Bearer wygenerowany przez administratora zservices/apiTokens.js, wyłączone, chyba że włączone w Ustawieniach; zobaczdocs/public-api.md).services/- serce aplikacji. Każda usługa jest właścicielem jednej domeny i może zależeć od infrastruktury i innych usług.docker/- opakowania dockerode:connect(wykrywanie punktu końcowego + stan demona),containers(tworzenie/uruchamianie/zatrzymywanie/ponowne tworzenie z montowaniami, limitami pamięci/CPU i etykietami),logs,stats,images,networks(odkrywanie sieci hosta),hostPath(przekierowuje ścieżki montowania podDATA_DIR_HOST) iwatcher, który zamienia zdarzenia Docker w historię + wykrywanie awarii.db/- opakowanie SQLite i runner migracji.storage/- inicjalizacja./data, strażnik ścieżek (safeJoin, kręgosłup bezpieczeństwa plików) oraz indeksator rozmiaru w tle + egzekwowanie limitów.
Przekrojowo:
config/- konfiguracja środowiskowa plus katalog pól: jedno źródło prawdy dla ustawień serwera. Każda zmienna środowiskowa itzg jest katalogowana (etykieta, pomoc, typ, jednostka, domyślna, walidacja, sekcja, flagi zagrożenia). Kreator, formularze ustawień i walidacja zod są pochodne od niego, więc udostępnienie nowego ustawienia jest zmianą danych, a nie nowym potokiem UI.events/-recordEvent()to jedyny punkt wejścia do dziennika historii; zdarzenia cyklu życia przechwytują również fragmenty logów kontenera dodata/logs/<id>/events/.ws/- uwierzytelnione WebSockety konsoli + statystyk (ciasteczko sesji zweryfikowane przy uaktualnieniu,Originsprawdzany w celu zablokowania ataków między witrynami), pośredniczone na serwer (patrz “Kształt wykonania”).logger.js+instrument.js-require('./logger')(label)zwraca logger Pino dla każdego modułu; poziom zLOG_LEVEL,makeFailureThrottle()utrzymuje pętlę w tle, która stale się psuje, do jednej linii logu plus linii “odzyskana”.src/utils/logSanitize.jsusuwa klucze w formacie poświadczeń i tokeny webhook z ustrukturyzowanych metadanych;src/config/logLevel.jsto współdzielona lista dozwolonych poziomów (utrzymywana oddzielnie, aby uniknąć cyklu wymagania zconfig).src/instrument.jsto uśpione złącze Sentry, ładowane jako pierwsze wsrc/server.js.src/web/middleware/requestLog.jszapisuje jedną linię logu dostępu na żądanie (pomijając/healthzi zasoby statyczne). ESLint egzekwujeno-consolewsrc/**, z wyłączeniempreflight.js,instrument.jsiconfig/index.js(działają one przed istnieniem logera).- Ograniczanie szybkości -
src/web/middleware/rateLimit.jsumieszczaexpress-rate-limitprzed/api(RATE_LIMIT_API_PER_MIN, domyślnie 1200) oraz logowania / 2FA / POSTy konfiguracyjne (RATE_LIMIT_AUTH_PER_15MIN, domyślnie 100);0wyłącza ogranicznik. Kluczuje się nareq.ip, więcTRUST_PROXYma znaczenie za proxy./api/v1ma własne ograniczniki: limit na klienta IP (pięciokrotność budżetu na token), który działa przed weryfikacją tokenu, a następnie budżet na token (RATE_LIMIT_PUBLIC_API_PER_MIN, domyślnie 120) kluczowany na identyfikator zweryfikowanego tokenu. Oddzielny licznik miękki na konto wsrc/web/middleware/auth.jsobsługuje blokadę logowania (na IP i globalnie na konto, zanikający). - Autoryzacja: dwie warstwy. Globalna rola (
requireAuth→requireRole/requireWritewsrc/web/middleware/auth.js) blokuje akcje w całym panelu i jest domyślna dla każdego serwera. Uprawnienia na serwer (src/services/permissions.js, dziewięć możliwości przechowywanych jako lista JSON na(użytkownik, serwer)wuser_server_permissions) doprecyzowują ten domyślny dla jednego serwera; każda trasa/api/servers/:id, montowanie podroutera, strona, WebSocket i lista obejmująca całą flotę przechodzi przezsrc/web/middleware/serverAccess.js(serverScope, zamontowany na prefiksie/servers/:idzarówno API, jak i routera stron, ukrywa serwer bezviewjako 404;requireCap(cap)nazywa możliwość, której potrzebuje trasa). Zapisy, które nazywają swój serwer w treści (harmonogramy, ekstrakcja i instalacja świata, eksport schematów), są otwierane dla widzów tylko przezrequireWritedla tego serwera, a każda taka trasa sama sprawdza możliwość.test/permissions-routes.test.jsprzechodzi przez stosy routerów na żywo i kończy się niepowodzeniem, jeśli trasa zapisu powiązana z serwerem, montowanie lub strona nie ma bramki.
Kluczowe zachowania domenowe
Dział zatytułowany „Kluczowe zachowania domenowe”- Modpacki są zawsze przypinane. Obraz automatycznie aktualizuje nieprzypięte paczki przy każdym ponownym uruchomieniu, więc panel rozwiązuje “najnowszy” do konkretnego identyfikatora wersji w momencie instalacji i przypina go. Aktualizacje to jawny, skoordynowany przepływ (
updates/): podgląd → kopia zapasowa przed aktualizacją → płynne zatrzymanie → ponowne przypięcie → ponowne utworzenie → monitorowanie stanu → przywracanie jednym kliknięciem. - Nakładka niestandardowych modów jest zarządzana przez panel: dodane przez użytkownika mody trafiają do zdeduplikowanej biblioteki i są łączone twardymi linkami z serwerem, dzięki czemu przetrwają aktualizacje paczek. Wyłączanie jest świadome klasy. Ponieważ biblioteka przechowuje każdą pobraną wersję, aktualizacja zapisuje wersję, którą zastąpiła (
server_content.previous_*) i może zostać przywrócona tylko z plików lokalnych. Wyłączenie moda paczki zapisuje zmienną środowiskową wykluczenia paczki zamiast tego;packs.applyPackprzenosi to i resztę dostrajania paczki (PACK_TUNING_KEYS) przez zmianę wersji tej samej paczki i usuwa ją po zmianie paczki. - Aktualizacja wersji Minecraft musi zostać zasłużona.
services/compat.jsskanuje mody serwera – rozwiązane z wierszy zainstalowanych przez panel, następnie manifestu paczki CurseForge, a następnie przez skrót zawartości w stosunku do Modrinth/CurseForge – i buduje macierz wsparcia (ładowarka, wersja Minecraft) na projekt zlatestFilesIndexesCurseForge (200 projektów na żądanie) i listy wersji Modrinth na projekt (jedno żądanie na projekt, co utrzymuje parę ładowarka i wersja). Sprawdzanie aktualizacji oferuje tylko najnowszą wersję, którą WSZYSTKIE mody obsługują, i nic nie oferuje, gdy odpowiedź nie może zostać ustalona: brak skanowania, skanowanie dla innej wersji lub ładowarki, które nigdy się nie zakończyło, lub plik jar, którego żaden rejestr nie rozpoznaje. Skanowania są tylko ręczne, a ich postęp i częściowe wyniki znajdują się wversion_compat(nie wservices/tasks.jsw pamięci), więc odświeżenie lub ponowne uruchomienie panelu wznawia zamiast zawieszać się na spinnerze;reconcileScans()oznacza skany osierocone przez zamknięcie przy następnym uruchomieniu. - Wersja ładowarki modów jest przypinana, jak wszystko inne.
services/loaderPin.jsodczytuje zainstalowaną wersję z manifestu instalacyjnego obrazu (.forge-manifest.jsoni podobne) i zapisuje przypięcie: zmienną itzg ładowarki na zwykłym serwerze (FORGE_VERSION, …), lubCF_MOD_LOADER_VERSIONna paczce CurseForge Forge lub Fabric, która nadpisuje wersję zadeklarowaną przez paczkę. Instalator CurseForge obrazu ignoruje to nadpisanie dla NeoForge, a paczki Modrinth i FTB nie mają go, więc ich ładowarka podąża za paczką.packs.applyPackusuwa wszystkie zmienneCF_przy aktualizacji lub przywracaniu paczki, co usuwa nadpisanie wraz z resztą. Wersja typowana jest najpierw sprawdzana w stosunku do pełnej listy rejestru (services/loaderVersions.js; Forge pochodzi z metadanych maven, które pomijają liczby; brakujące jest ponownie sprawdzane raz w stosunku do samego rejestru), a następnie zmiana jest tworzona kopia zapasowa → przypięcie (nad zmienną środowiskową taką, jaka jest po kopii zapasowej) → przebudowa. - Porty są alokowane z podstawowego schematu (gra od
PORT_GAME_STARTw górę, RCON = gra +PORT_RCON_OFFSET, Bedrock odPORT_BEDROCK_START), sprawdzane pod kątem dostępności i rezerwowane w bazie danych. “Zajęte” to suma roszczeń każdego serwera (porty na żywo, plus oczekująca para poniżej), każdy port hosta, który publikuje jakikolwiek kontener Docker (containers.publishedHostPorts: powiązania na żywo działających kontenerów plus skonfigurowane dla każdego zatrzymanego kontenera, ponieważ sonda powiązania systemu operacyjnego z wnętrza własnego kontenera panelu widzi tylko przestrzeń sieciową tego kontenera) i sonda systemu operacyjnego. Część Docker jest buforowana przez 3 sekundy i ograniczona: lista, która nie odpowiada w ciągu 2,5 sekundy, usuwa tylko część Docker, a powolna inspekcja kosztuje tylko porty tego kontenera. Tworzenie serwera iservers.changeGamePortwybierają porty przez jeden łańcuch serializacji, który obejmuje tylko wybór i jego roszczenie (zapis wiersza dla utworzenia, rezerwacja w pamięci dla zmiany portu); wybierak portów BlueMap i dodatkowe nadpisania portów nie są w nim zawarte i nie konsultują Dockera. Zmiana portu na istniejącym serwerze (servers.changeGamePort, pod blokadą operacyjną serwera) jest stosowana natychmiast, ponieważ Docker naprawia powiązania portów przy tworzeniu kontenera: nowa para (RCON zawsze gra +PORT_RCON_OFFSET) jest sprawdzana i rezerwowana w pamięci (ports.reserve, zarówno stara, jak i nowa para, honorowana przez każdy inny wybór) pod blokadą portu. Jest odrzucana (409PENDING_CHANGES), gdy inne ustawienia czekają na przebudowę, więc przebudowuje tylko kontener, który już działał, na nowym porcie; a działający serwer jest zmieniany tylko wtedy, gdy żądanie mówirestart: true(w przeciwnym razie 409NEEDS_CONFIRM). Obraz jest pobierany, a niestandardowa nazwa kontenera jest sprawdzana przed dotknięciem czegokolwiek. Działający serwer jest zatrzymywany; następnie nowa para jest zapisywana zpending_recreate = 1(więc awaria panelu od tego momentu pozostawia uczciwy “rebuild pending”), kontener jest usuwany, przebudowywany na nowej parze i uruchamiany. Jeśli jakikolwiek krok po zatrzymaniu się nie powiedzie,putBackOnOldPortzapisuje starą parę z powrotem, przebudowuje (i restartuje, jeśli działał) na niej i zapisuje, który krok się nie powiódł; historia i alerty mówią, czy nawet to się nie powiodło, co pozostawia serwer zatrzymany, dopóki ktoś go nie uruchomi. Możliwośćsettingsjest wystarczająca, w tym działający serwer. Nie-administratorzy mogą wybierać tylko odPORT_GAME_STARTw górę. (Kolumnyport_*_pendingz migracji 029 należą do wcześniejszego, niepublikowanego projektu i są nieużywane; 031 je czyści.) Zderzenie blokady odpowiada 409 zcode: 'BUSY', które ponawiające próby wywołań poniżej sprawdzają zamiast tekstu. Automatyczny restart po awarii (watcher.restartAfterCrash) i zaplanowana kopia zapasowa lub uruchomienie (scheduler.runTaskWithRetry), które znajdują serwer zajęty inną akcją, próbują ponownie co 20 s / 60 s przez maksymalnie 30 minut, a aktualizacja lub przywracanie paczki ponawia swoje zablokowane kroki w ten sam sposób (opLock.retryWhileBusy); restart po awarii lub oczekujące zaplanowane uruchomienie rezygnuje, gdy ktoś zatrzymał, zabił lub uruchomił serwer od tego czasu (events.lifecycleActionSince), a restart po awarii również, gdy automatyczny restart jest wyłączony lub serwer zniknął. Zaplanowane restarty, zatrzymania i polecenia nie są ponawiane, a harmonogram, którego ostatnie uruchomienie nadal czeka, pomija następne uruchomienie. - Limity dyskowe są egzekwowane przez panel, ponieważ Docker nie może ograniczyć użycia bind-mount: indeksator buforuje rozmiary katalogów, a operacje powiększania dysku są na nich blokowane.
- Sekrety (hasła RCON, klucze API, sekrety TOTP, adres URL webhooka Discord) są szyfrowane w spoczynku za pomocą AES-256-GCM przy użyciu dedykowanego losowego klucza w
$DATA_DIR/.secret-key(tryb0600, automatycznie generowany). Jest niezależny odSESSION_SECRET; klucz pochodny odSESSION_SECRETjest przechowywany jako zapasowy tylko do deszyfrowania dla wartości zapisanych przed istnieniem dedykowanego klucza, asrc/services/secretsMigration.jsponownie szyfruje je pod dedykowanym kluczem raz przy starcie..secret-key, który istnieje, ale nie może zostać sparsowany, jest poważnym błędem startowym (nigdy nie jest cicho regenerowany nad istniejącym). Schematy usuwają wszystkie sekrety podczas eksportu. server.propertiesjest własnością panelu, ale jest zacieniony przez zmienne środowiskowe. Obraz itzg ponownie potwierdza każdą właściwość opartą na zmiennej środowiskowej przy każdym uruchomieniu (OVERRIDE_SERVER_PROPERTIESdomyślnie true), więc wartość, którą panel edytuje bezpośrednio - PvP/trudność Kontroli Świata, przełącznik białej listy, edytor plików - zostałaby cicho przywrócona przy następnym uruchomieniu, chyba że pasująca zmienna środowiskowa zostanie usunięta, a kontener ponownie utworzony. Każdy bezpośredni zapis właściwości przechodzi przezwriteServerProperties()(cały plik) lubsetServerProperty()(jeden klucz) wsrc/services/servers.js, które atomowo przepisują plik, usuwają zmienną środowiskową za każdym zmienionym kluczem (poprzez atrybutprop:w polach katalogu, sprawdzany w testach w stosunku do własnych definicji właściwości obrazu) i oznaczająpending_recreate. Trudność jest zapisywana zarówno w pliku, jak i wysyłana przez RCON, ponieważ dedykowany serwer ponownie stosuje właściwośćdifficultyprzy każdym uruchomieniu. Sam Minecraft ponownie zapisuje server.properties z wartości początkowych przy włączaniu/wyłączaniuwhitelist, co cofnęłoby edycje dokonane podczas działania serwera, więc działający przełącznik białej listy tworzy migawkę pliku, a następnie zapisuje go z powrotem, zmieniając tylkowhite-list. Zmienne środowiskowe pozostają w pełni konfigurowalne przy tworzeniu (kreator je renderuje i stosują się raz); odpinają się dopiero za pierwszym razem, gdy panel edytuje podstawową właściwość. MOTD ma tę samą umowę: bezpośrednia edycja plikumotdją odznacza, więc ostatni zapis wygrywa.
Formaty danych i transmisji
Dział zatytułowany „Formaty danych i transmisji”data/panel.db- baza danych SQLite. Codziennie tworzona migawka za pomocąVACUUM INTOdodata/backups/_panel/(zachowywane najnowsze 14);PRAGMA integrity_checkuruchamiany przy starcie.data/.session-secret- automatycznie generowany sekret podpisywania ciasteczek, tworzony przy pierwszym uruchomieniu, jeśliSESSION_SECRETjest nieustawiony. Usunięcie go powoduje zmianę sekretu (co unieważnia sesje).data/.secret-key- dedykowany 32-bajtowy klucz szyfrowania w spoczynku (tryb0600), automatycznie tworzony przy pierwszym uruchomieniu. Niezależny odSESSION_SECRET; jego usunięcie sprawia, że każde przechowywane poświadczenie jest niemożliwe do odszyfrowania, więc należy je przechowywać wraz z kopiami zapasowymi.- Schematy (
.mcserver.zip) - archiwum zip zmanifest.jsonopisującym konfigurację, zasoby, przypięte odniesienie do paczki, manifest nakładki (adresy URL źródłowe + sha256), wybrane pliki konfiguracyjne i opcjonalnie świat. Import ponownie pobiera i weryfikuje skrót każdego moda oraz przydziela nowe porty. - Kontenery Docker tworzone przez panel są nazwane i oznaczone etykietami, aby watcher mógł je znaleźć; panel jest właścicielem ich pełnego cyklu życia.
Sekwencja startowa
Dział zatytułowany „Sekwencja startowa”require('./instrument')(złącze Sentry) przed wszystkim innym, a następnierequire('./preflight'), aby jasno poinformować o nieobsługiwanej wersji Node.- Załaduj konfigurację; zapewnij/wygeneruj
.session-secretoraz.secret-key. ensureDataRoot()- utwórz układ./data, wyczyśćtmp/.- Uruchom migracje bazy danych, a następnie
PRAGMA integrity_check(głośno loguje, wskazuje nadata/backups/_panelw przypadku błędu). - Szyfruj ponownie wszelkie starsze sekrety kluczowane
SESSION_SECRETpod.secret-key(secretsMigration). - Jednorazowo zaimportuj klucze API ze środowiska (
apiKeys.importFromEnvOnce()), przypnij wszelkie serwery nadal posiadające nieprzypięty selektor modpacka (packPins.pinUnpinnedServers()), oznacz skany zgodności wersji pozostawione uruchomione przez poprzedni proces jako przerwane (compat.reconcileScans()), a następnie zainicjuj schematy startowe (zabezpieczone). - Uruchom serwer HTTP + WS. Na odsłoniętym połączeniu wydrukuj PIN
/setupz pierwszego uruchomienia. - Zainstaluj strażnika wykonania po uruchomieniu (wyłapuje nieprzechwycone błędy;
MSM_EXIT_ON_FATAL=1powoduje twarde wyjście dla wdrożeń nadzorowanych). - Uruchom usługi w tle: pośrednik WS, indeksator pamięci masowej, watchery awarii + inwentarza, harmonogram, mostek zdarzeń Discord, watcher outreach czatbota i codzienny timer konserwacji (usuwa stare wiersze analityczne, transkrypcje czatbota, historię zdarzeń (365 dni) i wiersze pamięci podręcznej API, a następnie tworzy migawkę
panel.db). - Zainicjuj Docker w tle. Interfejs użytkownika jest w pełni użyteczny, gdy demon jest niedostępny; funkcje Docker włączają się, gdy stanie się dostępny. Po połączeniu
refreshStatuses({ boot })uzgadnia buforowane statusy, emituje jednorazowe zdarzenieoffline-after-restartdla serwera, który był uruchomiony przed ponownym uruchomieniem panelu i nie zostanie przywrócony, a pętla uruchamiania rozpoczynaauto_startserwery plus odzyskujeauto_restartserwery znalezione jako awaryjne podczas awarii (z uwzględnieniem cofania pętli awarii).
Kolejność instrument-before-preflight to świadomy kompromis: pozwala przyszłemu okablowaniu Sentry na załatanie środowiska wykonawczego jako pierwszemu, kosztem nieco mniej przyjaznego komunikatu w przypadku naprawdę starego Node.
Potok budowania
Dział zatytułowany „Potok budowania”pnpm run build = build:css (Tailwind → public/css/app.css) + build:js (esbuild → public/dist/js/, ESM z podziałem kodu). postinstall uruchamia tylko CSS. public/css/app.css i public/dist/ to artefakty budowania ignorowane przez git; etap budowania Dockerfile uruchamia pełne pnpm run build i kopiuje public/ do obrazu wykonawczego. Zasoby statyczne są serwowane z immutable/długim buforem dla plików z odciskiem palca, krótkim buforem dla CSS/JS i no-cache dla HTML i /api.