メインコンテンツまでスキップ

トラブルシューティング

症状別の原因と対処をまとめました。ほとんどの問題は以下の3つのコマンドで原因が絞り込めます。

cd /opt/kopens/plantpulse-studio-docker

bash bin/status.sh                  # ① 컨테이너 상태 + 헬스 + 세션 수
curl -s localhost:5170/health       # ② 서버가 살아 있는가
docker logs --tail 100 pp-studio-server   # ③ 무엇이 잘못됐는가

ログの見方​

対象コマンド
Studio サーバ（最重要）docker logs -f --tail 200 pp-studio-server
Web（nginx）docker logs --tail 100 pp-studio-web
データベース（バンドルモード）docker logs --tail 100 pp-studio-postgres
ビルダーサイドカーdocker logs --tail 100 pp-studio-agent-server
スクリプトで追跡bash bin/logs.sh （デフォルトサーバ）· bash bin/logs.sh studio-web
自動バックアップtail -50 dist/backup.log
アプリセッションコンテナdocker ps --filter label=plantpulse-studio=1 で名前確認後 docker logs <name>
時間帯で絞り込む
docker logs --since 30m pp-studio-server
docker logs --since "2026-07-28T09:00:00" pp-studio-server
ログにキーは残りません

API キー・トークンはログに記録されません（監査ログにも値の代わりにフィンガープリントのみ）。ログをサポートチームに 送信する場合は、サイト名・設備名といった現場情報の確認だけで構いません。

症状 → 原因の素早い照合​

症状よくある原因確認対処
Web 画面が開きませんスタックがダウンしているか80ポートが占有されているbash bin/status.sh
docker logs pp-studio-web		bash bin/start.sh · 80ポートを使用している他のサービスをクリーンアップ
画面は表示されるがログイン失敗ブートストラップアカウントが未設定、またはプラットフォームに到達不可grep STUDIO_LOCAL_USERS .env
curl -s localhost:5170/health		.env でアカウントを指定後 bash bin/restart.sh
ログインが急に遮断される（しばらく後に再試行）ログインレートリミット（IP あたり 10 回/分）docker logs --tail 50 pp-studio-server1分待ってから再試行
ヘルスが継続して DOWN、ログに DB 認証エラー既存データがあるのに PG_PASSWORD を変更したdocker logs pp-studio-postgres
docker logs pp-studio-server		元のパスワードに戻すか、PostgreSQL 内でアカウントパスワードを先に変更
プロジェクト オープンが失敗（500）セッションランタイムイメージがないdocker image inspect plantpulse-studio-runtime:latestbash bin/start.sh を再実行（エアギャップは bin/load.sh で持ち込み）
プレビュー・デプロイアプリが空白画面（IP アクセス）ファイアウォールで 5171 がブロックされているcurl -I http://<server-ip>:5171/ファイアウォールで 5171 を開く
プレビューが空白画面 + コンソール Mixed ContentStudio は HTTPS だがアプリアセットが HTTP で要求されているブラウザ開発者ツール コンソールプロキシに X-Forwarded-Proto $scheme を追加 → ドメイン
コードを修正しても プレビューが変わらないプロキシが HMR WebSocket をアップグレードしていない開発者ツール → ネットワーク → WS リクエストが 101 か確認両 vhost に Upgrade/Connection ヘッダを追加
ビルドチャットが長時間かかり「接続エラー: ネットワークエラー」プロキシ無転送タイムアウト（デフォルト 60 秒）プロキシ vhost 設定を確認両 vhost に proxy_read_timeout 3600s を追加
回答がリアルタイムではなく塊で表示されるproxy_buffering が有効（デフォルト）〃proxy_buffering off を設定
どのドメインでアクセスしても別の場所へ飛ぶWeb nginx 設定ロード順序（最初の server がデフォルトサーバ）docker exec pp-studio-web ls /etc/nginx/conf.dvhost ファイル名を zz- で始まるように変更
デプロイアプリで実データが 401①ドメイン分離前にログインしたセッション ②プラットフォームキーが未設定ログアウト→再ログイン試行
設定 → プラットフォームタブ		①再ログイン 1 回 ②PLATFORM_API_KEY を設定後 bin/restart.sh
キーを変更したが反映されないdocker restart は .env を再読み込みしない設定画面に「環境変数で管理中」という表示があるかどうかbash bin/restart.sh （または docker compose up -d --force-recreate ）
アプリビルドが「サイドカー」エラーで失敗ビルダーサイドカーが起動していないdocker ps --filter name=pp-studio-agent-server
curl -s localhost:8000/health		bash bin/restart.sh · 急ぎの場合は設定 → エージェントでビルダーエンジンを組み込みに切り替え
チャットが「AI プロバイダに接続できません」AI アドレス・キーエラー、ゲートウェイダウン設定 → AI タブの接続テスト
docker logs --tail 50 pp-studio-server		アドレス・キーを修正 → bin/restart.sh
3D・大規模アプリビルドが途中で停止メモリ不足（セッションコンテナ上限 2 GB、ホスト余裕）docker stats · free -h同時に開いているプロジェクトを減らす · ホストメモリを増設
自動バックアップが実行されないcron がインストールされていないか DB に到達できないcat /etc/cron.d/pp-studio-backup
tail -50 dist/backup.log		sudo bash bin/install-backup-cron.sh を再インストール · DRYRUN=1 bash bin/restore.sh で DB 到達確認
ディスク容量が満杯バックアップ・ビルド成果物の蓄積df -h
du -sh dist /var/lib/pp-studio/*		保存個数を削減（BACKUP_KEEP） · 古いバックアップをクリーンアップ
更新後も古い画面のままですブラウザキャッシュまたはイメージ pull 失敗ブラウザ強力リロード（Ctrl+Shift+R）
bash bin/start.sh の pull 結果出力		レジストリログイン確認後 bash bin/start.sh を再実行

詳細診断​

スタックが起動しない場合​

cd /opt/kopens/plantpulse-studio-docker
bash bin/status.sh
docker ps -a --filter name=pp-studio          # Exited 인 컨테이너 찾기
docker logs --tail 200 pp-studio-server

コンテナが継続的に再起動（Restarting）している場合、ログの最後の行に原因があります。最も一般的なのは データベース接続失敗と .env 値エラーです。

grep -E '^(DATABASE_URL|COMPOSE_PROFILES|PG_|DATA_ROOT|PLATFORM_API_TARGET)' .env

インストールが「正常な状態」か一度に判定​

bash bin/smoke-install.sh

ヘルス · 無認証設定 API · Web レスポンス · 実際のログイン · セッションランタイムイメージ · コンテナ状態を 順番に確認し、失敗した最初の項目を報告します。

アプリセッション（プロジェクト オープン）の問題​

docker ps --filter label=plantpulse-studio=1     # 지금 떠 있는 세션 컨테이너
docker image inspect plantpulse-studio-runtime:latest >/dev/null && echo "런타임 이미지 OK"
  • セッションコンテナはアイドル 30 分後に自動回収されます — リストにないからといってエラーではありません。
  • サーバを再起動するとそれまであったセッションコンテナは自動的にクリーンアップされます。
  • 複数のユーザーが同時に開くと、その分のメモリを使用します（docker stats で確認）。

プラットフォーム（実データ）接続の問題​

症状は通常「チャット質問はできるが値が取得できない」または「設備リストが空」です。

  1. 設定 → プラットフォームタブで接続状態を確認します。
  2. .env の PLATFORM_API_TARGET アドレスが正しいか確認します。
  3. PLATFORM_API_KEY が設定されているか確認します → シークレット管理
  4. サーバログでプラットフォーム呼び出しエラーを確認します。
docker logs --tail 200 pp-studio-server | grep -i platform

プラットフォームが一時的にダウンすると、ウォッチャー実行は自動的にスキップされます（再起動後に自動再開）。

ドメイン・プロキシの問題​

症状はさまざまに現れますが、原因は通常 4 つの設定のいずれかが不足しています。 ドメインとリバースプロキシのチェックリストをそのまま照合してください。

リカバリ手段​

状況対処
設定を誤って変更しスタックが異常になった.env で原状復帰後 bash bin/restart.sh
データが破損したバックアップと復旧 — bash bin/restore.sh
更新後に問題が発生.env の TAG を直前のバージョンに固定後 bash bin/start.sh
デプロイ済みアプリに問題が発生Studio 画面のデプロイ履歴から以前のバージョンへロールバック

サポート要求時に一緒に送ると良いもの​

cd /opt/kopens/plantpulse-studio-docker

bash bin/status.sh                    > /tmp/pp-status.txt
docker logs --tail 500 pp-studio-server &> /tmp/pp-server.log
grep -vE 'KEY|TOKEN|PASSWORD' .env    > /tmp/pp-env-safe.txt   # 비밀 제외본
  • いつから、どの操作で発生したか
  • 画面キャプチャ（ブラウザ開発者ツール コンソール付きがより良い）
  • インストールバージョン（.env の TAG ）とアクセス方法（IP / ドメイン / プロキシあり/なし）
ログ・設定を送信する前に

.env オリジナルには API キーが含まれています。上記のようにシークレットを除いたコピーを作成して送信してください。

関連ドキュメント​