快速开始指南

概述

如果你已通过单行安装或 Docker 安装部署了 PlantPulse Platform，所有运维脚本都在 /opt/kopens/plantpulse-platform-docker/bin/ 目录下。本页面指导你如何启动和运维以 Docker Compose 堆栈运行的平台。

平台由九个容器组成 — 一个证书一次性容器、一个数据湖、六个应用、一个代理。完整构成请见 Docker 安装 — 安装结果。

使用旧脚本名称

下方左侧的名称已不再存在。请使用右侧的通用动词。

旧名称	现在使用
`start.sh`	`up.sh`
`platform-stop.sh`	`down.sh`
`platform-update.sh`	`update.sh`
`platform-remove.sh`	`remove.sh`
`platform-bash.sh`	`shell.sh`
`platform-verify-boot.sh`	`stack-verify-boot.sh`
`worker-run.sh` · `worker-stop.sh` · `worker-update.sh` · `worker-bash.sh`	参考工作节点管理

stack-run.sh · stack-stop.sh · stack-bash.sh · stack-update.sh · stack-remove.sh 仍可正常使用（新增一行说明后执行相同功能）。

设置环境变量

启动平台前，请检查环境变量。资源值在安装时根据主机自动计算，因此大多数服务器几乎不需要修改。

vi /opt/kopens/plantpulse-platform-docker/bin/env.sh

常调整的项目

变量	说明	默认值
`PP_LANG`	平台区域设置 (`ko` / `en`)	`en`
`PP_TZ`	平台时区	`Asia/Seoul`
`DOCKER_PP_CPUS`	分配给容器的 vCPU 数	`nproc` 结果
`DOCKER_PP_MEMORY`	内存上限	主机 RAM 的 90%
`DOCKER_DATALAKE_MEMORY`	数据湖内存上限	`80G` (主机较小时为 RAM 的 90%)
`DOCKER_PP_DATA_DISK_NAME`	数据磁盘名称	自动回溯 (失败时 `sda`)
`DOCKER_PP_EXTERNAL_IP`	NAT 环境的外部 advertise IP	空值

完整环境变量列表请参考环境变量参考页面。

应用变更：修改 env.sh 后必须用 ./restart.sh 重启，新配置才会生效。

env.sh 无法修改密码

在安装完成的节点上，秘密边车（/etc/kopens/plantpulse-platform.env）会同时覆盖 env.sh 和 shell export。密码修改请使用密码轮换中的 passwd.sh。

启动平台

首次安装后启动

安装（install.sh）完成后，堆栈已在运行中。仅需检查状态。

cd /opt/kopens/plantpulse-platform-docker/bin
./status.sh
./ops-check.sh

启动已停止的堆栈

当堆栈因 ./down.sh 或主机重启等原因停止时，重新启动。

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

up.sh 具有幂等性，等待至就绪。退出代码 0 的意思不是"命令成功"，而是**"现在可用"**。

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

卷（pp-data、pp-temp、pp-backup、pp-security、pp-proxy-certs）中的数据保持不变。模板/配置由主机绑定挂载（/etc/kopens/conf）管理。

启动顺序

容器按 compose 的 depends_on 定义的顺序启动。service_healthy 条件，等待"可用"而非"进程已启动"。

plantpulse-certs        (완료까지 — 원샷)
      │
plantpulse-datalake     (healthy 까지)
      │
plantpulse-server-web   (healthy 까지) ──── plantpulse-proxy
      │
plantpulse-batch-web    (healthy 까지)
      │
      ├── plantpulse-warehouse
      ├── plantpulse-plugin-opcua-server
      ├── plantpulse-plugin-aasx-server
      └── plantpulse-ha        (이 넷은 서로 순서가 없습니다)

在数据湖容器内部，基础设施组件按顺序再次启动。

顺序	类别	组件
1	存储	Valkey(Redis)、PostgreSQL、Cassandra、MinIO
2	分析	Spark、Hadoop、Hive、Kyuubi、Gravitino
3	时序	时序引擎、时序 UI
4	消息	Kafka、MQTT
5	工作流	Temporal、Kestra
6	处理	CEP、Data Gateway、SQL、Monitor

所需时间

进程启动本身需要 3~~5 分钟（JVM 预热），但全新安装**至所有组件稳定需要 15~~18 分钟**。Cassandra 模式迁移和稳定化最耗时。

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

启动验证

cd /opt/kopens/plantpulse-platform-docker/bin
./stack-verify-boot.sh

stack-verify-boot.sh 判定的是整个堆栈而非单个容器 — 一次性容器是否正常退出、数据湖和应用是否 running·healthy、代理是否服务 443。识别节点级别（PP_TIER — FULL / DATALAKE / APP），仅验证该级别存在的组件。

up.sh 和 restart.sh 轮询直至此脚本通过，这就是这两个命令退出代码 0 表示"可用"的依据。

确认正常启动

# 서비스 / health / 볼륨 요약 (0 = 정상 / 2 = 비정상)
./status.sh

# 운영 health + 최근 critical log 점검
./ops-check.sh

# 헬스체크 엔드포인트 직접 호출
curl -kfsS https://<server-ip>:4950/api/health | jq

# Docker 상태
docker ps

docker ps 中八个应为 (healthy)，plantpulse-certs 应为 Exited (0)。一次性容器的 Exited (0) 是成功状态，不是故障。

停止平台

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

安全停止堆栈。数据保存在 Docker 卷中，用 ./up.sh 重启时会保持之前的状态。

注意：docker kill 或主机强制关闭会破坏数据一致性。必须使用 ./down.sh。

重启平台

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

优雅地关闭（drain）内部组件，按依赖顺序反向停止堆栈，然后按 depends_on 顺序重新启动，等待至就绪。

用于 env.sh 变更、解决运行时临时问题、定期重启。

检查服务状态

全体概览

./status.sh

一次显示服务列表、容器状态、health 结果、卷信息。退出代码是约定 — 0 正常，2 异常，可直接用于监控自动化。

运维巡检

./ops-check.sh

一起检查容器 health、健康 API 响应、最近的 critical 日志。遍历全部八个容器。

主机侧资源检查

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

每个容器都有单独的 mem_limit，可以单独检查哪个容器接近上限。应用别的上限值见环境变量参考。

进入容器内部

cd /opt/kopens/plantpulse-platform-docker/bin
./shell.sh                          # 인자가 없으면 데이터레이크
./shell.sh plantpulse-server-web    # 특정 컨테이너

可进入的服务列表用 ./status.sh 查看。

集群工作节点不在此列表中

shell.sh 仅按名称解析基础堆栈的服务。工作节点在生成的覆盖层（compose/docker-compose.worker.yml）中，用 docker exec -ti plantpulse-worker-<n> /bin/bash 进入。

按组件重启

容器分散分布，重启方法也有两种。

应用六个 — 按容器单位重启

应用各自在自己的容器中运行，重启容器就是重启该应用。其他应用和基础设施不受影响。

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

容器	运行内容
`plantpulse-server-web`	Web 控制台
`plantpulse-batch-web`	批处理
`plantpulse-warehouse`	数据仓库
`plantpulse-plugin-opcua-server`	OPC-UA 插件
`plantpulse-plugin-aasx-server`	AASX 插件
`plantpulse-ha`	冗余恢复守护进程

docker compose restart 不遵守依赖顺序

需要同时重启多个应用，用 ./restart.sh 重启整个堆栈更安全。启动顺序为 plantpulse-server-web → plantpulse-batch-web → 其他四个。

数据湖内的组件 — 容器内脚本

存储、分析、消息等基础设施组件在 plantpulse-datalake 容器内部共同运行，需进入容器使用单个脚本。

# 호스트에서 데이터레이크 진입
./shell.sh

# 컨테이너 내부에서
/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd restart storage
exit

脚本	目标
`pd restart storage`	Cassandra、PostgreSQL、Valkey、MinIO
`pd restart analytics`	Spark、Hive、Kyuubi、Gravitino
`pd restart messaging`	Kafka、MQTT
`pd restart timeseries`	时序引擎及 UI
`pd restart workflow`	Temporal、Kestra
`pd restart cep`	复杂事件处理引擎
`pd restart data-gateway`	数据查询网关
`pd restart sql`	SQL 查询工具
`restart-monitor.sh`	系统监控

参考：重启基础设施组件后，建议同时重启依赖该组件的应用容器。

不要在数据湖内运行应用重启脚本

restart-server.sh · restart-batch.sh · restart-warehouse.sh · restart-opcua-server.sh · restart-aasx-server.sh 脚本文件仍存在，但只在各自应用的容器内有意义。数据湖容器中没有这些应用的可执行文件，会以"模块不存在"错误结束。应用应使用上面的容器单位重启。

平台更新

新镜像发布时，用以下命令更新。

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

自动执行顺序：

docker pull 新镜像
graceful 关闭现有容器
用新镜像重建容器
health 验证 — 失败时自动 rollback 至前一个镜像

目标标签由 PP_IMAGE_TAG（默认 latest）决定。数据单独存储在卷中，更新期间安全保存。

日志管理

查看日志 — `logs.sh`

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

./logs.sh                             # 전체 컨테이너를 한 화면에 (서비스 이름 접두, 시간순)
./logs.sh plantpulse-server-web       # 그 컨테이너의 로그
./logs.sh cassandra                   # 데이터레이크 안 컴포넌트 로그 파일
./logs.sh --list                      # 볼 수 있는 대상 전체 목록
./logs.sh -n 500 cep                  # 500줄만
./logs.sh -f plantpulse-server-web    # 계속 따라가기 (Ctrl-C 로 종료)

默认"打印一次后退出"

logs.sh 打印最后 N 行（默认 200）后退出。要持续跟踪，加上 -f。--no-follow 为兼容接受，但现在是默认行为，无需加上。

不知道是哪个容器时无参数运行

问题发生时很难预知问题在哪个容器。无参数运行会将八个容器的日志按时间混合输出，避免只看一个容器而错过根本原因。

--list 从 compose 读取服务列表，从数据湖容器读取组件日志目录。显示的是那一时刻的真实列表，不是手工维护的列表。

容器内部日志目录

数据湖容器内组件的日志路径。(用 ./shell.sh 进入后查看)

模块	日志路径
Valkey	`plantpulse-storage/cache/valkey/logs/system.log`
PostgreSQL	`plantpulse-storage/db/postgres/logs/system.log`
Cassandra	`plantpulse-storage/db/cassandra/logs/system.log`
MinIO	`plantpulse-storage/object/minio/logs/system.log`
Gravitino	`plantpulse-analytics/gravitino/logs/system.log`
Hive	`plantpulse-analytics/hive/logs/system.log`
Spark	`plantpulse-analytics/spark/logs/system.log`
Kyuubi	`plantpulse-analytics/kyuubi/logs/system.log`
时序引擎	`plantpulse-timeseries/engine/logs/system.log`
Kafka	`plantpulse-messaging/kafka/logs/server.log`
MQTT	`plantpulse-messaging/mqtt/logs/hivemq.log`
Temporal	`plantpulse-workflow/temporal/logs/system.log`
Kestra	`plantpulse-workflow/kestra/logs/system.log`
CEP	`plantpulse-cep/logs/system.log`
Data Gateway	`plantpulse-data-gateway/logs/system.log`
SQL	`plantpulse-sql/logs/system.log`
Monitor	`plantpulse-monitor/logs/system.log`

路径基准是 /opt/kopens/plantpulse-platform/。应用六个的日志在各自容器内，用 ./logs.sh <컨테이너> 查看更快。

复制日志到主机

cd /opt/kopens/plantpulse-platform-docker/bin
./tools/copy-log-to-local.sh

故障诊断

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

生成诊断 tarball（/tmp/pp-doctor-<호스트>-<타임스탬프>.tar.zst）。包含所有容器的状态、health probe 输出、日志和配置，以及主机环境，密码和密钥被掩码处理。完全不修改系统。

将生成的 tarball 提交给 KOPENS 技术支持团队，便于快速分析。

工作节点管理（集群环境）

从单主节点运维发展到需要处理能力扩展时，添加工作节点容器。工作节点列表的权威来源是 compose/workers.roster（一行一个 <id> <ip>），覆盖 compose 文件从此生成。

cd /opt/kopens/plantpulse-platform-docker

# 추가 — roster 등록 → 오버레이 재생성 → 볼륨 → pull → up → 링 조인 확인
bin/worker-add.sh                  # 빈 id·주소 자동 선택
bin/worker-add.sh 3                # id 지정
bin/worker-add.sh 3 10.99.0.103    # id·주소 지정

# 진입
docker exec -ti plantpulse-worker-3 /bin/bash

# 제거 — 반드시 이 순서
bin/worker-decommission.sh 3       # 데이터 이관 + 링 이탈 확인 + 복제 슬롯 정리
bin/worker-remove.sh               # 그 다음에 컨테이너 제거

从活跃工作节点删除 docker rm 是"遗弃"而非移除

Cassandra 仍然持有该节点的令牌范围和 host id（RF=3 时 QUORUM 仍然成立，不会产生任何告警），主节点不释放该工作节点的 PostgreSQL 物理复制插槽，WAL 会被固定至磁盘满。必须先执行 worker-decommission.sh — worker-remove.sh 会在容器运行时拒绝。

已删除的工作节点脚本

worker-run.sh · worker-stop.sh · worker-update.sh · worker-bash.sh 在 2026-08-31 删除。这些基于手工管理的工作节点列表，改为 roster 方式后删除。替代方案分别为 worker-add.sh（包括 pull）· compose 动词 · compose pull+up -d · docker exec。

详见集群安装页面。

安装后初始访问

项目	值
Web 控制台 URL	`https://[서버IP]` (80/443)
管理 UI URL	`https://[서버IP]:7443`
监控 UI URL	`https://[서버IP]:4950`
默认管理员 ID	admin
默认密码	admin123!

安全提示：首次登录后，建议修改默认密码以提高安全性。→ 初始密码

节点管理脚本（数据湖容器内部）

Cassandra 及数据库管理由 plantpulse-datalake 容器内的 pd CLI（/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd）负责。用 ./shell.sh 进入后使用。

Cassandra 管理

脚本	说明	使用时机
`pd node status`	检查集群状态	定期巡检、问题确认
`pd node info`	节点详细信息	节点配置确认
`pd node compact`	执行手动压缩	磁盘空间回收
`pd node compactionstats`	检查压缩进度	性能巡检
`pd node flush`	Memtable 刷写	内存清理
`pd node drain`	节点 Drain（安全关闭准备）	节点关闭前
`pd node repair`	节点数据恢复/同步	数据不一致
`pd node repair-table`	特定表恢复	表级别恢复
`pd node cleanup`	节点清理（删除不必要数据）	节点变更后
`pd node remove`	从集群移除节点	节点下线
`pd node add`	向集群添加节点	扩展
`pd node upgrade`	节点升级	版本升级
`pd node tpstats`	线程池统计	性能分析
`pd node proxyhistograms`	代理直方图	延迟分析
`pd node table-histograms`	表直方图	表性能分析
`pd node table-stats`	表统计	数据大小/记录数确认
`pd node sstable-size`	SSTable 大小确认	磁盘使用量检查
`pd node cache-clear`	缓存初始化	缓存问题
`pd node topic`	Kafka 主题管理	消息巡检
`pd node disk`	磁盘使用量确认	容量检查
`pd node errors`	错误日志查看	错误诊断
`pd node train-zstd`	ZStandard 压缩学习	压缩优化
`pd node init-cms`	CMS 初始化	初始设置

数据库连接

脚本	说明
`pd node psql`	PostgreSQL shell 连接（元数据 DB）
`pd node cql`	Cassandra CQL shell 连接（时序 DB）

配置脚本

脚本	说明
`configure.sh`	生成数据湖配置（基于 env 自动生成各服务配置）
`prepared.sh`	启动前环境验证和准备（检查必需目录、权限等）

不要在容器内运行 env-reset.sh

env-reset.sh 是仅供开发用的工具，unset 所有 PP_*，然后重新读取 env.sh。在数据湖容器内运行会丧失 compose 注入的值，回到镜像内置默认值。

二进制安装环境

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

现行发布版本仅为上述 Docker Compose 堆栈。基于二进制安装构建的现有系统的运维命令保留在二进制安装页面，请参考那里。新建不要使用。

常用命令速查

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

./preflight.sh            # 설치 전 비파괴 사전 점검
./install.sh              # 최초 설치 (OS+Docker+방화벽+스택)
./up.sh                   # 기동 — 준비될 때까지 대기 (0 = 준비 완료)
./down.sh                 # 정지 (상태 보존)
./restart.sh              # graceful 재시작 (drain + 준비 대기)
./status.sh               # 서비스 / health / 볼륨 요약 (0=정상 / 2=비정상)
./logs.sh [서비스]        # 로그 보기 — 1회 출력. -f 로 따라가기 (인자 없으면 전체, 목록은 --list)
./shell.sh [서비스]       # 컨테이너 bash 진입
./ops-check.sh            # 운영 health + critical log 점검
./update.sh               # 이미지 갱신 (pull + recreate + rollback)
./remove.sh               # 컨테이너 제거 (볼륨은 보존)
./backup.sh               # 볼륨 백업 (기본 pp-data · pp-security)
./doctor.sh               # 장애 진단 tarball 생성
./passwd.sh --list        # 바꿀 수 있는 비밀번호 목록
./stack-verify-boot.sh    # 스택 전체 준비 판정

所有动词都支持 --help。

概述​

设置环境变量​

常调整的项目​

启动平台​

首次安装后启动​

启动已停止的堆栈​

启动顺序​

启动验证​

确认正常启动​

停止平台​

重启平台​

检查服务状态​

全体概览​

运维巡检​

主机侧资源检查​

进入容器内部​

按组件重启​

应用六个 — 按容器单位重启​

数据湖内的组件 — 容器内脚本​

平台更新​

日志管理​

查看日志 — logs.sh​

容器内部日志目录​

复制日志到主机​

故障诊断​

工作节点管理（集群环境）​

安装后初始访问​

节点管理脚本（数据湖容器内部）​

Cassandra 管理​

数据库连接​

配置脚本​

二进制安装环境​

常用命令速查​

概述