系统启动和关闭

概述

PlantPulse 以 Docker Compose 栈的方式运行。启动/关闭/重启由 /opt/kopens/plantpulse-platform-docker/bin/ 的通用动词在一处统一管理，容器间的依赖顺序由 compose 的 depends_on 自动应用，运维人员无需逐一关注顺序。

退出码 0 的含义不同

up.sh 和 restart.sh 的 0 不是«命令成功»，而是**«现在可用»**。在 2026-08-14 凭据轮换时，曾有因仅看到«已启动»就进入下一步，结果在尚未就绪的 Broker 处卡住的事故，因此两个动词现已改为等待就绪。

status.sh 不同 — 0 = 正常 / 2 = 异常。

环境变量	默认值	含义
`PP_READY_TIMEOUT`	`900`	就绪等待超时（秒）
`PP_READY_INTERVAL`	`15`	检查间隔（秒）
`PP_WAIT=0`	—	不等待。此时 `0` 不代表就绪

启动顺序（自动）

容器间

compose 的 depends_on 以**service_healthy 条件**维持顺序 — 等待的不是«进程已启动»，而是«可用»。这个顺序不是任意的，而是直接来自应用编排器的启动顺序。

最后四个（warehouse · opcua · aasx · ha）之间无顺序关系。

数据湖容器内部

基础设施组件在 plantpulse-datalake 的单个容器内按顺序逐次启动。

顺序	领域	主要组件	代表端口
1	存储	Cassandra、PostgreSQL、Valkey、MinIO	9042 / 5432 / 6379 / 9000
2	分析	Spark、Hive、Kyuubi、Gravitino	7077 / 9083 / 10000 / 19001
3	时序	TSE Engine、UI	7800 / 3000
4	消息	Kafka、MQTT	9092 / 1883
5	工作流	Temporal、Kestra	7233 / 8233 / 8380
6	处理	CEP、Data Gateway、SQL、Monitor	7400 / 5500 / 4000 / 4950

所需时间

进程本身的启动需要 3~~5 分钟（JVM 预热），但全新安装由于 Cassandra 模式迁移和稳定化，**全部组件稳定需要 15~~18 分钟**。

实测（2026-08-31，32 vCPU / 128GiB）：数据湖 217 秒，网页服务器 316 秒。已有数据的重启要快得多。

关闭顺序

cd /opt/kopens/plantpulse-platform-docker/bin
./down.sh

无需手动维持顺序。 compose 会按依赖顺序的逆序停止，因此写入数据的一方（应用）先停，数据湖最后停。每个容器都配有充分的停止宽限期（stop_grace_period）— 数据湖为 180 秒 — 确保 Cassandra 有时间刷新 Memtable。

卷（pp-data · pp-temp · pp-backup · pp-security · pp-proxy-certs）与停止·删除无关，始终保留。

不要使用 docker kill 或主机强制关闭

Cassandra 未刷新的 Memtable 数据可能丢失。必须使用 ./down.sh 。如果容器已无响应，请按紧急程序操作。

重启

全量重启

cd /opt/kopens/plantpulse-platform-docker/bin
./restart.sh

（若正在运行）向数据湖请求 graceful drain
按依赖顺序的逆序停止整个栈
按 depends_on 顺序重新启动
等待就绪 — 退出码 0 表示可用

用于 bin/env.sh 变更、本地化/时区变更、暂时性问题解决、定期重启。

仅重启单个应用

六个应用各在独立容器中运行，因此仅重启其容器，其他应用和基础设施保持运行。这也是分离容器的原因之一。

cd /opt/kopens/plantpulse-platform-docker
docker compose -f compose/docker-compose.yml restart plantpulse-server-web

docker compose restart 不维持依赖顺序

若需同时恢复多个应用，用 ./restart.sh 重启整个栈更安全。

仅重启基础设施组件

./shell.sh                                                              # 데이터레이크 진입
/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd restart storage
exit

可用的脚本有 pd restart storage · pd restart analytics · pd restart messaging · pd restart timeseries · pd restart workflow · pd restart cep · pd restart data-gateway · pd restart sql · restart-monitor.sh 。详见启动指南。

状态检查

一行总结

./status.sh            # 0 = 정상 / 2 = 비정상

status.sh 认为异常的五种情况：

判定	内容
无法读取服务列表	compose 解析失败或无法访问 docker
compose 声明的服务中无对应容器	未启动
常驻容器的 `running` 不是正常状态	排除一次性的 `plantpulse-certs`
常驻容器的 health 不是 `unhealthy`	`starting` / `none` 暂停判定
健康检查 API 未返回 OK	在数据湖内部进行 probe

卷和 conf 仅报告，不计入退出码 — 因为两节点分离安装（PP_TIER=APP）中部分资源不存在是正常的。

一次性的 Exited (0) 即成功

plantpulse-certs 烤制证书后自行退出。compose 显式关闭了该容器的健康检查（healthcheck: disable），因此 health 列为空 — 给一次性的加健康检查会导致«正常运行的容器永远不健康»，所有人都要记住这一个例外。status.sh 和 ops-check.sh 仅根据该容器的退出码判定 — 手工查看时也要这样看。

容器检查

docker ps                       # 여덟 개가 (healthy), certs 는 Exited (0)
docker stats --no-stream        # 컨테이너별 CPU / 메모리

健康检查 API

# 호스트 / 외부에서 — 4950 이 publish 되어 있습니다
curl -kfsS https://<server-ip>:4950/api/health | jq

# 컨테이너 안에서 — 어떤 구성에서도 동작합니다
docker exec plantpulse-datalake curl -kfsS https://127.0.0.1:4950/api/health | jq

"status" 的值仅有 OK · WARN · FAIL 三种，OK/WARN 为正常范围。

4949 也提供同一 API

控制台和健康检查 API 在两个端口都可用 — 4950（HTTPS）和 4949（明文 HTTP）。同一控制台·同一 API，仅协议不同。4949 不再重定向到 4950。

4949 为明文 — 登录密码和会话 Cookie 以明文传输。在不可信网络中请用 4950 。4949 是为了那些自签证书警告会真正阻止运维人员的场景而提供的选择。

日志检查

./logs.sh                              # 여덟 컨테이너를 시간순으로 한 화면에
./logs.sh plantpulse-server-web -n 200 # 특정 컨테이너
./logs.sh cassandra                    # 데이터레이크 안 컴포넌트 로그 파일
./logs.sh --list                       # 볼 수 있는 대상 전체
./logs.sh -f plantpulse-proxy          # 계속 따라가기 (Ctrl-C 로 종료)

默认显示最后 N 行（默认 200）后结束。要跟随日志，请附加 -f 。

自动启动设置

无需单独配置。 常驻容器在 compose 中声明为 restart: always ，主机重启后 Docker 守护进程启动时会随之启动。一次性的（plantpulse-certs）是 restart: "no" ，不会再次运行 — 再运行会重新生成证书。

唯一需要检查的是 Docker 守护进程的自动启动。

systemctl is-enabled docker     # enabled 여야 합니다
sudo systemctl enable docker    # 아니라면

重启直后代理可能暂时显示红色

主机重启是唯一不应用 depends_on 顺序的路径 — 因为所有容器同时启动，网页服务器启动完成前（实测最多 316 秒）代理的健康检查可能暂时失败。重试预算设为 360 秒，docker 不会因 unhealthy 重启容器，所以这是自行恢复的临时状态。

紧急程序

网页控制台无响应

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

# 1. 어느 컨테이너가 문제인가
./status.sh

# 2. 프록시와 웹 서버 로그
./logs.sh plantpulse-proxy -n 100
./logs.sh plantpulse-server-web -n 200

# 3. 웹 서버만 재시작 (인프라는 유지)
cd /opt/kopens/plantpulse-platform-docker
docker compose -f compose/docker-compose.yml restart plantpulse-server-web

# 4. 회복되지 않으면 진단 번들
bin/doctor.sh

代理显示绿色但页面返回 502

代理的健康检查仅检查自身 + 上游可达（后端健康状态由网页服务器自身的健康检查判定）。代理绿色但页面无响应，请查看 plantpulse-server-web 。

OOM（内存溢出）

# 1. 어느 컨테이너가 OOM 인가
docker inspect plantpulse-server-web --format '{{.State.OOMKilled}} {{.State.ExitCode}} {{.RestartCount}}'

# 2. 호스트 커널 로그
dmesg | grep -i "out of memory\|oom"

# 3. 컨테이너별 사용량
docker stats --no-stream

每个容器都有独立限制 — 数据湖为 DOCKER_DATALAKE_MEMORY（默认 80G），应用为 DOCKER_SERVER_MEMORY · DOCKER_BATCH_MEMORY 等（见环境变量）。调整值后用 ./restart.sh 应用。

一个应用的 OOM 不会影响全局

为每个应用独立设置 mem_limit 是容器分离的首要目的。一个应用达到限制，基础设施和其他应用仍然运行。

数据库连接失败

所有数据库都在 plantpulse-datalake 内。

cd /opt/kopens/plantpulse-platform-docker/bin
./shell.sh                                                            # 데이터레이크 진입

/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd node psql       # PostgreSQL
/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd node cql        # Cassandra
/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd node status     # Cassandra 링 상태

仅恢复基础设施可在容器内使用 pd restart storage ，若还有问题则在主机上使用 ./restart.sh 。

怀疑数据损坏时

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

./down.sh                                  # 즉시 정지 (추가 손상 방지)
ls -lh /data1/pp-backup/docker-volume/     # 최신 백업 확인
./doctor.sh                                # 진단 번들 (데이터를 임의로 수정하지 마세요)

生成的 tarball 请发送至 webmaster@kopens.com。

运维检查清单

日检

检查项	命令/检查方法	正常标准
全体服务状态	`./status.sh`	退出码 0
运维健康	`./ops-check.sh`	无 critical 日志
健康检查 API	`curl -kfsS https://<server-ip>:4950/api/health`	`status` 为 `OK` 或 `WARN`
容器	`docker ps`	八个 `(healthy)` ，certs 为 `Exited (0)`
磁盘使用量	`df -h /data1`	占用率 80% 以下
容器资源	`docker stats --no-stream`	相对限制有余量
Cassandra 状态	容器内执行 `pd node status`	所有节点 UN（Up/Normal）

周检

检查项	命令/检查方法	正常标准
Cassandra Compaction	容器内执行 `pd node compactionstats`	待处理任务不过多
Cassandra 表	容器内执行 `pd node table-stats`	无异常增长
Kafka 主题/lag	容器内执行 `pd node topic`	延迟消息数在正常范围
备份检查	`ls -lh /data1/pp-backup/docker-volume/`	存在正常备份
Docker 使用量	`docker system df`	无未使用镜像堆积
日志容量	`du -sh /opt/kopens/plantpulse-platform-docker/logs`	无异常增长
安全更新	OS 软件包更新检查	无已知漏洞

二进制（本地）环境

当前版本不支持二进制（本地）安装

以下内容为以二进制安装方式构建的现有系统保留。现行发行版本仅为上述 Docker Compose 栈，在容器环境中请勿使用下列程序（systemd 服务、Windows 服务、单个进程启动）。

在二进制环境中，运维脚本位于 /opt/kopens/plantpulse-platform/plantpulse-startup/ — start-daemon.sh · stop.sh · restart.sh · status.sh · kill.sh · log-viewer.sh 。详见二进制安装。

Linux 启动（systemd）

如果已注册了 systemd 服务，可用以下命令启动：

# 1. 스토리지 서비스 시작
sudo systemctl start plantpulse-postgresql
sudo systemctl start plantpulse-redis
sudo systemctl start plantpulse-cassandra

# Cassandra가 완전히 시작될 때까지 대기 (약 30~60초)
until cqlsh 127.0.0.1 -e "DESCRIBE KEYSPACES" > /dev/null 2>&1; do
    echo "Cassandra 시작 대기 중..."
    sleep 5
done
echo "Cassandra 시작 완료"

# 2. 메시징 서비스 시작
sudo systemctl start plantpulse-kafka
sudo systemctl start plantpulse-mqtt

# 3. 엔진 서비스 시작
sudo systemctl start plantpulse-timeseries
sudo systemctl start plantpulse-cep

# 4. 웹서버 시작
sudo systemctl start plantpulse-server

# 5. 에이전트 시작
sudo systemctl start plantpulse-agent

Linux 手动启动

不使用 systemd 的情况下，可直接执行各模块的启动脚本。

# 스토리지
/opt/kopens/plantpulse-platform/plantpulse-storage/db/postgres/bin/pg_ctl start -D /opt/kopens/plantpulse-platform/plantpulse-storage/db/postgres/data
/opt/kopens/plantpulse-platform/plantpulse-storage/db/valkey/bin/valkey-server /opt/kopens/plantpulse-platform/plantpulse-storage/db/valkey/conf/valkey.conf &
/opt/kopens/plantpulse-platform/plantpulse-storage/db/cassandra/bin/cassandra

# 메시징
/opt/kopens/plantpulse-platform/plantpulse-messaging/kafka/bin/kafka-server-start.sh -daemon /opt/kopens/plantpulse-platform/plantpulse-messaging/kafka/config/server.properties
/opt/kopens/plantpulse-platform/plantpulse-messaging/mqtt/bin/startup.sh

# 엔진
/opt/kopens/plantpulse-platform/plantpulse-timeseries/bin/startup.sh
/opt/kopens/plantpulse-platform/plantpulse-cep/bin/startup.sh

# 웹서버
/opt/kopens/plantpulse-platform/plantpulse-server/bin/startup.sh

# 에이전트
/opt/kopens/plantpulse-platform/plantpulse-plugin/opc-ua/bin/startup.sh

启动脚本（含依赖检查）

下面是检查依赖并顺序启动的脚本示例。

#!/bin/bash
# plantpulse-start-all.sh - 전체 플랫폼 시작 스크립트

KOPENS_HOME="/opt/kopens"
LOG_FILE="/var/log/plantpulse/startup.log"

log() {
    echo "[$(date '+%Y-%m-%d %H:%M:%S')] $1" | tee -a "$LOG_FILE"
}

wait_for_port() {
    local host=$1 port=$2 timeout=${3:-60}
    local elapsed=0
    while ! nc -z "$host" "$port" 2>/dev/null; do
        if [ $elapsed -ge $timeout ]; then
            log "ERROR: $host:$port 연결 타임아웃 (${timeout}초)"
            return 1
        fi
        sleep 2
        elapsed=$((elapsed + 2))
    done
    log "OK: $host:$port 연결 확인"
    return 0
}

# 1. PostgreSQL
log "PostgreSQL 시작 중..."
sudo systemctl start plantpulse-postgresql
wait_for_port 127.0.0.1 5432 30 || exit 1

# 2. Redis
log "Redis 시작 중..."
sudo systemctl start plantpulse-redis
wait_for_port 127.0.0.1 6379 15 || exit 1

# 3. Cassandra
log "Cassandra 시작 중..."
sudo systemctl start plantpulse-cassandra
wait_for_port 127.0.0.1 9042 120 || exit 1

# 4. Kafka & MQTT
log "Kafka 시작 중..."
sudo systemctl start plantpulse-kafka
wait_for_port 127.0.0.1 9092 30 || exit 1

log "MQTT 시작 중..."
sudo systemctl start plantpulse-mqtt
wait_for_port 127.0.0.1 1883 15 || exit 1

# 5. TSE
log "시계열 엔진 시작 중..."
sudo systemctl start plantpulse-timeseries
wait_for_port 127.0.0.1 7800 30 || exit 1

# 6. CEP
log "CEP 엔진 시작 중..."
sudo systemctl start plantpulse-cep
wait_for_port 127.0.0.1 7400 30 || exit 1

# 7. 웹서버
log "PlantPulse 웹서버 시작 중..."
sudo systemctl start plantpulse-server
wait_for_port 127.0.0.1 80 60 || exit 1

# 8. OPC Agent
log "OPC Agent 시작 중..."
sudo systemctl start plantpulse-agent
wait_for_port 127.0.0.1 60000 30 || exit 1

log "전체 플랫폼 시작 완료"

Windows 启动

Windows 服务

在 Windows 环境中已注册为服务的情况下，可在服务管理器（services.msc）或命令提示符中启动。

# 서비스 시작 (관리자 권한 PowerShell)
Start-Service PlantPulse-PostgreSQL
Start-Service PlantPulse-Redis
Start-Service PlantPulse-Cassandra
Start-Service PlantPulse-Kafka
Start-Service PlantPulse-MQTT
Start-Service PlantPulse-TSE
Start-Service PlantPulse-CEP
Start-Service PlantPulse-Server
Start-Service PlantPulse-Agent

批处理文件启动

@echo off
REM plantpulse-start-all.bat - 전체 시작 배치 파일

echo [%date% %time%] PostgreSQL 시작 중...
net start PlantPulse-PostgreSQL
timeout /t 10 /nobreak > nul

echo [%date% %time%] Redis 시작 중...
net start PlantPulse-Redis
timeout /t 5 /nobreak > nul

echo [%date% %time%] Cassandra 시작 중...
net start PlantPulse-Cassandra
timeout /t 60 /nobreak > nul

echo [%date% %time%] Kafka 시작 중...
net start PlantPulse-Kafka
timeout /t 10 /nobreak > nul

echo [%date% %time%] MQTT 시작 중...
net start PlantPulse-MQTT
timeout /t 5 /nobreak > nul

echo [%date% %time%] 시계열 엔진 시작 중...
net start PlantPulse-TSE
timeout /t 10 /nobreak > nul

echo [%date% %time%] CEP 시작 중...
net start PlantPulse-CEP
timeout /t 10 /nobreak > nul

echo [%date% %time%] 웹서버 시작 중...
net start PlantPulse-Server
timeout /t 30 /nobreak > nul

echo [%date% %time%] OPC Agent 시작 중...
net start PlantPulse-Agent
timeout /t 10 /nobreak > nul

echo [%date% %time%] 전체 시작 완료
pause

关闭顺序

关闭必须按启动的逆序进行。应先关闭收集数据的代理，最后关闭数据库。

顺序	服务	说明
1	OPC Agent	停止数据采集
2	PlantPulse 网页服务器（Tomcat）	停止网页服务
3	CEP	停止事件处理
4	TSE	停止时序引擎
5	MQ（Kafka / MQTT）	停止消息代理
6	Cassandra	停止时序数据库
7	Redis（Valkey）	停止缓存
8	PostgreSQL	停止元数据库

注意： 若在其他服务之前关闭 Cassandra，尚未刷新的 Memtable 数据可能丢失。必须先关闭代理和网页服务器以停止数据写入，再关闭 Cassandra。建议在关闭 Cassandra 前用 nodetool drain 命令强制刷新 Memtable。

Linux 关闭命令

# 1. 에이전트 종료
sudo systemctl stop plantpulse-agent

# 2. 웹서버 종료
sudo systemctl stop plantpulse-server

# 3. 엔진 종료
sudo systemctl stop plantpulse-cep
sudo systemctl stop plantpulse-timeseries

# 4. 메시징 종료
sudo systemctl stop plantpulse-mqtt
sudo systemctl stop plantpulse-kafka

# 5. Cassandra 안전 종료 (Memtable 플러시 후 종료)
/opt/kopens/plantpulse-platform/plantpulse-storage/db/cassandra/bin/nodetool drain
sudo systemctl stop plantpulse-cassandra

# 6. Redis 종료
sudo systemctl stop plantpulse-redis

# 7. PostgreSQL 종료
sudo systemctl stop plantpulse-postgresql

Windows 关闭命令

# 역순으로 서비스 중지 (관리자 권한 PowerShell)
Stop-Service PlantPulse-Agent
Stop-Service PlantPulse-Server
Stop-Service PlantPulse-CEP
Stop-Service PlantPulse-TSE
Stop-Service PlantPulse-MQTT
Stop-Service PlantPulse-Kafka
Stop-Service PlantPulse-Cassandra
Stop-Service PlantPulse-Redis
Stop-Service PlantPulse-PostgreSQL

@echo off
REM plantpulse-stop-all.bat - 전체 종료 배치 파일

echo [%date% %time%] OPC Agent 종료 중...
net stop PlantPulse-Agent
timeout /t 5 /nobreak > nul

echo [%date% %time%] 웹서버 종료 중...
net stop PlantPulse-Server
timeout /t 10 /nobreak > nul

echo [%date% %time%] CEP 종료 중...
net stop PlantPulse-CEP
timeout /t 5 /nobreak > nul

echo [%date% %time%] 시계열 엔진 종료 중...
net stop PlantPulse-TSE
timeout /t 5 /nobreak > nul

echo [%date% %time%] MQTT 종료 중...
net stop PlantPulse-MQTT
timeout /t 5 /nobreak > nul

echo [%date% %time%] Kafka 종료 중...
net stop PlantPulse-Kafka
timeout /t 10 /nobreak > nul

echo [%date% %time%] Cassandra 종료 중...
net stop PlantPulse-Cassandra
timeout /t 30 /nobreak > nul

echo [%date% %time%] Redis 종료 중...
net stop PlantPulse-Redis
timeout /t 5 /nobreak > nul

echo [%date% %time%] PostgreSQL 종료 중...
net stop PlantPulse-PostgreSQL
timeout /t 10 /nobreak > nul

echo [%date% %time%] 전체 종료 완료
pause

重启

常规重启

要重启整个平台，需按顺序先关闭再启动。

# 전체 종료 (역순)
sudo systemctl stop plantpulse-agent
sudo systemctl stop plantpulse-server
sudo systemctl stop plantpulse-cep
sudo systemctl stop plantpulse-timeseries
sudo systemctl stop plantpulse-mqtt
sudo systemctl stop plantpulse-kafka
/opt/kopens/plantpulse-platform/plantpulse-storage/db/cassandra/bin/nodetool drain
sudo systemctl stop plantpulse-cassandra
sudo systemctl stop plantpulse-redis
sudo systemctl stop plantpulse-postgresql

# 전체 시작 (정순)
sudo systemctl start plantpulse-postgresql
sudo systemctl start plantpulse-redis
sudo systemctl start plantpulse-cassandra
sleep 60  # Cassandra 시작 대기
sudo systemctl start plantpulse-kafka
sudo systemctl start plantpulse-mqtt
sudo systemctl start plantpulse-timeseries
sudo systemctl start plantpulse-cep
sudo systemctl start plantpulse-server
sudo systemctl start plantpulse-agent

滚动重启（无中断重启）

在集群环境中，可进行滚动重启实现无服务中断，逐一重启节点。

#!/bin/bash
# rolling-restart.sh - 클러스터 Rolling Restart
# 사용법: ./rolling-restart.sh node1 node2 node3

NODES=("$@")

for NODE in "${NODES[@]}"; do
    echo "=== $NODE 재시작 시작 ==="

    # 1. 로드밸런서에서 노드 제거
    echo "$NODE 로드밸런서에서 제거 중..."
    # curl -X POST http://loadbalancer/api/remove-node -d "node=$NODE"

    # 2. 연결 드레인 대기 (기존 요청 처리 완료 대기)
    echo "기존 연결 드레인 대기 (30초)..."
    sleep 30

    # 3. 서비스 재시작
    echo "$NODE 서비스 재시작 중..."
    ssh "$NODE" "sudo systemctl restart plantpulse-server"

    # 4. 헬스체크 통과 대기
    echo "$NODE 헬스체크 대기 중..."
    until ssh "$NODE" "curl -sf http://localhost/api/v5/ping > /dev/null 2>&1"; do
        sleep 5
    done

    # 5. 로드밸런서에 노드 재등록
    echo "$NODE 로드밸런서에 재등록 중..."
    # curl -X POST http://loadbalancer/api/add-node -d "node=$NODE"

    echo "=== $NODE 재시작 완료 ==="
    echo "다음 노드 진행 전 안정화 대기 (60초)..."
    sleep 60
done

echo "Rolling Restart 완료"

提示： 滚动重启适用于网页服务器（Tomcat）。Cassandra 集群的滚动重启请在 nodetool drain 后顺序重启各节点。

状态检查

进程检查

# 전체 PlantPulse 관련 프로세스 확인
ps aux | grep plantpulse

# 특정 서비스 프로세스 확인
ps aux | grep plantpulse-server
ps aux | grep cassandra
ps aux | grep kafka

端口检查

# 핵심 포트 한 번에 확인
for port in 5432 6379 9042 9092 1883 7800 7400 80 60000; do
    if nc -z 127.0.0.1 $port 2>/dev/null; then
        echo "OK: 포트 $port 열림"
    else
        echo "FAIL: 포트 $port 닫힘"
    fi
done

健康检查 API

PlantPulse 网页服务器通过 /api/v5/ping 端点提供健康检查。

# 기본 헬스체크
curl -sf http://localhost/api/v5/ping
# 응답: {"status":"OK","timestamp":1709884800000}

# HTTP 상태 코드만 확인
curl -sf -o /dev/null -w "%{http_code}" http://localhost/api/v5/ping
# 200이면 정상

日志检查

# PlantPulse 웹서버 로그
tail -f /opt/kopens/plantpulse-platform/plantpulse-server/logs/system.log

# Cassandra 로그
tail -f /opt/kopens/plantpulse-platform/plantpulse-storage/db/cassandra/logs/system.log

# Kafka 로그
tail -f /opt/kopens/plantpulse-platform/plantpulse-messaging/kafka/logs/server.log

# 에이전트 로그
tail -f /opt/kopens/plantpulse-platform/plantpulse-plugin/opc-ua/logs/agent.log

# 시작 시 에러 로그만 필터링
grep -i "error\|exception\|fail" /opt/kopens/plantpulse-platform/plantpulse-server/logs/system.log | tail -20

JVM 状态检查

# Java 프로세스 목록 확인
jps -lv

# PlantPulse 서버 힙 메모리 확인
jstat -gc $(pgrep -f plantpulse-server) 1000 5

# GC 로그 확인
tail -f /opt/kopens/plantpulse-platform/plantpulse-server/logs/gc.log

# 스레드 덤프 (문제 진단 시)
jstack $(pgrep -f plantpulse-server) > /tmp/thread-dump-$(date +%Y%m%d%H%M%S).txt

systemd 服务状态

# 전체 PlantPulse 서비스 상태 확인
systemctl list-units 'plantpulse-*' --all

# 특정 서비스 상세 상태
sudo systemctl status plantpulse-server
sudo systemctl status plantpulse-cassandra

自动启动设置

Linux（systemd enable）

设置服务器启动时自动启动服务。

# 자동 시작 활성화
sudo systemctl enable plantpulse-postgresql
sudo systemctl enable plantpulse-redis
sudo systemctl enable plantpulse-cassandra
sudo systemctl enable plantpulse-kafka
sudo systemctl enable plantpulse-mqtt
sudo systemctl enable plantpulse-timeseries
sudo systemctl enable plantpulse-cep
sudo systemctl enable plantpulse-server
sudo systemctl enable plantpulse-agent

# 자동 시작 상태 확인
systemctl list-unit-files 'plantpulse-*' | grep enabled

提示： 在 systemd 单元文件中使用 After= 指令设置服务间的启动顺序依赖，主机启动时也会按正确顺序启动。示例：

[Unit]
Description=PlantPulse Server
After=plantpulse-postgresql.service plantpulse-redis.service plantpulse-cassandra.service
Requires=plantpulse-postgresql.service plantpulse-redis.service

[Service]
Type=forking
User=kopens
ExecStart=/opt/kopens/plantpulse-platform/plantpulse-server/bin/startup.sh
ExecStop=/opt/kopens/plantpulse-platform/plantpulse-server/bin/shutdown.sh
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Windows 服务自动启动

# 서비스 자동 시작 설정
Set-Service -Name "PlantPulse-PostgreSQL" -StartupType Automatic
Set-Service -Name "PlantPulse-Redis" -StartupType Automatic
Set-Service -Name "PlantPulse-Cassandra" -StartupType Automatic
Set-Service -Name "PlantPulse-Kafka" -StartupType Automatic
Set-Service -Name "PlantPulse-Server" -StartupType Automatic
Set-Service -Name "PlantPulse-Agent" -StartupType Automatic

# 자동 시작 상태 확인
Get-Service PlantPulse-* | Select-Object Name, StartType, Status

紧急程序

服务器无响应

网页服务器无响应时，请按以下顺序处理。

# 1. 헬스체크 확인
curl -sf --connect-timeout 5 http://localhost/api/v5/ping
echo "HTTP 응답 코드: $?"

# 2. 프로세스 상태 확인
ps aux | grep plantpulse-server

# 3. 포트 점유 확인
ss -tlnp | grep ':80'

# 4. 스레드 덤프 (행(hang) 의심 시)
jstack $(pgrep -f plantpulse-server) > /tmp/thread-dump-$(date +%Y%m%d%H%M%S).txt

# 5. GC 상태 확인
jstat -gcutil $(pgrep -f plantpulse-server) 1000 3

# 6. 웹서버만 재시작 (다른 서비스는 유지)
sudo systemctl restart plantpulse-server

# 7. 재시작 후 헬스체크 확인
sleep 30
curl -sf http://localhost/api/v5/ping

OOM（内存溢出）

# 1. OOM 발생 확인
dmesg | grep -i "out of memory\|oom"

# 2. 힙 덤프 확인 (자동 생성된 경우)
ls -la /opt/kopens/plantpulse-platform/plantpulse-server/logs/heapdump*

# 3. 메모리 사용량 확인
free -h
ps aux --sort=-%mem | head -10

# 4. JVM 힙 크기 조정 (catalina.sh 또는 setenv.sh)
# JAVA_OPTS="-Xms4g -Xmx8g -XX:+HeapDumpOnOutOfMemoryError"
# 설정 변경 후 재시작
sudo systemctl restart plantpulse-server

数据库连接失败

# 1. PostgreSQL 연결 확인
psql -h 127.0.0.1 -U plantpulse -d plantpulse -c "SELECT 1"

# 2. Cassandra 연결 확인
cqlsh 127.0.0.1 -e "DESCRIBE KEYSPACES"

# 3. Redis 연결 확인
redis-cli -h 127.0.0.1 ping

# 4. 연결 수 확인 (PostgreSQL)
psql -h 127.0.0.1 -U plantpulse -d plantpulse -c "SELECT count(*) FROM pg_stat_activity"

# 5. DB 서비스 재시작 (필요 시)
# 주의: DB 재시작 전 반드시 웹서버와 에이전트를 먼저 종료해 주세요
sudo systemctl stop plantpulse-agent
sudo systemctl stop plantpulse-server
sudo systemctl restart plantpulse-postgresql
sudo systemctl start plantpulse-server
sudo systemctl start plantpulse-agent

运维检查清单

日检

检查项	命令/检查方法	正常标准
全体服务状态	`systemctl list-units 'plantpulse-*'`	所有服务 active（running）
核心端口检查	端口检查脚本（上述参考）	所有端口开放
健康检查 API	`curl http://localhost/api/v5/ping`	HTTP 200，status OK
磁盘使用量	`df -h`	占用率 80% 以下
内存使用量	`free -h`	占用率 85% 以下
错误日志	`grep ERROR plantpulse.log \| tail -20`	无重复错误
Cassandra 状态	`nodetool status`	所有节点 UN（Up/Normal）

周检

检查项	命令/检查方法	正常标准
Cassandra Compaction	`nodetool compactionstats`	待处理任务不过多
PostgreSQL 统计	`pg_stat_activity` 查询	空闲连接不过多
Kafka Consumer Lag	`kafka-consumer-groups.sh --describe`	延迟消息数在正常范围
JVM GC 统计	`jstat -gcutil`	Full GC 频率低
备份检查	检查最近备份文件	存在正常备份
日志文件容量	`du -sh */logs/`	无异常增长
安全更新	OS 软件包更新检查	无已知漏洞

概述​

推荐运维命令（摘要）​

启动顺序（自动）​

容器间​

数据湖容器内部​

关闭顺序​

重启​

全量重启​

仅重启单个应用​

仅重启基础设施组件​

状态检查​

一行总结​

容器检查​

健康检查 API​

日志检查​

自动启动设置​

紧急程序​

网页控制台无响应​

OOM（内存溢出）​

数据库连接失败​

怀疑数据损坏时​

运维检查清单​

日检​

周检​

二进制（本地）环境​

Linux 启动（systemd）​

Linux 手动启动​

启动脚本（含依赖检查）​

Windows 启动​

Windows 服务​

批处理文件启动​

关闭顺序​

Linux 关闭命令​

Windows 关闭命令​

重启​

常规重启​

滚动重启（无中断重启）​

状态检查​

进程检查​

端口检查​

健康检查 API​

日志检查​

JVM 状态检查​

systemd 服务状态​

自动启动设置​

Linux（systemd enable）​

Windows 服务自动启动​

紧急程序​

服务器无响应​

OOM（内存溢出）​

数据库连接失败​

运维检查清单​

日检​

周检​

概述

推荐运维命令（摘要）

启动顺序（自动）

容器间

数据湖容器内部

关闭顺序

重启

全量重启

仅重启单个应用

仅重启基础设施组件

状态检查

一行总结

容器检查

健康检查 API

日志检查

自动启动设置

紧急程序

网页控制台无响应

OOM（内存溢出）

数据库连接失败

怀疑数据损坏时

运维检查清单

日检

周检

二进制（本地）环境

Linux 启动（systemd）

Linux 手动启动

启动脚本（含依赖检查）

Windows 启动

Windows 服务

批处理文件启动

关闭顺序

Linux 关闭命令

Windows 关闭命令

重启

常规重启

滚动重启（无中断重启）

状态检查

进程检查

端口检查

健康检查 API

日志检查

JVM 状态检查

systemd 服务状态

自动启动设置

Linux（systemd enable）

Windows 服务自动启动

紧急程序

服务器无响应

OOM（内存溢出）

数据库连接失败

运维检查清单

日检

周检