アップグレード

Platformを新しいバージョンに更新する公式な方法は、インストールワンライナーを同じサーバーで再実行することのみです。削除や整理を行うことなく、そのまま再実行してください。新バージョンの運用スクリプト・compose・イメージが適用され、新バージョンで追加されたサービス（例：現場アプリ）も同時に展開されます。

バージョンごとの連携修正が必要な事項や、初回起動時に発生する処理についてはアップグレードノートに記載されています。 本ドキュメントには手順を、アップグレードノートにはバージョン別の注意点を記載しています。

サポート範囲

サポート範囲は2026.11以降のバージョンのうち、最新3バージョンまでです。2026.10以前のバージョンからはアップグレードできないため、再インストールしてください（試行した場合、アップグレードは失敗し、自動的に元のバージョンにロールバックされます）。

実施タイミング

新バージョンがリリースされたタイミングで実施してください。ワンライナーはダウンロードサーバーの現行バージョンをインストールします。

リリースは、ステージング環境で直前バージョン → 今回のバージョンへのアップグレードを本手順通りに実行し、データが保持されるか、およびマイグレーションが完了するかを確認した後にリリースされます。

実施前の準備

平常時のバックアップを確認してください。 ワンライナーはアップグレード直前に自動バックアップを行いますが、これはロールバック用です。バックアップと復旧に従い、PostgreSQLおよびAster TSDBの定期バックアップが最新であるかを確認してください。
ディスク容量を確認してください。 自動バックアップはデータボリューム全体をコピーするため、ボリュームサイズ以上の十分な空き容量がバックアップ先（デフォルト /var/backups/kopens/upgrade）にある必要があります。
更新するバージョンのアップグレードノートを読んでください。 名称変更に伴い、連携設定をサーバーと共に更新しなければならないバージョンがあります。
bin/env.sh を直接修正していた場合は、移行してください。 ワンライナーはインストールフォルダ（/opt/kopens/plantpulse-platform-docker）を削除して新しく取得するため、その中での修正内容は保持されません。設定は後述するサーバー側のファイルに保存してください。

保持されるもの	場所
データ	Docker ボリューム `pp-data` · `pp-temp` · `pp-backup` · `pp-opcua-pki`
サービス資格情報・設定（サイドカー）	`/etc/kopens/plantpulse-platform.env` — 値がある行はそのまま使用されます
当該サーバー固有の値（外部IPなど）	`/etc/kopens/platform.node.env`
ワーカーリスト	`/etc/kopens/workers.roster`
Platform ルートCA	`/etc/kopens/ca/`
タイムゾーン・言語	前回のインストールがサイドカーに残した `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

スタックを事前に停止または削除する必要はありません。ワンライナーは以下の処理を行います。

新バージョンの運用スクリプト・composeをインストールフォルダの隣に取得します
インストール済みスタックがある場合、アップグレードと判断して先にバックアップを行います（[1/4] An installed stack (…) was found - this run is an UPGRADE） — 下記
インストールフォルダを新バージョンに差し替え、事前点検（preflight.sh）を行います
Dockerが既に動作している場合、OS設定はスキップします。ファイアウォールルールは再設定されます — 新バージョンで追加されたポートもこの時に開きます（既存のルールは維持されます）
サイドカーは値がある行を維持し、新バージョンで追加された項目のみを埋めます
新しいイメージを取得し、スタックを再起動します。ボリュームはそのままアタッチされます
ブート検証が3回連続で成功するまで待機します（最大25分）

新バージョンにマイグレーションがある場合、初回起動に時間がかかります。ワンライナーはマイグレーションが完了するまで待機し、その後スタックを完全に起動させます。バージョンごとの所要時間はアップグレードノートに記載されています。

自動バックアップと事前点検

インストール済みサーバーにおいて、ワンライナーは変更を加える前に新バージョンの bin/upgrade-backup.sh を呼び出します。点検で拒否された場合やバックアップに失敗した場合は、 何も変更せずに旧スタックを再起動させて終了します。

順序	処理内容	拒否される場合
1	インストール済みバージョン → 新バージョンが最新3バージョン以内か	理由を出力して拒否。それ以前のバージョンは段階的に更新してください
2	現在のスタックが正常（`status.sh`）か	故障しているスタックはアップグレードしません — 先に修正してください
3	ボリューム全体＋インストールフォルダをコピーする空間があるか	空間を確保するか、バックアップ場所を変更してください（`PP_UPGRADE_BACKUP_DIR`）
4	現在動作しているバージョンとサービス別イメージ（ダイジェスト）を記録	—
5	スタックを正常手順で停止し、データボリューム・`/etc/kopens`・インストールフォルダをコールドコピー	コピーに失敗した場合、旧スタックを再起動させます

バックアップは /var/backups/kopens/upgrade/<시각>-<판>/ に作成され、アップグレード成功時は最新2つのみを保持します。スタックを停止した瞬間から新バージョンが検証を通過するまでがダウンタイムとなり、ここにデータボリュームのコピー時間が加算されます。

バージョン固定

ワンライナーはダウンロードサーバーの現行バージョンを取得しますが、イメージバージョンはサイドカー（/etc/kopens/plantpulse-platform.env）の PP_IMAGE_TAG で固定できます。

PP_IMAGE_TAG=2026.11

すべてのサービスがそのバージョンで起動し、データレイクも別途指定がない限り（PP_IMAGE_TAG_DATALAKE）それに従います。 /etc/kopens/platform.node.env の値はサイドカーより優先され、サービス別の 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" 이면 정상

最後に表示されるPlatform ルート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` で整理する	不要です。ワンライナーが既存スタックの上に再展開します
`bin/tools/remove-all-volumes.sh` の使用	ボリュームを削除します — データおよびバックアップボリューム（`pp-backup`）まで消失します。アップグレードとは無関係のツールです
インストールフォルダ内の `bin/env.sh` を修正しておく	次回のアップグレード時に削除されます。サイドカーまたは `platform.node.env` に保存してください

問題が発生した場合

ワンライナーが [ERROR] で終了した場合は、失敗した検知項目が共に出力されます。状態を確認し、診断バンドルを作成して問い合わせてください。

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

失敗時の自動ロールバック

アップグレードに失敗した場合、UPGRADE FAILED ブロックにバックアップ先が出力され、デフォルトで以前のバージョンへ自動的にロールバックされます。 ロールバックはイメージだけでなく、データもバックアップ時点まで戻します — 新バージョンのマイグレーションによって既にスキーマが変更されている可能性があるためです。

ロールバックすると、新バージョンが動作していた間のデータは保持されません

ブロックに記載された時刻（スタックを停止した時刻）以降に流入したデータは、ロールバック後に存在しません。アップグレード自体は依然として «失敗» 状態であるため、原因を修正した後に同じワンライナーを再実行してください。

失敗した状態のまま診断を行う場合は、PP_UPGRADE_AUTO_ROLLBACK=0 を付与して実行してください。この場合は、ブロックに表示されたコマンドを使用して手動でロールバックを行います。

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

閉域網

閉域網ではワンライナーを使用できません。新バージョンのバンドルを展開し、その中の bin/airgap-load.sh を再実行してください — インストール済みのスタックを同様に先にバックアップし、イメージをロードした後にインストーラーを動作させます。失敗した場合は同様に自動でロールバックされます。バンドルの移動と検証方法は閉域網インストールに記載されています。update.sh は閉域網においてもアップグレード手段ではありません。

実施タイミング​

実施前の準備​

手順​

自動バックアップと事前点検​

バージョン固定​

確認​

新しいサービスが追加された場合​

禁止事項​

問題が発生した場合​

失敗時の自動ロールバック​

閉域網​