アーキテクチャ
Minecraft Server Manager は、単一プロセスでサーバーレンダリングされる Node.js アプリケーションです。
itzg/docker-minecraft-server イメージとして実行される Minecraft サーバーを Docker コンテナで管理します。Docker デーモンとは、docker CLI をシェルアウトするのではなく、API 経由で通信します。
ランタイムの構造
Section titled “ランタイムの構造”- Express + Handlebars でページをサーバーサイドでレンダリングします。SPA ではありません。
public/js/のブラウザ JS は、手書きのプログレッシブエンハンスメントです。esbuild ステップ (pnpm run build:js) がそれをバンドルおよびミニファイしてpublic/dist/js/に出力します。アプリは、それが存在する場合はそのバンドルを、そうでなければ生のソースを提供するため、ビルドなしの開発実行でも機能します。 node:sqlite(Node に組み込み。パネルは Node ≥ 24 を必要とします) がデータベースです。同期式で、ネイティブモジュールはなく、WAL モードです。小さなバージョン管理されたマイグレーションランナーが、起動時にsrc/db/migrations/*を適用します。プリペアドステートメントは、SQL テキストをキーとしてsrc/db/index.jsにキャッシュされます。wsがライブコンソールと統計ストリームを伝送します。どちらも ブローカー経由 です。サーバーごとに 1 つの上流docker logs --follow(またはdocker stats) があり、一度デマルチプレクスされて接続されているすべてのタブにファンアウトされます。ビューアごとに 1 つの上流ではありません。コンソールブローカーは、遅れて参加するタブのために小さなリプレイバッファを保持し、共有ストリームを遅延させるのではなく、ソケットが遅れすぎたサブスクライバをドロップします。- dockerode は、アプリが Docker と通信する唯一の方法です。エンドポイントはプラットフォームごとに自動検出されます (Windows 名前付きパイプ対 Unix ソケット)。
- すべての永続状態は 1 つのディレクトリ (
$DATA_DIR、デフォルトは./data) の下に保存されます。そのディレクトリをコピーすると、パネル全体が移行されます。
レイヤリング
Section titled “レイヤリング”依存関係は一方向に流れます。
┌─────────────────────────────┐ HTTP ───────▶│ web/routes/* (+ ミドルウェア)│ 入力を解析・検証し、応答を整形 └──────────────┬──────────────┘ │ ┌──────────────▼──────────────┐ │ services/* │ ドメインロジック (実際の機能) └───┬─────────┬─────────┬─────┘ │ │ │ ┌────────────▼──┐ ┌────▼────┐ ┌──▼──────────┐ │ docker/* │ │ db/* │ │ storage/* │ インフラストラクチャ └───────────────┘ └─────────┘ └─────────────┘web/routes/- ドメインごとに 1 つのルーター (players,worlds,crashes,blueprints,files, …)。web/app.jsはトップレベルのルーターをマウントします (api.js、コアサーバー ルートも保持し、サーバーごとのドメイン ルーターをマウントするセッション JSON API。index.js、ページ。auth,account,tasks, …)。ルーターは zod で検証し、サービスを呼び出し、JSON を返すかビューをレンダリングします。ビジネスロジックはここには属しません。2 つのルーターが 公開ゾーン のrequireAuthの前にマウントされます。routes/status.js(オプトインのサーバーごとの HTML ステータスページ) とroutes/apiV1.js(/api/v1、管理者発行の Bearer トークンで認証される読み取り専用 JSON API。services/apiTokens.jsから、設定で有効になっていない限り無効。docs/public-api.mdを参照)。services/- アプリケーションの心臓部です。各サービスは 1 つのドメインを所有し、インフラストラクチャや他のサービスに依存する場合があります。docker/- dockerode ラッパー:connect(エンドポイント検出 + デーモンヘルス)、containers(バインドマウント、メモリ/CPU 制限、ラベル付きで作成/開始/停止/再作成)、logs、stats、images、networks(ホストネットワーク検出)、hostPath(DATA_DIR_HOSTの下にバインドパスを再ルート)、および Docker イベントを履歴 + クラッシュ検出に変換するwatcher。db/- SQLite ラッパーとマイグレーションランナー。storage/-./dataのブートストラップ、パスガード (safeJoin、ファイル安全性のバックボーン)、およびバックグラウンド サイズインデクサー + クォータ強制。
横断的なもの:
config/- 環境設定と フィールドカタログ: サーバー設定の単一の真実の情報源。すべての itzg 環境変数がカタログ化されています (ラベル、ヘルプ、タイプ、単位、デフォルト、検証、セクション、危険フラグ)。ウィザード、設定フォーム、zod 検証はすべてこれらから派生しているため、新しい設定を公開することはデータ変更であり、新しい UI の配管ではありません。events/-recordEvent()は履歴ログへの唯一のエントリポイントです。ライフサイクルイベントは、コンテナログの抜粋をdata/logs/<id>/events/にキャプチャします。ws/- 認証済みコンソール + 統計 WebSocket (アップグレード時にセッション Cookie が検証され、Originがクロスサイトハイジャックをブロックするためにチェックされます)、サーバーごとにブローカーされます (「ランタイムの構造」を参照)。logger.js+instrument.js-require('./logger')(label)はモジュールごとの Pino ロガーを返します。レベルはLOG_LEVELから。makeFailureThrottle()は、永続的に失敗するバックグラウンドループを 1 つのログ行と「回復済み」行に制限します。src/utils/logSanitize.jsは、構造化メタデータから資格情報形式のキーと Webhook トークンを削除します。src/config/logLevel.jsは共有レベルの許可リストです (ロガーが存在する前にconfigとの要求サイクルを避けるために分離されています)。src/instrument.jsは休止状態の Sentry シームであり、src/server.jsで最初にロードされます。src/web/middleware/requestLog.jsはリクエストごとに 1 行のアクセスログを書き込みます (/healthzと静的アセットはスキップ)。ESLint はsrc/**の下でno-consoleを強制し、preflight.js,instrument.js,config/index.jsは例外です (これらはロガーが存在する前に実行されます)。- レート制限 -
src/web/middleware/rateLimit.jsはexpress-rate-limitを/api(RATE_LIMIT_API_PER_MIN、デフォルト 1200) およびログイン / 2FA / セットアップ POST (RATE_LIMIT_AUTH_PER_15MIN、デフォルト 100) の前に配置します。0はリミッターを無効にします。req.ipをキーとするため、プロキシの後ろではTRUST_PROXYが重要です。/api/v1には独自のレートリミッターがあります。クライアント IP ごとのキャップ (トークンあたりの予算の 5 倍) がトークン検証前に実行され、次にトークンごとの予算 (RATE_LIMIT_PUBLIC_API_PER_MIN、デフォルト 120) が検証済みトークンの ID をキーとして実行されます。src/web/middleware/auth.jsの個別のアカウントあたりのソフトカウンターがログインロックアウト (IP ごとおよびアカウント全体、減衰) を処理します。 - 認可: 2 つのレイヤー。グローバルロール (
requireAuth→requireRole/requireWriteinsrc/web/middleware/auth.js) はパネル全体の操作をゲートし、すべてのサーバーのデフォルトです。サーバーごとの権限 (src/services/permissions.js、(user, server)ごとにuser_server_permissionsに JSON リストとして保存される 9 つの機能) は、1 つのサーバーに対してそのデフォルトを洗練します。すべての/api/servers/:idルート、サブ ルーター マウント、ページ、WebSocket、およびフリート全体のリストはsrc/web/middleware/serverAccess.js(serverScope、API とページ ルーターの両方の/servers/:idプレフィックスにマウントされ、viewなしでサーバーを 404 として非表示にします。requireCap(cap)はルートが必要とする機能を指定します) を通過します。サーバー名を本文で指定する書き込み (スケジュール、ワールド抽出とインストール、ブループリントのエクスポート) は、requireWriteによってビューア向けにそのサーバーに対してのみ開かれ、各ルートは機能自体をチェックします。test/permissions-routes.test.jsはライブ ルーター スタックをウォークし、サーバー スコープの書き込みルート、マウント、またはページにゲートがない場合に失敗します。
主要なドメインの動作
Section titled “主要なドメインの動作”- Modpack は常にピン留めされます。 イメージは、ピン留めされていないパックを再起動ごとに自動アップグレードするため、パネルはインストール時に「latest」を具体的なバージョン ID に解決し、ピン留めします。アップグレードは明示的にオーケストレーションされたフローです (
updates/): プレビュー → アップデート前バックアップ → グレースフル停止 → 再ピン留め → 再作成 → ヘルスモニター → ワンクリックロールバック。 - カスタム Mod のオーバーレイ はパネル管理です。ユーザーが追加した Mod は重複排除ライブラリに配置され、サーバーにハードリンクされるため、パックの更新でも存続します。無効化はクラスを認識します。ライブラリはダウンロードしたすべてのビルドを保持するため、更新は置き換えられたビルドを記録し (
server_content.previous_*)、ローカルファイルからのみ元に戻すことができます。パック Mod を無効化すると、パックの除外環境変数が書き込まれます。packs.applyPackは、同じパックのバージョン変更時にその変数と残りのパックチューニング (PACK_TUNING_KEYS) を引き継ぎ、パックが変更されるとドロップします。 - Minecraft バージョンのアップグレードは「獲得」される必要があります。
services/compat.jsはサーバーの Mod をスキャンします (パネルインストール済み行から解決され、次に CurseForge パックマニフェストから、次に Modrinth/CurseForge に対してコンテンツハッシュで解決されます)。各プロジェクトの (ローダー、Minecraft バージョン) サポートマトリックスを、CurseForge のlatestFilesIndexes(リクエストあたり 200 プロジェクト) と Modrinth のプロジェクトごとのバージョンリスト (プロジェクトあたり 1 リクエスト、これがローダーとバージョンをペアで保持する理由) から構築します。更新チェッカーは、すべての Mod がサポートする最新バージョンのみを提供し、回答を確立できない場合は何も提供しません。スキャンは手動のみで、その進捗状況と部分的な結果はversion_compatに保存されます (メモリ内のservices/tasks.jsではありません)。そのため、リフレッシュまたはパネルの再起動は、スピンナーでハングするのではなく再開されます。reconcileScans()は、シャットダウンによって中断されたスキャンを次の起動時にマークします。 - Mod ローダーのバージョンは、他のすべてと同様にピンです。
services/loaderPin.jsは、イメージ自体のインストールマニフェスト (.forge-manifest.jsonなど) からインストール済みビルドを読み取り、ピンを書き込みます。プレーンサーバー (FORGE_VERSION, …) のローダーの itzg 変数、または Forge または Fabric CurseForge パックのCF_MOD_LOADER_VERSION。これはパックが宣言するバージョンをオーバーライドします。イメージの CurseForge インストーラーは NeoForge の場合はそのオーバーライドを無視し、Modrinth と FTB パックにはオーバーライドがないため、それらのローダーはパックに従います。packs.applyPackは、パックの更新またはロールバック時にすべてのCF_変数を削除し、残りの変数と共にオーバーライドをドロップします。型指定されたビルドは、最初にレジストリの完全なリストに対してチェックされます (services/loaderVersions.js。Forge のものは Maven メタデータから取得され、番号はスキップされます。見つからない場合はレジストリ自体に対して 1 回再チェックされます)。次に、変更はバックアップ → ピン (バックアップ後の環境変数をオーバーライド) → 再構築です。 - ポート はベーススキームから割り当てられます (ゲームは
PORT_GAME_START以降、RCON = ゲーム +PORT_RCON_OFFSET、Bedrock はPORT_BEDROCK_STARTから)。利用可能性がプローブされ、DB に予約されます。「使用中」は、すべてのサーバーの要求 (ライブポート、および保留中のペア)、Docker コンテナが公開するすべてのホストポート (containers.publishedHostPorts: 実行中のコンテナのライブバインディングと停止中のコンテナの設定済みバインディングの両方。パネル自身のコンテナ内からの OS バインドプローブは、そのコンテナのネットワーク名前空間のみを認識するため)、および OS プローブの和集合です。Docker の部分は 3 秒間キャッシュされ、制限されています。2.5 秒以内に応答しないリストは Docker 部分のみをドロップし、遅いインスペクトはコンテナのポートのみをコストとします。サーバーの作成とservers.changeGamePortは、ピックとその要求のみをカバーする 1 つのシリアライゼーションチェーンを通じてポートを選択します (作成の行書き込み、メモリ内のポート変更の予約)。BlueMap のポートピッカーと追加ポートのオーバーライドは含まれておらず、Docker を参照しません。既存サーバーのポート変更 (servers.changeGamePort、サーバーの op ロックの下) は一度に適用されます。Docker はコンテナ作成時にポートバインディングを修正するため、新しいペア (RCON は常にゲーム +PORT_RCON_OFFSET) はメモリ内でチェックおよび予約されます (ports.reserve、古いペアと新しいペアの両方、他のすべてのピックで尊重されます) ポートロックの下。再構築を待機している他の設定がある場合、拒否されます (409PENDING_CHANGES)。そのため、コンテナは既に実行されていたもののみを再構築し、新しいポートで実行されます。実行中のサーバーは、リクエストがrestart: trueを指定した場合にのみ変更されます (それ以外の場合は 409NEEDS_CONFIRM)。イメージはプルされ、カスタムコンテナ名は何も触れる前にチェックされます。実行中のサーバーは停止されます。次に、新しいペアがpending_recreate = 1で書き込まれ (これにより、そこからのパネルクラッシュは正直な「再構築保留中」を残します)、コンテナが削除され、新しいペアで再構築され、開始されます。停止後のいずれかのステップが失敗した場合、putBackOnOldPortは古いペアを書き戻し、再構築し (実行中だった場合は再起動)、それを記録し、どのステップが失敗したかを記録します。履歴とアラートは、それさえ失敗したかどうかを示し、サーバーは誰かが起動するまで停止したままになります。settings機能は、実行中のサーバーを含めて十分です。管理者以外はPORT_GAME_START以降からのみ選択できます。(マイグレーション 029 のport_*_pending列は、以前の未リリースデザインのものであり、使用されていません。031 でクリアされます。) ロックの競合は 409 をcode: 'BUSY'で応答し、再試行する呼び出し元は、その単語ではなく、それをチェックします。クラッシュ時の自動再起動 (watcher.restartAfterCrash) とスケジュールされたバックアップまたは開始 (scheduler.runTaskWithRetry) は、サーバーが他のアクションでビジー状態である場合、最大 30 分間、20 秒 / 60 秒ごとに再試行します。パックの更新またはロールバックは、同じ方法でロックされたステップを再試行します (opLock.retryWhileBusy)。クラッシュ再起動または待機中のスケジュールされた開始は、誰かがサーバーを停止、キル、または開始して以来、それらを放棄します (events.lifecycleActionSince)。クラッシュ再起動は、自動再起動が無効になっている場合やサーバーが存在しない場合にも放棄されます。スケジュールされた再起動、停止、およびコマンドは再試行されず、最後の実行がまだ待機中のスケジュールは次の実行をスキップします。 - ディスククォータ はパネルによって強制されます。Docker はバインドマウントの使用量を制限できないためです。インデクサーはディレクトリごとのサイズをキャッシュし、ディスク拡張操作はそれらにゲートされます。
- シークレット (RCON パスワード、API キー、TOTP シークレット、Discord Webhook URL) は、
$DATA_DIR/.secret-key(モード0600、自動生成) で専用のランダムキーを使用して AES-256-GCM で暗号化されて保存されます。これはSESSION_SECRETとは独立しています。SESSION_SECRETから派生したキーは、専用キーが存在する前に書き込まれた値の復号専用フォールバックとして保持され、src/services/secretsMigration.jsは起動時に 1 回それらを専用キーの下で再暗号化します。存在するが解析できない.secret-keyは、起動時の致命的なエラーです (決してサイレントに再生成されません)。ブループリントはエクスポート時にすべてのシークレットを削除します。 server.propertiesはパネル所有ですが、環境変数でシャドウされます。 itzg イメージは、各起動時に環境変数でバックアップされたすべてのプロパティを再アサートします (OVERRIDE_SERVER_PROPERTIESはデフォルトで true)。そのため、パネルが直接編集した値 (ワールドコントロールの PvP/難易度、ホワイトリストのトグル、ファイルエディタ) は、対応する環境変数が削除され、コンテナが再作成されない限り、次の起動時にサイレントに元に戻されます。すべての直接プロパティ書き込みはwriteServerProperties()(ファイル全体) またはsetServerProperty()(1 つのキー) をsrc/services/servers.jsで通過します。これはファイルをアトミックに書き直し、変更された各キーの後ろの環境変数を解除し (catalogフィールドのprop:属性経由で、イメージ自身のプロパティ定義に対してテストでチェックされます)、pending_recreateをフラグ付けします。難易度はファイルに書き込まれ、RCON にも送信されます。これは、専用サーバーが各起動時にdifficultyプロパティを再適用するためです。Minecraft 自体は、whitelist on/offの際に起動時の値から server.properties を再保存します。これにより、サーバー実行中に加えられた編集が元に戻されるため、実行中のホワイトリストトグルはファイルをスナップショットしてからwhite-listのみが変更された状態で書き戻します。環境変数は作成時に完全に構成可能であり続けます (ウィザードがそれらを描画し、それらは一度適用されます)。それらは、パネルが基になるプロパティを編集する最初の時間にのみピンを解除します。MOTD も同じ契約です。直接のmotdファイル編集はそれを解除するため、最後の書き込みが勝ちます。
データとワイヤフォーマット
Section titled “データとワイヤフォーマット”data/panel.db- SQLite データベース。毎日VACUUM INTOを使用してdata/backups/_panel/にスナップショットされます (最新 14 件を保持)。PRAGMA integrity_checkは起動時に実行されます。data/.session-secret- 自動生成された Cookie サインシークレット。最初の実行時にSESSION_SECRETが未設定の場合に作成されます。これを削除するとシークレットがローテーションされます (セッションが無効になります)。data/.secret-key- 専用の 32 バイト保存時暗号化キー (モード0600)。最初の実行時に自動作成されます。SESSION_SECRETとは独立しています。これを削除すると、保存されているすべての資格情報が復号できなくなります。そのため、バックアップと一緒に保管する必要があります。- ブループリント (
.mcserver.zip) - 設定、リソース、ピン留めされたパック参照、オーバーレイマニフェスト (ソース URL + sha256)、選択された設定ファイル、およびオプションでワールドを記述するmanifest.jsonを含む zip。インポートは、各 Mod を再ダウンロードしてハッシュ検証し、新しいポートを割り当てます。 - パネルによって作成された Docker コンテナ は、ウォッチャーがそれらを見つけられるように名前とラベルが付けられています。パネルはそれらの完全なライフサイクルを所有します。
起動シーケンス
Section titled “起動シーケンス”- 最初に
require('./instrument')(Sentry シーム)、次にrequire('./preflight')でサポートされていない Node バージョンで明確に失敗します。 - 設定をロードします。
.session-secretと.secret-keyを確認/生成します。 ensureDataRoot()-./dataレイアウトを作成し、tmp/をワイプします。- DB マイグレーションを実行し、次に
PRAGMA integrity_check(大声でログを記録し、失敗した場合はdata/backups/_panelを指します)。 - レガシー
SESSION_SECRETキーのシークレットを.secret-keyの下に再暗号化します (secretsMigration)。 - 環境から API キーを一度インポートします (
apiKeys.importFromEnvOnce())。まだピン留めされていない Modpack セレクターを持つサーバーをピン留めします (packPins.pinUnpinnedServers())。以前のプロセスによって実行中に中断されたバージョン互換性スキャンをマークします (compat.reconcileScans())。次に、スターターブループリントをシードします (保護されています)。 - HTTP + WS サーバーを起動します。公開されたバインドでは、最初の実行
/setupPIN を表示します。 - 起動後のランタイムガードをインストールします (キャッチされない障害をキャッチします。
MSM_EXIT_ON_FATAL=1は、監視対象のデプロイメントでハード終了させます)。 - バックグラウンドサービスを開始します: WS ブローカー、ストレージインデクサー、クラッシュ + インベントリウォッチャー、スケジューラー、Discord イベントブリッジ、チャットボットアウトリーチウォッチャー、および 毎日のメンテナンスタイマー (古い分析行、チャットボットトランスクリプト、イベント履歴 (365 日)、API キャッシュ行を削除し、
panel.dbをスナップショットします)。 - Docker を バックグラウンドで 初期化します。デーモンがダウンしている間も UI は完全に利用可能です。Docker 機能は、それが到達可能になると有効になります。接続後、
refreshStatuses({ boot })はキャッシュされたステータスを調整し、パネルが再起動する前にアップしていたが再起動されないサーバーに対して 1 回限りのoffline-after-restartイベントを発行し、ブートループはauto_startサーバーを起動し、アウトエージ中にクラッシュしたauto_restartサーバーを回復します (クラッシュループバックオフを尊重します)。
instrument-before-preflight の順序は意図的なトレードオフです。将来の Sentry 配線がランタイムを最初にパッチできるようにし、非常に古い Node でのメッセージのフレンドリーさがわずかに低下するコストがかかります。
ビルドパイプライン
Section titled “ビルドパイプライン”pnpm run build = build:css (Tailwind → public/css/app.css) + build:js (esbuild →
public/dist/js/、コード分割付き ESM)。postinstall は CSS のみ を実行します。public/css/app.css と public/dist/ は gitignore されたビルド成果物です。Dockerfile のビルドステージは完全な pnpm run build を実行し、public/ をランタイムイメージにコピーします。静的アセットは、フィンガープリントされたファイルには immutable/long-cache、CSS/JS には short-cache、HTML と /api には no-cache で提供されます。