问题解决

本文件提供了在通过 One-liner / Docker 安装运行的 PlantPulse Platform 中常见的问题及其解决方法。大多数问题可以通过按顺序执行以下步骤来解决。

共有九个容器

Platform 以 Docker Compose 栈形式运行 — 一个证书容器(plantpulse-certs)、一个数据湖、六个应用、一个代理。九个容器均应常驻运行且 (healthy) 状态正常。不存在名为 plantpulse-platform 的容器。

请先缩小「哪里出故障」的范围。./status.sh 会按服务提供响应 → 安装形态

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

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

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

容器启动问题

症状：容器无法从 `unhealthy` 状态恢复

原因	解决
Aster TSDB 模式迁移失败	通过 `./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 预热未完成	启动需要 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 在生成一次证书后持续运行并监控过期情况。(healthy) 为正常状态。健康检查并非查看进程是否存活，而是查看卷中的素材是否可用 — 包括确认距离过期剩余时间以及密钥库是否能打开。

症状：`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

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

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

详细端口列表请参考端口与服务管理页面。

镜像 / 仓库问题

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

仓库认证已过期或缺乏凭证。

docker login docker.kopens.io
# Username/Password 입력 후, 하던 설치 · 업그레이드 원라이너를 다시 실행

症状：镜像下载失败 (网络)

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

角色：存储用户信息、站点设置、资产设置等 Platform 元数据。

./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 是否一致

路径确认 — Secret Sidecar 的正本只有一个 /etc/kopens/plantpulse-platform.env (权限 0600)。旧安装中 /opt/kopens/ 下可能残留同名文件，但不会被读取，安装脚本会将其还原为正本 → 环境变量参考

Aster TSDB (时序 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 을 엽니다
ss -tlnp | grep -E ':(80|443)\s'

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

数据采集问题

数据采集路径：OPC 服务器 → 消息代理 (Kafka/MQTT) → 引擎流水线 → Aster TSDB。该路径中任何一环受阻，数据均无法进入。

症状：数据未采集

巡检项目	确认方法
OPC 连接状态	Web 控制台 > 连接管理 > 状态中确认 `CONNECTED`
引擎状态	控制台 > 监控 > 系统状态中确认 `RUNNING`
流水线	若 MPS (每秒消息数) 为 0，则接收停止
消息代理	进入 `./shell.sh` 后通过 `/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd node topic` 确认 Kafka Topic
网络	OPC 服务器 → Platform 主机 IP ping / telnet

症状：数据延迟

原因	解决
流水线队列积压	调高 properties 中的 `engine.pipeline.threads`
Aster TSDB 写入延迟	确认 `pd node compactionstats`, 监控磁盘 I/O
Kafka lag	通过 `pd node topic` 确认 consumer lag
网络延迟	测量 OPC 服务器 ↔ Platform 主机 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 进行分析。

报警问题

症状	原因	解决
未产生报警	报警设置为解除状态	报警 > 高级报警中勾选 → 选定报警设置部署
数值已超限但报警不在列表中	暂时隐藏 · 计划维护或维修抑制 · 排除服务	确认隐藏 · 抑制 · 排除服务。隐藏的发生可通过 `GET /api/v5/alarm/suppressed` 查看
报警推送重复发送	抑制时间为 0	报警设置 → 重复报警抑制 → 抑制时间 (分)
恢复被拒绝	恢复巡检失败 (数值不在正常范围内或 10 分钟内无数值)	确认数值后重新恢复，或填写原因后点击强制恢复
陈述保存被拒绝	缺少按种类划分的必填输出项	按种类必填项
报警设置创建 422 (API)	使用自定义 ID	使用通过 `GET /api/v5/alarm/config/new-id` 接收的 ID
电子邮件通知未发送	SMTP 设置错误	确认 `mail.properties` (容器内部 `/opt/kopens/plantpulse-platform/plantpulse-server/config/`)
通知无声音	浏览器自动播放政策	在浏览器设置中允许站点自动播放

UI 问题

症状	解决
画面崩溃	删除浏览器缓存 (Ctrl+Shift+Delete)
图表未显示	浏览器开发者工具 (F12) > Console 中确认 JS 错误
实时更新中断	确认代理/防火墙的 SSE (HTTP Streaming) 缓冲 · 超时设置
仪表板加载失败	确认所连接标签 / 数据源是否存在
韩文乱码	确认 `env.sh` 的 `PP_LANG=ko`, `PP_TZ=Asia/Seoul` 后执行 `./restart.sh`

对象存储 (RustFS) 问题

日志中不断出现 `AccessDenied`

[RUSTFS] level=ERROR op=GetObject err=S3Error(code: AccessDenied, message: "Access Denied")

这不是凭证问题。 管理 API 的指标采集器每 2 秒调用一次旧的 MinIO 指标路径 (/minio/v2/metrics/cluster)，但 RustFS 中没有该路径，请求掉落到 S3 路由。此时被识别为桶名为 minio 的查询，由于采集器未附加签名，导致请求变为匿名请求而被拒绝。

问题	回答
数据是否有风险	没有。仅是一次读取尝试被拒绝，与存储内容无关
修改密码能解决吗	不能 — 这不是运维人员可处理的范围。发送请求的是未附加签名的采集器，即使使其签名，指标依然为空 (因为端点不存在)
出现频率如何	2 秒周期 — 每天超过 4 万行
现在该做什么	请将此签名视为 «已知噪声» 并忽略。为了不掩盖真实错误，在查看日志时请过滤掉此行
何时消失	将在 2026.09 之后版本中消失 — 已修改采集器不再调用不存在的端点 — 每天约 4.3 万行日志将消失 (41 实测：反映后连续 36 分钟为 0 行)

即使日志安静下来，「指标」也不会恢复

下一版本消失的是 日志行 而非数值。离线驱动 · 离线节点 · 容量报警在之后仍无法接收数值 — 必须在 RustFS 中建立指标路径才会改变。请勿将安静下来误读为「已修复」。

MinIO 时期是 200

当时指标路径无需认证即可打开 (MINIO_PROMETHEUS_AUTH_TYPE=public)，因此可以采集。切换到 RustFS 后缺乏对应设置，因此那七项指标 (minio_cluster_*) 不再传输。控制台在该数值显示为空也是同样原因。

磁盘 / 卷问题

症状：磁盘空间不足

# 호스트 디스크 사용량
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` 清理 (镜像/网络/缓存)
Aster TSDB SSTable 堆积	在容器内部执行 `pd node cleanup`, `pd node compact`
日志目录过大	清理 `/opt/kopens/plantpulse-platform-docker/logs`

注意：docker volume prune 会删除所有未使用的卷。请勿将容器置于停止状态，以免 pp-* 卷被误删。

症状：需要恢复卷数据

请参考运行管理 - 备份与恢复页面的恢复步骤。

更新 / 回滚问题

症状：升级后容器无法正常运行

升级的官方流程是重新运行安装 One-liner。若升级失败，One-liner 将自动回滚至升级前备份的旧版本 (备份位置记录在 UPGRADE FAILED 块中)。请查看记录的检查项目并修复原因后，再次运行同一 One-liner。手动回滚时请使用 bin/upgrade-rollback.sh <백업 위치>。请勿仅通过 ./update.sh 更改镜像标签进行回滚 — 运行脚本 · compose 将停留在新版本。

症状：更新中出现 `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 成功的证据

Join 失败的 Worker 也会像成功 Worker 一样报告正常 — 因为容器的自检仅查看 «是否能触达 Master」。根据 2026-08-31 实测，Aster TSDB 发生 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)​

Aster TSDB (时序 DB)​

Valkey (Redis 缓存)​

登录 / 控制台 접속问题​

症状：浏览器无法 접속 控制台​

数据采集问题​

症状：数据未采集​

症状：数据延迟​

性能问题​

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

症状：OutOfMemoryError​

报警问题​

UI 问题​

对象存储 (RustFS) 问题​

日志中不断出现 AccessDenied​

磁盘 / 卷问题​

症状：磁盘空间不足​

症状：需要恢复卷数据​

更新 / 回滚问题​

症状：升级后容器无法正常运行​

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

网络 / 集群问题​

症状：Worker 无法 join 到 Master​

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

紧急响应​

容器无响应时​

疑似数据损坏时​

请求支持时所需信息​

相关文档​