入门指南

概述

如果您通过单行安装或 Docker 安装了 PlantPulse Platform，所有运行脚本均位于 /opt/kopens/plantpulse-platform-docker/bin/ 目录中。本页将引导您如何启动和运行以 Docker Compose 堆栈 形式运行的 Platform。

Platform 由九个容器组成 —— 一个证书、一个数据湖、六个应用、一个代理。这九个容器全部常驻运行。 完整配置请参阅 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`	参阅 Worker 管理

stack-run.sh · stack-stop.sh · stack-bash.sh · stack-update.sh · stack-remove.sh 仍可正常运行（在提示新名称后执行相同操作）。

环境变量设置

在启动 Platform 之前，请检查环境变量。资源值在安装时会根据主机自动计算，因此在大多数服务器上几乎无需手动修改。

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

常用调整项

变量	说明	默认值
`PP_LANG`	Platform 区域设置 (`ko` / `en`)	`en`
`PP_TZ`	Platform 时区	`Asia/Seoul`
`DOCKER_PP_CPUS`	分配给容器的 vCPU 数	`nproc` 结果
`DOCKER_PP_MEMORY`	内存上限	主机 RAM 的 90%
`DOCKER_DATALAKE_MEMORY`	数据湖内存上限	`96G`（最小值，不超过主机 RAM 的 90% — 主机 107G 以下为规格不足）
`DOCKER_PP_DATA_DISK_NAME`	数据磁盘名称	自动追溯 (失败时使用 `sda`)
`DOCKER_PP_EXTERNAL_IP`	NAT 环境的外部 advertise IP	空值

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

应用变更: 修改 env.sh 后，必须使用 ./restart.sh 重启才能使新设置生效。

密码无法通过 env.sh 修改

在安装完成的节点上，Secret Sidecar (/etc/kopens/plantpulse-platform.env) 的优先级高于 env.sh 和 Shell export。请使用密码轮转中的 passwd.sh 来修改密码。

启动 Platform

初次安装后启动

安装(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        (healthy 까지)
      │
plantpulse-datalake     (healthy 까지)
      │
plantpulse-server-web   (healthy 까지) ──── plantpulse-proxy
      │
plantpulse-batch-web    (healthy 까지)
      │
      ├── plantpulse-warehouse
      ├── plantpulse-plugin-opcua
      ├── plantpulse-plugin-aasx
      └── plantpulse-ha        (이 넷은 서로 순서가 없습니다)

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

顺序	类别	组件
1	存储	Valkey(Redis), PostgreSQL, Aster TSDB, RustFS
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 分钟才能使所有组件稳定**。Aster TSDB 模式迁移和稳定化耗时最长。

实测(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 端口服务。

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) 即为正常。

停止 Platform

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

安全地停止堆栈。数据将保存在 Docker 卷中，因此使用 ./up.sh 重新启动后将维持之前状态。

注意: 使用 docker kill 或强制关闭主机可能会破坏数据一致性。请务必使用 ./down.sh。

重启 Platform

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

在优雅地关闭(drain)内部组件后，按照依赖顺序的反向顺序停止堆栈，然后再次按照 depends_on 顺序启动并等待至就绪。

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

查看服务状态

整体摘要

./status.sh

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

运行巡检

./ops-check.sh

同时检查容器 Health、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 确认可进入的服务列表。

集群 Worker 不在此列表中

shell.sh 仅通过名称解析基础堆栈的服务。Worker 位于创建的 Overlay (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`	Batch
`plantpulse-warehouse-web`	数据仓库
`plantpulse-plugin-opcua`	OPC-UA 插件
`plantpulse-plugin-aasx`	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`	Aster TSDB, PostgreSQL, Valkey, RustFS
`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 admin-api`	管理控制台 API (截至 2026-09-03 为 «monitor»)

可接收的名称仅限于 services/order.txt 中的内容 —— storage · analytics · messaging · timeseries · cep · workflow · data-gateway · admin-api。除此之外的名称将以 unknown service 结尾。SQL 查询工具 (Kyuubi·Hive) 没有独立脚本，包含在 analytics 中。

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

请勿在数据湖内部执行应用重启脚本

restart-server.sh · restart-batch.sh · restart-warehouse.sh 虽然文件仍然存在，但它们位于主机的 bin/ 中，仅针对各应用的自有容器有效。在数据湖容器内调用会导致找不到该应用的执行文件而报 «无模块» 错误。

restart-opcua-server.sh 和 restart-aasx-server.sh 已不存在。 OPC-UA 和 AAS 分别在名为 plantpulse-plugin-opcua · plantpulse-plugin-aasx 的自有容器中运行，请直接重启容器。

docker restart plantpulse-plugin-opcua
docker restart plantpulse-plugin-aasx

Platform 更新

发布新版本时，在同一台服务器上再次运行安装单行程序。新版本的运行脚本、Compose 和镜像将一并导入，而数据将保留在卷中。

sudo -i
curl -fsSL https://product.kopens.io/plantpulse-platform/install.sh | bash

./update.sh 并非正式升级流程 —— 它仅更换镜像且无法识别新版本新增的服务。具体操作步骤和确认方法请参阅升级。

日志管理

查看日志 — `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`
Aster TSDB	`plantpulse-storage/db/cassandra/logs/system.log`
RustFS	`plantpulse-storage/object/rustfs/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`
管理控制台 API	`plantpulse-datalake-admin-api/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 技术支持团队即可进行快速分析。

Worker 管理 (集群环境)

在单主节点运行期间，若需扩展处理量，可添加 Worker 容器。Worker 列表的正本为 compose/workers.roster（每行一个 <id> <ip>），Overlay 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               # 그 다음에 컨테이너 제거

对运行中的 Worker 执行 docker rm 并非 «移除» 而是 «遗弃»

Aster TSDB 会持续持有该节点的 Token Range 和 Host ID (若 RF=3 则 QUORUM 依然成立，因此不会触发任何报警)，而主节点不会释放该 Worker 的 PostgreSQL 物理复制槽，导致 WAL 持续堆积直到磁盘满。请务必先执行 worker-decommission.sh —— 若容器正在运行，worker-remove.sh 将被拒绝。

使用脚本会自动降低 RF

worker-decommission.sh 内部会先调用 pd node rf <남는 수>。只有在手动输入 pd node remove 时才需要自行遵守顺序 → pd node rf

:::

已删除的 Worker 脚本

worker-run.sh · worker-stop.sh · worker-update.sh · worker-bash.sh 已于 2026-08-31 删除。这些脚本基于手动管理 Worker 列表而创建，在改为 Roster 模式后已废弃。替代方案分别为 worker-add.sh (含 pull)、Compose 动词、Compose pull+up -d 以及 docker exec。

详细内容请参考集群安装页面。

安装后初始 접속

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

安全指南: 为保障安全，建议在首次登录后更改默认密码。 → 初始密码

节点管理脚本 (数据湖容器内部)

Aster TSDB 及数据库管理由 plantpulse-datalake 容器内的 pd CLI (/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd) 负责。请通过 ./shell.sh 进入后使用。

Aster TSDB 管理

脚本	说明	使用时机
`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 rf` 降低 RF
`pd node rf [--check] [노드수]`	根据 Ring 调整所有 Keyspace 复制数	添加或移除节点时
`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 Topic 管理	消息巡检时
`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`	Aster TSDB CQL Shell 접속 (时序 DB)

常用命令摘要

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 점검
./remove.sh               # 컨테이너 제거 (볼륨은 보존)
./backup.sh               # 볼륨 백업 (기본 pp-data · pp-security)
./doctor.sh               # 장애 진단 tarball 생성
./passwd.sh --list        # 바꿀 수 있는 비밀번호 목록
./stack-verify-boot.sh    # 스택 전체 준비 판정

所有动词均支持 --help。

概述​

环境变量设置​

常用调整项​

启动 Platform​

初次安装后启动​

启动停止的堆栈​

启动顺序​

引导验证​

确认正常启动​

停止 Platform​

重启 Platform​

查看服务状态​

整体摘要​

运行巡检​

主机侧资源确认​

进入容器内部​

组件级重启​

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

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

Platform 更新​

日志管理​

查看日志 — logs.sh​

容器内部日志目录​

将日志复制到主机​

故障诊断​

Worker 管理 (集群环境)​

安装后初始 접속​

节点管理脚本 (数据湖容器内部)​

Aster TSDB 管理​

数据库 접속​

常用命令摘要​

概述