トラブルシューティング

このドキュメントは、ワンライン / Docker インストールで運用される PlantPulse プラットフォームで頻繁に発生する問題とその解決方法を案内します。ほとんどの問題は、以下の手順を順番に追うことで解決できます。

コンテナは9個です

プラットフォームは Docker Compose スタックとして動作します — 証明書1つ(plantpulse-certs)、データレイク1つ、アプリ6つ、プロキシ1つ。9個すべてが常時動作し (healthy) が正常です。plantpulse-platform という名前のコンテナはありません。

「何が故障したか」をまず絞り込んでください。./status.sh がサービス別に回答します → インストールされる構成

最初のステップ: どのような問題であっても、まず以下の3点を確認してください。

cd /opt/kopens/plantpulse-platform-docker/bin
./status.sh                                          # コンテナ / health / ボリューム要約
./ops-check.sh                                       # 運用 health + critical log
./logs.sh -n 200                                   # 最新のコンテナログ (全体)

それでも解決しない場合は ./doctor.sh で診断 tarball を生成し、技術サポートチームに送付してください。

コンテナ起動問題

症状：コンテナが `unhealthy` 状態から回復しない

原因	解決
Aster TSDB スキーママイグレーション失敗	`./logs.sh cassandra -n 300` でエラー確認後 `./restart.sh` を試行。繰り返し失敗する場合は `./doctor.sh`
データディレクトリ権限問題	ホストの `/data1/pp-data` 権限を確認。`sudo chown -R root:root /data1/pp-data && sudo chmod -R 755 /data1/pp-data`
メモリ不足 (OOMKilled)	`docker inspect <컨테이너> --format '{{.State.OOMKilled}}'` で確認。コンテナごとに上限値が異なります — データレイクは `DOCKER_DATALAKE_MEMORY`, アプリは `DOCKER_SERVER_MEMORY` など (環境変数)
JVM warm-up 未完了	起動には3〜5分かかります。5分以上 unhealthy が持続する場合は次段階の診断へ

# 어떤 서비스가 비정상인가 (0 = 정상 / 2 = 비정상)
./status.sh

# 스택 전체 준비 판정
./stack-verify-boot.sh

# 컨테이너별 메모리 / CPU
docker stats --no-stream

# 헬스체크 엔드포인트 응답 확인
curl -kfsS https://<server-ip>:4950/api/health | jq

証明書コンテナも常時動作します

plantpulse-certs は証明書を一度発行し、起動し続けたまま期限切れを監視します。(healthy) が正常です。ヘルスチェックはプロセスが生きているかではなく、ボリュームの資材が利用可能かを確認します — 期限まで残り時間、キーストアが開くかまで確認します。

症状：`no such service` · コンテナが存在しないと表示される

初回インストールが完了していないか、./remove.sh でコンテナが削除された状態です。

古いランブックに従って plantpulse-platform を探していた場合、その名前のコンテナはありません — 名前は ./status.sh または ./logs.sh --list で確認してください。

cd /opt/kopens/plantpulse-platform-docker/bin
./install.sh                                         # 최초 설치
# 또는 OS 설정이 이미 끝났다면
./up.sh                                    # 컨테이너 생성 + 기동

症状：`address already in use` (ポート衝突)

ホストに旧バージョンの plantpulse が native で動作しているか、他のサービスがポートを占有している場合です。

# 호스트 native plantpulse 정지
pkill -ef plantpulse

# 특정 포트 점유 프로세스 확인 (예: 80)
ss -tlnp | grep :80

# 충돌 프로세스를 종료한 후 재시도
./restart.sh

詳細なポートリストはポートおよびサービス管理ページを参照してください。

イメージ / レジストリ問題

症状：`docker pull` → `unauthorized: authentication required`

レジストリ認証が期限切れか、資格情報がない状態です。

docker login docker.kopens.io
# Username/Password 입력 후, 하던 설치 · 업그레이드 원라이너를 다시 실행

症状：イメージダウンロード失敗 (ネットワーク)

# 1. 레지스트리 접근 가능 여부 확인
curl -fsSL https://docker.kopens.io/v2/

# 2. DNS 확인
nslookup docker.kopens.io

# 3. 회사 방화벽 / 프록시 차단 가능성 — 네트워크 관리자에게 다음 도메인 허용 요청
#    docker.kopens.io, download.kopens.io

閉域網環境の場合は、Docker インストールページの閉域網(Airgap)インストール手順に従ってください。

データベース問題

データベースコンポーネントはコンテナ内部で動作します。点検は ./shell.sh でコンテナに進入した後に行います。

PostgreSQL (メタ DB)

役割: ユーザー情報、サイト設定、資産設定などプラットフォームのメタデータを保存します。

./shell.sh                                   # 컨테이너 진입

# 컨테이너 내부에서
/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd node psql         # PostgreSQL 셸 접속
psql=# SELECT 1;
psql=# SHOW max_connections;
psql=# SELECT count(*) FROM pg_stat_activity;

症状	原因	解決
Connection refused	PostgreSQL コンポーネントダウン	コンテナ内部で `pd restart storage` を実行。ホストでは `./restart.sh`
Too many connections	接続プール超過	`properties` の connection pool 設定を検討。一時的な場合は storage 再起動
Authentication failed	パスワード不一致	`/etc/kopens/plantpulse-platform.env` の `PP_PG_PASSWORD` とアプリケーション properties の一致を確認

パス確認 — シークレットサイドカーの正本は /etc/kopens/plantpulse-platform.env のみです(権限 0600)。古いインストールで /opt/kopens/ の下に同じ名前が残っている場合がありますが、読み込まれず、インストールスクリプトが正本に差し戻します → 環境変数リファレンス

Aster TSDB (時系列 DB)

役割: センサ時系列データ、アラーム履歴などの大量データを保存します。

./shell.sh

# 컨테이너 내부에서
/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd node status       # 클러스터 상태
/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd node compactionstats  # 컴팩션 진행 상태
/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd node cql          # CQL 셸 접속

症状	原因	解決
Connection timeout	ノードダウン	`pd node status` でノード状態確認後 `pd restart storage`
WriteTimeout	書き込み遅延 (ディスク I/O 飽和)	`pd node compactionstats` 確認、`pd node compact` で手動コンパクション
ReadTimeout	読み取り遅延 (巨大パーティション)	`pd node table-histograms` でパーティションサイズ確認
ディスク空間不足	SSTable 蓄積	`pd node cleanup` 実行後 `df -h /data1` で確認

Valkey (Redis キャッシュ)

./shell.sh

# 컨테이너 내부에서
redis-cli -a "$PP_REDIS_PASSWORD" ping
redis-cli -a "$PP_REDIS_PASSWORD" INFO memory

ログイン / コンソール接続問題

症状：ブラウザからコンソールに接続できない

# 1. 컨테이너 health 확인
./status.sh

# 2. 외부 노출 IP 설정 확인
grep DOCKER_PP_EXTERNAL_IP env.sh

# 3. 호스트 방화벽 확인
sudo firewall-cmd --list-ports                       # RHEL/Rocky/Oracle
sudo ufw status                                      # Ubuntu

# 4. 포트 점유 확인 — 프록시가 80/443 을 엽니다
ss -tlnp | grep -E ':(80|443)\s'

症状	原因	解決
ページが開かない	`plantpulse-proxy` が不正常	`./status.sh` でプロキシ状態を確認。プロキシが 80/443 を受ける唯一の入口です
ページが開かない	ファイアウォール遮断	会社/クラウドファイアウォールで 80, 443, 4950 許可を要請
ログイン失敗	パスワード不一致	デフォルトの `admin / admin123!` を確認。変更した場合は管理者に初期化を要請
403 Forbidden	ユーザー権限不足	管理者にロール(role)確認を要請
セッション切れ	30分間無活動で自動ログアウト	再ログイン

データ収集問題

データ収集経路: OPC サーバー → メッセージブローカー(Kafka/MQTT) → エンジンパイプライン → Aster TSDB. この経路のどこか一箇所でも詰まるとデータが入ってきません。

症状：データが収集されない

点検項目	確認方法
OPC 接続状態	Webコンソール > 接続管理 > 状態から `CONNECTED` を確認
エンジン状態	コンソール > モニタリング > システム状態から `RUNNING` を確認
パイプライン	MPS(秒間メッセージ数) が 0 であれば受信停止
メッセージブローカー	`./shell.sh` 進入後 `/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd node topic` で Kafka トピックを確認
ネットワーク	OPC サーバー → プラットフォームホスト IP ping / telnet

症状：データ遅延

原因	解決
パイプラインキュー滞留	properties の `engine.pipeline.threads` を上方修正
Aster TSDB 書き込み遅延	`pd node compactionstats` 確認、ディスク I/O モニタリング
Kafka lag	`pd node topic` で consumer lag を確認
ネットワーク遅延	OPC サーバー ↔ プラットフォームホスト RTT 測定

性能問題

症状：コンソール / API 応答が遅い

# 호스트에서 컨테이너 자원 사용량
docker stats --no-stream

# 앱 컨테이너의 JVM 메모리 (그 앱이 도는 컨테이너 안에서)
./shell.sh plantpulse-server-web
jmap -heap $(pgrep -f plantpulse-server)

どのコンテナかまず特定してください

アプリ6つはそれぞれ個別のコンテナで動作するため、データレイク内でアプリプロセスを探しても見つかりません。./status.sh で対象コンテナを確認してから ./shell.sh <컨테이너> で進入してください。

原因	解決
コンテナメモリ不足	該当コンテナの上限値を上方修正後 `./restart.sh` — データレイクは `DOCKER_DATALAKE_MEMORY`, アプリは `DOCKER_SERVER_MEMORY` など (環境変数)
JVM メモリ不足	コンテナ内部 setenv のヒープサイズ調整 (詳細は性能チューニング)
GC 頻発	GC ログ分析, G1GC オプションチューニング
DB スロークエリ	PostgreSQL slow query ログ確認
ホスト CPU 飽和	`top` / `htop` 確認後 `DOCKER_PP_CPUS` 上方修正を検討

症状：OutOfMemoryError

# 컨테이너 내부에서 heap dump 활성화
./shell.sh
# setenv 또는 JAVA_TOOL_OPTIONS 에 -XX:+HeapDumpOnOutOfMemoryError 추가

# 생성된 hprof 를 호스트로 복사
docker cp plantpulse-datalake:/path/to/heap.hprof /tmp/

Eclipse MAT / VisualVM で分析します。

アラーム問題

症状	原因	解決
アラームが発生しない	アラーム設定が解除状態	アラーム > 詳細アラームからチェック → 選択したアラーム設定配置
値は超えたがアラームがリストにない	一時的に非表示 · 計画整備または修理抑制 · サービス除外	非表示 · 抑制 · サービス除外を確認。非表示の発生は `GET /api/v5/alarm/suppressed` でも確認可能
アラームプッシュが繰り返し届く	抑制時間が 0	アラーム設定の重複アラーム抑制 → 抑制時間 (分)
復帰が拒否される	復帰点検失敗(値が正常範囲でないか、10分以内の値がない)	値を確認してから再度復帰させるか、理由を記入してそれでも復帰
ステートメント保存が拒否される	種類別必須出力項目がない	種類別必須項目
アラーム設定生成が 422 (API)	手動で設定した ID	`GET /api/v5/alarm/config/new-id` で受け取った ID を使用します
メール通知が送信されない	SMTP 設定エラー	`mail.properties` 確認 (コンテナ内部 `/opt/kopens/plantpulse-platform/plantpulse-server/config/`)
通知音が鳴らない	ブラウザ自動再生ポリシー	ブラウザ設定でサイトの自動再生を許可

UI 問題

症状	解決
画面が崩れる	ブラウザキャッシュ削除 (Ctrl+Shift+Delete)
チャートが表示されない	ブラウザ開発者ツール(F12) > Console で JS エラーを確認
リアルタイム更新が途切れる	プロキシ/ファイアウォールの SSE(HTTPストリーミング) バッファリング・タイムアウト設定を確認
ダッシュボードロード失敗	接続されたタグ / データソースの存在を確認
文字化け	`env.sh` の `PP_LANG=ko`, `PP_TZ=Asia/Seoul` 確認後 `./restart.sh`

オブジェクトストア(RustFS) 問題

ログに `AccessDenied` が延々と記録されます

[RUSTFS] level=ERROR op=GetObject err=S3Error(code: AccessDenied, message: "Access Denied")

資格情報の問題ではありません。 管理 API の指標収集器が2秒ごとに古い MinIO メトリクスパス(/minio/v2/metrics/cluster)を呼び出しますが、RustFS にはそのパスがないため、リクエストが S3 ルーターに送られます。するとバケット名が minio である照会として読み込まれ、収集器が署名を付与しないため匿名リクエストとなって拒否されます。

問い	答え
データは危険か	いいえ。読み取り試行が1回拒否されているだけであり、保存物とは無関係です
パスワードを直せばよいか	いいえ — 運用者が触れる場所ではありません。リクエストを送る側が署名を付与しない我々の収集器であり、仮に署名させたとしても指標は依然として空のままです(存在しないエンドポイントであるため)
どの程度記録されるか	2秒周期 — 1日4万行を超えます
今すべきこと	この署名を «既知のノイズ» として無視してください。本当のエラーが埋もれないよう、ログを見る際にこの1行をフィルタリングして確認してください
いつ消えるか	2026.09 次期バージョンで消えます — 収集器が存在しないエンドポイントを呼び出さないように修正しました — 1日約4万3千行が消えます(41実測: 反映後36分連続0行)

ログが静かになっても «指標は» 戻りません

次期バージョンで消えるのは ログの行 であり、値ではありません。オフラインドライブ · オフラインノード · 容量アラームはその後も 値を受け取れません — RustFS にメトリクスパスが作成されなければ変わりません。静かになったことを「直った」と読まないでください。

MinIO 時代は 200 でした

当時はメトリクスパスが認証なしで開放されていたため(MINIO_PROMETHEUS_AUTH_TYPE=public)、収集できていました。RustFS に変更したことで 対応する設定がなくなり、それら7つの指標(minio_cluster_*)は以上来届かなくなりました。コンソールでそれらの値が空に見えるのも同じ理由です。

ディスク / ボリューム問題

症状：ディスク空間不足

# 호스트 디스크 사용량
df -h
df -h /data1                                         # 데이터 디스크

# Docker 사용량 (이미지 / 볼륨 / 빌드 캐시)
docker system df

# 컨테이너 내부 사용량
./shell.sh
df -h
du -sh /opt/kopens/plantpulse-platform/plantpulse-storage/db/cassandra/data

原因	解決
古いバックアップの蓄積	`/data1/pp-backup/docker-volume` の古い tar.gz を整理
Docker 未使用イメージ	`docker system prune` で整理 (イメージ/ネットワーク/キャッシュ)
Aster TSDB SSTable 蓄積	コンテナ内部で `pd node cleanup`, `pd node compact`
ログディレクトリ肥大	`/opt/kopens/plantpulse-platform-docker/logs` 整理

注意: docker volume prune は使用されていないボリュームをすべて削除します。pp-* ボリュームが誤って消去されないよう、コンテナを停止状態にしないでください。

症状：ボリュームデータの復旧が必要

運用管理 - バックアップと復旧ページの復旧手順を参照してください。

アップデート / ロールバック問題

症状：アップグレード後コンテナが正常に動作しない

バージョンアップはインストールワンライナーの再実行が公式手順です。アップグレードに失敗した場合、ワンライナーがアップグレード直前のバックアップで 以前のバージョンに自動的に戻します(UPGRADE FAILED ブロックにバックアップ位置が記録されます)。記録された点検項目を見て原因を修正した後、同じワンライナーを再実行します。手動で戻す場合は bin/upgrade-rollback.sh <백업 위치> を使用します。./update.sh でイメージタグだけを変えて戻さないでください — 運用スクリプト · compose は新バージョンのまま残ります。

症状：アップデート中に `NOT FOUND CONTAINER`

初回インストール(./install.sh)が完了していない状態です。まずインストールを行ってください。

ネットワーク / クラスター問題

症状：ワーカーがマスターに join されない

# 1. 워커 컨테이너 진입 (워커는 기본 스택의 서비스가 아니라 shell.sh 로는 잡히지 않습니다)
docker exec -ti plantpulse-worker-1 /bin/bash
# 워커 내부에서 마스터 IP 로 연결 테스트
ping ${PP_MASTER_IP}

# 2. 마스터에서 링 확인 — 이것이 조인의 «유일한» 증거입니다
cd /opt/kopens/plantpulse-platform-docker/bin
./shell.sh
/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd node status

# 3. JGroups / Cassandra 포트 (7000, 7001, 7800, 7801, 9042) 방화벽 허용 확인

コンテナが起動していることはジョインの証拠ではありません

ジョインに失敗したワーカーも、成功したワーカーと同様に正常として報告します — コンテナの独自チェックは «マスターに到達するか» のみを見るためです。2026-08-31 の実測で, Aster TSDB が OOMKilled されたワーカーがリングは1ノードのままで health: starting を維持していました。

必ず pd node status のリングリストで判定してください。ワーカー追加は bin/worker-add.sh がこの確認を代行します → クラスターインストール

症状：MQTT / Kafka 外部クライアント接続失敗

ホストファイアウォールと会社/クラウドファイアウォールで 1883/1884 (MQTT), 9092/9093/9094 (Kafka) が許可されているか確認してください。詳細なポートリストはポート構成情報を参照してください。

MQTT は plantpulse-proxy が受けます。 設備はこのホストのみを知っていればよく、ブローカーが移動したり名前が変わったりしても設備設定を変更する必要はありません。1884 は TLS passthrough であり、ブローカーが TLS を終端します。
Kafka はプロキシを経由しません。 クライアントがブートストラップ後、advertised.listeners アドレスで再接続するためです — ブートストラップだけ成功し、その後静かに失敗している場合は、まずこのアドレスを疑ってください。

緊急対応

コンテナが応答しないとき

cd /opt/kopens/plantpulse-platform-docker/bin

# 1. 상태 확인
docker ps -a
./status.sh

# 2. 로그에서 마지막 에러 확인
./logs.sh -n 200

# 3. 안전 재시작
./restart.sh

# 4. 위 단계로 회복 안 될 경우 진단 tarball 생성
./doctor.sh
# 생성된 tarball 을 webmaster@kopens.com 으로 전달

データ破損が疑われるとき

# 1. 즉시 정지 (추가 손상 방지)
./down.sh

# 2. 최신 백업 확인
ls -lh /data1/pp-backup/docker-volume/

# 3. 진단 tarball 생성 (절대 데이터를 임의로 수정하지 마세요)
./doctor.sh

# 4. 기술 지원팀 연락

データ破損時の禁止事項: 直接 pd node repair, pd node cleanup, SSTable 削除などを行わないでください。誤った復旧作業は破損を拡大させる可能性があります。必ず技術サポートチームと協議した上で進めてください。

サポート要請時に必要な情報

上記の方法で解決しない場合、以下の情報を併せて送付いただければ迅速な分析が可能です。

項目	収集方法
診断 tarball	`./doctor.sh` 実行後に生成されたファイル
コンテナログ	`./logs.sh -n 500 > /tmp/container.log 2>&1` (8つのコンテナすべて)
モジュール別ログ	`./tools/copy-log-to-local.sh` の結果 (`/tmp/plantpulse-log/`)
イメージバージョン	`./stack-version.sh` の出力
環境変数	`env.sh` (パスワードはマスキング)
システム情報	OS, CPU, メモリ, ディスク (`uname -a`, `free -h`, `df -h`)
エラーメッセージ	正確なエラーメッセージ / ブラウザコンソール(F12)キャプチャ
再現手順	問題発生直前に実施した作業順序

技術サポート: webmaster@kopens.com

コンテナ起動問題​

症状：コンテナが unhealthy 状態から回復しない​

症状：no such service · コンテナが存在しないと表示される​

症状：address already in use (ポート衝突)​

イメージ / レジストリ問題​

症状：docker pull → unauthorized: authentication required​

症状：イメージダウンロード失敗 (ネットワーク)​

データベース問題​

PostgreSQL (メタ DB)​

Aster TSDB (時系列 DB)​

Valkey (Redis キャッシュ)​

ログイン / コンソール接続問題​

症状：ブラウザからコンソールに接続できない​

データ収集問題​

症状：データが収集されない​

症状：データ遅延​

性能問題​

症状：コンソール / API 応答が遅い​

症状：OutOfMemoryError​

アラーム問題​

UI 問題​

オブジェクトストア(RustFS) 問題​

ログに AccessDenied が延々と記録されます​

ディスク / ボリューム問題​

症状：ディスク空間不足​

症状：ボリュームデータの復旧が必要​

アップデート / ロールバック問題​

症状：アップグレード後コンテナが正常に動作しない​

症状：アップデート中に NOT FOUND CONTAINER​

ネットワーク / クラスター問題​

症状：ワーカーがマスターに join されない​

症状：MQTT / Kafka 外部クライアント接続失敗​

緊急対応​

コンテナが応答しないとき​

データ破損が疑われるとき​

サポート要請時に必要な情報​

関連ドキュメント​