컨테이너 모드 운영 가이드

2026.05 릴리즈 부터 PlantPulse Edge 는 단일 Docker 컨테이너로 배포됩니다. 이 페이지는 컨테이너 모드의 일상 운영 / 장애 대응을 한 곳에 모아둔 가이드입니다.

native 모드

기존 native 배포 (직접 시스템에 설치) 박스는 좌측 메뉴의 시작 (start.sh), 중지 (stop.sh), 재시작 (restart.sh) 등 native 페이지를 그대로 사용하세요. 본 페이지는 컨테이너 배포 (systemctl status plantpulse-edge.service 가 active) 박스 전용입니다.

컨테이너 vs native — 어디서 도는가?

# 컨테이너 모드면 active
systemctl is-active plantpulse-edge.service

# 또는 직접 확인
curl -ks https://127.0.0.1/api/v1/system/version | grep container_mode

container_mode=true → 컨테이너 모드. container_mode=false 또는 endpoint 미응답이면 native.

한 줄 상태 점검

sudo bash /opt/kopens/install/bin/status.sh

출력 항목:

• Container: name / image / image_tag / state / health / started 시각
• Resources: CPU 사용률 / MEM 사용량 / PID 수
• Listening ports: 10개 (80, 443, 1883, 1884, 6379, 7799, 9042, 1880, 12000, 12443)
• App.properties 핵심 키 (edge.id / site_id / dev.mode / mqtt.enable / sparkplug.enable)
• API: /api/v1/system/version + /api/v1/system/health 응답 + HTTP 코드
• Upgrade status: /etc/kopens/upgrade.status 내용 (idle/running/success/...)

일상 운영 명령

작업	명령
상태 확인	bash /opt/kopens/install/bin/status.sh
헬스 (exit code 기반)	bash /opt/kopens/install/bin/health.sh
로그 보기	bash /opt/kopens/install/bin/logs.sh tomcat (또는 cassandra/mqtt/redis/node-red/api/catalina)
로그 follow	bash /opt/kopens/install/bin/logs.sh -f tomcat
컨테이너 내부 shell	bash /opt/kopens/install/bin/shell.sh
설정 변경	bash /opt/kopens/install/bin/config.sh --set <key> <value>
재시작	sudo systemctl restart plantpulse-edge.service
백업	sudo bash /opt/kopens/install/bin/backup.sh
복구	sudo bash /opt/kopens/install/bin/restore.sh <archive>
진단 수집 (escalation)	sudo bash /opt/kopens/install/bin/doctor.sh
OTA 업그레이드	sudo bash /opt/kopens/install/upgrade.sh

헬스 체크 API

/api/v1/system/version — 인증 불필요

{
  "data": {
    "product_name": "PlantPulse Edge",
    "version": "2026",
    "build_date": "20260523",
    "image_tag": "2026-20260523",
    "container_mode": true
  },
  "meta": {
    "timestamp": 1778925572946,
    "request_id": "..."
  }
}

주 용도: OTA 업그레이드 검증, monitoring 도구의 fleet inventory.

/api/v1/system/health — 인증 불필요, HTTP 503 if any DOWN

{
  "data": {
    "status": "UP",
    "uptime_ms": 1720008,
    "components": {
      "cassandra": "UP",
      "redis": "UP",
      "mqtt": "UP",
      "node_red": "UP",
      "opc_ua": "UP"
    }
  }
}

하나라도 DOWN 이면 status=DEGRADED + HTTP 503. OTA upgrade.sh 의 90초 health probe 가 이걸 보고 auto-rollback 결정.

데이터 / 설정 위치

/data1/                                # 컨테이너 ↔ host bind mount, 컨테이너 교체에도 보존
├── pp-data/
│   ├── cassandra/{data, hints}        # SSTables, hints
│   ├── redis/                         # AOF / RDB
│   ├── hivemq/                        # MQTT persistence
│   └── node-userdir/                  # Node-RED flows + node_modules
├── pp-temp/cassandra/commitlog        # 휘발성 commit log
└── pp-backups/                        # backup.sh 산출물 + OTA pre-snapshot

/etc/kopens/                           # 설정 + signal files (read-write mount)
├── app.properties                     # 메인 설정 (165줄, 16개 섹션)
├── credentials.txt                    # 박스별 비번 (chmod 0600, 설치 시 1회 출력)
├── version.env                        # KOPENS_VERSION=<tag>
├── upgrade.status / upgrade.request   # OTA 시그널
└── host-action.status / .request      # restart/reboot/clean signal

/var/security/plantpulse/edge/         # SSL keystore (read-only mount, 100년 self-signed)

OTA 업그레이드

자동 (product.kopens.io 의 최신)

sudo bash /opt/kopens/install/upgrade.sh

특정 tag 로

sudo bash /opt/kopens/install/upgrade.sh --to 2026-20260601

직전 tag 로 rollback

sudo bash /opt/kopens/install/upgrade.sh --rollback

새 빌드 존재 여부만 확인

sudo bash /opt/kopens/install/upgrade.sh --check

흐름

1. META-INF/VERSION.JSON 의 build_date 비교 (--check 모드 / auto 모드)
2. pre-snapshot → /data1/pp-backups/pe-backup-<ts>.tar.zst
3. docker pull <new-tag>
4. /etc/kopens/version.env 갱신 + systemctl restart
5. /api/v1/system/health 90초 probe
6a. all UP → success — snapshot 경로 유지
6b. DEGRADED → auto-rollback to previous tag + snapshot 경로 안내

상태: cat /etc/kopens/upgrade.status — idle | running | success | rolling-back | rolled-back | error.

UI / API 트리거 (컨테이너 안에서)

echo '{"target_tag":"2026-20260601"}' > /etc/kopens/upgrade.request

호스트의 kopens-upgrade.path (inotify) 가 감지 → upgrade.sh --from-trigger 실행.

비번 (양산 출하 시)

iter 9 (2026.05) 이후 install.sh 첫 설치 시 박스마다 random 비번 자동 생성.

• 위치: /etc/kopens/credentials.txt (chmod 0600 root)
• 내용: admin / mqtt / opcua / API key / keystore 비번
• 출하 절차: 인쇄/저장 → 박스 봉인 시 함께 → cat 으로 재확인 가능 (root only)

운영 중 변경:

config.sh --set edge.admin_password "NewStrongPass!"
config.sh --restart

HiveMQ auth.properties 는 entrypoint 가 매 부팅 /etc/kopens/app.properties 의 mqtt.* 와 자동 sync 하므로 app.properties 만 변경하면 됨.

자원 한도 (cgroup)

systemd unit 의 기본값:

key	value
MemoryMax	12G
MemoryHigh	11G
CPUQuota	600% (6 cores)
TasksMax	8192

8GB 박스용 override (drop-in)

sudo mkdir -p /etc/systemd/system/plantpulse-edge.service.d
sudo tee /etc/systemd/system/plantpulse-edge.service.d/override.conf <<'EOF'
[Service]
Environment=HIVEMQ_HEAP=1g
Environment=CASSANDRA_HEAP=1g
Environment=TOMCAT_HEAP=1g
MemoryMax=6G
MemoryHigh=5G
EOF
sudo systemctl daemon-reload
sudo systemctl restart plantpulse-edge.service

컴포넌트 heap default

• HiveMQ : -Xms2g -Xmx2g (env HIVEMQ_HEAP 으로 override — 2026-07 힙 표준 2g)
• Cassandra : host /proc/meminfo 기반 auto-calc (1/4 of total) — 16G host → ~4G (env CASSANDRA_HEAP)
• Tomcat : -Xms2g -Xmx2g (env TOMCAT_HEAP)
• Redis / Node-RED : 기본

로그

container 안의 logrotate (cronie) 가 daily / size>100M 트리거 / 14일 gzip 보관 / copytruncate (앱 재시작 없이) 자동 처리.

컴포넌트	경로 (컨테이너 안)	tool
Tomcat app	$PE_HOME/server/log/system.log	logs.sh tomcat
Tomcat stdout	$PE_HOME/server/logs/catalina.out	logs.sh catalina
Cassandra	$PE_HOME/db/logs/system.log	logs.sh cassandra
HiveMQ	$PE_HOME/mqtt/logs/hivemq.log	logs.sh mqtt
Redis	$PE_HOME/cache/log/redis.log	logs.sh redis
Node-RED	$PE_HOME/node/log/node-red.log	logs.sh node-red
API audit	$PE_HOME/server/log/api.log	logs.sh api
host	journalctl -u plantpulse-edge.service	journalctl

장애 대응 (간단)

자세한 시나리오 매트릭스는 /opt/kopens/install/RUNBOOK.md 참조.

증상	빠른 처방
/health components 일부 DOWN	logs.sh <컴포넌트> 로 원인 추적. mqtt 면 auth.properties / app.properties 비번 일치 확인
컨테이너 restart loop	journalctl -u plantpulse-edge -n 100 + 포트 점유 (ss -tlnp | grep :80) 확인
/ui/apps 도커 카드 비어있음	docker.sock 마운트 누락 — systemd unit 의 -v /var/run/docker.sock 확인
PLC 깜빡임	NET_RAW cap / PLC port 확인 (MELSEC 5001, LS 2004, Modbus 502, OPC UA 49320)

30분 내 복구 안 되면 → escalation

sudo bash /opt/kopens/install/bin/backup.sh    # 1. 악화 전 스냅샷
sudo bash /opt/kopens/install/bin/doctor.sh    # 2. 진단 tarball (≈200KB)
# 3. /tmp/pe-doctor-*.tar.zst + .sha256 을 support@kopens.io 또는 https://support.kopens.io 업로드

pe-doctor tarball 내용: api / docker / systemd / 7컴포넌트 logs / config (비번 redacted) / host metrics.

참고 / 관련 페이지

• 설치: 설치 > 한눈에 보기
• REST API 전체: 고급 / 통합 파트너용 > REST API
• 호스트 OS / sysctl / nmcli: 박스의 /opt/kopens/install/install.sh 와 install/RUNBOOK.md
• 시나리오 매트릭스 (A~E): 박스의 /opt/kopens/install/RUNBOOK.md