minecraft-server-admin

Minecraft サーバー管理スキル

範囲とルーティング境界

ルーティング境界

• 使用する場合: タスクが Minecraft サーバーのインフラストラクチャまたは稼働中の運用（デプロイ方法の選択、チューニング、バックアップ、プロキシ設定、セキュリティ、インシデント対応）に関する場合。
• 使用しない場合: プラグインコードの作成（minecraft-plugin-dev）や、MOD／ローダーの作成（minecraft-modding、minecraft-multiloader）に関するタスク。
• 使用しない場合: WorldEdit コマンドのワークフロー（minecraft-worldedit-ops）や EssentialsX のワークフロー／ポリシー設計（minecraft-essentials-ops）に関するタスク。
• 使用しない場合: データパック／リソースパックの作成（minecraft-datapack、minecraft-resource-pack）に関するタスク。

参考資料

• タスクがインシデント、ロールアウト期間、プロキシの変更、または復旧訓練に関するもので、作業前に簡潔なチェックリストが必要な場合は、references/deployment-checklists.md を参照してください。

---

デプロイの判断マトリックス

デプロイ方法を選択する際は、この表を使用してください。既存のサーバーの場合は、 まずスタックとバージョンを確認し、移行を依頼されていない限り、現状を維持してください。

デプロイプロファイル	推奨スタック	選択する状況	注意点
Paper の小規模 SMP	Paper のみ	同時接続プレイヤー数が約30人までで、幅広いプラグインとの互換性が必要であり、運用負荷を抑えたい場合	早い段階で過剰にチューニングしないでください。多くのデフォルト設定を変更する前にプロファイリングしてください
大規模な公開 Paper サーバー	Paper + Spark + より厳格なプラグイン／変更管理	参加者の入れ替わりが頻繁な公開サーバーで、プラグインが適度に導入され、稼働時間が重要な場合	プラグインの増えすぎが TPS にとって最大のリスクです
Velocity バックエンドのネットワーク	Velocity + 複数の Paper バックエンド	ハブ／ミニゲーム／派閥をサーバー間で分割し、共通の接続口が必要な場合	転送設定／認証設定の不一致により、接続できなくなることがあります
ゲームプレイ重視の Purpur サーバー	Purpur（必要に応じて Velocity の背後に配置）	カスタムプラグインコードを使わず、設定からゲームプレイ関連の調整項目を利用したい場合	切り替え項目が増えると、設定ミスのリスクも高まります
高同時接続数の Folia サーバー	Folia + Folia 対応プラグインのみ	リージョンスレッド化を目指し、非常に多くのプレイヤーが同時接続する場合	Folia で安全に動作するプラグインは限られています
Fabric／NeoForge MOD サーバー	Fabric または NeoForge サーバービルド	ローダー MOD、カスタムコンテンツ、MOD パックの動作が必要な場合	Bukkit／Paper プラグインは適用されません

デプロイタイプのルーティング

• 小規模 SMP とほとんどの公開プラグインサーバーでは、まず Paper を基本構成として使用してください。
• Purpur のゲームプレイ設定が明確に必要な場合に限り、Purpur を使用してください。
• リージョンスレッド化に対するプラグインの互換性を検証した場合に限り、Folia を使用してください。
• 1つのプロセスでは不十分な場合や、バックエンドの役割を分離する必要がある場合は、Velocity を使用してください。
• 要件がプラグインではなく MOD によるものの場合は、Fabric／NeoForge を使用してください。

Java のバージョン

• Paper と Purpur：Minecraft 26.1 以降では Java 25 が必要です。Minecraft 1.21.x では Java 21 を使用します。バージョンを変更する前に、正確な Paper／Purpur ビルドとインストール済みプラグインを確認してください。
• 現行の Velocity 4.x には Java 25 が必要です。旧バージョンのプロキシでは、 現行バージョンをデフォルトで適用するのではなく、そのプロキシの正確なリリースが必要とする Java バージョンを維持してください。

---

プレイブック：パフォーマンスのチューニング

ステップ 1：ベースラインの確立

編集する前にベースラインを収集してください。Linux ホストの例：

free -h
top -b -n 1 | head -n 25

Windows PowerShell ホストの例：

Get-CimInstance Win32_OperatingSystem | Select-Object FreePhysicalMemory,TotalVisibleMemorySize
Get-Process java | Sort-Object CPU -Descending | Select-Object -First 5 Id,CPU,WorkingSet,Path

サーバーコンソールで実行：

tps
mspt
spark healthreport

次の項目を記録してください：

• ピーク時のプレイヤー数
• アイドル時およびピーク稼働時の MSPT
• Spark レポートで CPU 使用率が高いプラグイン

ステップ 2：実際のボトルネックをプロファイリングする

推測ではなく、Spark を使用してください：

spark profiler --timeout 180
spark tps
spark tickmonitor --threshold-tick 50

50 ms のしきい値は、通常の 20 TPS の1ティックを超過したティックを報告します。インシデントのしきい値が意図的に異なる場合に限り、調整してください。

次に、問題が以下のどれに該当するかを特定してください：

• プラグインのタスク負荷
• エンティティ数／モブファームによる負荷
• チャンク生成／ディスク I/O
• ガベージコレクションの一時停止

ステップ 3：対象を絞って調整する

一度にすべてを調整しないでください。グループごとに一つずつ適用します。

1. チャンクとシミュレーションの負荷：

• まず view-distance と simulation-distance を下げます
• サバイバル重視のマップでは、ワールドを事前生成します

1. エンティティの負荷：

• Paper のワールド設定で、デスポーン範囲とモブのスポーン動作を調整します
• 必要に応じて、問題のあるエンティティに上限を設けます

1. プラグインの負荷：

• Spark のトレースから、特に負荷の高いプラグインを無効化するか、置き換えます
• プラグインの設定で可能な場合は、非同期タスクの頻度を下げます

ステップ 4：安定した起動フラグを使用する

現在の Paper／Purpur で Java 25 を使用する場合は、まずシンプルで測定済みの基準値から始めます。

java -Xms4G -Xmx4G -jar server.jar --nogui

ヒープを増やすのは、プロファイリングとプレイヤーの負荷から必要性が確認された場合に限ります。ガベージコレクターのフラグを追加するのは、使用する JDK と Paper のバージョンで検証してからにしてください。

ステップ 5：改善を確認する

変更セットを適用するたびに、次を実行します。

spark tps
spark healthreport

代表的な負荷のもとで MSPT／ティックの安定性が改善した場合に限り、その変更を維持します。

---

プレイブック：プラグイン運用

安全なプラグイン変更ワークフロー

1. プラグインの一覧を作成します：

• プラグイン名とバージョン
• 必須の依存関係
• 最低サーバーバージョン

1. 更新をステージングします：

• まずステージング環境でプラグインを更新します
• スモークテストを実行します：ログイン、テレポート、経済機能、権限、保存

1. 本番環境への展開期間：

• メンテナンス期間を告知します
• サーバーを正常に停止します
• プラグインの JAR ファイルと設定のスナップショットを作成します
• 更新分をまとめて展開します

1. 展開後の確認：

• 起動ログを監視し、API の警告を確認します
• コマンドと権限の健全性を確認します
• TPS／MSPT を 15～30 分間追跡します

ロールバックのチェックリスト

• 以前のプラグインディレクトリのスナップショットを保持します。
• 重大なリグレッションが発生した場合：
  • サーバーを停止します
  • 以前のプラグイン JAR ファイルと設定を復元します
  • 起動し、ログインとワールドの整合性を確認します
• 今後の更新を防げるよう、問題を起こしたプラグインとバージョンの組み合わせを記録します。

---

プレイブック：プロキシと転送（Velocity）

Velocity の基本設定

velocity.toml の要点：

bind = "0.0.0.0:25565"
online-mode = true
player-info-forwarding-mode = "modern"
forwarding-secret-file = "forwarding.secret"

バックエンドサーバーの要件

バックエンドの server.properties：

online-mode=false

Paper バックエンドの転送設定（config/paper-global.yml）：

proxies:
  velocity:
    enabled: true
    online-mode: true
    secret: "paste-the-shared-forwarding-secret-here"

Velocity の forwarding.secret ファイルに保存されているものと同じシークレット値を使用します。バックエンドの設定にはファイルパスではなく、シークレット文字列そのものを指定します。

特定のレガシークライアントへの対応やインシデント時の回避策が必要な場合を除き、enforce-secure-profile はサーバーのデフォルトのままにしてください。これは Velocity の基本設定には含まれません。また、spigot.yml で settings.bungeecord: false になっていることも確認してください。BungeeCord 転送と Velocity のモダン転送を同時に有効にしないでください。

検証手順

1. クライアントからプロキシのポートに接続できることを確認します。
2. バックエンドがインターネットから直接アクセスできないよう、ファイアウォールで保護されていることを確認します。
3. プロキシ経由でログインし、次を確認します：

• UUID の一貫性
• スキン／プロフィールの転送
• プラグインの権限動作

よくあるプロキシのインシデント

• 「Invalid player info forwarding」：
  • Velocity とバックエンドの間で、転送モードまたは共有シークレットが一致していません。
• 認証／セッションの失敗がランダムに発生する：
  • online-mode の想定が混在しているか、バックエンドが直接公開されています。

---

プレイブック：バックアップと復旧

バックアップポリシーのテンプレート

資産	頻度	保持期間	備考
設定済みのすべてのワールドフォルダー	1 時間ごとの増分バックアップ＋毎日のフルバックアップ	7 日分、4 週分	カスタムワールドと外部に保存されたワールドを含めます
plugins/、config/、およびサーバールートの状態	毎日	14 日分	運用環境の復元に必要です
プロキシの設定／シークレット	毎日	30 日分	ホスト外に暗号化して保存します
コンテナー／オーケストレーションのファイル	変更時＋毎週	8 週間	可能な場合は Git で追跡します

バックアップスクリプトの例（Paper/Purpur）

本番サーバーでは、稼働中のワールドフォルダーをコピーする前に、ワールドへの書き込みを停止してください。 以下の例は、メンテナンス時間を確保し、サーバーを正常に停止した状態を前提としています。 RCON を使った稼働中のバックアップを利用する場合は、コマンド引数にパスワードが露出しないクライアント／シークレット管理方式を選んでください。 安全な実装では、save-off、続いて save-all を実行してからデータをコピーし、コピーに失敗した場合も必ず save-on による後処理を行う必要があります。 フラッシュや save-all だけを、稼働中のバックアップ手順として扱わないでください。 Folia では save-all が無効になっています。その場合は、サーバーを正常に停止するか、検証済みのプラットフォームスナップショットを使用してください。 バックアップを信頼する前に、復元手順をテストしてください。

Fabric または NeoForge の復旧では、さらに mods/ の内容を把握し、その環境で使用している正確なローダーの起動状態を記録してください。Minecraft とローダーのバージョン、Java のバージョン、起動コマンドと引数、ランチャーまたはインストーラーの成果物、デプロイ時に使用したバージョンまたはライブラリのマニフェストが対象です。 設定済みのワールドフォルダーとともに、それらの一致するコンポーネントを復元してください。この Paper/Purpur の例では、これらはバックアップされません。

SERVER_ROOT からの相対パスで、ワールドフォルダーの完全な一覧を引数として指定してください。その前に level-name と複数ワールド対応プラグインの設定を確認してください。 ルートの外部に保存されているワールドは別途バックアップしてください。world* からバックアップ対象を推測しないでください。

#!/usr/bin/env bash
set -euo pipefail

if [[ "${SERVER_STOPPED_CONFIRMED:-}" != "1" ]]; then
  echo "Set SERVER_STOPPED_CONFIRMED=1 only after stopping the server cleanly." >&2
  exit 1
fi

DATE="$(date +%Y-%m-%d_%H-%M-%S)"
BACKUP_ROOT="/backups/minecraft"
SERVER_ROOT="/srv/minecraft"
DEST="${BACKUP_ROOT}/${DATE}"

if [[ "$#" -eq 0 ]]; then
  echo "Usage: backup.sh <world-folder> [additional-world-folders...]" >&2
  exit 1
fi
for world_dir in "$@"; do
  if [[ ! -d "$SERVER_ROOT/$world_dir" ]]; then
    echo "Missing configured world folder: $world_dir" >&2
    exit 1
  fi
done

mkdir -p "$DEST"

tar -czf "${DEST}/worlds.tar.gz" -C "$SERVER_ROOT" -- "$@"

state_items=()
for item in \
  plugins config server.properties bukkit.yml spigot.yml paper-global.yml \
  paper-world-defaults.yml permissions.yml ops.json whitelist.json \
  banned-players.json banned-ips.json; do
  [[ -e "$SERVER_ROOT/$item" ]] && state_items+=("$item")
done

if [[ "${#state_items[@]}" -gt 0 ]]; then
  tar -czf "${DEST}/server-state.tar.gz" -C "$SERVER_ROOT" "${state_items[@]}"
fi

復旧訓練（テスト必須）

1. サーバーを停止します。
2. 選択したバックアップをステージングディレクトリに復元します。
3. 所有権／アクセス許可を確認します。
4. メンテナンスモードでサーバーを起動します。
5. 次の項目を確認します：

• ワールドのスポーン地点が読み込まれる
• プレイヤーデータを読み取れる
• 主要なプラグインが初期化される

1. プレイヤーに再公開します。

目標を定義します：

• RPO（許容できるデータ損失の時間幅）
• RTO（許容できる復元所要時間）

---

運用手順書：稼働中のトラブルシューティング

インシデントのトリアージフロー

1. インシデントを分類します：

• 起動時のクラッシュ
• 深刻なラグ／TPS の急落
• ログイン／認証の失敗
• メモリ／ディスクの圧迫

1. まず証拠を収集します。Linux ホストの例：

df -h
free -h

Windows PowerShell ホストの例：

Get-PSDrive -PSProvider FileSystem
Get-CimInstance Win32_OperatingSystem | Select-Object FreePhysicalMemory,TotalVisibleMemorySize

サーバー／プロキシのコンソールから：

spark tps
spark healthreport

1. 安定化させます：

• リスクのある変更のロールアウトを停止する
• 最も新しく、原因の疑いがあるプラグインを最初に無効化する
• プレイヤーへの影響を軽減する（メンテナンスモード、一時キュー、ワールドの制限）

1. 復旧して記録します：

• ロールバックまたはホットフィックスを適用する
• 根本原因と恒久的な予防策を記録する

症状別の早見表

症状	最初に確認する項目	典型的な根本原因
プラグイン更新後に起動時クラッシュが発生する	最新のログ、プラグインの依存関係	プラグイン／API の非互換性
ピーク時間帯だけ MSPT が高い	Spark プロファイラー、エンティティ／チャンクの統計	モブトラップ、負荷の高い定期タスク、チャンク I/O
プロキシ経由でプレイヤーが参加できない	転送モード＋シークレット＋バックエンドの公開状態	Velocity／バックエンドの設定不一致
周期的に大きなラグのスパイクが発生する	GC の一時停止＋自動保存＋バックアップの重複	メモリの圧迫、バックアップ I/O の競合

---

運用設定リファレンス

server.properties の影響が大きいキー

max-players=100
view-distance=10
simulation-distance=8
sync-chunk-writes=true
max-tick-time=60000
enable-rcon=false

bukkit.yml と spigot.yml

バージョン固有のデフォルト値と副作用については、Spigot/Bukkit のドキュメントを正としてください。 慎重に調整し、変更セットごとに再測定してください。

Paper の設定ファイル

• config/paper-global.yml
• config/paper-world-defaults.yml

プロファイリングによって対応可能なボトルネックが特定された後にのみ、これらを調整してください。

---

デプロイパターン

Docker Compose（Paper）

services:
  paper:
    image: itzg/minecraft-server:java25
    container_name: mc-paper
    environment:
      EULA: "TRUE"
      TYPE: "PAPER"
      VERSION: "26.3"
      MEMORY: "10G"
    ports:
      - "25565:25565"
    volumes:
      - ./data:/data
    restart: unless-stopped

この Docker の例は、現在の Paper 26.3 と Java 25 を対象としています。 既存サーバーの Minecraft または Java の系統を変更する前に、プラグインの互換性を再確認し、復元可能なバックアップを作成してください。

Pterodactyl/Wings に関する注意事項

• 起動コマンドとメモリ割り当てを、テスト済みの JVM フラグに合わせてください。
• パネルと Wings のバージョンを、サポートされている組み合わせに固定してください。
• 本番環境で使用する前に、バックアップのマウントと復元のワークフローを検証してください。

---

セキュリティ強化チェックリスト

• プロキシ転送でバックエンドのonline-mode=falseが必要な場合を除き、online-mode=trueを維持してください。
• Velocityを使用する場合は、バックエンドのPaperポートを直接公開しないでください。
• RCONおよびパネル／管理用のインターフェースは、ファイアウォールやIP許可リストで制限してください。
• シークレット（forwarding.secret、パネルの認証情報、バックアップの認証情報）をローテーションしてください。
• 信頼できるプラグインソースを使用し、インストール前にチェックサムとリリース元を確認してください。
• ホスト外に暗号化バックアップを保管してください。
• JavaランタイムとホストOSにパッチを適用してください。

---

参考資料

Paper（主要資料）

• https://docs.papermc.io/paper/
• https://docs.papermc.io/paper/getting-started/
• https://docs.papermc.io/paper/admin
• https://docs.papermc.io/paper/profiling/

Spigot/Bukkit（主要な設定リファレンス）

• https://www.spigotmc.org/wiki/spigot-configuration/
• https://www.spigotmc.org/wiki/bukkit-configuration/
• https://www.spigotmc.org/wiki/start-up-parameters/

プロキシおよびエコシステムのドキュメント

• https://docs.papermc.io/velocity/
• https://docs.papermc.io/velocity/getting-started/
• https://docs.papermc.io/folia/faq/
• https://spark.lucko.me/docs
• https://spark.lucko.me/docs/Command-Usage
• https://github.com/itzg/docker-mc-backup
• https://geysermc.org/wiki/geyser/
• https://pterodactyl.io/project/introduction.html