Zum Hauptinhalt springen

Leitfaden zur Fehlerbehebung

Dienst startet nicht​

Symptom: Bestimmter Dienst im Status [DOWN]​

./status.sh

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

Ursachen und Abhilfe:

UrsacheAbhilfe
Vorheriger Prozess läuft nochPID-Datei prüfen und Prozess beenden
PortkonfliktBelegenden Prozess mit ss -tlnp | grep <port> ermitteln
Abhängiger Dienst nicht gestartetDB muss zuerst starten (Startreihenfolge prüfen)
Datenträger vollDatenträger mit df -h prüfen, dann ./clean.sh ausführen
# 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

Symptom: Gesamtes System startet nicht​

Prüfreihenfolge:

# 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

Datenbankprobleme​

Cassandra startet langsam / Timeout​

Cassandra benötigt 20–60 Sekunden zum Start. start.sh wartet automatisch; beim manuellen Start ist ausreichend Wartezeit einzuplanen.

# 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-Verbindung schlägt fehl​

# 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"

Hauptursachen:

  • max_connections überschritten → in der PostgreSQL-Konfiguration erhöhen
  • Zu wenig Speicherplatz → df -h prüfen
  • PID-Datei vorhanden → Datei .pid in db/postgres/ löschen und neu starten

Neo4j startet nicht​

# 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 startet nicht​

# 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

Probleme mit AI Chat Web​

Symptom: Webseite nicht erreichbar​

# 웹 서비스 상태 확인
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

Symptom: Keine Chat-Antwort (SSE-Streaming schlägt fehl)​

Der Chat wird vom integrierten Agenten von AI Chat Web (AgentOrchestrator) ausgeführt, der LiteLLM (gpt-4o) aufruft.

Prüfreihenfolge:

# 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

Symptom: Diagramme werden nicht gerendert​

  • JavaScript-Fehler in der Browser-Konsole (F12) prüfen
  • ECharts/Mermaid-Bibliothek nicht geladen → CDN-Zugriff im Netzwerk-Tab prüfen
  • Bei blockiertem externem CDN in On-Premise-Umgebungen → Nutzung lokaler Bibliotheken konfigurieren

Probleme mit dem integrierten MCP​

MCP- und Ontologie-Werkzeuge werden vom integrierten MCP der server-web der PlantPulse Platform (/api/v5/mcp) bereitgestellt. Die früheren eigenständigen Dienste (mcp-server:50000, ontology:8888) wurden archiviert.

Symptom: Aufruf eines MCP-Werkzeugs schlägt fehl​

# 통합 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

Hauptursachen:

FehlerUrsacheAbhilfe
Connection refusedPlatform server-web nicht erreichbarmcp.api.url prüfen, Netzwerk prüfen
401 Unauthorizedapi_key-Authentifizierung fehlgeschlagenmcp.api.token prüfen, Token neu ausstellen
Werkzeug wird nicht angezeigttools.enabled deaktiviertmcp.tools.enabled=true prüfen
TimeoutAbfrage großer DatenmengenPaginierung verwenden

Probleme mit TimeSeries-Insight​

Symptom: Anomalieerkennung / Prognose schlägt fehl​

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

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

Hauptursachen:

FehlerUrsacheAbhilfe
No data foundKeine Sensordatenlookback_minutes erhöhen
Model loading failedKI-Modell konnte nicht geladen werdenGPU-Speicher prüfen, in CPU-Modus wechseln
Cassandra timeoutVerzögerte Antwort der Zeitreihen-DBCassandra-Status prüfen, TS_CASS_HOST prüfen
CUDA out of memoryZu wenig GPU-SpeicherBatchgröße verringern oder CPU-Modus verwenden

Bei zu wenig GPU-Speicher​

# GPU 상태 확인
nvidia-smi

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

Probleme mit RAG (LightRAG)​

Die RAG-Engine ist ein LightRAG-1.5.4-Server. Die Dokumentenverwaltung erfolgt über die WebUI (/webui).

Symptom: Keine Suchergebnisse in Dokumenten​

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

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

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

Hauptursachen:

FehlerUrsacheAbhilfe
Empty resultsKeine Dokumente registriertDokumente in der LightRAG WebUI (/webui) hochladen
Embedding timeoutVerzögerte Antwort des Embedding-ServersStatus von LiteLLM/Embedding prüfen
Qdrant connection errorVektor-DB nicht erreichbarQdrant-Port (6333) prüfen
Reranker errorReranker-Modell fehlgeschlagenReranker-Konfiguration vorübergehend deaktivieren

Symptom: Dokumentenindizierung schlägt fehl​

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

Probleme mit der Ontologie (Wissensgraph)​

info

Die Ontologie ist kein eigenständiger Dienst mehr, sondern im integrierten MCP der Platform (/api/v5/mcp) aufgegangen. Fehler bei Graph-Werkzeugen oder Synchronisationsprobleme werden nach dem Verfahren Probleme mit dem integrierten MCP diagnostiziert; die Synchronisationslogik DB↔Neo4j ist auf Seiten der Platform server-web zu prüfen.

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

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

Hauptursachen:

  • Neo4j nicht gestartet → Neo4j zuerst starten
  • Integriertes MCP nicht erreichbar → mcp.api.url / mcp.api.token prüfen

Probleme mit LiteLLM (LLM-Proxy)​

Symptom: Keine KI-Antwort​

# 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

Hauptursachen:

FehlerUrsacheAbhilfe
Model not foundFehlerhafte Modellkonfigurationtemplate/proxy.yaml prüfen
Connection to vLLM failedInferenzserver nicht erreichbarNetzwerk zum Inferenzserver (192.168.0.240) prüfen
Rate limit exceededZu viele AnfragenWiederholung abwarten oder num_retries anpassen
API key invalidSchlüssel stimmt nicht übereinPI_INFERENCE_SERVER_API_KEY prüfen

Zu wenig Speicherplatz​

# 디스크 사용량 확인
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/

Zu wenig Arbeitsspeicher​

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

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

Netzwerkprobleme​

Kommunikation zwischen internen Diensten prüfen​

# 전체 포트 스캔
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

Verbindung zum PlantPulse-IIoT-Server prüfen​

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

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

Notfallwiederherstellung​

Gesamtes System neu starten​

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

Nur bestimmtes Modul neu starten​

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

Zurücksetzen unter Beibehaltung der Daten​

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

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

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

# 4. 재시작
./start.sh
warnung

Im Verzeichnis /data1/pp-data/ sind zentrale Daten gespeichert. Beim Löschen dieses Verzeichnisses gehen unter anderem sämtliche LightRAG-Dokumente/-Indizes verloren. Vor dem Löschen unbedingt eine Sicherung erstellen.