升级

将 Platform 升级到新版本的官方唯一方法是在同一台服务器上重新运行安装单行命令（One-liner）。 无需删除或清理，直接重新执行。新版本的运行脚本、compose 和镜像将一同导入， 并在此时启动新版本中新增的服务（例如：现场 App）。

关于各版本的联动变更及首次启动时的具体事项，请参阅 升级笔记。 本页重点描述操作步骤，升级笔记则重点描述版本差异与注意事项。

支持范围

支持范围为 2026.11 之后的最新 3 个版本。2026.10 及更早版本不支持直接升级，请重新安装（若强行尝试，升级将失败并自动回滚至原版本）。

升级时机

在发布新版本时进行升级。单行命令将安装下载服务器上的当前版本。

发布前，会在 Staging 环境按照此步骤执行前一版本 → 当前版本的升级，验证数据是否保留以及迁移是否顺利完成。

升级前准备

1. 确认常规备份。 虽然单行命令在升级前会进行 自动备份，但该备份仅用于回滚。 请按照 备份与恢复 指南，确认 PostgreSQL 和 Aster TSDB 的定期备份为最新状态。
2. 检查磁盘空间。 自动备份会复制整个数据卷，因此备份路径（默认 /var/backups/kopens/upgrade）必须有超过卷大小的充足可用空间。
3. 阅读目标版本的 [升级笔记](/platform/admin-guide/upgrade-notes]。 部分版本涉及名称变更，需将联动配置与服务器一同升级。
4. 迁移手动修改的 bin/env.sh。 单行命令会删除并重新下载安装文件夹（/opt/kopens/plantpulse-platform-docker），因此该文件夹内的任何修改都不会保留。配置请保存至下方所述的服务器端文件。

保留项	位置
数据	Docker 卷 pp-data · pp-temp · pp-backup · pp-opcua-pki
服务凭证 · 配置 (Sidecar)	/etc/kopens/plantpulse-platform.env — 仅保留有值的行
本服务器特有值 (如外部 IP)	/etc/kopens/platform.node.env
Worker 列表	/etc/kopens/workers.roster
Platform 根 CA	/etc/kopens/ca/
时区 · 语言	直接使用先前安装留在 Sidecar 中的 PP_TZ · PP_LANG

操作步骤

通过 SSH 登录服务器，执行与安装时相同的命令。

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

如果手动管理防火墙规则，请像安装时那样附加 --skip-fw。

curl -fsSL https://product.kopens.io/plantpulse-platform/install.sh | bash -s -- --skip-fw

无需提前停止或删除 Stack。单行命令的操作流程如下：

1. 在安装文件夹旁下载新版本的运行脚本和 compose
2. 若检测到已安装 Stack，判定为升级并首先进行备份 ([1/4] An installed stack (…) was found - this run is an UPGRADE) — 详见 下方
3. 将安装文件夹替换为新版本并执行预检 (preflight.sh)
4. 若 Docker 已在运行，则跳过 OS 配置。重新配置防火墙规则 — 同时开启新版本所需端口（保留现有规则）
5. Sidecar 保留有值的行，仅填充新版本新增的项
6. 下载新镜像并重新启动 Stack。卷将直接挂载
7. 等待启动验证连续三次通过 (最多 25 分钟)

若新版本包含迁移任务，首次启动时间将较长。单行命令会在迁移运行期间等待，随后完成 Stack 启动。各版本具体耗时请参考 升级笔记。

自动备份与预检

在安装服务器上，单行命令在执行任何更改前会调用新版本的 bin/upgrade-backup.sh。若预检被拒绝或备份失败，则不进行任何更改，在重新启动原 Stack 后结束。

顺序	执行事项	拒绝时的处理
1	检查「已安装版本 → 新版本」是否在最新 3 个版本内	记录原因并拒绝。版本跨度过大时需分阶段升级
2	检查当前 Stack 是否正常 (status.sh)	不对故障 Stack 进行升级 — 请先修复
3	检查是否有足够的空间复制整个卷 + 安装文件夹	清理空间或更改备份位置 (PP_UPGRADE_BACKUP_DIR)
4	记录当前运行版本及各服务镜像 (Digest)	—
5	按正常流程停止 Stack，对数据卷 · /etc/kopens · 安装文件夹进行冷复制	复制失败时重新启动原 Stack

备份文件保存在 /var/backups/kopens/upgrade/<시각>-<판>/，升级成功后仅保留最近 2 个备份。 停机时间从停止 Stack 开始，直到新版本通过验证为止 — 包含复制数据卷的时间。

版本固定

单行命令默认下载当前版本，但可通过 Sidecar (/etc/kopens/plantpulse-platform.env) 的 PP_IMAGE_TAG 固定镜像版本。

PP_IMAGE_TAG=2026.11

所有服务将启动为该版本，除非另行指定 (PP_IMAGE_TAG_DATALAKE)，否则数据湖也将同步。 优先级顺序为：/etc/kopens/platform.node.env → Sidecar → 服务单独定义的 PP_IMAGE_TAG_<서비스>。 在固定版本的情况下再次运行单行命令，相当于重新安装相同版本 — 如需升级，请更改或删除固定设置。

验证

单行命令必须通过启动验证后才会显示 «Installation complete.»。完成后请按照安装时的流程进行确认。

cd /opt/kopens/plantpulse-platform-docker/bin
./status.sh        # 0 = 정상 / 2 = 비정상
./ops-check.sh

curl -kfsS https://<server-ip>:4950/api/health | jq   # "status":"OK" 또는 "WARN" 이면 정상

检查最后显示的根 CA 的 SHA-256 是否与升级前一致。在同一台服务器上运行，根 CA 应保持不变。

成功横幅中的 Upgrade downtime: 行即为实际停机时间。每次升级的结果均会被记录。

记录内容	位置
升级履历 (时间 · 版本跨度 · 成功/失败 · 备份位置)	/etc/kopens/upgrade-history.log
安装程序日志	/var/log/kopens/install-*.log

新增服务处理

若新版本增加了服务，docker ps 的容器数量会随之增加。单行命令会使用新的 compose 启动，无需额外操作，仅需根据相关文档配置该服务的设置（地址、账号等）。2026.11 版本请参考 升级笔记中的 «升级后事项»。

禁止事项

禁止操作	原因
通过 ./update.sh 升级版本	非官方升级程序。 仅更换镜像而运行脚本和 compose 仍为旧版，无法识别新服务
重新执行前使用 remove.sh · down.sh 清理	无需清理。单行命令会在现有 Stack 之上重新部署
使用 bin/tools/remove-all-volumes.sh	会删除卷 — 导致数据及备份卷 (pp-backup) 全部丢失。该工具与升级无关
修改安装文件夹内的 bin/env.sh	在下次升级时会被覆盖。请配置在 Sidecar 或 platform.node.env 中

问题处理

若单行命令以 [ERROR] 结束，将同步打印失败的检查项。请根据状态创建诊断包并进行咨询。

cd /opt/kopens/plantpulse-platform-docker/bin
./status.sh
./logs.sh [서비스]
./doctor.sh        # 지원 요청용 tarball. 비밀값은 마스킹됩니다

失败时自动回滚

升级失败时，UPGRADE FAILED 块会显示备份位置，并默认自动回滚至前一版本。 回滚不仅限于镜像，数据也会回滚至备份时点 — 因为新版本的迁移可能已经修改了 Schema。

回滚后，新版本运行期间的数据将丢失

在块中记录的时间（停止 Stack 的时间）之后进入的数据将在回滚后消失。升级状态仍为 «失败»， 请在修复原因后重新运行相同的单行命令。

如需在失败状态下进行诊断，请附加 PP_UPGRADE_AUTO_ROLLBACK=0 后运行。此时需通过块中显示的命令手动执行回滚。

/opt/kopens/plantpulse-platform-docker/bin/upgrade-rollback.sh /var/backups/kopens/upgrade/<시각>-<판>

隔离网络

隔离网络无法使用单行命令。请解压新版本的 Bundle，并重新执行其中的 bin/airgap-load.sh — 该过程会先按相同方式备份已安装 Stack，加载镜像后运行安装程序，失败时同样执行自动回滚。 Bundle 迁移与验证方法请参阅 隔离网络安装。update.sh 在隔离网络中亦不属于升级操作。