系统启动与停止

概述

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 = 异常。

推荐运维命令（概要）

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

./up.sh                # 기동 (멱등) — 준비될 때까지 대기. 0 = 준비 완료
./down.sh              # 안전 종료 (의존 순서의 역순, 상태 보존)
./restart.sh           # graceful drain → 정지 → 기동 → 준비 대기
./status.sh            # 서비스 / health / 볼륨 요약. 0 = 정상 / 2 = 비정상
./ops-check.sh         # 헬스 + 최근 critical log
./logs.sh [서비스]     # 로그 보기 — 1회 출력, -f 로 따라가기 (인자 없으면 전체)
./stack-verify-boot.sh # 스택 전체 준비 판정
./doctor.sh            # 진단 tarball (시스템 변경 없음)

所有动词都支持 --help。旧名称（stack-run.sh · stack-stop.sh · stack-bash.sh · stack-update.sh · stack-remove.sh）仍然有效。

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

启动顺序（自动）

容器之间

compose 的 depends_on 以 service_healthy 条件 维护顺序 —— 等待的不是「进程已启动」，而是「可写入」。此顺序并非随意，而是照搬了应用编排器的启动顺序。

最后四个（warehouse · opcua · aasx · ha）彼此之间没有顺序。

数据湖容器内

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

顺序	领域	主要组件	代表端口
1	存储	Aster TSDB, PostgreSQL, Valkey, RustFS	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

所需时间

进程启动本身需要 35 分钟（JVM 预热），但全新安装时，由于 Aster TSDB schema 迁移和稳定化，**所有组件稳定下来需要 1518 分钟**。

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

停止顺序

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

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

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

不要使用 docker kill 或主机强制终止

Aster TSDB 中未刷新的 Memtable 数据可能会丢失。务必使用 ./down.sh。如果容器已无响应，请遵循 紧急流程。

重启

全栈重启

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

1. （若在运行）向数据湖发送 graceful drain 请求
2. 按依赖顺序的逆序停止整个栈
3. 按 depends_on 顺序重新启动
4. 等待就绪 —— 退出码为 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 <서비스> 接受的名称只有 services/order.txt 中的八个 —— storage · analytics · messaging · timeseries · cep · workflow · data-gateway · admin-api。其他名称将以 unknown service 结束。详情请参考 启动指南。

状态检查

一行摘要

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

status.sh 判定异常的情况有五种。

判定	内容
无法读取服务列表	compose 解析失败或 docker 不可访问
compose 声明的服务没有对应容器	未启动
容器状态不是 running	九个全部常驻运行 —— 无例外
常驻容器的 health 不是 unhealthy	starting / none 判定保留
健康 API 非 OK	在数据湖内部探测

卷和 conf 仅报告，不纳入退出码 —— 因为根据安装配置，缺失部分属正常现象。

九个容器用同一标准判定

plantpulse-certs 会烧录一次证书，然后持续驻留并监控过期。九个容器可用同一标准（healthy）来判定。

健康检查由镜像自带。 compose 中没有 probe 块是有意为之，pp.healthcheck: image 标签明确说明了这一点。若将源自其他仓库的 probe 路径写入 compose，一旦对方替换文件，就会在客户现场出错。

容器检查

docker ps                       # 아홉 개가 모두 (healthy)
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 中声明了重启策略，因此即使主机重启，Docker 守护进程启动后容器也会一起启动。plantpulse-certs 是 restart: unless-stopped —— 如果人为停止，即使重启守护进程也会保持停止状态。重启不会重新烧录证书。

需要检查的只有 Docker 守护进程的自动启动一项。

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

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

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

紧急流程

Web 控制台无响应

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 时

代理的健康检查仅检查自身 + 上游可达性（后端健康状态由 Web 服务器自身的健康检查判定）。若代理为绿色但页面无法显示，请检查 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（默认 96G），应用为 DOCKER_SERVER_MEMORY · DOCKER_BATCH_MEMORY 等（环境变量）。调整值后通过 ./restart.sh 应用。

单个应用的 OOM 不会拖垮整个系统

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

DB 连接失败

所有数据库都在 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)
磁盘使用量	df -h /data1	使用率低于 80%
容器资源	docker stats --no-stream	相对限制值有足够余量
Aster TSDB 状态	容器内执行 pd node status	所有节点 UN (Up/Normal)

每周巡检

检查项	命令 / 确认方法	正常标准
Aster TSDB Compaction	容器内执行 pd node compactionstats	无过多 Pending 任务
Aster TSDB 表	容器内执行 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 包更新	无已知漏洞

---