升级

容器模式 (2026.05+, 推荐)

# 자동 (META-INF/VERSION.JSON 이 가리키는 빌드)
sudo bash /opt/kopens/install/upgrade.sh

# 특정 불변 태그 (YYYY.MM-YYYYMMDD-HHMM). 움직이는 태그는 거부합니다
sudo bash /opt/kopens/install/upgrade.sh --to 2026.11-20261103-1006

# 진행 중인 현재 업그레이드만 롤백 (trial · rollback_failed 상태에서만)
sudo bash /opt/kopens/install/upgrade.sh --rollback

# 사전 점검만 (0 최신, 10 새 빌드 있음)
sudo bash /opt/kopens/install/upgrade.sh --check

不支持降级到旧版本

--rollback 仅用于回滚进行中的升级，无法从已确认的构建版本降级到旧构建版本。即使通过 --to 指定旧标签也会被拒绝（退出码 3）。

隔离网络设备

无法连接至注册表的设备需通过单个镜像文件进行升级 — 详见下方隔离网络升级。

执行顺序（自动）：

事前巡检 — 检查目标是否为不变标签、是否比当前构建更新，以及签名工具 · 备份工具 · 磁盘空间是否充足。若有任一项不符，将停止操作且不更改任何内容。
下载 — docker pull <태그>
验证 — 确认 cosign 签名和镜像的 build_date。若无法验证签名则不继续。使用已验证镜像中的升级工具替换自身以继续流程。
快照 — /data1/pp-backups/pe-backup-pre-upgrade-<ts>.tar.zst 备份、旁侧的 CQL 导出(<아카이브>.cql/, 下方)、Cassandra 快照。此步骤为必需且不可跳过。若任一环节失败，将停止操作且不更改任何内容(snapshot_failed, 退出码 4)。
切换 — 将 /etc/kopens/version.env 替换为已验证的摘要并重启。
试运行 — 等待 /api/health?verdict=upgrade&expect_build=<빌드일> 返回 200。默认 300 秒(HEALTH_TIMEOUT)，若迁移正在进行，最长可达 2400 秒(MIGRATION_TIMEOUT)。
确认或自动回滚 — 通过则执行 committed。失败则将 Cassandra 还原至快照并回退到上一个镜像(rolled_back)。若回退也失败，则执行 rollback_failed。

试运行期间若断电，在启动时 kopens-upgrade-resume.service 将重新判定为 --resume。若在未确认状态下启动超过 3 次(OTA_MAX_TRIAL_BOOTS)，将直接回滚而不进行判定。

进度状态：cat /etc/kopens/upgrade.status — JSON。状态为 idle · downloading · verified · snapshot · switching · trial · committed · rolling_back · rolled_back · rollback_failed。

退出码：0 确认或已是最新 · 10 --check 存在新构建 · 3 拒绝降级至旧构建请求 · 4 未更改任何内容 · 5 下载或验证失败 · 6 回滚完成 · 7 回滚失败 · 75 另有升级正在进行。

UI / API 触发：POST /api/v1/system/upgrade 使用 /etc/kopens/upgrade.request，主机端的 kopens-upgrade.path 感知后执行 upgrade.sh --from-trigger。

详细指南：容器模式运营的 “OTA 升级” 章节。

升级前 CQL 导出

除 tar 归档和 Cassandra 快照外，事前备份还需创建一份 与引擎无关的副本 — 架构为 CQL 文本(schema.cql)，行数据为每表一个 CSV。这是因为在涉及数据库引擎变更的升级中，无法保证引擎文件能在新引擎中读取。

位置：归档旁侧 <아카이브에서 .tar.zst 를 뗀 이름>.cql/。与归档同步仅保留最新 3 份。
不包含时序 · 监控表的行数据(仅保留架构，以空表形式还原)。排除列表为 BACKUP_CQL_EXCLUDE_TABLES。
若无法创建导出，则视为备份失败，不启动升级。若必须在无导出状态下升级，请指定 BACKUP_CQL=0 — 将留下警告，且该归档仅能在相同引擎中还原。

还原方法请参考备份及恢复的 pe restore --cql。

隔离网络升级

在无注册表 · 无互联网环境下，通过镜像文件执行相同的升级流程（事前巡检 → 快照 → 切换 → 试运行 → 确认或回滚）。

sudo pe upgrade --bundle /media/usb/plantpulse-edge-2026.12.tar.zst
# 박스에 cosign 3 이 없으면 바이너리를 같이 넘깁니다
sudo pe upgrade --bundle <파일> --cosign /media/usb/cosign-linux-amd64

三个文件必须在同一位置：<파일>, <파일>.sha256, <파일>.sha256.sig。使用隔离网络包中 images/ 内的文件或分发处的 plantpulse-edge-<YYYY.MM>.tar.zst。
先验证签名。 使用设备中的 /etc/kopens/cosign.pub 对 .sha256 的签名进行离线验证，仅在文件的 sha256 与签名值一致时才执行 docker load。若缺少签名文件 · 签名不符 · 或 sha256 不一致，则不加载镜像(与 COSIGN_REQUIRE 无关)。
cosign： 若设备中无 cosign 3，则执行 --cosign <파일>，或安装文件旁侧的 cosign-linux-<arch> · 包含在包中的 tools/cosign-linux-amd64。若与固定版本(3.1.3)的校验和不符则拒绝。
仅允许升级到更新构建版本。 若为相同构建则 up_to_date，若为旧构建则 refused_downgrade。
--bundle 不能与 --to · --check 同时使用（退出码 2）。Web 端的 «SW 升级» 按钮仅使用注册表路径。

2026.11-20261103-1006 及以下设备的首次隔离网络升级

安装在不具备此功能的发行版中的 upgrade.sh 不识别 --bundle。首次升级需通过 包内的新脚本 直接执行。

sudo bash <번들>/repo/bin/upgrade.sh --bundle <번들>/images/<파일>

若仅获取了镜像文件，请同时获取存储库 tarball(plantpulse-edge-docker.tar.gz 和 .sig) 并解压，以相同方式执行。此后可通过 pe upgrade --bundle 进行。

发布前回滚验证

在新发行版告知现场设备之前，需在分阶段设备中验证 刻意触发失败的升级是否能实际回滚。使用会导致迁移失败的测试镜像进行升级以引发自动回滚，并检查上一个构建版本 · 架构 · 数据是否保持原样。此检查是发行链的必需步骤，通过后才会发行 VERSION.JSON，设备随后将把该发行版视为 «最新»。在升级工具变更的发行版中，需同步运行健康检查失败和启动循环场景。

2. 事前巡检

在开始升级之前：

# 1. 외부 망이 충분히 빠른지 — 회선이 느리면 download 만 수십 분
$PE_HOME/bin/network-speed-test.sh

# 2. 디스크 여유 (산출물 크기의 2–3배는 있어야)
df -h /opt /data1

# 3. 살아있는 백업이 있는지
ls -lt /data1/pp-backup | head -3

3. 升级结果验证

$PE_HOME/bin/ps.sh                              # 모든 컴포넌트 살아있는지
curl -s http://127.0.0.1/api/v1/edge | jq      # 버전/엣지 ID 새 값 확인
curl -s http://127.0.0.1/ui/opcua/tree | jq '.data.tree | length'  # 사이트/태그 정상
$PE_HOME/bin/log-viewer.sh                      # 30초 정도 봐서 SEVERE 없는지
# (Ctrl+C)

同时在外部 SCADA / Sparkplug 接收端确认数据是否正常到达。

4. 常见问题

症状	原因 / 解决方法
停在 `download install.sh`	检查外部网络 / `product.kopens.io`。通过 `curl -v http://product.kopens.io/...` 直接确认
`extracting` 后新产出物损坏	下载过程中中断。检查磁盘空间 + 重新尝试
升级后仅部分组件运行	`start.sh` 的分步失败 — 通过 `log-viewer.sh` 确认阻塞位置
`cosign 3 or later is not installed and could not be installed` (退出码 4)	设备无法访问 github.com 导致无法获取 cosign。内容未变更。请开启网络或预先安装 cosign 3.x 后重新尝试
升级后回滚至旧版本	从备份还原 → 备份 / 恢复

5. `firmware.sh` — OS 软件包更新

$PE_HOME/bin/firmware.sh

内部机制：

dnf update -y
dnf clean all

用于季度安全补丁应用。若包含内核更新，则需要重启 (reboot)。

$PE_HOME/bin/firmware.sh
needs-restarting -r              # 새 커널이 깔렸는지 확인
# 결과가 "Reboot is required" 이면
$PE_HOME/bin/stop.sh
$PE_HOME/bin/reboot.sh

容器模式 (2026.05+, 推荐)​

升级前 CQL 导出​

隔离网络升级​

发布前回滚验证​

2. 事前巡检​

3. 升级结果验证​

4. 常见问题​

5. firmware.sh — OS 软件包更新​

更多信息​