Porta VM トラブルシューティングプレイブック

このページは、Porta VM 上で稼働する Porta On Prem デプロイメントの、症状ベースのトラブルシューティングプレイブックです。各セクションは一般的な症状をキーとし、考えられる原因と復旧手順を説明します。

最初に実行する上から下までのチェックについては、Porta VM Support Checklist を参照してください。
ログと構成がどこにあるかのリファレンスについては、Porta VM Diagnostics Cheatsheet を参照してください。

VM ライフサイクルの問題

The VM’s IP address is shown as 127.0.0.1

これは、VirtualBox が正しいネットワークアダプターに接続されていないか、選択したアダプターで DHCP が機能していないことを意味します。

VM が実行中の場合はシャットダウンします。
Windows ホストで PowerShell を開き、ipconfig /all を実行してすべてのアダプターとその名前を一覧表示します。実際の IPv4 リースを示すアダプターをメモします。
VirtualBox で VM の Settings → Network を開きます。次を確認します。
- 「Attached to」が Bridged Adapter に設定されている。
- 「Name」がステップ 2 のアダプター（多くの場合 d3net というラベル）と一致している。
VM を起動し、VirtualBox コンソールで portavm としてログインし、次で IP を確認します。
Terminal window
```
~/scripts/vm_info.sh
```

setup_vm.ps1 実行中の “Failed to establish SSH connection”

原因は、障害が発生したステップによります。セットアップスクリプトはエラーメッセージにステップを報告します。

Network Configuration 中 で IP が 127.0.0.1 と表示される場合は、上記の The VM’s IP address is shown as 127.0.0.1 を参照してください。
Resetting Identity 中 の場合、その IP の SSH ホストキーがキャッシュされているか、再起動中に SSH セッションが切断された可能性があります。VM が復帰したら、VirtualBox コンソールから手動で識別情報をリセットします。Manually Resetting the Identity of a Porta On Prem VM を参照してください。
Setting Static IP Address 中 の場合、VirtualBox コンソールから手動で静的 IP を設定します。Manually Setting Up a Static IP を参照してください。

ACPI シャットダウンに 3 分以上かかる

これは通常、VM の OS がスタックしているか、リソースが不足していることを意味します。

VM のターミナルウィンドウで、File → Close → Power Off Machine を選択します。
ターミナルが閉じたら、VirtualBox から VM を再度起動します。
これが再発する場合は、VM の RAM と CPU の割り当てを確認します。最小は 8 GB と 4 vCPU です。

VM のオンライン化待ちでタイムアウトする

このメッセージは、識別情報のリセットや静的 IP 設定の再起動中によく発生します。セットアップスクリプトの待機時間が、一部の VM が必要とするよりも短いためです。

VM を正常にシャットダウンします。
- VM のターミナルウィンドウで、File → Close → ACPI Shutdown を選択します。
- ACPI がハングする場合は、代わりに Power Off Machine を使用します。
PowerShell ウィンドウで Ctrl+C を押してセットアップスクリプトを停止します。
setup_vm.ps1 を再実行します。
新しい Porta VM のインポートか既存のものの使用を求められたら、2 を入力して Enter を押します。
先ほどインポートした VM を選択します。
ネットワーク構成ステップから続行します。

VM ターミナルに “rcu: detected stalls on CPUs/tasks” が表示される

このメッセージは、VM のリソースが不足していることを示します。

File → Close → ACPI Shutdown（ACPI がハングする場合は Power Off Machine）で VM を正常にシャットダウンします。
VirtualBox の Settings → System で、VM に少なくとも次があることを確認します。
- 8 GB RAM
- 4 vCPU
- AVX2 をサポートする CPU
VM を起動し、再発を監視します。

このメッセージが定期的に再発する場合、ホストマシンは Porta VM に対してプロビジョニング不足です。より多くのリソースを割り当てるか、VM をより高性能なホストに移動することを検討してください。

起動時に VM が “Begin: Loading essential drivers” で止まる

ストレージコントローラーがソリッドステートドライブのヒントを失ったか、パッケージ更新後に VirtualBox のストレージ構成がドリフトしています。

VM をシャットダウンします。
VirtualBox の Settings → Storage で、SATA 仮想ディスクをクリックします。
次の両方をチェックします。
- Solid-state Drive
- Use host I/O cache
VM を起動します。

.ova のインポート時に VirtualBox が “E_INVALIDARG 0X80070057” を表示する

VirtualBox のデフォルトマシンフォルダがあるドライブに、十分な空き容量がありません。

VirtualBox で File → Preferences → General に移動します。
「Default Machine Folder」を十分な容量のあるドライブに変更します。
VM セットアップを再度実行します。

静的 IP セットアップが失敗を報告したが SSH は実際には機能する

これは、一部の Porta VM セットアップスクリプトバージョンでの既知の偽陽性警告です。

直接確認します。

~/scripts/static_ip_info.sh

静的 IP が構成されており、その IP で VM に到達できる場合、警告は誤りでした。続行してください。
静的 IP が実際には設定されていなかった場合は、VirtualBox コンソールから ~/scripts/setup_static_ip.sh を実行します。

静的 IP ウィザードが予期しないサブネットを選択した

ウィザードは既存の DHCP 構成からサブネットを推測しますが、複雑なネットワークでは誤ることがあります。

ウィザードの手動入力オプションを使用するか、VirtualBox コンソールから Manually Setting Up a Static IP に従ってください。不明な点がある場合は、IT チームに正しいサブネットを確認してください。

VM の IP が変わり Porta が壊れた

VM の IP 変更は、Porta VM 上のライブインシデントで最も一般的な根本原因です。複数の症状がすべてこれに起因する可能性があります。

Porta がデータベースに到達できない。
Porta UI でデータベースステータスが赤と表示される。
Porta Bridge が接続できない。
エンジンクライアント（Unreal、Designer）が Porta に到達できない。

正式な復旧手順は Changing the IP of Porta On Prem にあります。以下のサマリーは、最も見落とされやすい部分を強調しています。

IP 変更後の復旧サマリー

VirtualBox コンソール（SSH ではない）から、VM の静的 IP を再構成します。

実行中の仮想マシンのネイティブ VirtualBox ターミナルウィンドウを使用して、VM にログインします。
- ユーザー名 portavm を入力して Enter を押します。
- 提供されたパスワードを入力し、再度 Enter を押してログインします。
次に実行します。
Terminal window
```
sudo ./scripts/disable_static_ip.sh
sudo reboot
```
VM が復帰したら、再度ログインして次を実行します。
Terminal window
```
sudo ./scripts/setup_static_ip.sh
```
Porta Manager → Porta Configuration Management → Machines で、各マシンの IP を新しい値に編集し、Save Changes をクリックします。
Porta Manager ダッシュボードで、Fix IP Settings をクリックして確認します。
成功メッセージを待ちます。
ブラウザで Porta を更新します。

Porta アプリケーション面

更新後にブラウザが古い Porta バージョンを表示する

ブラウザが古いバージョンをキャッシュしています。

Ctrl+Shift+R でページをハードリロードします。
それでも解決しない場合は、Porta オリジンのすべての Cookie とサイトデータをクリアしてから再読み込みします。
VM 内でバックエンドのバージョンを確認します。
Terminal window
```
porta_check_version
```
バックエンドが新しいバージョンを報告する場合、更新は成功しており、ブラウザだけが古い状態のままです。

ログインが “500 Internal Server Error” または “Could not create token: Key provided is shorter than 256 bits” で失敗する

JWT シークレットが空であるか、短すぎます。これは通常、.env の編集後や部分的なインストール後に発生します。

VM 内で、porta コンテナに対して次を実行します。

docker exec -it porta bash -c "php artisan cache:clear && php artisan jwt:secret && php artisan config:cache"

Porta オリジンのブラウザ Cookie をクリアします。
再度ログインを試みます。

ソケットサーバーが Redis に到達できない（“ECONNREFUSED 127.0.0.1:6379”）

ソケットコンテナが Redis の準備が整う前に起動したか、ソケットサーバーが開いた接続を保持している間に Redis が再起動されました。

ソケットサーバーコンテナを停止します。
Terminal window
```
docker stop porta-socket
```
Redis を再起動し、数秒待ちます。
Terminal window
```
docker restart porta-redis
```
ソケットサーバーを再度起動します。
Terminal window
```
docker start porta-socket
```

ディスクとリソース

”No space left on device”、または VM の動作が遅い

ディスク使用量を確認します。
Terminal window
```
check_diskspace
```
Docker が再利用できるものを確認します。
Terminal window
```
docker_disk_usage
```
「Images Reclaimable」が大きい場合は、未使用のイメージを削除します。ボリュームは保持されます。
Terminal window
```
docker image prune -af
```
ステップ 3 の後も / が逼迫している場合は、仮想ディスクを拡張する必要があります。これは VirtualBox 側の操作（Virtual Media Manager で .vdi をリサイズ）に 加えて、parted、pvresize、lvextend、resize2fs を使用した VM 内のリサイズチェーンが必要です。Disguise サポートにお問い合わせください。パーティションのリサイズは元に戻すのが難しく、エンジニアリングの指導のもとで行うのが最善です。

VM のメモリ使用量が高い

VirtualBox の Settings → System → Motherboard → Base Memory でホストの割り当てが少なくとも 8 GB であることを確認します。大規模なデプロイメントには 16 GB が推奨されます。
VM 内でコンテナごとのメモリを調べます。
Terminal window
```
docker stats
```
通常、porta-db が最も重いコンテナです。

Designer、Unreal、Porta Bridge の接続

これらの連携の構成値は、IP が変わるたびに変わります。次を順番に確認します。

Porta Bridge が Porta に接続できない

Windows ホストで Porta Bridge のインスタンスが 1 つだけ実行されていることを確認します。Windows システムトレイとタスクマネージャーの両方を確認します。重複を終了して Bridge を再起動します。
Bridge → Window → Porta で、次を確認します。
- Socket Server URL: http://<VM-IP>:6001。
- API URL: http://<VM-IP>:8000。
Bridge HTTP Listener IP Address が、VM の IPv4 ではなく Windows ホストの IPv4 であることを確認します。
Bridge マシンの Windows ファイアウォールで、インバウンドトラフィック用にポート 1500 が開いていることを確認します。
porta-socket.server または porta.server を使用している場合、Bridge マシンの Windows hosts ファイルがそれらを VM の現在の静的 IP にマッピングしていることを確認します。

Designer 連携が機能しない

Designer が実行されていることを確認します。
アクティブな Designer プロジェクトが、Porta が使用するよう構成されているページ、テンプレート、チャネルと一致していることを確認します。
Bridge が正常であることを確認します。Bridge がダウンしていると、Designer の連携は失敗します。

Porta Manager とインストーラーウィザード

ポート 88 で Porta Manager に到達できない

コンテナのステータスを確認します。
Terminal window
```
docker ps -a
```
porta-manager-app が終了している場合は、そのログを表示します。
Terminal window
```
docker logs porta-manager-app
```
既存のイメージから再作成して、非破壊的に復旧します。
Terminal window
```
mngr_recreate
```
それでも失敗する場合は、Disguise サポートにお問い合わせください。

Porta Manager 更新後の “MAC Invalid” または “Invalid MAC” エラー

実行中のコンテナの APP_KEY が、データが暗号化されたキーと異なっています。Manager の更新は関連する構成を自動的にバックアップするため、これはまれなはずです。

保持された env ファイルを復元します。
Terminal window
```
mngr_restore_env
```
Manager コンテナを再作成します。
Terminal window
```
mngr_recreate
```

災害復旧

完全なバックアップと復元の手順（自動バックアップの仕組み、手動バックアップの取得方法、単一ノード復旧、複数ノード復旧、Unreal Engine フェイルオーバー、VirtualBox スナップショットのロールバックを含む）については、Porta VM Disaster Backup and Restore を参照してください。