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

トラブルシューティング

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

cd /opt/kopens/plantpulse-studio-docker

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

ログの確認方法​

対象コマンド
スタジオサーバー(最も重要)docker logs -f --tail 200 plantpulse-studio-server
Web(nginx)docker logs --tail 100 plantpulse-studio-web
ビルダーサイドカーdocker logs --tail 100 plantpulse-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 plantpulse-studio-server
docker logs --since "2026-07-28T09:00:00" plantpulse-studio-server
ログにキーは残りません

APIキー・トークンはログに記録されません(監査ログにも値の代わりに指紋のみ)。ログをサポートチームに 送付する際は、サイト名・設備名などの現場情報だけ確認していただければ結構です。

このインストールが「できるか」を一括確認する​

GET /api/v1/diagnostics     (관리자 전용)

「画面は出るのにPDFが出ない」「アプリが開かない」といった問い合わせに、まず押していただく場所です。

{"ok": true,
 "os":        {"ok": true, "detail": "Debian GNU/Linux 13"},
 "chromium":  {"ok": true, "detail": "Chromium 153…"},
 "pdf":       {"ok": true, "detail": "26568 bytes"},
 "fontsCjk":  {"ok": true, "detail": "15 faces"},
 "docker":    {"ok": true, "detail": "server 29.8.1"}}

項目ごとに {ok, detail} で、一番上の ok はすべて真のときのみ真です。pdf は説明ではなく 実際に韓国語PDFを1枚焼き上げた結果であり、docker はセッションコンテナを起動できるかを確認します。

/health とは異なる質問です — 画面からポーリングしないでください

/health は「生きているか」を安価に頻繁に問い、診断は「できるか」を高価にたまに問います (PDFを実際に焼きます)。ダッシュボードから定期的に呼び出すと、それ自体が負荷になります。

症状 → 原因の早見表​

症状よくある原因確認対処
Web画面が全く開かないスタックが停止している、または80番ポートを占有bash bin/status.sh
docker logs plantpulse-studio-web		bash bin/up.sh · 80番ポートを使用中の他サービスを停止
画面は出るがログイン失敗ブートストラップアカウント未設定、またはプラットフォームに到達不可grep STUDIO_LOCAL_USERS .env
curl -s localhost:5170/health		.env にアカウントを指定後 bash bin/restart.sh
ログインが突然ブロック(しばらくして再試行)ログインレートリミット(IPあたり10回/分)docker logs --tail 50 plantpulse-studio-server1分待って再試行
ヘルスが継続的にDOWN、ログにDB認証エラーDATABASE_URL のパスワードだけ変更し、DB内のロールは変更していないdocker logs plantpulse-studio-server
外部PGから psql で直接接続		元のパスワードに戻すか、PostgreSQL内でアカウントのパスワードを先に変更
プロジェクトを開く操作が失敗(500)セッションランタイムイメージがないdocker image inspect plantpulse-studio-runtime:latestbash bin/up.sh を再実行(エアギャップは bin/load.sh で取り込み)
プレビュー・配信アプリが空白画面(IP接続)ファイアウォールで5171を遮断curl -I http://<server-ip>:5171/ファイアウォールで5171を開放
プレビューが空白画面 + コンソールに Mixed ContentスタジオはHTTPSなのにアプリ資産がHTTPで要求されるブラウザ開発者ツールコンソールプロキシに X-Forwarded-Proto $scheme を追加 → ドメイン
コードを修正してもプレビューがそのままプロキシがHMR WebSocketをアップグレードしていない開発者ツール → ネットワーク → WSリクエストが101か両vhostに Upgrade/Connection ヘッダー
ビルドチャットが時間がかかると「接続エラー: network error」プロキシの無送信タイムアウト(デフォルト60秒)プロキシvhost設定を確認両vhostに proxy_read_timeout 3600s
回答がリアルタイムではなく一塊で表示されるproxy_buffering が有効(デフォルト値)〃proxy_buffering off
どのドメインでアクセスしても別の場所に飛ばされるWeb nginx設定のロード順(最初の server がデフォルトサーバー)docker exec plantpulse-studio-web ls /etc/nginx/conf.dvhostのファイル名を zz- で始まるように変更
配信アプリで実データが401①ドメイン分離前にログインしたセッション ②プラットフォームキー未設定ログアウト→再ログインを試す
環境設定 → プラットフォームタブ		①再ログイン1回 ②PLATFORM_API_KEY 設定後 bin/restart.sh
キーを変更したのに反映されない.env のみ修正し、docker restart は .env を再読み込みしていない環境設定画面のバッジが 환경변수 기본값 か早道 — 環境設定画面に新しいキーを入力(再起動なしで即時反映)。環境変数側を変更する必要がある場合は bash bin/restart.sh (または docker compose up -d --force-recreate)
アプリビルドが「サイドカー」エラーで失敗ビルダーサイドカーが未起動docker ps --filter name=plantpulse-studio-agent-server
curl -s localhost:8000/health		bash bin/restart.sh · 急ぐ場合は環境設定 → エージェントでビルダーエンジンを内蔵に切り替え
チャットに**「AIプロバイダー <address> に接続できません。環境設定 → AIタブでアドレス・キーを確認してください。」**AIアドレス・キーエラー、ゲートウェイ停止環境設定 → AIタブの接続テスト
docker logs --tail 50 plantpulse-studio-server		アドレス・キーを画面上で修正 — 即時反映されます(再起動不要)
チャットに**「AIプロバイダーが設定されていません(環境設定)。」**AIプロバイダーが完全に空環境設定 → AIタブアドレス・キーを入力後[接続テスト]
3D・大規模アプリのビルドが途中で停止メモリ不足(セッションコンテナ上限2GB、ホストに余裕あり)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/update.sh 出力のpull結果		レジストリログインを確認後 bash bin/update.sh を再実行

詳細な診断​

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

cd /opt/kopens/plantpulse-studio-docker
bash bin/status.sh
docker ps -a --filter name=pp-studio          # Exited 인 컨테이너 찾기
docker logs --tail 200 plantpulse-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 plantpulse-studio-server | grep -i platform

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

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

症状は多岐にわたりますが、原因は通常4つの設定のうち1つが欠けていることです。 ドメインとリバースプロキシのチェックリストをそのまま照合してください。

復旧手段​

状況対処
設定を誤って変更しスタックが異常.env で元に戻した後 bash bin/restart.sh
データが破損バックアップと復元 — bash bin/restore.sh
アップデート後に問題発生.env の PP_IMAGE_TAG を直前のバージョンに固定後 bash bin/update.sh
配信したアプリに問題発生スタジオ画面の配信履歴から以前のバージョンにロールバック

サポート依頼時に一緒に送付すると良いもの​

cd /opt/kopens/plantpulse-studio-docker

bash bin/status.sh                    > /tmp/pp-status.txt
docker logs --tail 500 plantpulse-studio-server &> /tmp/pp-server.log
grep -vE 'KEY|TOKEN|PASSWORD' .env    > /tmp/pp-env-safe.txt   # 비밀 제외본
  • いつから、どの操作で発生したか
  • 画面キャプチャ(ブラウザ開発者ツールコンソールを含むとより良い)
  • インストールバージョン(.env の PP_IMAGE_TAG、空の場合は VERSION のカルバー)と接続方法(IP / ドメイン / プロキシの有無)
ログ・設定を送付する前に

.env 原本にはAPIキーが含まれています。上記のように秘密を除いたコピーを作成して送付してください。

関連ドキュメント​