環境変数リファレンス

komugi は起動時に実行ディレクトリの .env ファイルを自動的に読み込みます。未設定の項目には既定値 (デフォルト) が適用されます。

転送先 (必須)

環境変数名	既定値	説明
`TARGET_HOST`	`play.example.com`	バックエンドとなるオンラインサーバー
`TARGET_PORT`	`19132`	—

待受設定

環境変数名	既定値	説明
`RELAY_HOST`	`0.0.0.0`	—
`RELAY_PORT`	`19132`	—

認証

環境変数名	既定値	説明
`PROFILES_DIR`	`./profiles`	上流 XBL セッションのキャッシュ先。リレープロセスが書込可能な安全な場所に置く

サーバー一覧表示

環境変数名	既定値	説明
`MOTD_TITLE`	`Komugi Relay`	—
`MOTD_SUBTITLE`	`Bedrock Relay Server`	—

動作

環境変数名	既定値	説明
`MAX_PLAYERS`	`10`	—
`LOG_PACKETS`	`false`	true で全中継パケットをログ出力 (DB 肥大の原因になるため通常は false 推奨。デコード失敗などの失敗パケットはライブラリ側で破棄+ログされる)
`LOG_PACKETS`	`false のときに中身を記録するパケット名 (カンマ区切り)。`	—
`LOG_PACKET_ALLOWLIST`	`command_request,command_output,transfer,disconnect,change_dimension,start_game,play_status,toast_request,award_achievement,text`	未設定なら接続・移動・切断の核心 + 低頻度の実績系だけ (command_request, command_output, transfer, disconnect, change_dimension, start_game, play_status, toast_request, award_achievement)。空文字で完全無効化。例: 既定セットにチャットを足す場合 (指定時は上書きなので既定分も列挙する)
`LOG_PACKET_ALLOWLIST`	`(空 / 未設定)`	—
`LOG_OUTPUT`	`stdout`	ログの出力先: stdout (標準出力) \| file (ファイル書き込み) \| sqlite (SQLite DB 保存) \| none (出力なし)
`LOG_OUTPUT`	`file のときの出力先ファイル (日ごとに LOG_FILE-YYYY-MM-DD.log へ自動ローテート)`	—
`LOG_FILE`	`./komugi.log`	—
`LOG_OUTPUT`	`sqlite のときの出力先 SQLite DB ファイル`	—
`LOG_DB_PATH`	`./komugi-logs.db`	—
`FORCE_SINGLE`	`false`	未知のパケットは型なしのまま転送され、不正なパケットは破棄される (いずれもログに残る)。 TS 版の OMIT_PARSE_ERRORS / IGNORE_CHECKSUM_ERRORS に相当する動作が標準のため、設定項目は廃止 true で同時接続を 1 クライアントに制限

ユーザー情報 (SQLite)

環境変数名	既定値	説明
`DB_PATH`	`./komugi.db`	プレイヤーごとの最終接続サーバー等を保存する DB のパス
`DEFAULT_SERVER`	`lobby`	接続時に割り当てる既定の配下サーバー名
`LIMBO_HOST`	`(空 / 未設定)`	Limbo (待機用サーバー) のアドレス。空文字の場合は無効
`LIMBO_PORT`	`19132`	—

バックエンド監視・再接続

環境変数名	既定値	説明
`BACKEND_POLL_INTERVAL`	`5000`	バックエンド稼働確認のポーリング間隔 (ms)
`BACKEND_DOWN_THRESHOLD`	`3`	バックエンド停止判定に必要な連続失敗回数
`BACKEND_PING_TIMEOUT`	`1000`	個々の ping のタイムアウト (ms)
`RECONNECT_INTERVAL`	`10000`	バックエンド再接続のリトライ間隔 (ms)
`RECONNECT_ATTEMPTS`	`10`	バックエンド再接続の最大リトライ回数
`SERVER_CLOSED_MESSAGE`	`Server Closed`	サーバー終了時にクライアントへ送るメッセージ

リソースパック中継

環境変数名	既定値	説明
`RESOURCE_PACK_CACHE`	`./packs-cache`	上流から取得したリソースパックのキャッシュ先 (gophertunnel の DirResourcePackCache 形式: <uuid>_<version>.mcpack)。起動時に読み込んでリスナーへ登録し、上流接続ごとに更新する。登録したパックは次回ログインからクライアントへ提示される。
`TEXTURE_PACKS_REQUIRED`	`true`	クライアント接続時にリソースパックのダウンロード・適用を必須にするか (既定: true)。 Geyser 拡張パック (GeyserIntegratedPack) 等を確実に反映させるには true を推奨。 false の場合はクライアント側でダウンロードや適用がスキップされる可能性があります。

PROXY Protocol (IP Forwarding)

環境変数名	既定値	説明
`ENABLE_PROXY_PROTOCOL`	`false`	上流接続時に HAProxy PROXY protocol v2 ヘッダーを送信し、クライアントの実 IP アドレスを伝達する (Geyser の bedrock.enable-proxy-protocol などの対応サーバー向け)。転送先サーバーが対応していない状態で true にすると接続できなくなるため、必ず相手側の設定と合わせて使用する

ステータス IPC (UNIX ドメインソケット)

環境変数名	既定値	説明
`STATUS_SOCKET_PATH`	`/tmp/komugi.sock`	komugi status コマンドで接続中プレイヤーや統計情報を取得するためのソケットパス。空文字を指定した場合はソケットを作成せず、IPC 機能を無効化する

設定例 (.env)

# 必須項目: 転送先 Bedrock サーバーのアドレス
TARGET_HOST=mc.example.com
TARGET_PORT=19132

# リレー待受設定
RELAY_HOST=0.0.0.0
RELAY_PORT=19132

# サーバー名表示
MOTD_TITLE=Komugi Relay
MOTD_SUBTITLE=Bedrock Relay Server

# ログ出力先 (stdout | file | sqlite | none)
LOG_OUTPUT=stdout
LOG_FILE=./komugi.log
LOG_DB_PATH=./komugi-logs.db

# ユーザー情報 DB
DB_PATH=./komugi.db
DEFAULT_SERVER=lobby

# バックエンド監視・Limbo 待機
LIMBO_PORT=19132
BACKEND_POLL_INTERVAL=5000
BACKEND_DOWN_THRESHOLD=3