诊断与巡检
用于怀疑发生故障/异常运行时的诊断脚本集。
2026.05+ 容器模式以 pe-doctor 为标准
以下流程适用于原生盒子（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)
详情：容器模式运维。
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-app.sh # 1차: 앱(Tomcat)만 — 30~90초
# 그래도 이상 시
$PE_HOME/bin/restart.sh # 2차: 전체 스택 (stop + start 를 한 프로세스로)
# 그래도 이상 시
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 或对应子组件的 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 客户端端口处于监听状态 |
Heap > 80% | OOM 临近 — 清理数据/加大堆内存 |
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 连接 | 偶尔出现的启动竞争问题。再次调用一次 restart.sh |
clean.sh 后 ssh 会话突然断开 | /tmp/* 同时清除了 ssh socket — 通过其他会话重新连接 |
upgrade.sh 过程中下载失败 | 检查外部网络 / product.kopens.io。network-speed-test.sh |
start.sh 停滞过久（[4] DB START） | Cassandra commitlog 回收 — 通常需等待 30 秒以上。若仍未结束，检查 db/logs/system.log |
| Tomcat 频繁崩溃 | 可能存在 OOM — 检查 server/logs/catalina.out 的 OutOfMemoryError / heapdump 目录 |
| Node-RED 在 Deploy 后消失 | userDir 损坏。设计为可通过 $PE_HOME/node/conf 的主副本恢复 — node/bin/start.sh 会自动同步 |
| 从外部无法访问网关 | 防火墙（firewall-cmd --list-all 或 iptables -L）/ SELinux 策略 / 路由器 NAT 检查 |
9. 了解更多
- 磁盘不足时：清理与维护
- 分阶段故障诊断场景：运维场景
- 监控（REST 指标）：监控（运维/REST）