トラブルシューティング

1. 接続・プロトコル関連

クライアントが「サーバーのバージョンが一致しません」等でキックされる

原因: Bedrock Edition のプロトコルバージョンが一致していません。Komugi が使用している gophertunnel ライブラリは厳密なプロトコル整合性を持つため、ライブラリの対応版と異なるバージョンのクライアントはログイン時に切断されます。
対処法:
1. Komugi 起動時のログを確認します: リレー待受中: ... (protocol 712 / v1.21.20)
2. 最新の Bedrock バージョンに追従する場合、リポジトリで以下を実行して再ビルドしてください:
  ターミナルウィンドウ
```
go get -u github.com/sandertv/gophertunnel@latest
go mod tidy
./build.sh
```

接続がタイムアウトする / 応答がない

原因 1: ファイアウォール: UDP ポート（既定: 19132）が開放されているか確認してください。Bedrock Edition は UDP プロトコルを使用します（TCP ではありません）。
原因 2: PROXY Protocol の不整合:
- ENABLE_PROXY_PROTOCOL=true にしている場合、転送先のバックエンドサーバー（Geyser や HAProxy）側でも PROXY protocol v2 の受付が有効化されていないと、パケットヘッダーの解釈エラーで接続が切断されます。
- バックエンドが非対応の場合は、.env で ENABLE_PROXY_PROTOCOL=false に設定してください。

「TARGET と RELAY が同一アドレス・ポートです」という警告が出る

原因: RELAY_HOST / RELAY_PORT と TARGET_HOST / TARGET_PORT が完全に同じ宛先を指しています。
対処法: 自身へパケットを転送する無限中継ループを防ぐため、TARGET_HOST には本番のバックエンドサーバー（または別ポート）を指定してください。

2. 認証・ログイン関連

初回認証が完了しない / 毎回コード入力を求められる

原因: Xbox Live トークンを保存するディレクトリに書き込み権限がない可能性があります。
対処法:
- .env の PROFILES_DIR（既定: ./profiles）が書き込み可能な権限になっているか確認してください。
- 認証が完了すると、./profiles/<XUID>.json にトークンが保存されます。

3. ログ・データベース関連

SQLite ログやデータベースで「database is locked」エラーが発生する

原因: 複数のプロセスが同時に同一の DB ファイルを通常モードで開こうとしているか、NFS などのネットワークドライブ上で SQLite を運用している場合に発生します。
対処法:
- Komugi は内部で WAL モード（Write-Ahead Logging）を有効化し、高速な単一ライター・複数リーダーを実現しています。
- DB ファイル (komugi.db, komugi-logs.db) はローカルの高速ストレージ (SSD) 上に配置してください。
- komugi logs コマンドは常に安全な Read-Only モードで DB を開くため、リレー起動中も安全に実行できます。

4. プロセスの耐障害性

Komugi は単一のパケット異常やセッション内エラーでサーバープロセス全体が落ちないよう、多重のフェイルセーフ設計が施されています:

異常事象	Komugi の動作
未知のパケット ID	破棄せず raw パケットのまま透過転送（クライアント側で正しく解釈可能）
破損パケット (デコード失敗)	該当パケットのみ破棄してログに記録、セッションと通信は継続
配下サーバーの再起動	切断通知をブロックし、自動復帰リトライを実行
ハンドラ内の例外 (Panic)	各セッションの goroutine 内で `recover` され、ログ出力後にセッションのみ切断（プロセス全体は停止しない）