トラブルシュート

1切り分けの基本フロー

「フロント表示がおかしい」と感じたら、まず次の 3 段階で切り分けます。

1. smoke.py で全サービスの応答を確認
   powershell

   python scripts\smoke.py
   python scripts\smoke.py --direct

   既定モードと --direct モードの結果を比べて、Gateway 経由のみ FAIL か、サービス本体も FAIL かを判定します。

2. status.ps1 でプロセスの生死を確認
   powershell

   pwsh scripts\status.ps1

   PID は実在するのに smoke が FAIL = ポート bind 失敗や起動途中のクラッシュ。両方 not running なら起動失敗（§2 へ）。

3. logs/<service>.err.log を読む

   FAIL になっているサービスの err.log 末尾に、ほぼ確実に原因の Python 例外 / .NET 例外 / バインドエラーが残っています。

2サービスが起動しない

2.1 ポート衝突 (address already in use)

start.ps1 出力や err.log に address already in use が出るパターン。前回の stop.ps1 が失敗してプロセスが残っているケースが大半です。

pwsh scripts\kill_by_port.ps1 -Port 8080

該当ポートを掴んでいる PID を強制終了します。Gateway (8080) / replay_parser (12345) / log_monitor (8000) / map (8001) / prepare_upload (8002) / suite_core (8003) のうち、衝突しているポートを指定してください。

2.2 ヘルスチェックでタイムアウト

• Python サービス（log_monitor / map / prepare_upload / suite_core）: logs/<svc>.err.log に ModuleNotFoundError → ../venv への pip install -r services/requirements.txt 漏れ
• .NET サービス（replay_parser）: It was not possible to find any compatible framework version → .NET 9 SDK が未インストール
• Suite Core が config 読み込みエラー: ~/.fortnite-suite/config.json が JSON として壊れている。assets/config.template.json から復元するか、空 {} にして起動

3サービスは上がっているが応答しない / 503

フロントから 503 が頻発する場合、まず Gateway の /health でどの上流が落ちているかを特定します。

curl http://localhost:8080/health

応答 JSON 内の upstreams に各サービスの reachable 状況が出ます。落ちているサービスの logs/<svc>.log を確認し、必要なら全停止 → 全起動で復旧させてください。

4OBS 連携が動かない

設定ページの「OBS 録画フォルダ」バッジが 緑（OBS WebSocket）にならない場合は、次のチェックリストを順番に確認します。

5動画トリミングが失敗する

5.1 ヘッダの ffmpeg/ffprobe バッジが赤（FAIL）

ffmpeg / ffprobe が PATH に通っていません。公式ビルドを解凍し、bin/ をシステム環境変数 PATH に追加 → 全サービス再起動。

ffmpeg -version
ffprobe -version

新しい PowerShell セッションで上記が動けば OK。動かない場合は環境変数の設定後に新しいウィンドウを開き直してください。

5.2 候補が空 / 「対応する動画がありません」

• 選択した .replay の試合時刻と、録画動画のタイムスタンプが重なっていない
• OBS の録画ファイルが選択リプレイの試合より後に作成された（よくある）
• obs_recording_dir が間違ったフォルダを指している → 設定ページで確認

5.3 トリミング実行で 500 エラー

• 出力先ディスクが容量不足
• 入力動画が破損 / 部分的に書き込み中（OBS 録画停止前のファイルを掴んでいる）
• logs/prepare_upload.err.log に ffmpeg のエラー出力が残るので、ここから判別

6リプレイ詳細が表示されない / 試合情報が空のまま

マッチ詳細で「人間プレイヤー数 / Bot 数」が空のままになる、リプレイ詳細でテキストが出ないケース。

• 初回は数秒かかるのが正常動作です。.NET の replay_parser が .replay をパースする時間です。2 回目以降は suite_core キャッシュで即時表示
• 10 秒以上待っても出ない場合は logs/replay_parser.err.log を確認。FortniteReplayReader 系の例外が出ていれば、Fortnite のバージョン更新でフォーマットが変わった可能性があります（パーサのアップデート待ち）
• 巨大リプレイ（200MB 超）/ 破損ファイルでも JSON 生成に失敗します。該当 .replay を別ツールで開けるか確認

7ログ監視がイベントを拾わない

7.1 「ログファイル(未検出)」バナーが出る

config.json の log_path が空、もしくは存在しないパスを指しています。設定ページで %LOCALAPPDATA%\FortniteGame\Saved\Logs\FortniteGame.log を入力し、保存してください。

7.2 トグル ON でも何も流れない

• Fortnite が起動していない → 正常動作（追記が無いので tail から何も出ない）
• Fortnite 起動中なのに無反応 → logs/log_monitor.err.log を確認。PermissionError ならログファイルが他プロセスにロックされている

7.3 トグル UI が ON のまま戻らない

サービス側の /api/log-monitor/status が真実、フロントのトグルはその投影です。stop.ps1 中に SSE が切断されると、稀にトグル表示だけ ON で残ります。ページをリロードするかページ移動すれば整合します。

8障害挙動の確認シナリオ

新しいマシンで運用を始める前に、わざと壊した状態で UI が落ちないかを確認しておくと安心です。

9ログの場所一覧

調査時に見るべきファイルの早見表です。<service> は gateway / replay_parser / log_monitor / map / prepare_upload / suite_core のいずれか。