故障排查

本文档介绍在通过一键式安装 / Docker 安装方式运行的 PlantPulse 平台中经常出现的问题及其解决方法。大部分问题按照下列步骤依次排查即可解决。

容器共有九个

本平台以 Docker Compose 堆栈的形式运行 —— 一个证书一次性容器（plantpulse-certs、Exited (0) 属正常），一个数据湖，六个应用，一个代理。不存在名为 plantpulse-platform 的容器。

请先缩小「到底是哪里出了故障」。./status.sh 会按服务分别回答 → 安装后的形态

第一步：无论遇到什么问题，请先确认以下 3 项。

cd /opt/kopens/plantpulse-platform-docker/bin
./status.sh                                          # 容器 / health / 卷 概要
./ops-check.sh                                       # 运行 health + critical log
./logs.sh -n 200                                   # 最近的容器日志（全部）

如果仍未解决，请用 ./doctor.sh 生成诊断 tarball 并转交给技术支持团队。

容器启动问题

症状：容器停留在 `unhealthy` 状态无法恢复

原因	解决方法
Cassandra 模式迁移失败	用 `./logs.sh cassandra -n 300` 确认错误后重试 `./restart.sh`。反复失败时 `./doctor.sh`
数据目录权限问题	确认主机上的 `/data1/pp-data` 权限。`sudo chown -R root:root /data1/pp-data && sudo chmod -R 755 /data1/pp-data`
内存不足（OOMKilled）	用 `docker inspect <컨테이너> --format '{{.State.OOMKilled}}'` 确认。每个容器的限制值不同 —— 数据湖为 `DOCKER_DATALAKE_MEMORY`，应用为 `DOCKER_SERVER_MEMORY` 等（环境变量）
JVM warm-up 未完成	启动需要 3~5 分钟。若 unhealthy 持续超过 5 分钟，请进行下一步诊断

# 어떤 서비스가 비정상인가 (0 = 정상 / 2 = 비정상)
./status.sh

# 스택 전체 준비 판정
./stack-verify-boot.sh

# 컨테이너별 메모리 / CPU
docker stats --no-stream

# 헬스체크 엔드포인트 응답 확인
curl -kfsS https://<server-ip>:4950/api/health | jq

一次性容器不是「已死的容器」

plantpulse-certs 会生成证书后自行结束，因此 Exited (0) 才是成功状态。由于 compose 明确关闭了该容器的健康检查（healthcheck: disable），health 一栏为空，正常运行的容器也不会被误判为 unhealthy。status.sh 和 ops-check.sh 唯独对这个容器以退出码来判断，手动查看时也请这样判断。

症状：显示 `no such service` · 找不到容器

说明最初的安装尚未完成，或容器已被 ./remove.sh 删除。

如果您是按照旧版运维手册在寻找 plantpulse-platform，不存在该名称的容器 —— 请以 ./status.sh 或 ./logs.sh --list 确认名称。

cd /opt/kopens/plantpulse-platform-docker/bin
./install.sh                                         # 최초 설치
# 또는 OS 설정이 이미 끝났다면
./up.sh                                    # 컨테이너 생성 + 기동

症状：`address already in use`（端口冲突）

主机上以前版本的 plantpulse 仍以 native 方式运行，或其他服务占用了该端口。

# 호스트 native plantpulse 정지
pkill -ef plantpulse

# 특정 포트 점유 프로세스 확인 (예: 7500)
ss -tlnp | grep :7500

# 충돌 프로세스를 종료한 후 재시도
./restart.sh

详细端口列表请参见端口及服务管理页面。

镜像 / 仓库问题

症状：`docker pull` → `unauthorized: authentication required`

镜像仓库认证已过期或缺少凭据。

docker login docker.kopens.io
# Username/Password 입력 후
./update.sh

症状：镜像下载失败（网络）

# 1. 레지스트리 접근 가능 여부 확인
curl -fsSL https://docker.kopens.io/v2/

# 2. DNS 확인
nslookup docker.kopens.io

# 3. 회사 방화벽 / 프록시 차단 가능성 — 네트워크 관리자에게 다음 도메인 허용 요청
#    docker.kopens.io, download.kopens.io

如果处于隔离网络环境，请按照 Docker 安装页面中的隔离网络（Airgap）安装步骤操作。

数据库问题

数据库组件在容器内部运行。请通过 ./shell.sh 进入容器后再进行巡检。

PostgreSQL（元数据 DB）

作用：保存用户信息、站点设置、资产设置等平台元数据。

./shell.sh                                   # 컨테이너 진입

# 컨테이너 내부에서
/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd node psql         # PostgreSQL 셸 접속
psql=# SELECT 1;
psql=# SHOW max_connections;
psql=# SELECT count(*) FROM pg_stat_activity;

症状	原因	解决方法
Connection refused	PostgreSQL 组件宕机	在容器内部执行 `pd restart storage`。在主机上执行 `./restart.sh`
Too many connections	连接池超限	检查 `properties` 中的 connection pool 设置。若为暂时性问题，重启 storage
Authentication failed	密码不一致	确认 `/etc/kopens/plantpulse-platform.env` 中的 `PP_PG_PASSWORD` 与应用 properties 是否一致

路径确认 —— 密钥 sidecar 的正本只有一份 /etc/kopens/plantpulse-platform.env（权限 0600）。旧版安装中 /opt/kopens/ 下可能仍留有同名文件，但不会被读取，安装脚本会将其恢复为正本 → 环境变量参考

Cassandra（时序 DB）

作用：保存传感器时序数据、报警历史等大量数据。

./shell.sh

# 컨테이너 내부에서
/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd node status       # 클러스터 상태
/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd node compactionstats  # 컴팩션 진행 상태
/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd node cql          # CQL 셸 접속

症状	原因	解决方法
Connection timeout	节点宕机	用 `pd node status` 确认节点状态后 `pd restart storage`
WriteTimeout	写入延迟（磁盘 I/O 饱和）	确认 `pd node compactionstats`，用 `pd node compact` 手动 compaction
ReadTimeout	读取延迟（分区过大）	用 `pd node table-histograms` 确认分区大小
磁盘空间不足	SSTable 累积	执行 `pd node cleanup` 后用 `df -h /data1` 确认

Valkey（Redis 缓存）

./shell.sh

# 컨테이너 내부에서
redis-cli -a "$PP_REDIS_PASSWORD" ping
redis-cli -a "$PP_REDIS_PASSWORD" INFO memory

登录 / 控制台访问问题

症状：浏览器无法访问控制台

# 1. 컨테이너 health 확인
./status.sh

# 2. 외부 노출 IP 설정 확인
grep DOCKER_PP_EXTERNAL_IP env.sh

# 3. 호스트 방화벽 확인
sudo firewall-cmd --list-ports                       # RHEL/Rocky/Oracle
sudo ufw status                                      # Ubuntu

# 4. 포트 점유 확인 — 프록시가 80/443 을, 데이터레이크가 7443 을 엽니다
ss -tlnp | grep -E ':(80|443|7443)\s'

症状	原因	解决方法
页面无法打开	`plantpulse-proxy` 异常	用 `./status.sh` 确认代理状态。代理是接收 80/443 的唯一入口
页面无法打开	防火墙拦截	请求企业/云端防火墙放行 80、443、7443、4950
登录失败	密码不一致	确认默认 `admin / admin123!`。若已更改，请联系管理员重置
403 Forbidden	用户权限不足	请管理员确认角色（role）
会话过期	30 分钟无操作自动登出	重新登录

数据采集问题

数据采集路径：OPC 服务器 → 消息代理（Kafka/MQTT）→ 引擎流水线 → Cassandra。该路径中任一环节受阻，数据都无法进入。

症状：未采集到数据

检查项	确认方法
OPC 连接状态	在网页控制台 > 连接管理 > 状态中确认 `CONNECTED`
引擎状态	在控制台 > 监控 > 系统状态中确认 `RUNNING`
流水线	MPS（每秒消息数）为 0 表示接收中断
消息代理	进入 `./shell.sh` 后用 `/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd node topic` 确认 Kafka 主题
网络	从 OPC 服务器向平台主机 IP 执行 ping / telnet

症状：数据延迟

原因	解决方法
流水线队列积压	上调 properties 中的 `engine.pipeline.threads`
Cassandra 写入延迟	确认 `pd node compactionstats`，监控磁盘 I/O
Kafka lag	用 `pd node topic` 确认 consumer lag
网络延迟	测量 OPC 服务器 ↔ 平台主机的 RTT

性能问题

症状：控制台 / API 响应缓慢

# 호스트에서 컨테이너 자원 사용량
docker stats --no-stream

# 앱 컨테이너의 JVM 메모리 (그 앱이 도는 컨테이너 안에서)
./shell.sh plantpulse-server-web
jmap -heap $(pgrep -f plantpulse-server)

请先确定是哪个容器

六个应用分别在各自的容器中运行，因此在数据湖内查找应用进程是找不到的。请先用 ./status.sh 确认目标容器，再进入 ./shell.sh <컨테이너>。

原因	解决方法
容器内存不足	上调该容器的限制值后 `./restart.sh` —— 数据湖为 `DOCKER_DATALAKE_MEMORY`，应用为 `DOCKER_SERVER_MEMORY` 等（环境变量）
JVM 内存不足	调整容器内部 setenv 的堆大小（详情参见性能调优）
GC 频繁	分析 GC 日志，调优 G1GC 选项
DB 慢查询	确认 PostgreSQL slow query 日志
主机 CPU 饱和	确认 `top` / `htop` 后考虑上调 `DOCKER_PP_CPUS`

症状：OutOfMemoryError

# 컨테이너 내부에서 heap dump 활성화
./shell.sh
# setenv 또는 JAVA_TOOL_OPTIONS 에 -XX:+HeapDumpOnOutOfMemoryError 추가

# 생성된 hprof 를 호스트로 복사
docker cp plantpulse-datalake:/path/to/heap.hprof /tmp/

用 Eclipse MAT / VisualVM 进行分析。

报警问题

症状	原因	解决方法
未产生报警	报警设置未部署	在报警设置界面点击“部署”
报警重复产生	重复检查未启用	在报警设置中启用重复检查
邮件通知未发送	SMTP 设置错误	确认 `mail.properties`（容器内部 `/opt/kopens/plantpulse-platform/plantpulse-server/config/`）
通知声音不响	浏览器自动播放策略	在浏览器设置中允许该网站自动播放

UI 问题

症状	解决方法
界面显示异常	清除浏览器缓存（Ctrl+Shift+Delete）
图表未显示	在浏览器开发者工具（F12）> Console 中确认 JS 错误
实时刷新中断	确认代理/防火墙的 SSE（HTTP 流式传输）缓冲、超时设置
仪表盘加载失败	确认是否存在已连接的标签 / 数据源
韩文乱码	确认 `env.sh` 的 `PP_LANG=ko`、`PP_TZ=Asia/Seoul` 后 `./restart.sh`

磁盘 / 卷问题

症状：磁盘空间不足

# 호스트 디스크 사용량
df -h
df -h /data1                                         # 데이터 디스크

# Docker 사용량 (이미지 / 볼륨 / 빌드 캐시)
docker system df

# 컨테이너 내부 사용량
./shell.sh
df -h
du -sh /opt/kopens/plantpulse-platform/plantpulse-storage/db/cassandra/data

原因	解决方法
旧备份累积	清理 `/data1/pp-backup/docker-volume` 中的旧 tar.gz
Docker 未使用镜像	用 `docker system prune` 清理（镜像/网络/缓存）
Cassandra SSTable 累积	在容器内部执行 `pd node cleanup`、`pd node compact`
日志目录膨胀	清理 `/opt/kopens/plantpulse-platform-docker/logs`

注意：docker volume prune 会删除所有未使用中的卷。为避免误删 pp-* 卷，请勿让容器处于停止状态。

症状：需要恢复卷数据

请参见运营管理 - 备份与恢复页面中的恢复步骤。

更新 / 回滚问题

症状：更新后容器无法正常运行

./update.sh 在 health 验证失败时会自动 rollback 到之前的镜像。如需手动 rollback：

# 1. 이전 버전 태그를 env.sh 에 지정
vi env.sh
#   PP_IMAGE_TAG="2026.04"   ← 이전 안정 버전

# 2. 업데이트 재실행
./update.sh

症状：更新过程中出现 `NOT FOUND CONTAINER`

说明尚未完成最初安装（./install.sh）。请先执行安装。

网络 / 集群问题

症状：worker 未能 join 到 master

# 1. 워커 컨테이너 진입 (워커는 기본 스택의 서비스가 아니라 shell.sh 로는 잡히지 않습니다)
docker exec -ti plantpulse-worker-1 /bin/bash
# 워커 내부에서 마스터 IP 로 연결 테스트
ping ${PP_MASTER_IP}

# 2. 마스터에서 링 확인 — 이것이 조인의 «유일한» 증거입니다
cd /opt/kopens/plantpulse-platform-docker/bin
./shell.sh
/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd node status

# 3. JGroups / Cassandra 포트 (7000, 7001, 7800, 7801, 9042) 방화벽 허용 확인

容器处于运行状态并不代表已加入集群

join 失败的 worker 和成功的 worker 一样会报告为正常 —— 因为容器自身的检查只确认「是否能连通 master」。2026-08-31 的实测中，一个因 Cassandra 被 OOMKilled 的 worker，其 ring 仍只有 1 个节点，却持续保持 health: starting。

必须以 pd node status 的 ring 列表为准进行判定。新增 worker 时 bin/worker-add.sh 会替你完成这项确认 → 集群安装

症状：MQTT / Kafka 外部客户端连接失败

请确认主机防火墙及企业/云端防火墙已放行 1883/1884（MQTT）、9092/9093/9094（Kafka）。详细端口列表请参见端口配置信息。

MQTT 由 plantpulse-proxy 接收。 设备只需知道这个主机名即可，即使代理迁移或改名，也无需修改设备设置。1884 为 TLS passthrough，由代理来终结 TLS。
Kafka 不经过代理。 因为客户端在 bootstrap 之后会用 advertised.listeners 地址重新连接 —— 如果只有 bootstrap 成功而之后悄然失败，请优先怀疑这个地址。

紧急应对

容器无响应时

cd /opt/kopens/plantpulse-platform-docker/bin

# 1. 상태 확인
docker ps -a
./status.sh

# 2. 로그에서 마지막 에러 확인
./logs.sh -n 200

# 3. 안전 재시작
./restart.sh

# 4. 위 단계로 회복 안 될 경우 진단 tarball 생성
./doctor.sh
# 생성된 tarball 을 webmaster@kopens.com 으로 전달

疑似数据损坏时

# 1. 즉시 정지 (추가 손상 방지)
./down.sh

# 2. 최신 백업 확인
ls -lh /data1/pp-backup/docker-volume/

# 3. 진단 tarball 생성 (절대 데이터를 임의로 수정하지 마세요)
./doctor.sh

# 4. 기술 지원팀 연락

数据损坏时的禁止事项：请勿自行执行 pd node repair、pd node cleanup、删除 SSTable 等操作。错误的恢复操作可能扩大损坏范围。请务必与技术支持团队协商后再进行处理。

请求支持时所需的信息

若上述方法仍无法解决，请附带以下信息一并发送，以便快速分析。

项目	收集方法
诊断 tarball	执行 `./doctor.sh` 后生成的文件
容器日志	`./logs.sh -n 500 > /tmp/container.log 2>&1`（全部八个容器）
各模块日志	`./tools/copy-log-to-local.sh` 的结果（`/tmp/plantpulse-log/`）
镜像版本	`./stack-version.sh` 输出
环境变量	`env.sh`（密码需打码）
系统信息	OS、CPU、内存、磁盘（`uname -a`、`free -h`、`df -h`）
错误信息	准确的错误信息 / 浏览器控制台（F12）截图
复现步骤	问题发生前所执行的操作顺序

技术支持：webmaster@kopens.com

容器启动问题​

症状：容器停留在 unhealthy 状态无法恢复​

症状：显示 no such service · 找不到容器​

症状：address already in use（端口冲突）​

镜像 / 仓库问题​

症状：docker pull → unauthorized: authentication required​

症状：镜像下载失败（网络）​

数据库问题​

PostgreSQL（元数据 DB）​

Cassandra（时序 DB）​

Valkey（Redis 缓存）​

登录 / 控制台访问问题​

症状：浏览器无法访问控制台​

数据采集问题​

症状：未采集到数据​

症状：数据延迟​

性能问题​

症状：控制台 / API 响应缓慢​

症状：OutOfMemoryError​

报警问题​

UI 问题​

磁盘 / 卷问题​

症状：磁盘空间不足​

症状：需要恢复卷数据​

更新 / 回滚问题​

症状：更新后容器无法正常运行​

症状：更新过程中出现 NOT FOUND CONTAINER​

网络 / 集群问题​

症状：worker 未能 join 到 master​

症状：MQTT / Kafka 外部客户端连接失败​

紧急应对​

容器无响应时​

疑似数据损坏时​

请求支持时所需的信息​

相关文档​