Przejdź do głównej zawartości

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).

  • 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 do public/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 stosuje src/db/migrations/* przy starcie. Przygotowane instrukcje są buforowane w src/db/index.js z kluczem opartym na tekście SQL.
  • ws obsługuje strumienie konsoli i statystyk na żywo. Oba są pośredniczone: jeden strumień nadrzędny docker logs --follow (lub docker 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.

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.js montuje 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, przed requireAuth: routes/status.js (strony statusu serwera HTML z opcją wyboru) i routes/apiV1.js (/api/v1, JSON API tylko do odczytu uwierzytelniane przez token Bearer wygenerowany przez administratora z services/apiTokens.js, wyłączone, chyba że włączone w Ustawieniach; zobacz docs/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 pod DATA_DIR_HOST) i watcher, 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 do data/logs/<id>/events/.
  • ws/ - uwierzytelnione WebSockety konsoli + statystyk (ciasteczko sesji zweryfikowane przy uaktualnieniu, Origin sprawdzany 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 z LOG_LEVEL, makeFailureThrottle() utrzymuje pętlę w tle, która stale się psuje, do jednej linii logu plus linii “odzyskana”. src/utils/logSanitize.js usuwa klucze w formacie poświadczeń i tokeny webhook z ustrukturyzowanych metadanych; src/config/logLevel.js to współdzielona lista dozwolonych poziomów (utrzymywana oddzielnie, aby uniknąć cyklu wymagania z config). src/instrument.js to uśpione złącze Sentry, ładowane jako pierwsze w src/server.js. src/web/middleware/requestLog.js zapisuje jedną linię logu dostępu na żądanie (pomijając /healthz i zasoby statyczne). ESLint egzekwuje no-console w src/**, z wyłączeniem preflight.js, instrument.js i config/index.js (działają one przed istnieniem logera).
  • Ograniczanie szybkości - src/web/middleware/rateLimit.js umieszcza express-rate-limit przed /api (RATE_LIMIT_API_PER_MIN, domyślnie 1200) oraz logowania / 2FA / POSTy konfiguracyjne (RATE_LIMIT_AUTH_PER_15MIN, domyślnie 100); 0 wyłącza ogranicznik. Kluczuje się na req.ip, więc TRUST_PROXY ma znaczenie za proxy. /api/v1 ma 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 w src/web/middleware/auth.js obsługuje blokadę logowania (na IP i globalnie na konto, zanikający).
  • Autoryzacja: dwie warstwy. Globalna rola (requireAuth → requireRole / requireWrite w src/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) w user_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 przez src/web/middleware/serverAccess.js (serverScope, zamontowany na prefiksie /servers/:id zarówno API, jak i routera stron, ukrywa serwer bez view jako 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 przez requireWrite dla tego serwera, a każda taka trasa sama sprawdza możliwość. test/permissions-routes.test.js przechodzi 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.
  • 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.applyPack przenosi 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.js skanuje 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 z latestFilesIndexes CurseForge (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ę w version_compat (nie w services/tasks.js w 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.js odczytuje zainstalowaną wersję z manifestu instalacyjnego obrazu (.forge-manifest.json i podobne) i zapisuje przypięcie: zmienną itzg ładowarki na zwykłym serwerze (FORGE_VERSION, …), lub CF_MOD_LOADER_VERSION na 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.applyPack usuwa wszystkie zmienne CF_ 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_START w górę, RCON = gra + PORT_RCON_OFFSET, Bedrock od PORT_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 i servers.changeGamePort wybierają 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 (409 PENDING_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ówi restart: true (w przeciwnym razie 409 NEEDS_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 z pending_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, putBackOnOldPort zapisuje 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ść settings jest wystarczająca, w tym działający serwer. Nie-administratorzy mogą wybierać tylko od PORT_GAME_START w górę. (Kolumny port_*_pending z migracji 029 należą do wcześniejszego, niepublikowanego projektu i są nieużywane; 031 je czyści.) Zderzenie blokady odpowiada 409 z code: '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 (tryb 0600, automatycznie generowany). Jest niezależny od SESSION_SECRET; klucz pochodny od SESSION_SECRET jest przechowywany jako zapasowy tylko do deszyfrowania dla wartości zapisanych przed istnieniem dedykowanego klucza, a src/services/secretsMigration.js ponownie 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.properties jest 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_PROPERTIES domyś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 przez writeServerProperties() (cały plik) lub setServerProperty() (jeden klucz) w src/services/servers.js, które atomowo przepisują plik, usuwają zmienną środowiskową za każdym zmienionym kluczem (poprzez atrybut prop: 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ść difficulty przy każdym uruchomieniu. Sam Minecraft ponownie zapisuje server.properties z wartości początkowych przy włączaniu/wyłączaniu whitelist, 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 tylko white-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 pliku motd ją odznacza, więc ostatni zapis wygrywa.
  • data/panel.db - baza danych SQLite. Codziennie tworzona migawka za pomocą VACUUM INTO do data/backups/_panel/ (zachowywane najnowsze 14); PRAGMA integrity_check uruchamiany przy starcie.
  • data/.session-secret - automatycznie generowany sekret podpisywania ciasteczek, tworzony przy pierwszym uruchomieniu, jeśli SESSION_SECRET jest nieustawiony. Usunięcie go powoduje zmianę sekretu (co unieważnia sesje).
  • data/.secret-key - dedykowany 32-bajtowy klucz szyfrowania w spoczynku (tryb 0600), automatycznie tworzony przy pierwszym uruchomieniu. Niezależny od SESSION_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 z manifest.json opisują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.
  1. require('./instrument') (złącze Sentry) przed wszystkim innym, a następnie require('./preflight'), aby jasno poinformować o nieobsługiwanej wersji Node.
  2. Załaduj konfigurację; zapewnij/wygeneruj .session-secret oraz .secret-key.
  3. ensureDataRoot() - utwórz układ ./data, wyczyść tmp/.
  4. Uruchom migracje bazy danych, a następnie PRAGMA integrity_check (głośno loguje, wskazuje na data/backups/_panel w przypadku błędu).
  5. Szyfruj ponownie wszelkie starsze sekrety kluczowane SESSION_SECRET pod .secret-key (secretsMigration).
  6. 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).
  7. Uruchom serwer HTTP + WS. Na odsłoniętym połączeniu wydrukuj PIN /setup z pierwszego uruchomienia.
  8. Zainstaluj strażnika wykonania po uruchomieniu (wyłapuje nieprzechwycone błędy; MSM_EXIT_ON_FATAL=1 powoduje twarde wyjście dla wdrożeń nadzorowanych).
  9. 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).
  10. 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 zdarzenie offline-after-restart dla serwera, który był uruchomiony przed ponownym uruchomieniem panelu i nie zostanie przywrócony, a pętla uruchamiania rozpoczyna auto_start serwery plus odzyskuje auto_restart serwery 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.

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.