容器模式运维指南

自 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）
跟踪日志	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 升级验证、监控工具的 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 的 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

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）

运行中修改：

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 覆盖 —— 2026-07 堆标准为 2g）
• Cassandra：基于宿主机 /proc/meminfo 自动计算（总量的 1/4）—— 16G 宿主机 → 约 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 个组件日志 / config（密码已脱敏）/ host metrics。

参考 / 相关页面

• 安装：설치 > 한눈에 보기
• REST API 全量：고급 / 통합 파트너용 > REST API
• 宿主机 OS / sysctl / nmcli：设备上的 /opt/kopens/install/install.sh 与 install/RUNBOOK.md
• 场景矩阵（A~E）：设备上的 /opt/kopens/install/RUNBOOK.md