본문으로 건너뛰기

트러블슈팅 가이드

서비스 시작 실패​

증상: 특정 서비스가 [DOWN] 상태​

./status.sh

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

원인 및 해결:

원인해결 방법
이전 프로세스가 남아있음PID 파일 확인 후 프로세스 종료
포트 충돌ss -tlnp | grep <포트> 로 점유 프로세스 확인
의존 서비스 미시작DB가 먼저 시작되어야 함 (시작 순서 확인)
디스크 풀df -h로 디스크 확인 후 ./clean.sh 실행
# PID 파일로 프로세스 확인
cat /home/kopens/plantpulse-ai/<모듈>/*.pid
kill -9 <PID>
rm /home/kopens/plantpulse-ai/<모듈>/*.pid

# 모듈 재시작
cd /home/kopens/plantpulse-ai/<모듈>/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 문제​

증상: 웹 페이지 접속 안 됨​

# 웹 서비스 상태 확인
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 Unauthorizedapi_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 failedAI 모델 로드 실패GPU 메모리 확인, CPU 모드 전환
Cassandra timeout시계열 DB 응답 지연Cassandra 상태 확인, TS_CASS_HOST 확인
CUDA out of memoryGPU 메모리 부족배치 크기 줄이기 또는 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 문서/인덱스 등이 모두 삭제됩니다. 삭제 전 반드시 백업하세요.