2节点分离安装 (数据湖 / 应用程序)

概述

PlantPulse 平台分别在数据湖节点和应用程序节点两台服务器上的安装方法。与单机(FULL)安装不同，存储·消息·分析层和控制台·批处理层运行在不同的机器上，因此大容量批处理作业(归档等)不会影响控制台响应性，且各节点的内存需求也会降低。

何时使用? 当单台服务器内存不足 128GB，或希望将数据处理负载与控制台服务分离以提高稳定性时较为适合。如果一台服务器足够(建议 256GB)，请使用单行安装的默认(FULL)安装。

层级(PP_TIER)概念

安装时通过 PP_TIER 环境变量指定节点的角色。

PP_TIER	角色	启动服务
`FULL` (默认值)	单机一体化	全部(未指定时与现有安装完全相同)
`DATALAKE`	数据湖节点	Cassandra · PostgreSQL · Kafka · MQTT · Redis · MinIO · Spark · Hive · TSE · CEP · Data Gateway · Temporal · Kestra · Monitor 等基础设施层
`APP`	应用程序节点	Server(控制台 80/443) · Batch · Warehouse · OPC-UA · AASX · HA 等应用程序层

PP_TIER 与群集变量 PP_MODE(MASTER/WORKER) 独立。
APP 节点的所有数据湖访问(主机变量)自动连接到 PP_MASTER_IP(数据湖节点 IP)。

节点间配置文件 (复制目标 vs 节点专有)

2节点安装中 /etc/kopens/ 的文件角色各不相同。什么应该复制，什么不应该复制是最重要的。

文件/目录	内容	特性	节点间复制
`/etc/kopens/plantpulse-platform.env`	服务密钥侧车(DB/消息传递密码等)	群集共享	✅ 复制目标
`/etc/kopens/ca/`	共享群集 CA(`CA.crt`/`CA.key`) — 节点间 TLS 信任	群集共享	✅ 复制目标
`/etc/kopens/platform.node.env`	节点拓扑(`PP_TIER`, `PP_MASTER_IP`) — 安装时自动记录	节点身份	❌ 禁止复制

路径确认 — 密钥侧车的正本只有一个 /etc/kopens/plantpulse-platform.env(权限 0600)。旧安装中可能在 /opt/kopens/ 下残留同名文件，但不会被读取，安装脚本会自动恢复为正本 → 环境变量参考

platform.node.env 在安装时由 stack-run.sh 自动生成并记录，正因为有此文件，重启·升级后节点才能记住自己的层级。
拓扑(PP_TIER)单独成文件而不在密钥侧车中的原因：侧车是要直接复制到应用节点的文件，如果层级信息在其中，数据湖节点的层级就会泄露到应用节点，导致应用节点误以为是 DATALAKE 安装。

节点间需求规格

节点	最小规格	备注
数据湖	16 vCPU / 64GB RAM / 500GB+ 磁盘	根据数据存储量扩展磁盘
应用程序	8 vCPU / 48GB RAM / 100GB 磁盘	实际驻留约 35GB

两个节点必须位于同一网络中，互相可达(端口列表见下文防火墙章节)。

安装步骤

第 1 步 — 数据湖节点安装

在用作数据湖的服务器上执行。

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

启动网关自动识别层级。数据湖节点需等待监控健康状态(:4950/api/health)达到 OK/WARN，并通过全栈准备判定(bin/stack-verify-boot.sh)后才视为安装成功。
安装完成后自动生成加入包：
- /etc/kopens/plantpulse-platform.env — 服务密钥(群集共享)
- /etc/kopens/ca/ — 共享群集 CA(节点间 TLS 信任)

数据湖节点是群集的 CA 发行权威。应用程序节点接收此 CA 并复用，因此节点间 TLS(CEP 事件通道)自动建立信任。

第 2 步 — 复制加入包

从数据湖节点复制两项内容到应用程序节点。

# 데이터레이크 노드에서 실행 (<app-ip> = 애플리케이션 노드 IP)
scp /etc/kopens/plantpulse-platform.env root@<app-ip>:/etc/kopens/
scp -r /etc/kopens/ca root@<app-ip>:/etc/kopens/

注意: 不能复制 /etc/kopens/platform.node.env 文件。此文件保存节点的层级身份(自己的角色)，是节点专有文件。复制目标仅为上述两项(节点间配置文件参考)。

如果是旧版本安装过的服务器，platform.env.generated 内可能遗留 export PP_TIER=... 行。最新安装脚本会自动删除(迁移)，但复制前手动删除此行更安全。

第 3 步 — 应用程序节点安装

在应用程序节点上执行。在 PP_MASTER_IP 中指定数据湖节点 IP。

sudo -i
export PP_TIER=APP
export PP_MASTER_IP=<datalake-node-ip>
curl -fsSL https://product.kopens.io/plantpulse-platform/install.sh | bash

stack-run.sh 在首次启动前自动将加入包中的共享 CA(/etc/kopens/ca/)应用(seed)到 pp-security 卷。之后认证证书准备阶段用共享 CA 签署该节点的证书并构成信任库，数据湖节点的 TLS 服务(CEP 事件通道等)自动建立信任。
所有数据湖后端(Cassandra/PostgreSQL/Kafka/Redis/MinIO/TSE/CEP 等)的访问自动设置为 PP_MASTER_IP。
应用节点没有监控(:4950)，启动网关基于控制台(:80/status) 200 响应判定。

防火墙 (数据湖节点)

需允许应用程序节点访问数据湖节点。最简单的方法是在 firewalld 的 trusted 区域添加应用程序节点 IP。

# 데이터레이크 노드에서 실행
firewall-cmd --permanent --zone=trusted --add-source=<app-ip>
firewall-cmd --reload

主要跨节点端口: 9042(Cassandra) · 5432(PostgreSQL) · 9092/9093/9094(Kafka) · 1883/1884(MQTT) · 6379(Redis) · 9000(MinIO) · 7077(Spark) · 9083(Hive) · 10000(Kyuubi) · 19001(Gravitino) · 7800/7801(TSE) · 7400(CEP) · 5500(Data Gateway) · 7233(Temporal) · 4950(Monitor)

安装验证

# 데이터레이크 노드 — 인프라 헬스 (OK 또는 WARN 이면 정상)
curl -kfsS https://127.0.0.1:4950/api/health | jq .status

# 애플리케이션 노드 — 콘솔 상태
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:80/status   # 200 이면 정상

网页控制台访问: https://<app-node-ip> — 必须成功登录才是最终验证(初始账户见登录)。

跨节点 TLS (共享 CA) 验证

在两个节点上都输出 CA 指纹，验证是否相同。指纹不同表明节点间 TLS 信任已断裂。

CA 材料在 pp-security 卷中，需在挂载此卷的容器内读取。各节点查询的容器不同 — 数据湖节点有 plantpulse-datalake，应用节点没有。

# 데이터레이크 노드에서
docker exec plantpulse-datalake \
  openssl x509 -in /var/security/plantpulse/CA.crt -noout -fingerprint -sha256

# 애플리케이션 노드에서 (앱 컨테이너면 무엇이든 같은 볼륨을 읽습니다)
docker exec plantpulse-server-web \
  openssl x509 -in /var/security/plantpulse/CA.crt -noout -fingerprint -sha256

检查应用程序节点日志中是否有 TLS 信任错误(PKIX)0 条。

# 애플리케이션 노드에서 — 아무 것도 출력되지 않아야 정상
grep -Rl "PKIX" /opt/kopens/plantpulse-platform-docker/logs 2>/dev/null

数据湖连接验证

在应用程序节点上验证数据湖连接：

应用容器没有数据湖的配置渲染器，也不读取那边的 env.sh。应用看到的值的唯一定义来源是 compose，因此直接查看实际注入容器中的环境变量。

# 애플리케이션 노드에서 — 백엔드 호스트가 데이터레이크 IP 로 잡혀 있는지
docker exec plantpulse-server-web env | grep -E '_HOST=|MASTER_IP='

若值为 127.0.0.1 表示安装时未指定 PP_MASTER_IP。

重启·升级时行为

层级身份保存在各节点的 /etc/kopens/platform.node.env 中，重启·升级后会保留。除非重新安装，否则无需再次指定 PP_TIER。
容器镜像升级按节点采用既有步骤(update.sh)相同。

层级转换·重新安装时注意

重新安装为单机(FULL)时必须先删除 /etc/kopens/platform.node.env。此文件残留会导致环境设置自动读取它，以前一个层级(DATALAKE/APP)启动。未指定 PP_TIER(FULL)的安装不会覆写此文件。
```
rm -f /etc/kopens/platform.node.env
```
将 APP 节点转换为 FULL(单机)时需清洁重新安装。APP 节点从未初始化过本地基础设施(数据库架构等)，需删除全部容器·卷·配置后从头以 FULL 安装(删除步骤见Docker 安装的完全删除章节)。

故障排查

症状	原因/处置
APP 节点服务尝试以 `127.0.0.1` 方式连接	`PP_MASTER_IP` 未指定安装 — 检查 node.env 后重新安装
重新安装后仍以旧层级启动	`/etc/kopens/platform.node.env` 残留 — 删除后重新安装(层级转换·重新安装时注意)
应用节点以 DATALAKE 身份安装	旧版侧车残留 `PP_TIER` 行状态下被复制 — 在侧车中删除该行后重新安装
CEP 事件 TLS 错误(PKIX)	加入包中 `ca/` 复制遗漏(CA 指纹不匹配) — 重新执行第 2 步，然后重新安装 APP 节点
APP 节点 Kafka 发布失败(Expiring records)	数据湖防火墙未允许 APP 节点，或使用旧版安装脚本 — 检查防火墙后用最新脚本重新安装
登录页面出错	APP 节点启动初期数据湖连接延迟 — 重启控制台容器(`docker compose -f compose/docker-compose.yml restart plantpulse-server-web`)

概述​

层级(PP_TIER)概念​

节点间配置文件 (复制目标 vs 节点专有)​

节点间需求规格​

安装步骤​

第 1 步 — 数据湖节点安装​

第 2 步 — 复制加入包​

第 3 步 — 应用程序节点安装​

防火墙 (数据湖节点)​

安装验证​

跨节点 TLS (共享 CA) 验证​

数据湖连接验证​

重启·升级时行为​

层级转换·重新安装时注意​

故障排查​

概述