Docker 安装

概述

本页指导如何通过 Docker Compose 堆栈 以 手动（分步）方式安装 PlantPulse 平台。

在一般环境下，建议使用一键安装。一键安装可一次性完成从软件包下载、环境自动检测、安装到启动验证的所有流程。仅在以下情况下请使用本页的手动步骤：

必须直接审查并批准每个安装步骤的情况（如安全审查、变更管理流程等）
需要将环境变量 (bin/env.sh) 直接指定为非自动检测值的情况
在禁止互联网访问的隔离网络环境中安装的情况 → 隔离网络安装

安装架构 — 九个容器

平台通过 一个 docker compose 堆栈 运行。正本为 compose/docker-compose.yml，所有运行脚本均通过此文件管理容器。

容器	层级	角色
`plantpulse-certs`	证书	生成 TLS 资源并持续运行以监控过期。`(healthy)` 为正常状态
`plantpulse-datalake`	基础设施	存储 · 消息 · 分析 · CEP · SQL · 监控
`plantpulse-server-web`	应用程序	Web 控制台
`plantpulse-batch-web`	应用程序	批处理
`plantpulse-warehouse-web`	应用程序	数据仓库
`plantpulse-plugin-opcua`	应用程序	OPC-UA 服务器插件 (11004 / 11005)
`plantpulse-plugin-aasx`	应用程序	AASX 服务器插件
`plantpulse-ha`	应用程序	冗余恢复守护进程 (10210)
`plantpulse-proxy`	Edge	用户唯一的入口 (80 / 443 / 1883 / 1884)

常驻容器共有八个

在 docker ps 中，若 全部九个均显示为 (healthy) 即为正常。

此外，compose 中定义了用于镜像的 plantpulse-mirror-maker，但因绑定在 mirror 配置文件中，默认不会启动。

原单容器配置已移除

在 2026-08-29 之前，可以选择所有组件在单个 plantpulse-platform 容器中共同运行的«单体»配置。该配置已被废弃，相关选择变量 (PP_TOPOLOGY) 和 compose 文件也已删除。现在无需选择 — bin/up.sh 将启动上述堆栈。

残留在旧版运行手册中的 docker logs plantpulse-platform 等命令 由于不存在该名称的容器而无法运行。替代命令请参阅运行命令汇总。

将每个应用分开容器的首要目的是 OOM 隔离。即使某个应用耗尽内存，其他应用和基础设施仍能保持运行，并可按应用单位进行重启或回滚。

准备工作

在开始安装前，请确认以下事项。

项目	要求
账户权限	root (或 sudo 权限)。安装脚本将配置 OS 设置和 Docker 守护进程
操作系统	RHEL · Rocky Linux · Oracle Linux 8.x · 9.x · 10.x, Ubuntu 20.04+, Amazon Linux 2/2023
Docker	需要 Compose v2 (`docker compose` — 不带连字符形式)。若无 `install.sh` 则需安装
数据磁盘	建议在 `/data1` 路径挂载大容量磁盘 — Docker 数据 (`/data1/docker-data`) 和平台数据卷将使用此路径
注册表访问	必须能够通过 HTTPS 访问 `docker.kopens.io` (镜像注册表) 和 `product.kopens.io` (安装包)。禁止访问的环境请使用隔离网络安装
注册表凭证	`docker.kopens.io` 登录凭证 (由 KOPENS 运营团队发放)

磁盘路径指南：若无独立数据磁盘，在根磁盘创建 /data1 目录亦可运行，但生产环境建议将专用磁盘挂载至 /data1。

手动安装步骤

第 1 步：下载安装包

从下载服务器获取安装包 (tar.gz) 并解压至标准路径。无需 Git clone 或安装其他工具。

sudo -i

# 표준 설치 경로 생성 후 패키지 다운로드 + 압축 해제
mkdir -p /opt/kopens/plantpulse-platform-docker
curl -fsSL "https://product.kopens.io/plantpulse-platform/plantpulse-platform-docker.tar.gz" \
  | tar -xz -C /opt/kopens/plantpulse-platform-docker --strip-components=1

cd /opt/kopens/plantpulse-platform-docker/bin
chmod +x *.sh tools/*.sh

安装包中实际使用的位置有两处：

位置	包含内容
`bin/`	所有安装及运行脚本
`compose/`	堆栈正本 `docker-compose.yml` 和集群工作节点覆盖层

第 2 步：预检 (preflight)

preflight.sh 在 完全不变更系统 的情况下仅确认是否可安装。

./preflight.sh

巡检项目：

Docker 安装/守护进程运行状态 (即使未安装也可 — install.sh 将负责安装)
Docker data-root 上级路径 (/data1) 是否存在
Secret Sidecar (/etc/kopens/plantpulse-platform.env) 是否存在
主要运行端口 (80, 443, 4949, 4950) 是否被占用

仅出现 OK 时即可进入下一步。若出现 ERROR，请参考问题解决。(WARN 仅供参考，不影响安装。)

第 3 步：环境变量审查 (env.sh)

bin/env.sh 决定宿主机侧值的 默认值，运行者修改的值则写在 Sidecar /etc/kopens/plantpulse-platform.env 中。容器实际可见的值由 compose/docker-compose.yml 决定 — 详细关系请参考环境变量参考。

vi /etc/kopens/plantpulse-platform.env

请勿修改安装树内部

写在 bin/env.sh 中的值在 重新安装或升级时会丢失。安装脚本会删除安装树并重新下载。

资源值大多为«计算»得出 — 几乎无需修改

env.sh 会根据宿主机情况自行决定 CPU、内存和磁盘。由于并非固定默认值，即使不干预，在小型设备上也会自动分配较小的值。为设备单独指定的值将始终生效。

变量	如何确定	何时修改
`DOCKER_PP_CPUS`	`nproc` (读取失败时使用 `8`)	希望减少分配给容器的核心数时
`DOCKER_PP_CLUSTER_CORES`	`DOCKER_PP_CPUS - 2`, 最小 4 · 最大 30	通常保持默认
`DOCKER_PP_MEMORY`	宿主机 RAM 的 90%, 最小 `8G`	希望为 OS 预留更多内存时
`DOCKER_DATALAKE_MEMORY`	`96G` (最小值)。上限为宿主机 RAM 的 90% — 宿主机低于 107G 则规格不足	仅在增加时修改。不可低于 96G
`DOCKER_PP_DATA_DISK_NAME`	自动反向追踪承载 `/` 的实际磁盘 (失败时使用 `sda`)	自动检测错误时
`PP_LANG`	`en`	韩语运行环境请使用 `ko`
`PP_TZ`	`Asia/Seoul`	海外设备
`DOCKER_PP_EXTERNAL_IP`	空值	仅在 NAT 环境中需告知外部公网 IP 时使用

请勿在 DOCKER_PP_EXTERNAL_IP 中输入无效 IP

该值经由 PP_SERVICE_IP 进入 TLS 证书的 SAN 列表。若包含任何格式不正确的 IP，openssl 将拒绝整个扩展文件，导致 无法生成任何证书，从而无法启动堆栈。若非处于 NAT 之后，请 保持为空 — 这即是默认值。

当前服务器的值可通过以下命令确认：

hostname -I | awk '{print $1}'          # 서버 IP
free -g | awk '/^Mem:/{print $2"G"}'    # 전체 메모리
nproc                                    # CPU 코어 수
lsblk                                    # 디스크 이름 (sda, sdb, nvme0n1 …)

在韩语运行设备中，通常只需修改两行：

export PP_LANG=ko
export PP_TZ=Asia/Seoul

Locale 仅在启动时生效

PP_LANG / PP_TZ 在 JVM 启动时固定。若要在已运行的堆栈中更改，需要 ./restart.sh。此外，由于 Aster TSDB 时序数据以 KST epoch 存储，韩国运营环境请维持 Asia/Seoul。

第 4 步：执行安装 (install.sh)

sudo ./install.sh

单个 install.sh 将自动执行整个安装过程：

OS 检测与系统设置 — 文件限制 (limits)、内核参数 (sysctl)、时间同步 (chrony)、SELinux 转为 permissive、禁用 swap
Docker Engine 安装 — 使用各 OS 包管理器安装 + 将 data-root 配置为 /data1/docker-data (若无 Compose v2 则同步安装)
防火墙设置 — 开放公开端口 (80/443/4949/4950)，限制内部端口仅限私有网段访问
服务凭证生成 — 创建 /etc/kopens/plantpulse-platform.env Secret Sidecar (权限 0600, 重执行不覆盖原值)
注册表登录 — 输入 docker.kopens.io 凭证 (已登录则自动跳过)
堆栈启动 — 创建网络/卷 → pull 镜像 → 填充配置模板 → docker compose up -d

安装时的单次选项 (仅在需要时通过环境变量指定)：

选项	效果
`SKIP_OS=1`	跳过 OS 设置与 Docker 安装 (Docker 已安装且运行中)
`SKIP_LOGIN=1`	跳过注册表登录 (已登录或镜像已在本地)
`SKIP_FW=1`	跳过防火墙设置 (由单独的防火墙管理)
`DOCKER_DATA_DIR=<path>`	更改 Docker data-root (默认 `/data1/docker-data`)

# 예: Docker가 이미 설치된 서버
SKIP_OS=1 sudo -E ./install.sh

更换凭据必须在«安装前»进行

Secret Sidecar (/etc/kopens/plantpulse-platform.env) 采用 export VAR=값 形式的强制赋值，优先级高于 Shell export。在安装完成的节点上，PP_PG_PASSWORD=... ./up.sh 将被静默忽略。交付时更换请在安装前通过 export PP_*_PASSWORD=... 进行；安装完成后请通过密码轮转的 passwd.sh 进行。

第 5 步：启动与引导验证

install.sh 启动堆栈后即返回。必须单独确认引导是否完成。

./up.sh

up.sh 是幂等的，即使已启动也安全，且会 等待直至准备就绪。退出码 0 不代表«命令成功»，而是代表 «现在可以使用»。

环境变量	默认值	含义
`PP_READY_TIMEOUT`	`900`	准备等待上限 (秒)
`PP_READY_INTERVAL`	`15`	确认间隔 (秒)
`PP_WAIT=0`	—	不等待。此时的 `0` 不代表准备就绪

首次纯净安装耗时 15~18 分钟

进程启动本身需 3~~5 分钟 (JVM Warm-up)，但 **直到所有组件稳定需 15~~18 分钟**。Aster TSDB 模式迁移与稳定化最为缓慢。重启时因模式已存在，速度会快得多。

实测标准 (2026-08-31, 32 vCPU / 128GiB): Data Lake 217秒, Web Server 316秒。

也可以手动运行准备判定：

./stack-verify-boot.sh

该脚本 并非检查单个容器，而是检查整个堆栈 — 确认九个容器是否 running · healthy，以及代理是否在服务 443 端口。

第 6 步：状态与运行巡检

./status.sh      # 0 = 정상 / 2 = 비정상
./ops-check.sh

status.sh 汇总服务列表 · 容器状态 · health · 卷。退出码即为判定结果 — 可直接用于自动化。

判定	视为异常的情况
无法读取服务列表	compose 解析失败或无法访问 docker
compose 声明的服务缺失容器	未启动
容器状态非 `running`	全部九个应为常驻运行 — 无排除对象
常驻容器 health 为 `unhealthy`	`starting` / `none` 为判定保留
Health API 非 OK	在 Data Lake 内部进行探测 (probe)

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

ops-check.sh 在此基础上还会扫描最近的严重日志 (OOM, FATAL, SSL 错误等)。

健康检查

监控 API 由 plantpulse-datalake 容器提供服务。根据询问位置不同，命令有所区别。

# 컨테이너 안에서 — 어떤 구성에서도 동작하는 방법
docker exec plantpulse-datalake curl -kfsS https://127.0.0.1:4950/api/health | jq

# 호스트/외부에서 — 4950 이 publish 되어 있습니다
curl -kfsS https://<server-ip>:4950/api/health | jq

"status" 为 OK 或 WARN 时为正常范围，为 FAIL 时为故障。

无法通过其他端口查看 Health

控制台与 Health API 在两个端口 均提供服务 — 4950 (HTTPS) 和 4949 (明文 HTTP)。两者为同一控制台 · 同一 API，仅协议方案不同。4949 不再重定向至 4950。

4949 为明文 — 登录密码和会话 Cookie 将以明文传输。在不可信网络中请使用 4950。4949 仅适用于自签名证书警告确实会阻碍运行者操作的设备。

安装产物

网络与卷

资源	名称	用途
网络	`pp-net`	平台专用 Docker 网络 (默认 `10.99.0.0/24`, 网关 `10.99.0.1`)
卷	`pp-data`	数据持久化存储 (Aster TSDB, PostgreSQL, Kafka 等)
卷	`pp-temp`	临时数据 (Spark, Hive 工作空间)
卷	`pp-backup`	备份存储
卷	`pp-security`	TLS 证书 · Keystore。仅 `plantpulse-certs` 可写，其余只读
卷	`pp-proxy-certs`	代理在 443 端口使用的证书

即使停止或删除容器，卷 始终被保留，因此在更新或重新安装时数据依然存在。

宿主机目录

路径	用途
`/opt/kopens/plantpulse-platform-docker`	安装 · 运行脚本与 compose 正本
`/etc/kopens/conf`	平台配置模板 (宿主机绑定挂载)。首次执行时从镜像自动填充，后续可由运行者直接编辑，重新安装亦保留
`/etc/kopens/plantpulse-platform.env`	服务凭据 Secret Sidecar (权限 0600)
`/etc/kopens/platform.node.env`	节点唯一标识 (IP · 磁盘等该设备特有值)。禁止节点间复制
`/etc/kopens/ca`	共享集群 CA (用于 2 节点分离安装)

访问地址

用途	地址
Web 控制台	`http://<server-ip>/` · `https://<server-ip>/` — 由 `plantpulse-proxy` 接收
管理 UI	`https://<server-ip>` (与 Web 控制台地址相同)
监控 UI · Health	`https://<server-ip>:4950/api/health`
MQTT	`<server-ip>:1883` (明文) · `<server-ip>:1884` (TLS)
OPC-UA	`<server-ip>:11004` · `<server-ip>:11005`

安全指南：Web 控制台首次登录后，请务必更改默认管理员密码。 → 初始密码

运行命令汇总

日常运行使用的命令。均在 /opt/kopens/plantpulse-platform-docker/bin/ 中执行。所有动词均支持 --help。

操作	命令	备注
状态巡检	`./status.sh`	服务 / health / 卷汇总。0=正常 / 2=异常
运行巡检	`./ops-check.sh`	容器 health + Health API + 最近严重日志
启动	`./up.sh`	幂等。0 = 准备就绪
停止	`./down.sh`	保留状态
重启	`./restart.sh`	graceful drain → 停止 → 启动 → 等待就绪
查看日志	`./logs.sh [서비스]`	打印最后 200 行后结束。实时追踪请使用 `-f`。无参数则显示所有容器。列表见 `--list`
进入容器	`./shell.sh [서비스]`	无参数则进入 Data Lake
版本升级	重新运行安装 One-liner	非 `./update.sh` — 请参阅升级
完全移除	`./remove.sh`	仅移除容器 (保留卷 · 配置)。`RM_IMAGE=1` / `RM_NETWORK=1`
备份	`./backup.sh [볼륨 …]`	默认 `pp-data` · `pp-security`
引导验证	`./stack-verify-boot.sh`	整个堆栈准备就绪判定
诊断包	`./doctor.sh`	技术支持用 tarball。敏感值将被脱敏
密码修改	`./passwd.sh --list`	可修改的 Key 列表

# 운영 중 빠른 점검 루틴
cd /opt/kopens/plantpulse-platform-docker/bin
./status.sh
./ops-check.sh

# 문제가 의심되면 진단 번들 생성
./doctor.sh

旧名称依然有效

stack-run.sh · stack-stop.sh · stack-bash.sh · stack-update.sh · stack-remove.sh 尚未删除。直接执行仅会提示新名称，功能不变。无需一次性修改现有客户的手册。

注意 — 删除所有卷：./tools/remove-all-volumes.sh 将永久删除所有数据。请务必在完成备份后使用。

隔离网络安装

隔离网络安装已移至 隔离网络安装。有关 Bundle 包含内容、airgap-bundle.sh 的环境变量以及 airgap-load.sh 在安装前拦截的项目，请参阅该页。

问题解决

preflight 巡检失败

消息	处理措施
`docker is installed but daemon is not ready while SKIP_OS=1`	请先启动 Docker 守护进程: `systemctl start docker`。或在不带 `SKIP_OS` 的情况下执行，由 `install.sh` 配置 Docker
端口已被占用 (WARN)	该端口正被其他服务使用。请通过 `ss -tlnp \| grep :<port>` 确认进程并在安装平台前清理
缺少 Docker data-root 上级路径 (WARN)	`/data1` 目录不存在。请将数据磁盘挂载至 `/data1` 或创建该目录

堆栈无法启动

docker compose up -d 会等待 depends_on 所有条件满足，因此若有一个容器未通过健康检查，整个命令将仅剩一行输出并失败。

dependency failed to start: container plantpulse-server-web is unhealthy

此行输出除容器名称外不提供其他信息。此时运行脚本会自动输出 容器列表 · 状态 · health probe 输出 · 各日志尾部，请先阅读该输出。如需手动确认：

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

# 어떤 컨테이너가 어떤 상태인가
./status.sh

# 문제가 있는 컨테이너의 로그
./logs.sh --list                       # 볼 수 있는 서비스 목록
./logs.sh plantpulse-server-web -n 200

# 자원 상황
df -h
docker stats --no-stream

常见原因：

原因	确认方式
内存不足 (OOM)	`docker inspect <컨테이너> --format '{{.State.OOMKilled}}'`。各应用 `mem_limit` 请参考环境变量参考
磁盘空间满	`/data1` 剩余空间
缺失必要凭据	compose 要求密码为 `:?`。若为空，堆栈完全无法启动 — 请先执行 `install.sh` 创建 Sidecar
数据库初始化延迟	首次安装因创建 Schema 耗时较长。若日志中无错误且正在进行，请稍作等待

若难以确定原因，请通过 ./doctor.sh 生成诊断包并随技术支持请求发送。诊断包包含 所有容器 的状态与日志。

TLS 握手仅显示为 `TimeoutException` 时

若应用连接后端的名称不在证书 SAN 列表中，错误消息中将完全不提及证书，表现为超时。若更改了容器名称或直接指定了后端宿主机，请怀疑此原因。证书重新生成方法请参阅安全管理。

注册表认证失败

# unauthorized 오류 시 재로그인
docker login docker.kopens.io

若无登录凭证或凭证过期，请请求 KOPENS 运营团队发放。
公司内部防火墙可能会拦截注册表访问。请请求网络管理员允许 HTTPS 访问 docker.kopens.io 和 product.kopens.io 域名。
在源头禁止外部访问的环境中，请使用隔离网络安装。

技术支持

如果在安装或运行过程中需要帮助，请随时联系：webmaster@kopens.com

概述​

安装架构 — 九个容器​

准备工作​

手动安装步骤​

第 1 步：下载安装包​

第 2 步：预检 (preflight)​

第 3 步：环境变量审查 (env.sh)​

第 4 步：执行安装 (install.sh)​

第 5 步：启动与引导验证​

第 6 步：状态与运行巡检​

健康检查​

安装产物​

网络与卷​

宿主机目录​

访问地址​

运行命令汇总​

隔离网络安装​

问题解决​

preflight 巡检失败​

堆栈无法启动​

TLS 握手仅显示为 TimeoutException 时​

注册表认证失败​

技术支持​

概述