容器模式运行

从 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: 名称 / 镜像 / 镜像标签 / 状态 / 健康状况 / 启动时间
• Resources: CPU 使用率 / 内存使用量 / 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 升级验证、监控工具的设备资产管理。

/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

使用特定标签 (tag) 升级

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

仅接收不可变标签 (YYYY.MM-YYYYMMDD-HHMM)。

回滚进行中的升级

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 设备覆盖配置 (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) 自动处理：每日 / 大于 100M 触发 / 14 天 gzip 保留 / copytruncate (无需重启应用)。

组件	路径 (容器内)	工具
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 端口 (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 压缩包内容：api / docker / systemd / 7 个组件日志 / 配置 (密码已脱敏) / 主机指标。

参考 / 相关页面

• 安装: 설치 > 한눈에 보기
• REST API 全集: 고급 / 통합 파트너용 > REST API
• 主机 OS / sysctl / nmcli: 设备的 /opt/kopens/install/install.sh
• 安装场景: 安装