主页界面 (/ui/main) — 卡片 / 操作 / 刷新周期完全指南
网关 Web UI 的主页面。在一个界面上以卡片形式展示网关的全部运行状态。卡片以1 秒周期从后端(/monitor/bean)重新获取数值并刷新，仅 Sparkplug B 卡片单独以 5 秒周期(/api/v1/transfer)刷新。
点击左上角的 PlantPulse 徽标，或直接访问 http://<gateway>/ui/main。
- MQTT / Sparkplug B / OPC UA 服务器卡片：直接查找
app.properties中的*.enable/host/port/user键。由于 install.sh 会为每台设备生成随机密码，user 可能为空或每台设备显示不同的值。 - Docker 卡片：需要挂载
/var/run/docker.sock。plantpulse-edge自身会 self-exclude —— 不会显示在列表中（安全地阻止 start/stop/delete）。 - 网络卡片 (LAN1/LAN2/WiFi/GSM/VPN/管理)：按
edge.net.<role>.iface的值映射。 若像 dev 设备那样使用enp1s0 / enp2s0 / tailscale0之类的 systemd predictable 名称，请在app.properties中直接配置（可通过 install.sh 的LAN1_IFACE=...env 自动生效）。 - 一行确认组件健康状态：
curl http://localhost/api/v1/system/health（无需认证，8 个组件的 status map + 503 分支）。
卡片一览（共约 30 个）
横向 6 列网格。卡片共 3 种：
| 种类 | 颜色 | 含义 |
|---|---|---|
| action_box（白底、大图标） | 灰色边框 | 点击后跳转到对应菜单 |
| black_box（黑底） | 灰色文字 | 不会变化的网关信息 |
| gray_box（白底、灰色表头） | 浅灰 | 实时监控 —— 数值每秒刷新 |
1. 顶部操作 / 信息（第 1 行）
1.1 엣지 정보 (black_box)
显示内容：本网关不会变化的身份信息。仅在启动时测定一次并固定显示在界面上。
| 字段 | 含义 | 来源 |
|---|---|---|
| HOST名 | OS 的 hostname（例：pe-edge-01） | EdgeContext.hostname |
| O/S | OS 名称 + 架构（例：Linux (amd64)） | os.name + os.arch |
| 内核 | 内核版本（例：5.14.0-...） | os.version |
| 版本 | 网关软件版本（例：V2026.05.08） | app.properties |
| 构建日期 | 产物构建日期（例：2026-05-08） | BUILD_DATE |
⚠ HOST名、O/S 信息仅在网关重启后 OS 发生变化时才会改变。
1.2 프로토콜 연결 하기 (action_box)
→ 点击后跳转至 /ui/connect/connect。用于添加新的 PLC / OPC-UA / MQTT / 模拟器连接的界面。
1.3 연결된 목록 (N) (action_box)
→ 点击后跳转至 /ui/connect/list。括号中的 N 为当前已注册的 OPC（连接）数量（monitor.opc_count）。
1.4 애플리케이션 (action_box)
→ /ui/apps。启动 / 停止 / 管理基于 Docker 的用户应用。
1.5 노-코드 플로우 (action_box)
→ /ui/flow（Node-RED 嵌入）。
详细用法：流程 (Node-RED)
1.6 환경 설정 (action_box)
→ /ui/system/config。直接编辑 app.properties + 系统重启 / 重新引导 / 备份 / 临时文件清理等。
2. 网关标识（3 个卡片）
2.1 엣지 시작 시간 (gray_box)
显示内容：网关（Tomcat）最后一次启动的准确时刻 —— yyyy년 MM월 dd일 [a] HH시 mm분 ss초 (KST)。
若对重启时间存疑，可通过该值确认“最后一次重启”。
2.2 엣지 ID (gray_box)
显示内容：本网关的唯一 ID（例：EDGE_00303）。它是 Sparkplug、REST API、OPC-UA 节点树等所有标识的基准。来自 app.properties 的 edge.id。
2.3 배포 사이트 ID (gray_box)
显示内容：该 Edge 部署在哪个站点（工厂 / 产线）（例：SITE_00001）。用于确定外部 SCADA / Sparkplug 的 Group ID。来自 app.properties 的 site.id。
3. 网络状态（6 个卡片）
每个卡片显示链路状态图标 + IP 或 DISCONNECTED（灰色）。
3.1 인터넷 (gray_box)
网关是否能 ping 通外部互联网。图标颜色：
- 绿色 globe：连接正常
- 红色 globe：连接失败
ping 目标为 app.properties 中的 monitor.ping.targets（例：8.8.8.8）。
3.2 이더넷 (gray_box) — 分为两格
- 左：1 WAN（外网 NIC，
net_1_ip） - 右：2 PLC（PLC 网 NIC，
net_2_ip）
各格的颜色会随互联网 ping 结果一起变化（简化显示）。
3.3 WIFI (gray_box)
wifi-1 图标 + IP，或 wifi-slash 灰色 (DISCONNECTED)。
3.4 3G/4G/5G (gray_box)
GSM 调制解调器的 IP 或 DISCONNECTED。SIM 卡图标。
3.5 VPN (gray_box)
shield-check 图标。VPN 连接时显示 IP，断开时为灰色 + DISCONNECTED。
3.6 관리 포트 (gray_box)
wrench 图标。USB / 独立管理 NIC 的 IP。通常是与站点网络隔离的诊断用通道。
4. 系统资源（5 个卡片）
4.1 온도 (gray_box)
CPU 温度。达到 90°C 以上时显示红色 + temperature-high 图标（危险），以下则为绿色 + temperature-low。在工业环境中这是风扇堵塞 / 高温报警的首要信号。
4.2 CPU (gray_box)
仪表盘（0–100%）+ 总核心数。使用 JustGage 库。1 秒刷新。
若持续超过 90%，需检查 PLC 轮询周期 / 标签数量。
4.3 물리 메모리 (gray_box)
仪表盘 + 사용 / 전체（KB/MB/GB 自动换算单位）。与 swap 无关的 RSS 使用量。
4.4 가상 메모리 (gray_box)
交换分区（swap）使用量。仪表盘 + 사용 / 전체。平时 0–10% 为正常，若持续超过 30% 则可能是 RAM 不足。
4.5 디스크 (gray_box)
/data1（或网关主目录）的使用率。仪表盘 + 사용 / 전체。
超过 90% 时应立即执行整理 / 清理 (clean.sh / node-cleanup.sh) 流程。
5. 网络流量（1 个卡片）
5.1 네트워크 사용량 (gray_box)
- 下载 (RX) —— 累计接收字节数
- 上传 (TX) —— 累计发送字节数
KB/MB/GB 自动换算单位。为启动后的累计值。
6. 采集 / 处理（4 个卡片）
6.1 연결 | 태그 건수 (gray_box)
- 上方大数字：连接 (OPC) 数（
opc_count） - 下方大数字：标签数（
tag_count）
网关已知 OPC/标签的全部计数。也包含系统标签（EDGE_*）。
6.2 PLC 연결 및 수집 상태 (gray_box) — 2x4 矩阵
| 左侧（连接） | 含义 |
|---|---|
| 🟢 连接 | TCP/UDP 连接正常的 OPC 数（plc_con_connected_count） |
| 🔴 断开 | 连接失败的 OPC 数（plc_con_disconnected_count） |
| 右侧（采集） | 含义 |
|---|---|
| 🟢 正常 | 已启动采集且 read 成功中（plc_scan_start_count） |
| 🟧 异常 | 已启动采集但一段时间内 read 失败（plc_scan_not_collect_count） |
| ⬜ 停止 | 用户点击停止的 OPC（plc_scan_stop_count） |
连接与采集不同：即使 TCP 处于存活状态（连接 ✅），若因任何原因读不到数据，也会被归类为采集异常。
6.3 PLC 읽기/쓰기 결과 (gray_box)
采集器/REST API 累计的 read/write 计数器。以 K/M/B 单位压缩显示。
| 成功 | 失败 | |
|---|---|---|
| 读取 (R) | plc_value_read_success_count | plc_value_read_error_count |
| 写入 (W) | plc_value_write_success_count | plc_value_write_error_count |
点击右上角 ↻ 刷新图标 → 调用 /connect/reset-read-error → 仅将失败计数器清零。适用于报警处理完毕后希望从下一周期重新计数的场景。
6.4 MPS (gray_box)
Messages Per Second —— 每秒处理的数据点数量（monitor.mps）。
正下方为 sparkline（近期趋势迷你图表）。可一眼掌握负载变化。
若站点平时 mps 为 100，突然降至 0 → PLC 连接或采集异常。
7. 传输 / 存储（5 个卡片）
7.1 대기 큐 (gray_box)
等待传输的数据点队列大小（queue_size）。
平时为 0–数十。若外部传输受阻（Sparkplug 断开等）会迅速增长 → 溢出到磁盘队列（
queue_disk_size）。若该卡片持续增长，需检查外部通信。
7.2 포인트 전송 건수 (gray_box)
启动后成功向外部传输的累计数据点数（sended_point_count）。
7.3 포인트 전송량 (gray_box)
启动后的累计发送字节数（sended_point_bytes）。自动换算单位。可作为流量费用核算参考。
7.4 데이터 저장량 (gray_box)
存储在 Cassandra 的 keyspace pe 中的时序数据总大小（输入 MBytes → 自动换算单位）。请结合磁盘剩余空间一同查看。
7.5 데이터 저장 기간 (gray_box)
tm_tag_point 的 TTL (Time-To-Live) 天数（system_db_ttl，默认 30 天）。超过该天数后自动过期。可在 app.properties 中修改。
8. 系统错误（1 个卡片）
8.1 시스템 오류 (오늘) (gray_box)
今日（00:00–当前）发生的 ERROR 级别系统日志条数（system_error_count）。以红色大数字显示。
点击数字 → 跳转至 /system/log/list，可查看实际日志正文。
9. 外部服务 / 集成（5 个卡片）
每个卡片包含状态条（绿色/红色/灰色）+ 连接信息表。
9.1 플랫폼 API 서버 (gray_box)
与上位 PlantPulse 平台 API 的连接状态。点击右上角外部链接图标可在新窗口中访问该服务器。
| 行 | 含义 |
|---|---|
| 状态条 | 🟢 连接成功 / 🔴 连接失败（monitor.api） |
| HOST/IP | server.host |
| PORT | server.port |
| USER | server.username |
9.2 OPC-UA 서버 (gray_box)
网关内置 OPC-UA 服务器信息。外部 SCADA 通过此处接入并订阅标签。
| 行 | 含义 |
|---|---|
| 状态条 | 🟢 已启用（服务器始终运行） |
| HOST/IP | opc.ua.server.host |
| PORT | opc.ua.server.tcp.port（默认 12000） |
| USER | opc.ua.server.user |
详细节点树 / 时序图表：使用 OPC-UA 节点查看器
9.3 MQTT 서버 (gray_box)
网关内置 HiveMQ 信息 + 用于发布 Sparkplug 等的主题。
| 行 | 含义 |
|---|---|
| 状态条 | 🟢 已启用 / ⬜ 已禁用（mqtt.enable） |
| HOST/IP | mqtt.server.host |
| PORT | mqtt.server.port（默认 1883） |
| USER | mqtt.server.user |
| TOPIC | mqtt.server.topic（Sparkplug spBv1.0/... 或用户主题） |
9.4 Sparkplug B (gray_box)
Sparkplug 发布组件的实时状态（5 秒刷新，/api/v1/transfer 的 Sparkplug 项）。
| 行 | 含义 |
|---|---|
| 状态条 | 🟢 已启用（已连接） / 🔴 连接断开（已启用但与 broker 断开） / ⬜ 已禁用（sparkplug.enable=false） |
| GROUP | Sparkplug Group ID（例：Plant1） |
| NODE | Edge Node ID（例：EDGE_00303） |
| 会话 # | bdSeq（设备 birth/death 序列 —— 重连次数） |
| 消息 # | seq（当前发布消息编号 —— 0–255 循环） |
若消息 # 停止变化，表示已停止发送。若会话 # 频繁增加，说明 broker 连接不稳定。
9.5 도커 (gray_box)
Docker 守护进程状态 + 用户应用容器统计。
| 行 | 含义 |
|---|---|
| 状态条 | 🟢 运行中 / 🔴 已停止（monitor.docker_on） |
| 计数 | [ 살아있는 / 전체 ] 容器数（docker_container_up_count / docker_container_total_count） |
可一眼确认在 /ui/apps 中注册的应用是否全部存活。
10. 页脚（所有页面通用）
界面底部会显示以下内容。
- PlantPulse Edge 文本 + 许可证
- ☁ 软件升级图标 —— 点击后调用
upgrade.sh（经确认对话框后）- 图标旁的徽标：
- 红色“可升级！” → 下载服务器上存在新版本
- 灰色“无法连接下载服务器” → 外网 /
product.kopens.io访问失败 - （无徽标） → 当前已是最新版本
- 图标旁的徽标：
- 外部端口快捷方式 —— 在新窗口打开其他外部服务（例：Grafana 3000）
内部由 /config/upgrade/check 以 server-to-server 方式获取 https://product.kopens.io/.../VERSION.JSON 并进行比较 → 无 CORS 错误，干净地显示徽标。
11. 刷新周期 / 数据来源整理
| 区域 | 刷新周期 | 端点 |
|---|---|---|
| 仪表盘 / 资源 / 网络 / 计数器 / 队列 / 存储量 / 错误 | 1 秒 | GET /monitor/bean |
| Sparkplug B 卡片 | 5 秒 | GET /api/v1/transfer |
| 升级徽标 | 页面加载时 1 次 | GET /config/upgrade/check |
| 黑色信息卡片（HOST名/OS/版本等） | 不刷新（页面加载时的值） | EdgeContext（服务器启动时确定） |
12. 常见现象
| 界面信号 | 疑点 / 处理 |
|---|---|
| 温度为红色 (90°C↑) | 风扇堵塞 / 环境温度 —— 立即巡检 |
| CPU 持续 90%+ | 轮询周期过快 / 标签数量过多 |
| 磁盘 90%+ | 整理 / 清理 —— clean.sh + node-cleanup.sh |
| PLC 断开计数突然增加 | PLC 网线 / 交换机 / PLC 电源 |
| 采集异常 > 0 | 连接正常但 read 失败 —— 检查地址格式 / PLC 固件 |
| MPS 降至 0 | 所有 PLC read 失败或采集器停止 |
| 等待队列持续增长 | 外部传输 (Sparkplug / MQTT) 受阻 —— 查看 9.3/9.4 卡片 |
| 系统错误显示红色数字 | 点击 → 在 /system/log/list 中查看正文 |
| Sparkplug 消息 # 不变化 | 已停止发送 —— 检查 app.properties 的 sparkplug.* |
| Docker 为红色 | 在 systemctl status docker 中确认守护进程状态 |
13. 了解更多
- 添加连接：添加新的 PLC 连接
- 连接列表 / 标签界面：查看实时值
- OPC-UA 节点查看器：使用 OPC-UA 节点查看器
- 流程自动化：开始使用流程 (Node-RED)
- 系统环境设置 / 运维脚本：运维 —— 一览