诊断 / 巡检
怀疑发生故障 / 异常动作时使用的诊断脚本合集。
2026.05+ 容器模式以 pe-doctor 为标准
以下步骤适用于 native 主机（bin/ps.sh、bin/log-viewer.sh）。容器模式：
bash /opt/kopens/install/bin/status.sh # 한 줄 상태
bash /opt/kopens/install/bin/health.sh # 종합 헬스 (exit 0/1)
bash /opt/kopens/install/bin/logs.sh -f tomcat # 로그 follow
sudo bash /opt/kopens/install/bin/doctor.sh # 진단 일괄 tarball (support escalation)
详情：容器模式运维指南 + /opt/kopens/install/RUNBOOK.md。
1. 分步诊断流程
# 1. 누가 죽었나?
$PE_HOME/bin/ps.sh
# 2. 어디가 시끄러운가?
$PE_HOME/bin/log-viewer.sh
# (실시간 — Ctrl+C 로 빠져나옴)
# 3. Cassandra 의심
$PE_HOME/bin/node-info.sh
# 4. Disk 의심
df -h /data1
du -sh $PE_HOME/*/log/* /data1/* 2>/dev/null | sort -h | tail -20
# 5. 다 안 맞으면 — 안전하게 단계적 재시작
$PE_HOME/bin/restart.sh # 1차: Tomcat 만
# 그래도 이상 시
$PE_HOME/bin/stop.sh
$PE_HOME/bin/start.sh # 2차: 전체
# 그래도 이상 시
sudo $PE_HOME/bin/reboot.sh # 3차: OS 재부팅 (최후의 수단)
2. 注意 — 非交互式 shell 中禁止调用 log-viewer.sh
log-viewer.sh 是无限 tail -f。在 CI / cron 之类的非交互式环境 中调用会导致 ssh 会话无法结束。请仅在 交互式 shell 中使用。
3. log-viewer.sh — 集成日志 tail
$PE_HOME/bin/log-viewer.sh
在同一屏幕上实时查看 7 类日志：
- Tomcat (
server/logs/catalina.out) - timeseries-engine
- Cassandra (
db/logs/system.log) - HiveMQ (
mqtt/log/hivemq.log) - Node-RED (
node/log/node-red.log) - Redis cache
- 其他
用 Ctrl+C 退出。发生故障时 最先执行 的工具。
4. ps.sh
$PE_HOME/bin/ps.sh
按 plantpulse 关键字列出存活的 Java 进程。正常状态下应能看到以下全部条目：
| 进程 | 含义 | PID 环境变量 |
|---|---|---|
apache.cassandra.service.CassandraDaemon | Cassandra | cassandra.pid |
hivemq.jar | MQTT | （无） |
plantpulse.timeseries.engine.Main | 时序引擎 | （无） |
org.apache.catalina.startup.Bootstrap | Tomcat | CATALINA_PID |
node-red (Node.js) | Node-RED | （无） |
若有缺失，说明该组件已停止 — 用 start.sh 或对应 sub-component 的 bin/start.sh 重新启动。
5. node-info.sh — Cassandra 状态
$PE_HOME/bin/node-info.sh
典型输出（nodetool info）：
ID : 8a4d...
Gossip active : true
Native Transport active: true
Load : 1.21 GiB
Generation No : 1778176430
Uptime (seconds) : 1234
Heap Memory (MB) : 824.10 / 2048.00
| 检查点 | 含义 |
|---|---|
Native Transport active : true | 9042 客户端端口处于 listen 状态 |
Heap > 80% | 接近 OOM — 清理数据 / 增大 heap |
Load 超过磁盘的 80% | 清理 sstable（node-cleanup.sh）或扩容磁盘 |
6. node-cql.sh — cqlsh 交互式
$PE_HOME/bin/node-cql.sh
会自动执行 cqlsh -u cassandra -p ... 并连接到 keyspace pe。用于 手动数据巡检 — 不建议在运行中直接执行 INSERT/UPDATE（缓存未刷新、副本不一致等）。
常用查询示例：
USE pe;
SELECT count(*) FROM app_tag;
SELECT opc_id, opc_type FROM app_opc;
DESCRIBE TABLE app_tag;
7. network-speed-test.sh
$PE_HOME/bin/network-speed-test.sh
从 product.kopens.io 获取 speedtest.py 并执行，以测量外网速度。线路慢时，升级 也会变慢 — 用于升级前诊断。
8. 常见陷阱 — 汇总
| 症状 | 原因 / 解决 |
|---|---|
restart.sh 之后 OPC 连接为 0/N | 极少出现的启动 race。再调用一次 restart.sh |
clean.sh 之后 ssh 会话突然断开 | /tmp/* 连 ssh socket 一起清除了 — 用其他会话重新连接 |
upgrade.sh 过程中下载失败 | 检查外网 / product.kopens.io。network-speed-test.sh |
start.sh 停顿过久（[4] DB START） | Cassandra commitlog 回收 — 通常需等待 30s 以上。若仍未结束，请确认 db/logs/system.log |
| 只有 Tomcat 反复停止 | 可能是 OOM — 检查 server/logs/catalina.out 的 OutOfMemoryError / heapdump 目录 |
| Node-RED 在 Deploy 后消失 | userDir 损坏。设计上会从 $PE_HOME/node/conf 的 master 副本恢复 — node/bin/start.sh 会自动 sync |
| 无法从外部连接网关 | 检查防火墙（firewall-cmd --list-all 或 iptables -L）/ SELinux 策略 / 路由器 NAT |
9. 延伸阅读
- 磁盘不足时：整理 / 清理
- 分步故障诊断场景：运维场景
- 监控（REST 指标）：监控（运维人员/REST）