网关配置

开发预览

本页以提交 b1a16cbc 的运行时解析器（GatewayConfig、TagConfig::fromJson 等）和活动回调为准，同时收录项目配置文档中尚未被运行时读取的键并明确标注。写入配置不等于驱动已注册或端到端功能已验证。

1. 配置文件与生效方式

主配置文件默认为 config/gateway.json，进程通过 --config 指定路径。配置文件不存在时会按内置默认值自动创建；加载时以文件内容覆盖默认值（merge），保存时先写临时文件再原子 rename，避免断电损坏。

以下键由当前代码直接读取：

配置键	当前用途
`web.port`	Web UI/API 的 HTTP 端口，默认 `8080`
`system.logLevel`	日志级别，如 `trace`、`debug`、`info`、`warn`、`error`
`mqtt.broker` / `mqtt.port`	Broker 主机和端口；主机名不带 `tcp://` 或 `ssl://` 前缀
`mqtt.clientId`	MQTT Client ID
`mqtt.username` / `mqtt.password`	Broker 认证凭据
`mqtt.productId` / `mqtt.deviceNum`	属性上报和 function 主题的产品/设备段
`mqtt.keepAliveSec`	MQTT Keep Alive 秒数，默认 `60`
`mqtt.connectTimeoutMs`	连接超时（毫秒），默认 `10000`
`mqtt.cleanSession`	MQTT Clean Session，默认 `true`
`mqtt.qos`	发布和订阅 QoS，默认 `1`
`mqtt.tls`	是否使用 `ssl://` 连接；证书字段需另行正确配置
`mqtt.caCert` / `mqtt.clientCert` / `mqtt.clientKey`	可选 TLS CA、客户端证书和私钥路径
`mqtt.autoReconnect` / `mqtt.reconnectIntervalMs` / `mqtt.maxReconnectAttempts`	Paho 客户端自动重连选项与基础间隔；不构成生产断网数据保证
`drivers`	顶层驱动配置数组，见第 4 节
`engine.defaultPollMs` / `engine.maxTags` / `engine.batchSize`	TagEngine 默认轮询间隔、Tag 上限、批量大小
`alertManager.maxHistoryDays` / `alertManager.maxActiveAlerts` / `alertManager.deduplicateEnabled`	告警历史保留天数（30）、最大活跃告警数（1000）、告警去重
`ota.versionApiUrl` / `ota.binaryPath`	OTA 版本检查地址与可执行文件路径
`certificates.certDir` / `certificates.enabled`	TLS 证书目录与开关

PUT /api/mqtt/config 当前只处理 broker、port、clientId、username、password，随后保存配置，不会按 Web 文案自动重连。完整的 MQTT 修改应编辑真实配置并重启进程，同时先解决部署中的只读挂载问题。

2. 默认配置中暂未被运行时读取的键

仓库默认 config/gateway.json 还包含以下键，它们来自项目配置文档的设计目标，但当前 GatewayConfig 运行时代码没有读取方，不要把这些键当作已生效配置：

gateway.name / gateway.webPort / gateway.logLevel / gateway.dataDir：旧版键名，活动读取键是 web.port 和 system.logLevel。
network.*（wifiMode/wifiSsid/apSsid 等）：WiFi/AP 配网的设计配置，当前由 NetworkManager 模块负责，生效方式以其实现为准。
cache.*（enabled/maxRecords/maxSizeMB/dbPath）：断网缓存设计配置；SqliteCache 已构造但未接入活动上报链路。
engine.defaultPollIntervalMs / engine.reportIntervalMs / engine.batchMergeEnabled：引擎扩展设计键，活动读取键为 engine.defaultPollMs 等。
mqtt.reconnectMinSec / mqtt.reconnectMaxSec：指数退避设计键，活动读取键为 mqtt.reconnectIntervalMs。
FASTBEE_MQTT_*、FASTBEE_WEB_PORT、FASTBEE_LOG_LEVEL 等环境变量覆盖与配置热重载为设计目标，当前没有完整实现；Compose 中的 TZ 不应被类推为通用配置覆盖机制。

3. 配置加密与秘密管理

启动时会对配置启用 AES 加密支持（ConfigCrypto）：配置文件中的敏感字段以 ENC(...) 密文存储，加载时解密、保存时加密，密钥文件为配置目录下的 .secret.key（首次启动自动创建）。

备份密文配置时必须按安全策略同步保护密钥，且不能提交到公开仓库。
ENC(...) 密文依赖匹配的密钥，不能跨环境移植；部署时替换为本环境凭据。
Compose 的只读 config 挂载会阻止密钥创建和 API 保存，需要在部署设计中显式解决。
默认 admin/admin123 必须立即修改；匿名 Mosquitto 只允许用于隔离开发环境。

4. 驱动配置（drivers 数组）

运行时从顶层 drivers 数组读取以下字段（兼容旧键已标注）：

字段	说明
`protocolName`	协议名，Modbus 示例为 `modbus`，默认 `modbus`
`connectionType`	`tcp` 或 `rtu`，默认 `tcp`
`host` / `port`	TCP 目标地址和端口，默认 `127.0.0.1:502`
`serialDevice`	RTU 串口设备路径；兼容旧键 `serialPort`
`baudRate`	串口波特率，默认 `9600`；兼容旧键 `baudrate`
`parity`	整数奇偶校验：`0=N`、`1=O`、`2=E`
`dataBits` / `stopBits`	串口数据位（8）和停止位（1）；兼容小写旧键
`timeoutMs` / `retryCount`	请求超时（3000ms）与重试次数（3）
`pollIntervalMs`	驱动轮询间隔（1000ms）

TCP 示例：

json

{
  "drivers": [
    {
      "protocolName": "modbus",
      "connectionType": "tcp",
      "host": "192.0.2.10",
      "port": 502,
      "timeoutMs": 3000,
      "retryCount": 3,
      "pollIntervalMs": 1000
    }
  ]
}

192.0.2.10 仅为文档保留地址。真实 libmodbus 驱动代码存在，但当前应用只加载并记录这些配置，没有创建、初始化和注册驱动；其他协议也不能绕过这一共同阻塞。OPC UA 仅可选/开发，BACnet、IEC104、S7、DLT645 当前均按 Stub/联调中边界看待，详见概览第 7、8 节。

5. 设备与 Tag 字段

5.1 子设备

POST /api/devices 和 PUT /api/devices/:id 当前解析：

deviceId：内部唯一 ID；新增为空时会生成 dev-<timestamp>。
productId、deviceNum、deviceName：产品、设备编号和显示名。
protocolType：协议类型，如 modbus。
online、lastHeartbeat：可序列化的状态字段，不应被当作物理在线保证。

Web 当前发送/展示的 id、protocol、slaveAddress 等字段与运行时并不一致；不要根据界面推断 API 模型。

5.2 Tag 字段

POST /api/devices/:id/tags 使用 TagConfig::fromJson()。实际解析的字段：

字段	说明
`id`、`name`	Tag 标识与显示名；`deviceId` 由路由中的设备 ID 覆盖
`sourceType`	数字来源类型：`0=MODBUS`、`1=OPCUA`、`2=BACNET`、`3=IEC104`、`4=DLT645`、`5=S7`，另有 `10/11/12=GPIO_DI/DO/AI`、`20=SYSTEM`
`slaveAddr`、`registerAddr`、`registerCount`	Modbus 从站地址、零基寄存器地址、寄存器数量
`scale`、`offset`、`unit`	线性缩放因子、偏移量、工程单位
`scaleType`、`sqrtFactor`	缩放类型：`0=NONE`、`1=LINEAR`、`2=SQRT`、`3=CUSTOM`；SQRT 模式系数
`pollIntervalMs`、`deadband`、`reportOnChange`、`enabled`	采集周期（ms）、死区值、变化即报、启用开关
`nodeId`	OPC UA 节点 ID（如 `ns=2;s=Temperature`）
`objectType`、`instanceId`、`propertyId`	BACnet 对象类型、实例号、属性 ID
`gpioChannel`	GPIO 通道号

注意：

registerAddr 是零基地址并直接传给 libmodbus；第一个保持寄存器使用 0，不要直接以 40001 代替。
当前请求解析器不读取 dataType、function/functionCode、byteOrder 或 pollInterval 字段（byteOrder 恒为默认值大端序），尽管响应可能序列化 dataType；配置验收必须检查实际读取字段。
缩放转换在驱动层生效：LINEAR 为 工程值 = 原始值 × scale + offset，SQRT 为 工程值 = √原始值 × sqrtFactor；反向转换（控制下发）仅 LINEAR 支持。

6. GPIO 配置（gpio.json）

GPIO 通道配置独立于主配置，由 GpioManager 读取，字段细节以其运行时实现为准。项目文档给出的示例结构：

json

{
  "di":  [{"channel": 0, "name": "door_sensor", "productId": "P003", "propertyId": "door"}],
  "do":  [{"channel": 0, "name": "relay_1", "productId": "P003", "propertyId": "relay"}],
  "ai":  [{"channel": 0, "name": "temp_sensor", "range": [4, 20], "unit": "mA", "engMin": 0, "engMax": 100}],
  "led": [{"name": "power", "gpio": 17}, {"name": "network", "gpio": 27}, {"name": "fault", "gpio": 22}]
}

真实 GPIO 需要编译时启用 -DFASTBEE_ENABLE_GPIO=ON 并安装 libgpiod；否则使用模拟后端。以引脚为单位的更强外设模型（DI/DO/AI/AO/LED/蜂鸣器/看门狗）见外设与联动。

7. MQTT 主题与活动数据格式

属性上报主题：

text

/{productId}/{deviceNum}/property/post

function 订阅原语主题（当前未被生产代码调用）：

text

/{productId}/{deviceNum}/function/#

活动上报回调使用的 JSON 结构：

json

{
  "deviceId": "modbus-dev-001",
  "timestamp": 1700000000000,
  "tags": [
    { "id": "holding-0", "value": 25.5, "quality": 0 }
  ]
}

quality 取值：0=GOOD、1=BAD、2=UNCERTAIN、3=TIMEOUT、4=NOT_CONNECTED、5=CONFIG_ERROR。

另有未接入活动回调的 TagMapper::buildPropertyPost()，会生成不同的 params 格式。当前应区分"代码中存在的映射器"和"实际活动上报格式"。MQTT 断开时活动回调跳过本批数据，SqliteCache 的构造和 cache 配置不等于离线补报已经工作；生产代码也未调用 function 订阅。

8. 报警规则与聚合规则

报警规则通过 REST API 动态配置（POST /api/alarms/rules），无需修改配置文件。规则 JSON 结构：

json

{
  "id": "high-temp",
  "name": "高温报警",
  "tagId": "temp1",
  "type": "LEVEL",
  "enabled": true,
  "severity": "HIGH",
  "hEnabled": true,
  "highLimit": 80.0,
  "hhEnabled": true,
  "highHighLimit": 95.0,
  "lEnabled": true,
  "lowLimit": 10.0,
  "deadband": 2.0
}

字段	说明
`type`	报警类型：`LEVEL`/`DEVIATION`/`RATE_OF_CHANGE`/`QUALITY`/`DIGITAL`
`severity`	严重级别：`LOW`/`MEDIUM`/`HIGH`/`CRITICAL`
`highLimit` / `lowLimit`	高/低阈值（LEVEL 类型，支持 HH/H/L/LL 四级）
`deadband`	死区值，防止阈值附近抖动
`deviationBand` / `rateLimit`	偏差允许范围（DEVIATION）/ 变化率上限（RATE_OF_CHANGE）

报警引擎已通过 TagChangeObserver 与 TagEngine 联动：Tag 值更新时自动评估规则，状态机为 NORMAL → ACTIVE → ACKED → RETURNED。规则管理、活跃报警、确认/消音、统计与导入导出的接口见 API 报警引擎一节。

Tag 聚合器支持 MAX/MIN/AVG/TOTAL/DELTA/RATE 滑动窗口聚合。当前活动路由只有查询接口（GET /api/aggregator/rules、GET /api/aggregator/rules/:id/result），没有注册创建规则的接口，规则需待后续版本提供配置入口。

驱动健康监控器的参数（maxConsecutiveErrors=10、watchdogTimeoutMs=30000、autoRecoverMs=60000）在代码注册时设置，运行状态通过 GET /api/drivers/health 查询；由于驱动注册阻塞尚未解除，健康数据需结合该前提解读。

9. 秘密与配置安全检查清单

.secret.key 与密文配置必须与公开文档、镜像和日志隔离，并按组织秘密管理策略保存。
完整 MQTT 修改应编辑真实配置文件并重启进程，而不是依赖 PUT 接口的"保存并重连"文案。
tls: true 会选择 MQTT TLS 客户端连接，但随附 Mosquitto 的 8883 并未自动获得 TLS 配置，两者不能混为一谈。
恢复时同时核对配置路径、密钥匹配、文件所有者与写权限；只读配置挂载会阻止 .secret.key 和 API 配置写入，不能只通过反复重启掩盖该问题。

网关配置 ​

1. 配置文件与生效方式 ​

2. 默认配置中暂未被运行时读取的键 ​

3. 配置加密与秘密管理 ​

4. 驱动配置（drivers 数组） ​

5. 设备与 Tag 字段 ​

5.1 子设备 ​

5.2 Tag 字段 ​

6. GPIO 配置（gpio.json） ​

7. MQTT 主题与活动数据格式 ​

8. 报警规则与聚合规则 ​

9. 秘密与配置安全检查清单 ​

网关配置

1. 配置文件与生效方式

2. 默认配置中暂未被运行时读取的键

3. 配置加密与秘密管理

4. 驱动配置（drivers 数组）

5. 设备与 Tag 字段

5.1 子设备

5.2 Tag 字段

6. GPIO 配置（gpio.json）

7. MQTT 主题与活动数据格式

8. 报警规则与聚合规则

9. 秘密与配置安全检查清单