업그레이드

플랫폼을 새 판으로 올리는 공식 방법은 설치 원라이너를 같은 서버에서 다시 실행하는 것 하나입니다. 지우거나 정리하지 않고 그대로 다시 실행합니다. 새 판의 운영 스크립트 · 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`
플랫폼 루트 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 설정은 건너뜁니다. 방화벽 규칙은 다시 맞춥니다 — 새 판에 생긴 포트도 이때 열립니다(이미 있는 규칙은 그대로)
사이드카는 값이 있는 줄을 그대로 두고, 새 판에 생긴 항목만 채웁니다
새 이미지를 받아 스택을 다시 띄웁니다. 볼륨은 그대로 붙습니다
부팅 검증이 세 번 연달아 통과할 때까지 기다립니다(최대 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://<서버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` 로 정리	필요 없습니다. 원라이너가 기존 스택 위에 다시 띄웁니다
`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 를 다시 실행합니다 — 설치된 스택을 같은 방식으로 먼저 백업하고, 이미지를 load 한 뒤 설치기를 돌리며, 실패하면 똑같이 자동으로 되돌립니다. 번들을 옮기고 검증하는 법은 폐쇄망 설치에 있습니다. update.sh 는 폐쇄망에서도 업그레이드가 아닙니다.

언제​

하기 전에​

절차​

자동 백업과 사전 점검​

판 고정​

확인​

새 서비스가 생겼을 때​

하지 말 것​

문제가 생기면​

실패하면 자동으로 되돌립니다​

폐쇄망​

언제