コンテナモード運用

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。

1行状態点検

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

出力項目：

• Container: name / image / image_tag / state / health / started 時刻
• Resources: CPU 使用率 / MEM 使用量 / PID 数
• Listening ports: 9個 (80, 443, 1883, 1884, 6379, 9042, 1880, 12000, 12443)。7799(Tomcat JMX)は 127.0.0.1 専用のためリストに含まれません。
• 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/trial/committed/...)

日常運用コマンド

作業	コマンド
状態確認	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 — 認証不要、いずれかが DOWN の場合 HTTP 503

{
  "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 は別途判定アドレス /api/health?verdict=upgrade&expect_build=<빌드일> で試行起動を判定します（デフォルト 300秒）。

データ / 設定場所

/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

特定タグ指定

sudo bash /opt/kopens/install/upgrade.sh --to 2026.11-20261103-1006

不変タグ（YYYY.MM-YYYYMMDD-HHMM）のみ受け付けます。

進行中のアップグレード rollback

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

trial · rollback_failed 状態でのみ動作します。確定済みのビルドから旧ビルドへ戻すことはできません。

新ビルドの存在確認のみ

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

流れ

手順は アップグレード の「遂行順序」と同様です。事前点検 → ダウンロード → 署名検証 → スナップショット → 切り替え → 試行起動 → 確定または自動ロールバック。

状態：cat /etc/kopens/upgrade.status — idle · downloading · verified · snapshot · switching · trial · committed · rolling_back · rolled_back · rollback_failed。

UI / API トリガー (コンテナ内)

POST /api/v1/system/upgrade が /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 のみ)

運用中の変更：

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

HiveMQ auth.properties は entrypoint が起動ごとに /etc/kopens/app.properties の mqtt.* と自動同期するため、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) — 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

障害対応 (簡略)

インストールシナリオ（量産ライン · サイト単一ボックス · CI）については インストール を参照してください。

症状	迅速な処方
/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.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
• インストールシナリオ: インストール