网关运维

开发预览

本页用于检查当前进程和定位问题，不提供生产可用性保证。监控返回成功、Stub 写入成功或上传接口返回成功，都不能替代真实设备与故障场景验收。文中接口行为以提交 b1a16cbc 的注册路由为准。

1. 日常检查

Docker 环境：

bash

docker compose ps
docker compose logs -f gateway
curl -fsS http://127.0.0.1:8080/api/health
curl -fsS http://127.0.0.1:8080/api/metrics

GET /api/health 返回进程版本、运行时间、MQTT 连接状态和 Tag 数量等健康数据；GET /api/metrics 返回 Prometheus 文本格式。这两个端点当前无需 Token，应通过监听范围、防火墙或反向代理限制访问，避免暴露系统信息。

若已自行修正并验证 systemd 安装路径，可检查：

bash

systemctl status fastbee-gateway
journalctl -u fastbee-gateway

随附安装脚本和 unit 的路径尚未统一，不能直接假定服务已正确安装。

2. 日志管理

2.1 日志位置

日志源	路径/方式	说明
systemd 日志	`journalctl -u fastbee-gateway`	服务生命周期日志
应用日志	spdlog 输出（控制台/文件 sink）	运行日志
内存日志尾部	`GET /api/debug/logs`	最近约 50 条，用于远程诊断

2.2 查看与过滤

bash

sudo journalctl -u fastbee-gateway -f                 # 实时跟踪
sudo journalctl -u fastbee-gateway -n 100             # 最近 100 行
sudo journalctl -u fastbee-gateway -p err             # 仅错误
sudo journalctl -u fastbee-gateway --since "2026-10-01" --until "2026-10-02"

2.3 日志级别

支持级别（从详细到简略）：trace → debug → info → warn → error → critical → off。修改方式：

bash

# 配置文件: gateway.json → "system": { "logLevel": "debug" }
# 或启动参数:
fastbee-gateway --log-level debug

3. 认证后的运行信息

登录并携带 Bearer Token 后，可使用：

接口	运维用途与限制
`GET /api/mqtt/status`	查看连接状态、Broker、发布/订阅统计、错误和重连计数；计数不等于数据已可靠送达
`GET /api/overview/status`	查看系统资源（CPU/内存/温度/磁盘）和运行状态
`GET /api/overview/devices`	查看内部设备总数与在线/离线统计；当前在线模型不等于物理通信验收
`GET /api/overview/traffic`	查看 MQTT 字节、消息、发布、订阅和重连统计
`GET /api/drivers/health`	查看驱动健康摘要；驱动未注册时不能据此判断现场总线正常
`GET /api/debug/tags`	主动执行一次 `pollOnce()` 并返回 Tag 与统计
`GET /api/debug/logs`	返回内存日志尾部约 50 条，不是完整持久日志归档

4. 监控与告警接入

4.1 Prometheus / Grafana

网关提供 Prometheus 兼容指标端点（无需认证）：

bash

curl http://<网关IP>:8080/api/metrics

Prometheus 抓取配置示例：

yaml

scrape_configs:
  - job_name: 'fastbee-gateway'
    scrape_interval: 15s
    static_configs:
      - targets: ['<网关IP>:8080']
    metrics_path: '/api/metrics'

4.2 告警阈值建议

指标	告警阈值	严重阈值	处理方式
CPU 使用率	>70%	>90%	检查采集周期是否过短
内存使用	>80%	>95%	检查 SQLite 缓存大小
磁盘使用	>80%	>95%	清理日志和缓存
CPU 温度	>70°C	>85°C	检查散热/环境温度
MQTT 断连	>1min	>10min	检查网络和 Broker
设备离线	>5min	>30min	检查现场设备/接线

4.3 报警引擎监控

工业报警引擎（AlarmEngine）支持 5 种报警类型，已通过 TagChangeObserver 与 TagEngine 联动：

bash

# 查看活跃报警 / 统计 / 规则列表
curl -H "Authorization: Bearer $TOKEN" http://<网关IP>:8080/api/alarms/active
curl -H "Authorization: Bearer $TOKEN" http://<网关IP>:8080/api/alarms/stats
curl -H "Authorization: Bearer $TOKEN" http://<网关IP>:8080/api/alarms/rules

# 确认报警（操作员响应）
curl -X POST -H "Authorization: Bearer $TOKEN" http://<网关IP>:8080/api/alarms/<ruleId>/ack

报警类型：LEVEL（阈值，支持 HH/H/L/LL 四级）、DEVIATION（偏差）、RATE_OF_CHANGE（变化率）、QUALITY（质量）、DIGITAL（开关量）。报警状态机为 NORMAL → ACTIVE → ACKED → RETURNED → NORMAL。

4.4 驱动健康监控

驱动健康监控器（DriverHealthMonitor）采用 6 态连接状态机：

text

DISCONNECTED → CONNECTING → CONNECTED → RECONNECTING → FAILED → ISOLATED

bash

curl -H "Authorization: Bearer $TOKEN" http://<网关IP>:8080/api/drivers/health
curl -H "Authorization: Bearer $TOKEN" http://<网关IP>:8080/api/drivers/<name>/health

健康指标：state（连接状态）、consecutiveErrors（连续错误）、avgLatencyMs（平均延迟）、lastHeartbeat（最后心跳）、isolated（是否被自动隔离）。连续错误达到阈值后驱动进入 FAILED，持续超时进入 ISOLATED，之后按 autoRecoverMs（默认 60 秒）自动尝试恢复。

5. 配置与数据备份

5.1 备份范围

实际使用的 gateway.json、用户数据和后续修改过的配置。
.secret.key 等秘密材料；必须与公开文档、镜像和日志隔离，并按组织秘密管理策略保存。
Compose 命名卷中的业务数据、日志和证书；先确认卷与真实路径的对应关系。
自定义 systemd unit、反向代理和 Broker 认证/TLS 配置。

5.2 导出与导入

配置导出/导入接口在当前代码中真实可用（经 ConfigManager）：

bash

# 导出
curl -H "Authorization: Bearer <token>" \
  http://<网关IP>:8080/api/system/config -o gateway-backup.json

# 导入
curl -X POST -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d @gateway-backup.json \
  http://<网关IP>:8080/api/system/config

也可直接复制配置文件，或用 crontab 定时备份：

bash

#!/bin/bash
# /usr/local/bin/fastbee-backup.sh — 每天凌晨备份配置
BACKUP_DIR="/backup/fastbee-gateway"
DATE=$(date +%Y%m%d_%H%M%S)
mkdir -p "$BACKUP_DIR"
cp /etc/fastbee-gateway/gateway.json "$BACKUP_DIR/gateway-$DATE.json"
find "$BACKUP_DIR" -name "*.json" -mtime +30 -delete

恢复时同时核对配置路径、密钥匹配、文件所有者与写权限。只读配置挂载会阻止 .secret.key 和 API 配置写入，不能只通过反复重启掩盖该问题。

6. 固件升级（OTA）

设计的升级流程为：下载固件 → 校验 → 备份当前版本 → 安装新版本 → 重启服务 → 验证启动，失败回滚。当前 POST /api/system/upgrade 只确认收到文件并返回 uploading，未完成校验、安装与回滚。在此之前，升级请使用 deb 包手动方式：

bash

scp fastbee-gateway-1.1.0-arm64.deb root@<网关IP>:/tmp/
ssh root@<网关IP> "dpkg -i /tmp/fastbee-gateway-1.1.0-arm64.deb && systemctl restart fastbee-gateway"

版本检查：

bash

fastbee-gateway --version
curl -H "Authorization: Bearer <token>" http://<网关IP>:8080/api/system/info

7. 常见排障

7.1 Web 无法打开或静态资源缺失

确认访问的是 http://<host>:8080，不是未实现 HTTPS 服务的 8443。
确认实际读取键为 web.port，并检查端口映射与防火墙（ss -tlnp | grep 8080、ufw status）。
源码运行时使用相对 web-src；从源码根目录启动，避免工作目录错误。
安装脚本 web/ 与真实 web-src/、systemd /opt 与 CMake /usr 的路径差异需要先行修正。

7.2 MQTT 无法连接或保存后未生效

默认配置指向 192.168.1.100，不是 Compose 服务名 mosquitto。
依次检查：ping <broker_ip> → nc -zv <broker_ip> 1883 → DNS/路由 → Broker 进程与日志。
检查 ENC(...) 是否有匹配密钥，不能用解密失败的密文作为凭据；FastBee AES 认证密码在平台侧设备管理中生成。
检查匿名访问是否仅限隔离开发环境，以及生产 Broker 的认证/TLS 是否一致。
PUT /api/mqtt/config 只保存部分字段且不重连；核对真实配置并在受控窗口重启。
客户端自动重连选项不等于离线数据补报；当前活动回调在断开时跳过数据。

7.3 没有采集值或无法写入

检查 drivers、设备和 Tag 是否使用运行时字段，而不是旧 UI/文档字段。
Modbus 地址使用零基 registerAddr，并确认真实 libmodbus 而非 Stub 结果。
当前首要代码阻塞是应用没有将配置驱动注册到 TagEngine；配置正确也不能绕过该问题。
用调试 API 定位：GET /api/debug/tags 主动采集一次，POST /api/debug/write 手工写测试。
串口链路检查：RS485 A/B 接线、终端电阻、波特率/从站地址一致性、总线负载。

7.4 报警未触发或频繁抖动

检查规则是否启用（GET /api/alarms/rules 中的 enabled）、Tag 是否有数据更新、阈值是否合理。
报警在阈值附近抖动时增大 deadband（例如阈值 80°C、死区 5°C，则触发后需降到 75°C 以下才恢复）。

7.5 驱动被自动隔离

查看 GET /api/drivers/health 中的 isolated 与连续错误计数，检查串口连接、设备供电、总线地址、波特率配置；修复底层通信问题后驱动会按自动恢复机制重试。

8. 性能调优

优化项	配置	效果
死区过滤	Tag 配置 `deadband`	减少无效上报
采集周期分级	关键 Tag 100-500ms，普通 Tag 1000-5000ms	避免高频轮询低频数据
批量读取	连续寄存器合并为一次读取	减少 Modbus 事务
QoS 分级	属性 QoS 0，事件 QoS 1	平衡可靠性和性能
心跳间隔	`keepAliveSec` 适当调大	减少心跳开销

低内存设备可缩小日志与缓存规模；非关键 Tag 可适当增大 pollIntervalMs。

9. 调试接口安全边界

POST /api/debug/read 当前忽略请求中的设备/Tag ID，会执行全量 pollOnce()；在真实设备上可能触发额外总线负载。
POST /api/debug/write 是手工调试入口，不是云端 MQTT 反向控制；生产代码没有调用 subscribeFunction。
POST /api/debug/ping 将 host 直接拼接进 std::system() 命令，存在命令注入风险。不要向不可信用户或网络开放，应先修复输入处理或隔离该接口。
POST /api/system/reboot 会真实触发系统重启命令，必须严格限制 Token 和网络暴露面。
认证中间件主要验证 Token，不应据此推断管理员、操作员、只读角色已经在每个敏感路由强制隔离。

10. 不应当作已完成运维能力的功能

离线补报：活动上报路径未使用 SqliteCache 保存并补发断网批次。
配置重连：MQTT PUT 不执行界面所暗示的自动重连；客户端重连原语也不构成完整运维保证。
恢复出厂：当前接口只记录日志并返回 resetting，没有完成配置清理。
OTA：当前上传接口只返回文件名、大小和 uploading，没有完成固件校验、安装和回滚。
反向控制：生产 function 订阅与命令执行链路未接通。

网关运维 ​

1. 日常检查 ​

2. 日志管理 ​

2.1 日志位置 ​

2.2 查看与过滤 ​

2.3 日志级别 ​

3. 认证后的运行信息 ​

4. 监控与告警接入 ​

4.1 Prometheus / Grafana ​

4.2 告警阈值建议 ​

4.3 报警引擎监控 ​

4.4 驱动健康监控 ​

5. 配置与数据备份 ​

5.1 备份范围 ​

5.2 导出与导入 ​

6. 固件升级（OTA） ​

7. 常见排障 ​

7.1 Web 无法打开或静态资源缺失 ​

7.2 MQTT 无法连接或保存后未生效 ​

7.3 没有采集值或无法写入 ​

7.4 报警未触发或频繁抖动 ​

7.5 驱动被自动隔离 ​

8. 性能调优 ​

9. 调试接口安全边界 ​

10. 不应当作已完成运维能力的功能 ​

网关运维

1. 日常检查

2. 日志管理

2.1 日志位置

2.2 查看与过滤

2.3 日志级别

3. 认证后的运行信息

4. 监控与告警接入

4.1 Prometheus / Grafana

4.2 告警阈值建议

4.3 报警引擎监控

4.4 驱动健康监控

5. 配置与数据备份

5.1 备份范围

5.2 导出与导入

6. 固件升级（OTA）

7. 常见排障

7.1 Web 无法打开或静态资源缺失

7.2 MQTT 无法连接或保存后未生效

7.3 没有采集值或无法写入

7.4 报警未触发或频繁抖动

7.5 驱动被自动隔离

8. 性能调优

9. 调试接口安全边界

10. 不应当作已完成运维能力的功能