コンテナモード運用ガイド

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"
    }
  }
}

1つでも 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 の初回インストール時にボックスごとにランダムなパスワードが自動生成されます。

• 場所: /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 のデフォルト

• 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 : デフォルト

ログ

コンテナ内の 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 <component> で原因を追跡。mqtt の場合は auth.properties / app.properties のパスワード一致を確認
コンテナの restart loop	journalctl -u plantpulse-edge -n 100 + ポート占有 (ss -tlnp | grep :80) を確認
/ui/apps の Docker カードが空	docker.sock のマウント漏れ — systemd unit の -v /var/run/docker.sock を確認
PLC が断続的に切れる	NET_RAW cap / PLC ポートを確認 (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