ランチャー故障排查
ランチャーで発生するエラーは大きく分けて自律初期化フェーズのエラー（環境構築の失敗）と、ランタイムフェーズのエラー（バックエンドは起動したが接続できない）の2種類に分類されます。エラー画面に表示される現在のフェーズを確認し、段階的に切り分けてください。
自律初期化フェーズ
| フェーズ | 症状 | 主な原因 | 対処方法 |
|---|---|---|---|
.venv の作成 | 停止する / 権限エラー | フォルダが書き込み禁止、パスに特殊文字 | ユーザーホーム配下のパスへ配置場所を変更 |
| Python のダウンロード | タイムアウト / ハッシュ不一致 | 接続先ミラーの応答不良 | -cn 版を使用するか、ネットワーク環境を変更 |
| リポジトリの更新 | git コマンドの失敗 | プロキシ遮断、ブランチ不一致、ディスク満杯 | deploy.yaml を確認。--skip-update での起動を試行 |
| 依存関係の同期 | uv sync の失敗 | PyPI へのアクセス不能、ロックファイルの不整合 | ミラーソースを変更。コードと uv.lock の整合性を確認 |
| バックエンドの起動 | 起動直後に即時終了 | ポート競合、Python のクラッシュ | バックエンドログおよびポートの競合を確認 |
| ウィンドウ表示 | 画面が真っ白のまま | WebView ランタイムの欠落 | WebView2 または webkit2gtk をインストール |
よく使われる復旧コマンド
bash
# リポジトリ更新をスキップして起動
./alas-launcher --skip-update
# 依存関係を強制同期
uv sync --frozen
# 環境を完全に再構築（再度ダウンロードが行われます）
rm -rf .venv.venv を削除しても設定は失われません
ユーザー設定は config/ に、ログは log/ に保存されています。ただし再構築にはインターネット接続が必要で、数分程度の時間がかかります。
ポートの競合
| 現象 | 主な原因 | 対処方法 |
|---|---|---|
| 「ポートが既に使用されています」と警告 | 別のランチャーまたはバックエンドがポート 22267 を占有中 | 残存している古いプロセスを終了 |
| バックエンドが起動しないがポートは空いている | ランチャーの指定ポートとコアの設定ポートの不一致 | deploy.yaml の WebuiPort を確認 |
| ポートを変更したが反映されない | WebView が依然として古いアドレスを参照している | ランチャー本体を再起動 |
ランチャーは起動時に当該ポートを占有している既存プロセスの検出とクリーンアップを試みます。ソースコード版（ポート 25548）と同時に実行する場合、ポートが異なるため競合しません。
ネットワークとプロキシ
| 現象 | 主な原因 | 対処方法 |
|---|---|---|
| リポジトリ更新のタイムアウト | GitHub への接続不良 | CN 版を使用、または GitProxy を設定 |
| Python のダウンロードが遅い | デフォルトの配布元への帯域制限 | ネットワークを変更、または手動でミラーを設定 |
| 依存関係インストール時に 403 エラー | 企業プロキシ等による通信ブロック | PyPI ミラーを設定するかホワイトリストに登録 |
| ブラウザでは開くがランチャー上で接続不能 | システムプロキシがローカルループバックを遮断 | ランチャーは --no-proxy-server で起動します。グローバルプロキシ設定を確認 |
macOS 特有の問題
| 現象 | 対処方法 |
|---|---|
| 「悪質なソフトウェアが含まれているため開けません」 | ターミナルで xattr -dr com.apple.quarantine /Applications/AzurPilot.app を実行 |
| アプリを起動してもウィンドウが表示されない | コンソール（Console.app）でクラッシュログを確認。CPU アーキテクチャの適合を確認 |
| トレイアイコンが表示されない | メニューバーのアイコン過多による非表示。不要なトレイアイコンを整理 |
Linux 特有の問題
| 現象 | 対処方法 |
|---|---|
libwebkit2gtk-4.1 の不足エラー | apt install libwebkit2gtk-4.1-0 等でライブラリを導入 |
GLIBC_2.xx not found | ディストリビューションが古すぎます。ソースコード実行ルートへ移行してください |
| システムトレイが表示されない | GNOME 等で AppIndicator 拡張機能を有効化 |
| サンドボックスの権限エラー | Flatpak や Snap 等でラップせず、配布バイナリをネイティブ実行 |
Windows 特有の問題
| 現象 | 対処方法 |
|---|---|
| UAC プロンプトで拒否される | 管理者権限での実行が必須です |
| SmartScreen による実行ブロック | 「詳細情報」をクリックし、「実行」を選択 |
| WebView2 の不足エラー | Evergreen ランタイムを Microsoft 公式から導入 |
セキュリティソフトによる git.exe の隔離 | .venv フォルダを除外ホワイトリストに登録 |
| パス関連のエラー | 日本語やスペースを含まない英数字のみのパスへ移動 |
プロセスの残存
| 現象 | 主な原因 | 対処方法 |
|---|---|---|
アプリ終了後も python.exe が残る | プロセス回収処理の異常終了 | ランチャーログのプロセススキャンを確認。PC を再起動 |
| エミュレーターが一緒に道連れ終了される | Windows Job Object の継承 | バックエンドとランチャーが breakaway に対応しているか確認 |
| 起動時にバックエンドが2重起動する | 単一インスタンス制御の失敗 | 関連プロセスをタスクマネージャーから全終了して再起動 |
仕様の詳細はバックエンドプロセスのライフサイクルを参照してください。
ログの場所
text
log/<日付>_launcher.txtここには自律初期化フェーズで実行された各コマンド、終了コード、処理時間が記録されます。原因究明時は末尾100行を抜粋して Issue に添付してください。
ロールバック手順
- 直前の正常なバージョンの圧縮アーカイブをダウンロードします。
- 実行ファイルのみを上書き配置します（
.venv、config/はそのまま保持）。 - 新バージョンで
.venvの内部構造が改変されていた場合は、.venvを削除して再構築させてください。
コアプログラムのコードのロールバックはランチャーとは独立して実行します：
bash
git log --oneline -5
git checkout <コミットハッシュ>
uv sync --frozen