トラブルシューティングガイド

サービス起動失敗

症状: 特定のサービスが `[DOWN]` 状態

./status.sh

[DOWN] CASSANDRA (9042)
[DOWN] RAG (7114)

原因と対処:

原因	対処方法
以前のプロセスが残っている	PIDファイルを確認してプロセスを終了
ポート競合	`ss -tlnp \| grep <port>` で占有プロセスを確認
依存サービスが未起動	DBを先に起動する必要あり(起動順序を確認)
ディスクフル	`df -h` でディスクを確認後、`./clean.sh` を実行

# PID 파일로 프로세스 확인
cat /home/kopens/plantpulse-ai/<module>/*.pid
kill -9 <PID>
rm /home/kopens/plantpulse-ai/<module>/*.pid

# 모듈 재시작
cd /home/kopens/plantpulse-ai/<module>/bin
./stop.sh
./start.sh

症状: システム全体が起動しない

確認順序:

# 1. 환경 변수 파일 확인
source /home/kopens/plantpulse-ai/template/env.sh
echo $PP_HOME    # /home/kopens 이어야 함
echo $JAVA_HOME  # JDK 경로 확인

# 2. Java 확인
$JAVA_HOME/bin/java -version

# 3. Python 확인
python3 --version

# 4. 설치 로그 확인
tail -100 /home/kopens/plantpulse-ai/logs/setup.log

データベースの問題

Cassandra の起動が遅い / タイムアウト

Cassandra の起動には 20~60秒 かかります。start.sh は自動的に待機しますが、手動起動時は十分に待つ必要があります。

# Cassandra 상태 확인
nodetool status

# Cassandra 로그 확인
tail -50 /home/kopens/plantpulse-ai/db/cassandra/logs/*.log

# 키스페이스 재생성 (초기화 필요 시)
cd /home/kopens/plantpulse-ai/db/cassandra/support
./keyspace-create.sh

PostgreSQL 接続失敗

# PostgreSQL 상태 확인
pg_isready -h 127.0.0.1 -p 5432

# PostgreSQL 로그 확인
tail -50 /home/kopens/plantpulse-ai/db/postgres/logs/*.log

# 연결 테스트
psql -h 127.0.0.1 -U ch -d ch -c "SELECT 1"

主な原因:

max_connections 超過 → PostgreSQL 設定で上限を引き上げ
ディスク容量不足 → df -h を確認
PIDファイルの残存 → db/postgres/ 内の .pid ファイルを削除して再起動

Neo4j 起動失敗

# Neo4j 로그 확인
tail -50 /home/kopens/plantpulse-ai/db/neo4j/logs/neo4j.log

# 힙 메모리 부족 시 neo4j.conf 수정
vi /home/kopens/plantpulse-ai/db/neo4j/conf/neo4j.conf
# server.memory.heap.initial_size=512m
# server.memory.heap.max_size=1g

Qdrant 起動失敗

# Qdrant 로그 확인
tail -50 /home/kopens/plantpulse-ai/db/qdrant/logs/*.log

# 초기화 상태 확인
cat /home/kopens/plantpulse-ai/db/.qdrant-initialized

# 헬스 체크
curl http://127.0.0.1:6333/healthz

AI Chat Web の問題

症状: Webページに接続できない

# 웹 서비스 상태 확인
nc -z 127.0.0.1 80 && echo "OK" || echo "DOWN"

# 웹 서비스 로그 확인
tail -50 /home/kopens/plantpulse-ai/web/logs/system.log

# WAR 파일 존재 확인
ls -la /home/kopens/plantpulse-ai/web/app/*.war

症状: チャット応答が返ってこない(SSEストリーミング失敗)

チャットは AI Chat Web の 内蔵エージェント(AgentOrchestrator)が LiteLLM(gpt-4o)を呼び出して実行します。

確認順序:

# 1. LiteLLM 프록시가 실행 중인지 확인
nc -z 127.0.0.1 4000 && echo "OK" || echo "DOWN"

# 2. LiteLLM LLM 응답 확인
curl http://127.0.0.1:4000/health

# 3. 통합 MCP(플랫폼 server-web) 접근 및 api_key 확인
# web/config/application.properties의 mcp.api.url / mcp.api.token 확인

# 4. AI Chat Web 로그 확인
tail -50 /home/kopens/plantpulse-ai/web/logs/system.log

症状: チャート/ダイアグラムがレンダリングされない

ブラウザコンソール(F12)で JavaScript エラーを確認
ECharts/Mermaid ライブラリのロード失敗 → ネットワークタブで CDN へのアクセスを確認
オンプレミス環境で外部 CDN が遮断されている場合 → ローカルライブラリ使用設定が必要

統合 MCP の問題

MCP およびオントロジーツールは PlantPulse プラットフォームの server-web 統合 MCP(/api/v5/mcp)から提供されます。旧独立サービス(mcp-server:50000、ontology:8888)はアーカイブされました。

症状: MCP ツールの呼び出し失敗

# 통합 MCP 도구 목록 조회 (api_key 필요)
curl -X POST <mcp.api.url>/api/v5/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <mcp.api.token>" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# AI Chat Web 로그에서 MCP 호출 오류 확인
tail -50 /home/kopens/plantpulse-ai/web/logs/system.log | grep -i mcp

主な原因:

エラー	原因	対処
Connection refused	プラットフォーム server-web にアクセス不可	`mcp.api.url` を確認、ネットワークを確認
401 Unauthorized	api_key 認証失敗	`mcp.api.token` を確認、トークンを再発行
ツールが表示されない	`tools.enabled` が無効	`mcp.tools.enabled=true` を確認
Timeout	大量データの照会	ページネーションを使用

TimeSeries-Insight の問題

症状: 異常検知 / 予測の失敗

# TimeSeries 헬스 체크
curl http://127.0.0.1:8970/health

# 로그 확인
tail -50 /home/kopens/plantpulse-ai/timeseries/logs/system.log

主な原因:

エラー	原因	対処
No data found	センサーデータなし	`lookback_minutes` を延長
Model loading failed	AIモデルのロード失敗	GPUメモリを確認、CPUモードへ切り替え
Cassandra timeout	時系列DBの応答遅延	Cassandra の状態を確認、`TS_CASS_HOST` を確認
CUDA out of memory	GPUメモリ不足	バッチサイズを縮小、または CPU モードを使用

GPUメモリ不足の場合

# GPU 상태 확인
nvidia-smi

# GPU 메모리 정리 (프로세스 확인 후)
nvidia-smi --query-compute-apps=pid --format=csv,noheader | xargs kill -9

RAG (LightRAG) の問題

RAG エンジンは LightRAG 1.5.4 サーバーです。ドキュメント管理は WebUI(/webui)で行います。

症状: ドキュメント検索結果が返らない

# LightRAG 헬스 체크
curl http://127.0.0.1:7114/health

# Qdrant(벡터 저장소) 확인
curl http://127.0.0.1:6333/collections

# LightRAG 로그 확인
docker logs --tail 50 lightrag

主な原因:

エラー	原因	対処
Empty results	ドキュメント未登録	LightRAG WebUI(`/webui`)でドキュメントをアップロード
Embedding timeout	埋め込みサーバーの応答遅延	LiteLLM/埋め込みの状態を確認
Qdrant connection error	ベクトルDBにアクセス不可	Qdrant のポート(6333)を確認
Reranker error	リランカーモデルの失敗	リランカー設定を無効化して一時的に回避

症状: ドキュメントのインデックス作成失敗

# LightRAG 인덱싱/파싱 로그 확인
docker logs --tail 100 lightrag | grep -i "parse\|docling\|error"

オントロジー(ナレッジグラフ)の問題

備考

オントロジーは独立サービスではなく、プラットフォームの 統合 MCP(/api/v5/mcp)に統合されました。グラフツールのエラーや同期の問題は統合 MCP の問題の手順で診断し、DB↔Neo4j の同期ロジックはプラットフォーム server-web 側を確認してください。

# Neo4j 연결 확인 (LightRAG/온톨로지 그래프 저장소)
curl http://127.0.0.1:7474

# 그래프 통계 조회는 통합 MCP 도구 ontology_get_stats 호출

主な原因:

Neo4j が未起動 → Neo4j を先に起動
統合 MCP にアクセス不可 → mcp.api.url / mcp.api.token を確認

LiteLLM (LLMプロキシ) の問題

症状: AI応答が返ってこない

# LiteLLM 헬스 체크
curl http://127.0.0.1:4000/health

# 모델 목록 확인
curl -H "Authorization: Bearer 설치-시-변경" http://127.0.0.1:4000/v1/models

# 로그 확인
tail -50 /home/kopens/plantpulse-ai/lib/litellm/logs/*.log

主な原因:

エラー	原因	対処
Model not found	モデル設定の誤り	`template/proxy.yaml` を確認
Connection to vLLM failed	推論サーバーにアクセス不可	推論サーバー(192.168.0.240)のネットワークを確認
Rate limit exceeded	リクエスト過多	再試行まで待機、または `num_retries` を調整
API key invalid	認証キーの不一致	`PI_INFERENCE_SERVER_API_KEY` を確認

ディスク容量不足

# 디스크 사용량 확인
df -h

# 큰 파일 찾기
du -sh /home/kopens/plantpulse-ai/*/logs/ | sort -rh

# 로그 및 임시 파일 정리
cd /home/kopens/plantpulse-ai/bin
./clean.sh

# Cassandra 데이터가 큰 경우
du -sh /data1/pp-data/

メモリ不足

# 메모리 사용량 확인
free -h

# 프로세스별 메모리 확인
ps aux --sort=-%mem | head -20

ネットワークの問題

内部サービス間の通信確認

# 전체 포트 스캔
for port in 4000 5432 6333 6379 7114 7687 8970 9001 9042 80; do
  nc -z 127.0.0.1 $port 2>/dev/null && echo "[OK] $port" || echo "[FAIL] $port"
done

PlantPulse IIoT サーバーの接続確認

# IIoT 서버 접근 확인
curl -k https://100.68.69.41:7443/health

# SSL 인증서 확인
openssl s_client -connect 100.68.69.41:7443 -brief

緊急復旧

システム全体の再起動

cd /home/kopens/plantpulse-ai/bin
./stop.sh
sleep 10
./start.sh

特定モジュールのみ再起動

# 예: LightRAG(RAG)만 재시작
docker compose restart lightrag

データを保持したまま初期化

# 1. 전체 종료
./stop.sh

# 2. 로그/캐시만 정리 (데이터는 보존)
./clean.sh

# 3. 재설치 (의존성 재설치)
./setup.sh

# 4. 재시작
./start.sh

警告

/data1/pp-data/ ディレクトリには中核となるデータが保存されています。このディレクトリを削除すると LightRAG のドキュメント/インデックス などがすべて削除されます。削除前に必ずバックアップしてください。

サービス起動失敗​

症状: 特定のサービスが [DOWN] 状態​

症状: システム全体が起動しない​

データベースの問題​

Cassandra の起動が遅い / タイムアウト​

PostgreSQL 接続失敗​

Neo4j 起動失敗​

Qdrant 起動失敗​

AI Chat Web の問題​

症状: Webページに接続できない​

症状: チャット応答が返ってこない(SSEストリーミング失敗)​

症状: チャート/ダイアグラムがレンダリングされない​

統合 MCP の問題​

症状: MCP ツールの呼び出し失敗​

TimeSeries-Insight の問題​

症状: 異常検知 / 予測の失敗​

GPUメモリ不足の場合​

RAG (LightRAG) の問題​

症状: ドキュメント検索結果が返らない​

症状: ドキュメントのインデックス作成失敗​

オントロジー(ナレッジグラフ)の問題​

LiteLLM (LLMプロキシ) の問題​

症状: AI応答が返ってこない​

ディスク容量不足​

メモリ不足​

ネットワークの問題​

内部サービス間の通信確認​

PlantPulse IIoT サーバーの接続確認​

緊急復旧​

システム全体の再起動​

特定モジュールのみ再起動​

データを保持したまま初期化​

サービス起動失敗

症状: 特定のサービスが `[DOWN]` 状態

症状: システム全体が起動しない

データベースの問題

Cassandra の起動が遅い / タイムアウト

PostgreSQL 接続失敗

Neo4j 起動失敗

Qdrant 起動失敗

AI Chat Web の問題

症状: Webページに接続できない

症状: チャット応答が返ってこない(SSEストリーミング失敗)

症状: チャート/ダイアグラムがレンダリングされない

統合 MCP の問題

症状: MCP ツールの呼び出し失敗

TimeSeries-Insight の問題

症状: 異常検知 / 予測の失敗

GPUメモリ不足の場合

RAG (LightRAG) の問題

症状: ドキュメント検索結果が返らない

症状: ドキュメントのインデックス作成失敗

オントロジー(ナレッジグラフ)の問題

LiteLLM (LLMプロキシ) の問題

症状: AI応答が返ってこない

ディスク容量不足

メモリ不足

ネットワークの問題

内部サービス間の通信確認

PlantPulse IIoT サーバーの接続確認

緊急復旧

システム全体の再起動

特定モジュールのみ再起動

データを保持したまま初期化