原生安装 — 不使用容器，直接安装到主机

本页介绍在不使用 Docker、直接在主机操作系统上以原生（native）方式安装并运行 PlantPulse Edge 的方法。网关运行时（Tomcat / Cassandra / Redis / HiveMQ / Time-Series-Engine / Node-RED）分别作为主机进程启动，由一个 plantpulse.service (systemd) 管理整个技术栈。

何时使用原生方式

开发 / 调试工作站 — 直接上传代码，通过 JSP / 类热替换快速验证
2026.05 之前的 legacy 设备维护 — 已在以 native 方式运行的现场
安全策略不允许使用 Docker 的环境

新建量产/现场单机安装的标准是容器模式 → 快速安装 (install.sh) / Docker（容器）安装详解。

请勿在同一台设备上混用 native 与容器

原生方式使用 plantpulse.service，容器方式使用 plantpulse-edge.service。若同时启动这两个服务，80/443/1880/9042/12000 等端口以及 /data1 数据路径会发生冲突。若 systemctl is-active plantpulse-edge.service 为 active，则该设备属于容器设备 — 在启动原生方式之前，务必先 stop/disable 其中一方。

1. 运行时模型 — 什么在如何运行

原生模式将构成网关的7 个组件分别作为主机进程运行。编排由 $PE_HOME/bin/ 中的 bash 脚本负责，各组件在各自目录下拥有 bin/start.sh / bin/stop.sh。

组件	作用	目录
Redis (`cache`)	点位队列 (Redisson)	`$PE_HOME/cache/`
HiveMQ (`mqtt`)	MQTT broker / Sparkplug B	`$PE_HOME/mqtt/`
Cassandra (`db`)	时序存储 (`pe` keyspace)	`$PE_HOME/db/`
Time-Series-Engine (`tse`)	时序引擎	`$PE_HOME/timeseries/engine/`
Dashboard	仪表板	`$PE_HOME/timeseries/dashboard/`
Tomcat (`server`)	webapp `plantpulse-edge-web`（采集/REST/OPC-UA/UI）	`$PE_HOME/server/`
Node-RED (`node`)	流程 (`/ui/flow`)	`$PE_HOME/node/`

启动顺序（依赖顺序）— bin/start.sh 按此顺序启动：

cache → mqtt → db → tse → dashboard → server → node

通过 HTTP 80 / HTTPS 443 提供 Web UI 与 REST API（非 8080）
JVM 为 JDK 21（class file version 65）— Spring MVC 6.2 (non-boot)
graceful shutdown：ServerStartListener 依次清理 collector → Redisson → OPC → Cassandra 后 Runtime.halt(0)。截止时间 watchdog（-Dplantpulse.edge.shutdown.deadline.ms，默认 9000ms）可防止 STOP_TIMEOUT 竞态。

2. 目录结构 (`$PE_HOME = /opt/kopens/plantpulse-edge`)

$PE_HOME/
├── app/plantpulse-edge-web/      # webapp (WEB-INF/classes·jsp·lib + public)
├── bin/                          # 오케스트레이션 스크립트 (아래 6장)
│   ├── start.sh / stop.sh        # full stack — cache→mqtt→db→tse→dashboard→server→node
│   ├── restart.sh                # Tomcat(server) + Node-RED 만
│   ├── lifecycle-lib.sh          # pp_log / pp_wait_port / run_module_start 헬퍼
│   ├── upgrade.sh / firmware.sh / backup.sh / clean.sh / reboot.sh
│   └── log-viewer.sh / node-*.sh
├── conf/                         # canonical 설정 (운영자 편집)
│   ├── app.properties            # webapp 설정 (이 박스가 canonical)
│   └── env.sh                    # JAVA_HOME / PP_LANG / PP_TZ / PE_DATA_DIR …
├── server/                       # Tomcat (bin/ conf/ logs/)
│   ├── bin/setenv.sh             # JVM 옵션 / LOCALE / -Dpe.conf.dir
│   ├── conf/server.xml           # Connector(80/443) / Context
│   └── logs/                     # catalina.out / system.log / api.log / driver.log
├── cache/   → Redis              (bin/start.sh / stop.sh)
├── db/      → Cassandra          (bin/start.sh / stop.sh)
├── mqtt/    → HiveMQ             (bin/start.sh / stop.sh)
├── timeseries/engine/ + dashboard/
└── node/    → Node-RED           (userDir/node_modules/node-red-contrib-plantpulse-edge/)

数据目录分离到 $PE_DATA_DIR（默认 /data1）（Cassandra SSTable / Redis AOF / HiveMQ / Node-RED userDir）。

3. 前置要求 (native)

项目	标准
OS	Linux（推荐 RHEL/Rocky/Alma/Fedora 系列）
权限	root (`sudo -i`)
JDK	OpenJDK 21 (`dnf install java-21-openjdk java-21-openjdk-devel`) — 兼容 class file 65
Node.js	用于 Node-RED (`nodejs` / `npm`)
Python 3	辅助脚本
磁盘	`/opt/kopens` 3GB+，`/data1` 建议 100GB+
内存	最低 8GB（Cassandra heap + Tomcat heap），建议 16GB+
NIC	工业设备标准 2 个（1=WAN/外部，2=PLC/内部）
时间	NTP(chrony) 同步

OS / 软件包 / 网络自动配置请用 setup.sh

另有一款自动 native 安装工具，可一次性处理 OS 软件包、sysctl/limits、防火墙、chrony、 NIC 静态地址、SSL 签发、systemd 注册 → (legacy) H/W 完整安装 (tools/setup.sh)。本页讲解该工具所部署的运行时结构以及手动/调试启动流程。

4. 安装步骤

4.1 自动（推荐）— `tools/setup.sh`

如果是刚完成 OS 启动的空白设备，自动安装工具会一次性完成软件包 · 网络 · 调优 · JDK · systemd 的配置。逐步输入项（主机名、NIC、防火墙端口）及 22 个步骤的详情完全遵循 (legacy) H/W 完整安装。

sudo -i
cd /opt/kopens/tools
./setup.sh          # 대화형 — 호스트명 + NIC 입력 후 진행, 끝나면 10초 후 자동 reboot

重启后 plantpulse.service 会自动启动整个技术栈。

4.2 手动 / 调试 — 仅部署运行时

当在已准备好 OS / JDK 21 / 网络的设备（或开发工作站）上仅部署运行时时：

sudo -i

# 1) 런타임 배치를 $PE_HOME 에 펼침 (운영팀 제공 native bundle 기준)
#    /opt/kopens/plantpulse-edge/{app,bin,conf,server,cache,db,mqtt,timeseries,node}

# 2) 환경 파일 확인 — JDK 21 / 언어 / 시간대 / 데이터 경로
cat $PE_HOME/conf/env.sh
#   export JAVA_HOME=/usr/lib/jvm/java-21-openjdk
#   export PP_LANG="${PP_LANG:-en}"  / export PP_TZ="${PP_TZ:-Asia/Seoul}"
#   export PE_DATA_DIR=/data1
#   (상세: env 환경 설정 페이지)

# 3) 메인 설정 — 사이트/플랫폼/DB/MQTT 값
vi $PE_HOME/conf/app.properties     # edge.id / edge.site_id / server.host / cassandra.* …

# 4) 풀스택 기동 (cache→mqtt→db→tse→dashboard→server→node)
$PE_HOME/bin/start.sh

env.sh / app.properties 环境变量分层详情见 env 环境配置， app.properties 全部键值见 app.properties 指南。

5. systemd 集成 — `plantpulse.service`

安装完成后，systemd 会自动管理整个技术栈。

sudo systemctl enable  plantpulse        # 부팅 시 자동 시작 등록
sudo systemctl start   plantpulse        # 시작 (ExecStart → service-start.sh → bin/start.sh)
sudo systemctl stop    plantpulse        # 정지 (ExecStop  → service-stop.sh  → bin/stop.sh)
sudo systemctl status  plantpulse        # 상태
sudo systemctl restart plantpulse        # 풀스택 재시작 (60초+ 다운타임)
sudo journalctl -u plantpulse -n 100     # systemd 로그 마지막 100줄

内部 wiring：

plantpulse.service ─ ExecStart=service-start.sh ─→ bin/start.sh   (cache→mqtt→db→tse→dashboard→server→node)
                   └ ExecStop =service-stop.sh  ─→ bin/stop.sh

仅需应用代码 / app.properties 变更时，请用 restart.sh 而非重启整个栈

bin/restart.sh 仅重启 Tomcat(server) + Node-RED（约 6 秒，保持 Cassandra/Redis 运行）。应用 app.properties 的修改或更新 webapp 时请使用它。 systemd 的 restart 是 stop.sh → start.sh 全栈重启，会造成 60 秒以上的停机。详情：重启 (restart.sh)。

6. bin 脚本目录

脚本	范围	备注
`bin/start.sh`	全栈启动	cache→mqtt→db→tse→dashboard→server→node
`bin/stop.sh`	全栈停止	调用各组件的 stop.sh，超过 `STOP_TIMEOUT_SECONDS`（默认 10s）时 `kill -9`
`bin/restart.sh`	仅 Tomcat + Node-RED	约 6 秒，用于应用代码/配置
`bin/backup.sh`	配置备份	备份指南
`bin/upgrade.sh`	升级	升级
`bin/clean.sh`	清理工作目录	整理/清理
`bin/reboot.sh` / `firmware.sh`	主机 reboot / 固件	—
`bin/log-viewer.sh`	tail 查看 7 个组件日志	无限 `tail -f` — 自动化/非交互 SSH 中禁止直接调用（会话挂起）

各 run() 通过 catch(Throwable) 守护 + awaitTermination 安全退出。

7. 安装后正常运行确认（1 分钟）

# 1) systemd 서비스 살아있는지
systemctl status plantpulse        # active (running)

# 2) 시스템 헬스 — HTTP 200 이면 게이트웨이 정상
curl -s http://127.0.0.1/api/v1/system/health | python3 -m json.tool

# 3) OPC-UA 트리 (등록 0 이어도 빈 배열이면 OK)
curl -s http://127.0.0.1/ui/opcua/tree | python3 -c 'import sys,json;print(len(json.load(sys.stdin)["data"]["tree"]))'

# 4) 웹 UI
#    브라우저 → https://<gateway>/ui/main   (로고 + 카드가 보이면 정상)

日志全面检查 — 不仅要看 catalina.out（启动失败）+ system.log（ERROR/Exception），还要检查 7 个组件（server/cache/db/mqtt/tse/dashboard/node）的日志中是否存在 SEVERE/ERROR。自动化场景中请勿使用 log-viewer.sh（无限 tail），而应用 tail -n / timeout 以有界方式读取各 logs/*.log。

启动竞态（罕见）

若重启后 ServerStartListener 静默失败导致 collector 未完成（OPC 计数为 0），再执行一次 restart.sh。但 /api/v1/system/health 的 data.monitor=null（+ data.api_client=null）并非竞态，而是设计如此（HealthResponse.livenessWithComponents 会将这两个字段留空）。

8. 常见陷阱

现象	原因 / 解决
`UnsupportedClassVersionError` (class file 65)	未安装/未指定 JDK 21。检查 `env.sh` 中的 `JAVA_HOME=/usr/lib/jvm/java-21-openjdk`
UI 语言与预期不符(ko/en)	`setenv.sh` 的 `-Duser.language` 优先于 `JAVA_TOOL_OPTIONS`。参考 env 环境配置中的 LOCALE 动态化
`connect ECONNREFUSED 127.0.0.1:80`	Tomcat 未启动。执行 `bin/restart.sh` 或 `bin/stop.sh`+`start.sh`
端口/数据冲突	同一设备上 `plantpulse-edge.service`（容器）也处于 active。stop/disable 其中一方
停止时出现 `kill -9`	cleanup（约 10s）与 `STOP_TIMEOUT_SECONDS`（10s）产生竞态。已通过 deadline watchdog 缓解。若需完全 clean，使用 `STOP_TIMEOUT 25 + deadline 20000`
重启后未启动	用 `journalctl -u plantpulse --no-pager` 查看 unit 失败原因 → 直接执行 `bin/start.sh` 确认卡在哪一步

9. 后续文档

env 环境配置 — env.sh / PP_LANG / PP_TZ / -Dpe.conf.dir
Docker（容器）安装详解 — 量产标准部署
(legacy) H/W 完整安装 (tools/setup.sh) — 自动 native 安装 22 步骤
app.properties 指南 — 主配置键全集
重启 (restart.sh) / 启动 (start.sh) / 停止 (stop.sh)
安装后检查清单 / 生产验收标准

1. 运行时模型 — 什么在如何运行​

2. 目录结构 ($PE_HOME = /opt/kopens/plantpulse-edge)​

3. 前置要求 (native)​

4. 安装步骤​

4.1 自动（推荐）— tools/setup.sh​

4.2 手动 / 调试 — 仅部署运行时​

5. systemd 集成 — plantpulse.service​

6. bin 脚本目录​

7. 安装后正常运行确认（1 分钟）​

8. 常见陷阱​

9. 后续文档​