トラブルシューティング

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

コンテナは 9 つです

プラットフォームは Docker Compose スタックで動作します — 認証書ワンショット 1 つ（plantpulse-certs、Exited (0) が正常）、データレイク 1 つ、アプリ 6 つ、プロキシ 1 つです。plantpulse-platform という名前のコンテナは存在しません。

「何が故障しているのか」をまず絞り込んでください。./status.sh がサービス別に応答します → インストール時の様子

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

cd /opt/kopens/plantpulse-platform-docker/bin
./status.sh                                          # コンテナ / ヘルス / ボリューム サマリー
./ops-check.sh                                       # 運用ヘルス + クリティカルログ
./logs.sh -n 200                                   # 最近のコンテナログ（全体）

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

コンテナ起動問題

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

原因	解決
Cassandra スキーマ移行失敗	`./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 ウォームアップ未完了	起動には 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 は認証書を焼成して自身を終了するため、Exited (0) が成功状態です。compose がこのコンテナのヘルスチェックを明示的に無効化しているため（healthcheck: disable）、ヘルス欄は空白であり、正常に動作しているコンテナが unhealthy と表示される問題もありません。status.sh と ops-check.sh はこのコンテナだけを終了コードで判定するため、手動で確認する際もそのように見てください。

症状: `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 plantpulse 정지
pkill -ef plantpulse

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

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

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

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

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

レジストリ認証の有効期限が切れているか、認証情報がない状態です。

docker login docker.kopens.io
# Username/Password 입력 후
./update.sh

症状: イメージダウンロード失敗（ネットワーク）

# 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 の一致を確認

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

Cassandra（時系列 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 을, 데이터레이크가 7443 을 엽니다
ss -tlnp | grep -E ':(80|443|7443)\s'

症状	原因	解決
ページが開かない	`plantpulse-proxy` が異常	`./status.sh` でプロキシ状態を確認します。プロキシが 80/443 を受ける唯一の入口です
ページが開かない	ファイアウォールブロック	企業/クラウドファイアウォールで 80、443、7443、4950 の許可をリクエスト
ログイン失敗	パスワード不一致	デフォルト `admin / admin123!` を確認します。変更した場合は管理者にリセットをリクエスト
403 Forbidden	ユーザー権限不足	管理者にロール確認をリクエスト
セッションタイムアウト	30 分無操作で自動ログアウト	再度ログイン

データ収集問題

データ収集パス: OPC サーバー → メッセージブローカー（Kafka/MQTT） → エンジンパイプライン → Cassandra。このパスのいずれかが遮断されると、データが収集されません。

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

確認項目	確認方法
OPC 接続状態	ウェブコンソール > 接続管理 > ステータスで `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` を上向き
Cassandra 書き込み遅延	`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 スロークエリログを確認
ホスト 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 で分析します。

アラーム問題

症状	原因	解決
アラームが発生しない	アラーム設定が未配置	アラーム設定画面で「配置」をクリック
アラーム重複発生	重複チェック無効	アラーム設定で重複チェックを有効化
メール通知が未送信	SMTP 設定エラー	`mail.properties` を確認（コンテナ内部 `/opt/kopens/plantpulse-platform/plantpulse-server/config/`）
通知音が出ない	ブラウザ自動再生ポリシー	ブラウザ設定でサイト自動再生を許可

UI 問題

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

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

症状: ディスク容量不足

# 호스트 디스크 사용량
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` でクリーンアップ（イメージ/ネットワーク/キャッシュ）
Cassandra SSTable 蓄積	コンテナ内部で `pd node cleanup`、`pd node compact`
ログディレクトリが肥大	`/opt/kopens/plantpulse-platform-docker/logs` をクリーンアップ

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

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

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

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

症状: アップデート後にコンテナが正常に動作しない

./update.sh はヘルスチェック検証に失敗すると、自動的に以前のイメージにロールバックします。手動ロールバックが必要な場合:

# 1. 이전 버전 태그를 env.sh 에 지정
vi env.sh
#   PP_IMAGE_TAG="2026.04"   ← 이전 안정 버전

# 2. 업데이트 재실행
./update.sh

症状: アップデート中に`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) 방화벽 허용 확인

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

join に失敗したワーカーも成功したワーカーと同じように正常に報告します — コンテナの自体チェックは«マスターに到達しているか»だけを見るためです。2026-08-31 実測で Cassandra が 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 パススルーであり、ブローカーが 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）​

Cassandra（時系列 DB）​

Valkey（Redis キャッシュ）​

ログイン / コンソールアクセス問題​

症状: ブラウザからコンソールにアクセスできない​

データ収集問題​

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

症状: データ遅延​

パフォーマンス問題​

症状: コンソール / API レスポンスが遅い​

症状: OutOfMemoryError​

アラーム問題​

UI 問題​

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

症状: ディスク容量不足​

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

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

症状: アップデート後にコンテナが正常に動作しない​

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

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

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

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

緊急対応​

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

データ破損が疑われる場合​

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

関連ドキュメント​