故障排查指南
服务启动失败
症状：特定服务处于 [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 问题
症状：无法访问网页
# 웹 서비스 상태 확인
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 及本体（Ontology）工具由 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 文档/索引等全部丢失。删除前务必备份。