コンテンツにスキップ

アーキテクチャ

← ドキュメントインデックスに戻る

Minecraft Server Manager は、単一プロセスでサーバーレンダリングされる Node.js アプリケーションです。 itzg/docker-minecraft-server イメージとして実行される Minecraft サーバーを Docker コンテナで管理します。Docker デーモンとは、docker CLI をシェルアウトするのではなく、API 経由で通信します。

  • 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) の下に保存されます。そのディレクトリをコピーすると、パネル全体が移行されます。

依存関係は一方向に流れます。

┌─────────────────────────────┐
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 / requireWrite in src/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 はライブ ルーター スタックをウォークし、サーバー スコープの書き込みルート、マウント、またはページにゲートがない場合に失敗します。
  • 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、古いペアと新しいペアの両方、他のすべてのピックで尊重されます) ポートロックの下。再構築を待機している他の設定がある場合、拒否されます (409 PENDING_CHANGES)。そのため、コンテナは既に実行されていたもののみを再構築し、新しいポートで実行されます。実行中のサーバーは、リクエストが restart: true を指定した場合にのみ変更されます (それ以外の場合は 409 NEEDS_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 ファイル編集はそれを解除するため、最後の書き込みが勝ちます。
  • 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 コンテナ は、ウォッチャーがそれらを見つけられるように名前とラベルが付けられています。パネルはそれらの完全なライフサイクルを所有します。
  1. 最初に require('./instrument') (Sentry シーム)、次に require('./preflight') でサポートされていない Node バージョンで明確に失敗します。
  2. 設定をロードします。.session-secret と .secret-key を確認/生成します。
  3. ensureDataRoot() - ./data レイアウトを作成し、tmp/ をワイプします。
  4. DB マイグレーションを実行し、次に PRAGMA integrity_check (大声でログを記録し、失敗した場合は data/backups/_panel を指します)。
  5. レガシー SESSION_SECRET キーのシークレットを .secret-key の下に再暗号化します (secretsMigration)。
  6. 環境から API キーを一度インポートします (apiKeys.importFromEnvOnce())。まだピン留めされていない Modpack セレクターを持つサーバーをピン留めします (packPins.pinUnpinnedServers())。以前のプロセスによって実行中に中断されたバージョン互換性スキャンをマークします (compat.reconcileScans())。次に、スターターブループリントをシードします (保護されています)。
  7. HTTP + WS サーバーを起動します。公開されたバインドでは、最初の実行 /setup PIN を表示します。
  8. 起動後のランタイムガードをインストールします (キャッチされない障害をキャッチします。MSM_EXIT_ON_FATAL=1 は、監視対象のデプロイメントでハード終了させます)。
  9. バックグラウンドサービスを開始します: WS ブローカー、ストレージインデクサー、クラッシュ + インベントリウォッチャー、スケジューラー、Discord イベントブリッジ、チャットボットアウトリーチウォッチャー、および 毎日のメンテナンスタイマー (古い分析行、チャットボットトランスクリプト、イベント履歴 (365 日)、API キャッシュ行を削除し、panel.db をスナップショットします)。
  10. Docker を バックグラウンドで 初期化します。デーモンがダウンしている間も UI は完全に利用可能です。Docker 機能は、それが到達可能になると有効になります。接続後、refreshStatuses({ boot }) はキャッシュされたステータスを調整し、パネルが再起動する前にアップしていたが再起動されないサーバーに対して 1 回限りの offline-after-restart イベントを発行し、ブートループは auto_start サーバーを起動し、アウトエージ中にクラッシュした auto_restart サーバーを回復します (クラッシュループバックオフを尊重します)。

instrument-before-preflight の順序は意図的なトレードオフです。将来の Sentry 配線がランタイムを最初にパッチできるようにし、非常に古い Node でのメッセージのフレンドリーさがわずかに低下するコストがかかります。

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 で提供されます。