环境控制

环境控制是智档宝面向库房环境和现场安全的能力板块，关注环境数据采集、设备控制、异常告警和现场联动。

设备草稿

下面这张是讲解现场设备、网络、网关和调试入口时使用的 Excalidraw 草稿，用于辅助理解环境控制设备接入，不作为最终架构定稿。

业务定位

环境控制回答“库房现场是否安全、环境是否正常、设备是否可控”的问题。它服务于档案保管环境，也服务于现场运维和大屏展示。

设备类型

环境控制设备先按设备类型组织，再在每个类型下面看具体型号、主子设备关系和业务能力。这样比直接按“温湿度、漏水、空调”罗列更接近现场调试和后端实现。

设备类型	说明	典型设备
POE 设备	飞度自研或适配的 POE / MQTT 设备，是当前环境控制主线	网关 Lite、中枢网关、空气质量传感器、温湿度传感器、漏水报警、短信报警、16DI、8DO、加湿除湿一体机
其他设备	不走 POE 设备模型，但属于库房现场安防和视频能力	推流盒子、摄像头、门禁、海康 ISAPI / 网关、监控平台
虚拟设备	不一定有独立硬件，更多是平台内聚合、映射或软件状态	大屏卡片、智能面板展示项、软件模拟设备、状态聚合设备
无线设备	通过无线网络或 LoRaWAN 平台进入系统，后端以 chirpstack 源类型区分	ChirpStack 设备、无线温湿度、无线采集节点

POE 设备

POE 设备是当前环境控制的主线设备模型。这里的“POE”不只是供电方式，也代表一套现场接入方式：设备接入局域网，平台先通过 UDP 做发现和网络配置，再通过 MQTT 做运行期数据上报、状态同步和控制下发。

UDP

UDP 是 POE 设备的现场发现和初始化配置通道。设备刚上电、还没有接入平台时，实施人员先通过 UDP 在局域网里找到设备，再把设备改到正确的网络和 MQTT 配置。

能力	说明
发现设备	扫描局域网里的 POE 设备，拿到 SN、IP、MAC、设备型号、固件版本等基础信息
设置 IP	把设备设置为静态 IP 或指定网络参数，避免现场重启后地址漂移
设置 MQTT	把 MQTT 服务器地址、端口等连接参数写入设备
重启 / 重置	远程重启设备，或在配置错误时重置设备

端口	方向 / 场景	说明
10086/udp	平台广播 / 发现 / 配置	当前 fdmjj 后端 UdpBoardCast 使用的主线端口，后端 Dockerfile 也暴露这个 UDP 端口
1234/udp	历史发现 / 模拟工具 / 软网关兼容	virtual-device-builder、soft-gateway 等历史或模拟工具仍会向 255.255.255.255:1234 广播设备状态，后端 Dockerfile 也保留暴露
1883/tcp	MQTT 连接结果	不是 UDP 端口；UDP 的 Set_Mqtt 会把设备指向这个 MQTT broker 端口

现场排查时不要只看其中一个 UDP 端口。当前主线配置优先看 10086/udp，但历史虚拟设备、软网关和部分调试工具可能还在发 1234/udp；防火墙、容器端口映射、交换机 VLAN 和广播隔离要一起确认。

UDP 命令	方向	用途
Device_Status_BoardCast	设备 -> 平台	设备主动广播自己的 SN、IP、MAC、固件、MQTT 状态和基础信息，用于设备列表和在线发现
DISCOVERY	设备 -> 平台	设备请求平台下发 MQTT 地址；平台侧需要打开设备发现开关才会响应
Set_Mqtt	平台 -> 设备	下发 MQTT broker 地址和端口，让设备进入运行期 MQTT 通道
IP_MODE_SET	平台 -> 设备	设置静态 IP、网关、掩码、DNS 或网络模式
REBOOT	平台 -> 设备	重启设备
RESET	平台 -> 设备	重置设备配置

设备状态广播示例，常见于 Device_Status_BoardCast：

{
  "device_info": {
    "device_type": "FEIDU_POE_GATEWAY_LITE",
    "HW_version": "1.0",
    "FW_version": "1.4.0",
    "role": "NONE",
    "read_time_interval": 5000,
    "compile_time": 1714576349,
    "device_sn": "e465b86741fb",
    "ip": "192.168.0.52",
    "mac": "E4:65:B8:67:41:FB",
    "gateway": "192.168.0.1",
    "dns": "169.254.0.1",
    "subnet": "255.255.255.0",
    "NetWork_Mode": "STATIC",
    "mqtt_server_host": "192.168.0.2",
    "mqtt_server_port": 1883,
    "clientID": "esp32-e465b86741fb",
    "mqtt_status": true,
    "mqtt_config_st": "true",
    "device_ota_status": "false",
    "register_status": "false",
    "deviceOnDI1": "none",
    "deviceOnDI2": "none",
    "deviceOnDI3": "none",
    "deviceOnDI4": "none"
  },
  "command": "Device_Status_BoardCast",
  "task_id": -1,
  "param": {
    "message": "Device_Status_BoardCast"
  }
}

设备主动发现示例：

{
  "device_info": {
    "device_sn": "e465b86741fb"
  },
  "command": "DISCOVERY",
  "task_id": 1,
  "param": {}
}

平台回发 MQTT 配置示例：

{
  "device_sn": "e465b86741fb",
  "command": "Set_Mqtt",
  "task_id": 1,
  "mqtt_server_host": "192.168.0.2",
  "mqtt_server_port": "1883"
}

平台下发网络配置示例：

{
  "device_sn": "e465b86741fb",
  "command": "IP_MODE_SET",
  "task_id": 1710000000000,
  "param": {
    "NetWork_Mode": "STATIC",
    "ip": "192.168.0.52",
    "gateway": "192.168.0.1",
    "subnet": "255.255.255.0",
    "dns": "192.168.0.1"
  }
}

平台重启 / 重置设备示例：

{
  "device_sn": "e465b86741fb",
  "command": "REBOOT",
  "task_id": 123
}

{
  "device_sn": "e465b86741fb",
  "command": "RESET",
  "task_id": 123
}

UDP 解决的是“设备在哪里、怎么让它连上平台”。如果 UDP 扫不到设备，优先检查供电、网线、交换机 VLAN、电脑和设备是否在同一网段，以及现场防火墙是否拦截广播。

MQTT

MQTT 是 POE 设备运行期的主通道。设备完成 UDP 初始化后，会连接到平台配置的 MQTT 服务，后端再根据设备消息创建、更新和控制设备。

参考资料：POE 设备 MQTT 协议说明。

当前 fdmjj 后端订阅的是固定 topic，不是按设备 SN 分 topic。旧代码注释里出现过 /sn/control、/sn/information、/sn/warning 这种方向，但当前主线按 information、warning、control 三个 topic 维护。

Topic	方向	用途	后端入口
information	设备 / 虚拟设备 -> 后端	常规状态、传感器数据、控制回包、心跳类数据	MqttInfoMessageHandler
warning	设备 / 虚拟设备 -> 后端	突发事件、DI 变化、报警触发类数据	MqttWarningMessageHandler
control	后端 -> 设备 / 虚拟设备	控制命令、读取命令、继电器控制、空调控制、设置命令	SendCommand 发布

消息对象	说明
device_info	设备基础信息，包含 device_type、SN、IP、MAC、固件版本、MQTT 状态等
command	设备上报或控制命令，例如传感器读取、继电器状态、空调控制、漏水状态等
param	命令参数和业务数据，例如温湿度、空气质量、串口号、地址、DI/DO 状态等
device_type	后端识别设备处理分支的关键字段，例如 FEIDU_POE_GATEWAY_LITE
task_id	-1 表示普通上报；非负数通常表示控制请求 / 回包，用于后端等待响应
device_sn	控制下发时放在顶层；设备上报时以 device_info.device_sn 为准

后端按 device_type 分流处理 MQTT 消息。主设备消息会更新自己的在线和状态；网关类设备还会根据串口、地址、DI/DO 通道，把数据同步到子设备。

设备状态上报示例，发布到 information：

{
  "device_info": {
    "device_type": "FEIDU_POE_AIR_SENSOR",
    "HW_version": "0.3",
    "FW_version": "1.2.3",
    "role": "NONE",
    "read_time_interval": 5000,
    "compile_time": 1714455742,
    "device_sn": "a0b765fa0c77",
    "ip": "192.168.0.55",
    "mac": "A0:B7:65:FA:0C:77",
    "gateway": "192.168.0.1",
    "dns": "169.254.0.1",
    "subnet": "255.255.255.0",
    "NetWork_Mode": "STATIC",
    "mqtt_server_host": "192.168.0.2",
    "mqtt_server_port": 1883,
    "clientID": "esp32-a0b765fa0c77",
    "mqtt_status": true,
    "mqtt_config_st": "true",
    "register_status": "false"
  },
  "command": "get_sensor",
  "task_id": -1,
  "param": {
    "temp": 19.48,
    "humidity": 31.65,
    "tvoc": 216,
    "eco2": 534,
    "pm10": 31,
    "pm25": 46,
    "pm100": 58,
    "ch2o": 0.052
  }
}

网关子设备上报示例，发布到 information。后端会按 device_info.device_sn + serial + address 形成子设备 SN，例如 e465b86741fb_Serial1_3：

{
  "device_info": {
    "device_type": "FEIDU_POE_GATEWAY_LITE",
    "device_sn": "e465b86741fb",
    "clientID": "esp32-e465b86741fb",
    "mqtt_status": true,
    "mqtt_config_st": "true"
  },
  "command": "get_device_temp_hum",
  "task_id": -1,
  "param": {
    "serial": "Serial1",
    "address": 3,
    "temperature": 22.6,
    "humidity": 53.1,
    "message": "success"
  }
}

DI 变化示例，发布到 warning。后端只处理 DIstatusN = Changed 的通道，并把对应子设备状态同步到 Redis 和报警逻辑：

{
  "device_info": {
    "device_type": "FEIDU_POE_16DI_CONTROL",
    "device_sn": "d8132a2f7a1b"
  },
  "command": "IO_change",
  "task_id": -1,
  "param": {
    "DI1": 1,
    "DIstatus1": "Changed",
    "DI2": 0,
    "DIstatus2": "Unchanged"
  }
}

后端控制示例，发布到 control。设备或虚拟设备需要订阅 control，按顶层 device_sn 判断是否是自己的命令；如果 device_sn = "#"，表示广播命令：

{
  "command": "relay_control",
  "task_id": 123,
  "device_sn": "08f9e08bd9f3",
  "relay_states": [
    {
      "relay_index": 1,
      "activate": true,
      "connection_type": "normally_open"
    }
  ],
  "param": {}
}

控制类命令如果需要同步等待结果，设备应在 information 回一条相同 task_id 的消息。后端会把回包放进内存消息中心的 task_<task_id>；空调学习是例外，使用 air_conditioner_learn_<device_sn> 等待。

常见 device_type	常见 command	处理逻辑
FEIDU_POE_AIR_SENSOR	get_sensor	直接更新空气质量传感器状态
FEIDU_POE_GATEWAY_LITE	get_io_status	更新网关状态，并同步 DI 子设备
FEIDU_POE_GATEWAY_LITE	relay_status_read	按 relay_states 创建 / 更新 DO 子设备
FEIDU_POE_GATEWAY_LITE	get_device_temp_hum、get_air_quality	按 serial + address 更新网关串口子设备
FEIDU_POE_GATEWAY_LITE	custom_*	自定义第三方设备数据，直接同步到 网关SN_serial_address
FEIDU_POE_16DI_CONTROL	get_io_status、IO_change	16DI 主设备状态和 DI 子通道状态
FEIDU_POE_8DO_CONTROLLER	relay_status_read	8DO 主设备状态和继电器子通道状态
FEIDU_POE_DEHUMIDIFIER	DEVICE_STATUS_PUBLISH	独立 POE 加湿除湿一体机状态

在线方式

POE 设备在线不是只看页面上有没有设备，而是看设备是否能持续完成“网络连接 -> MQTT 连接 -> 状态上报 -> 后端更新时间”这条链路。

判断层	说明
UDP 可发现	说明设备在局域网里可见，但不等于已经接入业务系统
MQTT 已连接	说明设备已经连上 MQTT 服务，是进入业务系统的前提
最近有上报	后端根据最新 MQTT 消息刷新 LastUpdateTime、缓存和设备状态
主子设备关系正常	数据库里主设备 isMain = true，子设备通过 pid 挂到主设备下
来源类型正确	POE 主线设备默认属于 sourceType = fit，区别于无线设备的 sourceType = chirpstack

典型链路是：设备上电入网后，实施先用 UDP 扫描到设备，配置设备 IP 和 MQTT 服务器；设备连接 MQTT 后上报 device_info、command、param；后端按 device_type 创建或更新主设备，再按串口、地址、DI/DO 通道派生子设备。

现场排查时可以按这个顺序判断：先看 UDP 能不能发现设备；再看设备是否配置到正确的 MQTT 地址；再看 MQTT 是否在线并上报；最后看数据库里主设备 isMain、子设备 pid、SN 命名和通道绑定是否正确。

设备类型

POE 设备内部再按设备层级理解：主设备直接入网，子设备挂在主设备下面；部分独立传感器虽然不管理子设备，但仍作为 POE 主设备接入。

层级	说明	典型设备 / 能力
主设备	直接入网，有独立 SN，平台把它作为设备树的根节点或独立节点	网关 Lite、中枢网关、16DI、8DO、空气质量传感器、短信报警模块、POE 加湿除湿一体机、漏水报警模块
网关串口子设备	挂在网关串口下，通常按“父设备 SN + 串口 + 地址”形成子设备 SN	空调控制器、新风净化一体机、加湿除湿一体机、紫外线传感器、除霉机、新风机、窗帘、驱鼠器、健康防护一体机
DI 输入子设备	挂在网关或 16DI 下，采集开关量、报警输入或传感器触发状态	人体传感器、烟雾传感器、消防主机、温感传感器、漏水报警监测点、未连接通道
DO 输出子设备	挂在网关或 8DO 下，用于继电器输出、声光报警或设备联动	声光报警器、继电器输出、8DO 子设备
展示 / 操作子设备	以设备身份进入页面或大屏，但更多承担展示、入口或现场操作能力	智能面板、大屏可视设备图标

POE 主设备列表

设备型号	中文名称	主要职责	备注
FEIDU_POE_GATEWAY_LITE	网关 Lite	通过 MQTT 接入平台，管理 DI 通道、DO 输出和串口子设备	常见现场主网关；创建后会自动生成 DI 子通道
FEIDU_POE_CENTER_CONTROL	中枢网关	汇总或控制一组环境设备，处理传感器和漏水等状态	更偏集中控制入口
FEIDU_POE_16DI_CONTROL	16 路采集	采集多路开关量输入	常用于人体、烟感、消防、温感等输入
FEIDU_POE_8DO_CONTROLLER	8 路控制	控制多路继电器输出	常用于声光报警、联动输出
FEIDU_POE_AIR_SENSOR	空气质量传感器	上报温湿度、PM、TVOC、CO2、甲醛等空气质量数据	直接 MQTT 上报，更新频率较高
FEIDU_POE_DEHUMIDIFIER	POE 加湿除湿一体机	上报和控制加湿、除湿、漏水等状态	作为独立主设备接入
FEIDU_POE_SMS_SENDER	短信报警模块	上报在线和时间状态，配合报警通知	常用于现场短信告警
FEIDU_POE_VOICE_ALARM_WATER_LEAK_SENSOR	漏水报警模块	上报漏水状态和监测点状态	可以派生漏水报警监测点

网关子设备列表

子设备类型	代码 / 显示名	接入逻辑	典型用途
空调控制器	空调控制器	挂在网关串口，按串口和地址轮询状态、下发控制	空调学习、空调控制、环境联动
新风净化一体机	新风净化一体机	挂在网关串口，读取和控制净化设备	空气质量联动
加湿除湿一体机	加湿除湿一体机	可作为网关串口子设备，也可能有独立 POE 型号	湿度控制、恒温恒湿
紫外线传感器	紫外线传感器	挂在网关串口，上报紫外线状态	特殊环境监测
除霉机	除霉机	挂在网关串口，读取和控制除霉设备	库房环境治理
新风机	新风机	挂在网关串口，读取和控制新风设备	通风联动
智能窗帘	智能窗帘	挂在网关串口，执行窗帘控制	光照或现场联动
网关串口漏水报警	网关-串口-漏水报警	挂在网关串口，上报漏水状态	漏水报警和联动
网关空气质量传感器	空气质量传感器	挂在网关串口，上报空气质量数据	温湿度、PM、TVOC、CO2 等
驱鼠器	驱鼠器	挂在网关串口，读取或控制设备状态	安防和库房防护
健康防护一体机	健康防护一体机	挂在网关串口，读取和控制设备	综合环境治理
温湿度传感器	温湿度传感器	挂在网关串口，上报温湿度	环境曲线和报警
智能面板	智能面板	挂在网关下面，作为现场展示和操作入口	大屏、面板、库房现场查看

DI / DO 通道设备

类型	设备 / 通道	逻辑
DI 输入	人体传感器、烟雾传感器、消防主机、温感传感器	后端把输入通道作为子设备管理，通道状态变化进入报警或联动逻辑。
漏水监测点	漏水报警监测点	漏水模块或网关串口漏水设备可以拆出监测点，用于区分具体漏水位置。
DO 输出	声光报警器、继电器输出、8DO 子设备	输出通道用于报警联动、手动控制或自动控制策略。
未连接	未连接	网关 DI 通道默认可能先建成未连接，用于保留通道位置；现场绑定后再变成具体传感器。

其他设备

其他设备通常走独立接口或厂商协议，不一定进入 POE 的主子设备树，但产品上仍属于环境控制现场能力。当前按监控和门禁两条线维护。

监控

监控能力围绕摄像头接入、通道配置和视频预览。当前推流盒子对接的是讯思维（xsw），后端通过 smart-doc-vault/xsw 访问推流盒子。这里用的是逆向网页接口，不是按厂商正式对接文档接入；维护时应以现有页面接口、登录态和返回结构为准。

能力	当前口径
推流盒子	当前对接讯思维（xsw），作为监控推流服务器管理
摄像头通道	在推流盒子下维护通道、RTSP 地址、用户名、密码和所属位置
流状态	通过逆向网页接口读取讯思维设备信息、通道配置、推流状态和带宽信息
预览地址	后端按推流盒子 IP 和通道拼出 FLV、WebSocket FLV、RTMP、HLS、HTTP-TS、RTSP 等地址；前端当前优先播放 wsFlv
页面入口	设备管理 / 监控、库房监控大屏卡片、3D 库房或设备点位预览

当前前端监控预览不是普通 <video> 直接播 RTSP。推流盒子先把摄像头 RTSP 拉进来，再对外提供多种流地址；前端大屏和设备监控页面主要取 cameraModel.wsFlv，也就是 ws://<推流盒子>/ws/hlsram/liveN.flv 这种 WebSocket FLV 地址，然后交给 Jessibuca 播放器解码渲染。

播放链路	当前口径
摄像头到推流盒子	摄像头侧通常提供 RTSP，通道配置里保存 rtspUri、用户名、密码
推流盒子到后端	后端通过讯思维逆向接口读取通道、带宽和状态
后端返回地址	CameraModel.AfterFind 和大屏 WebSocket 会生成 httpFlv、wsFlv、rtmp、hls、httpTs、rstp
前端实际播放	大屏和监控组件取 wsFlv，用 Jessibuca 创建播放器实例并调用 play(wsFlv)
多路同屏	每个通道创建独立 Jessibuca 实例，退出或重连时销毁旧实例，避免页面长期堆积解码器

前端选择 ws-flv + Jessibuca，主要是为了解决库房监控大屏六路以上同屏播放的问题。浏览器原生能力不能直接播放 RTSP，HLS 延迟偏高，多路 <video> + 普通 FLV 方案在低配终端上容易卡顿。当前播放器配置启用了 useMSE、useSIMD、autoWasm 和 demuxUseWorker：能走 MediaSource 时走 MSE，解码失败或环境不支持时自动降级到 WASM，解封装放到 worker 里做，音频关闭以减少 CPU 消耗。

前端播放器配置	作用
videoBuffer: 0.2	控制低延迟缓存，减少监控画面滞后
useMSE: true	优先使用 MediaSource 播放 FLV 流
useSIMD: true	在支持的浏览器上启用 SIMD 加速
autoWasm: true	解码路径不可用时自动走 WASM 能力
demuxUseWorker: true	把 FLV 解封装放到 worker，减少主线程压力
hasAudio: false	监控预览不解音频，降低多路同屏负载
loadingTimeoutReplayTimes: -1 / heartTimeoutReplayTimes: -1	播放异常时持续重试，适配现场网络抖动

排查监控画面时按链路分层：通道没画面先看摄像头 RTSP 和讯思维通道状态；只有前端黑屏先看 wsFlv 地址、WebSocket 是否被代理或防火墙拦截、浏览器是否加载了 Jessibuca 的 decoder.js / decoder.wasm；六路以上卡顿优先看终端 CPU、浏览器 WebAssembly / SIMD 支持、是否开启音频、以及同屏实例是否正确销毁。

代码入口	说明
smart-doc-vault/service/env/camera_server.go	推流盒子服务，调用 xsw 客户端和 global.XswGateway
smart-doc-vault/router/env/common.go	/cameraServer/* 和 /camera/getTwoStream 路由
smart-doc-vault/model/system/camera.go	摄像头通道、RTSP、流地址和在线状态模型
fit-archive-ng/src/utils/jessiBucas.ts	前端 Jessibuca 播放器统一配置
fit-archive-ng/src/views/bigdatascreen/monitorBigScreen.vue	监控大屏多路 wsFlv 播放、重连和销毁逻辑
fit-archive-ng/src/views/bigdatascreen/componet/cencterIcon/IconCamera.vue	大屏图标点位里的摄像头播放逻辑

门禁

门禁能力当前按海康 ISAPI / 网关口径维护，主要对接明眸人脸门禁一体机和海康网关能力。它不走 POE 设备树，后端以 hik_isapi 表保存服务地址、账号、密码、端口和库房位置，再通过 HikIsapiGateway 查询门禁状态、人员、人脸、卡、事件和远程开门。

网盘文档：ISAPI开发指南_明眸_人脸门禁一体机_2023_07_18w.pdf

海康门禁历史上有两套实现口径：早期是单服务 / 单设备口径，当前是网关化的多设备口径。维护时优先看当前 fdmjj 分支的 /accessControl/*，只有追溯旧现场或旧分支时再看 /door/*。

阶段	实现口径	关键差异	GitLab 线索
历史方案	DoorApi + global.HikService + /door/*	以系统设置里的海康地址、账号、密码初始化一个全局 ISAPI 客户端，更偏单门禁服务；旧路由包括 /door/addPersonInfo、/door/controlDoor、/door/getAcsEvent 等	zks/smart-doc-vault-hikgateway
当前方案	HikIsapiGateway + hik_isapi 表 + /accessControl/*	多海康设备 / 网关管理，服务配置落库，支持连接状态、长连接事件、人员、人脸、卡、事件、远程开门和大屏数据源	fit-archive/fdmjj/smart-doc-vault

能力	当前口径
服务配置	维护海康设备 / 网关 IP、端口、账号、密码、名称和启用状态
在线状态	通过 HikIsapiGateway 判断连接状态和门禁状态
人员 / 人脸 / 卡	支持人员信息、人脸信息、卡信息的新增、修改、删除和查询
门禁事件	查询门禁事件、事件图片、事件数量和通行历史
门状态 / 远程开门	查询门状态，并通过 ISAPI / 网关执行远程开门
大屏展示	支持库房门禁、门禁信息统计、门禁信息列表等大屏卡片

代码入口	说明
smart-doc-vault/router/env/hik_isapi.go	/accessControl/* 门禁路由
smart-doc-vault/service/env/hik_isapi.go	海康 ISAPI 业务服务
smart-doc-vault/model/system/hik_isapi.go	hik_isapi 服务配置和运行状态模型
fit-archive-ng/src/api/ApiDevice/doorLock	前端门禁接口封装

虚拟设备

虚拟设备用于把软件状态、聚合状态或第三方设备数据放进 POE 设备体系。这里的重点不是“做一个新设备分类”，而是模拟 POE 设备的 MQTT 行为：软件进程直接发布 information / warning，订阅 control，让后端以为它面对的是一个真实网关或传感器。

这个方案适合对接第三方设备时使用。第三方设备如果已经有 TCP、Modbus、HTTP 或厂家 SDK，可以由一个软网关进程读取第三方数据，再翻译成飞度 POE MQTT JSON。这样可以绕过自研 POE 网关硬件和固件定制，减少现场定制硬件、烧录固件、调试串口协议的成本。

GitLab 线索	用途	当前判断
fit-archive/virtual-device-builder	早期虚拟设备 / 模拟器，包含空气质量、温湿度、DI、DO、空调、漏水等模拟脚本	适合看消息格式和测试思路
IOT-FIRMWARE/virtual-device-builder-GUI	虚拟设备 GUI 工具	适合现场演示或手动构造模拟数据
fit-archive/yd/soft-gateway	软网关实现，读取第三方设备数据后模拟 POE 设备上报	更接近第三方设备接入方案
fit-archive/yd/soft-gateway-new	新版软网关实现	新项目优先参考这个方向

方案结构

层	说明
第三方设备侧	真实硬件仍按厂商协议工作，例如 Modbus TCP、串口转 TCP、HTTP API、SDK 等
软网关进程	读取第三方设备状态，转换字段、单位、状态码和控制命令
POE MQTT 适配层	按飞度 POE 设备格式发布 information / warning，并订阅 control
智档宝后端	继续使用原有 POE 设备逻辑创建设备、更新 Redis、写历史、触发报警和下发控制

模拟对象

模拟对象	推荐模拟方式	说明
独立空气质量传感器	模拟 FEIDU_POE_AIR_SENSOR	最简单，直接上报 get_sensor
网关 + 串口设备	模拟 FEIDU_POE_GATEWAY_LITE	用 serial + address 映射第三方设备，生成子设备
16DI 输入	模拟 FEIDU_POE_16DI_CONTROL 或网关 DI	可把第三方开关量、报警量映射成 DI1、DIstatus1
8DO 输出	模拟 FEIDU_POE_8DO_CONTROLLER 或网关 DO	订阅 control 后转成第三方继电器控制
自定义第三方设备	使用 custom_* command	后端会按 网关SN_serial_address 同步数据，适合快速接入非标准设备

接入原则

原则	说明
SN 必须稳定	虚拟 MAC / SN 一旦上线就不要随意变化，否则后端会当成新设备
优先模拟已支持型号	能用 FEIDU_POE_AIR_SENSOR、FEIDU_POE_GATEWAY_LITE、16DI、8DO 就不要新增协议
保留 serial 和 address	第三方多设备接入时，用这两个字段稳定映射子设备
控制必须闭环	软网关订阅 control，执行第三方控制后用同 task_id 回包
状态码要归一	厂商状态、寄存器位、单位换算应在软网关里处理，后端只看 POE 标准字段
故障也要上报	读取失败、离线、通信超时不要静默，至少更新在线状态或错误字段

类型	说明
状态聚合	把多个设备状态聚合成一个展示项
大屏卡片	给大屏或智能面板提供可配置的数据源
软件模拟	调试或演示时模拟设备上报、报警和控制结果
平台设备	第三方平台、3D 巡检或算法系统映射进来的设备对象

软网关示例

以 fit-archive/yd/soft-gateway 为例，README 里的现场对象包括温湿度传感器、除湿机、空调控制器、漏水和人体开关量。代码结构上 fit_device 是飞度设备协议适配层，外层 gateway1.py 负责读第三方 Modbus / TCP 数据，再由 main.py 把数据发布到 MQTT。

{
  "device_info": {
    "device_type": "FEIDU_POE_GATEWAY_LITE",
    "device_sn": "08f9e08b6801",
    "ip": "虚拟设备",
    "mac": "08:F9:E0:8B:68:01",
    "mqtt_server_host": "192.168.1.218",
    "mqtt_server_port": 1883,
    "clientID": "esp32-08f9e08b6801",
    "mqtt_status": true,
    "mqtt_config_st": "true"
  },
  "command": "get_device_temp_hum",
  "task_id": -1,
  "param": {
    "serial": "Serial3",
    "address": 1,
    "temperature": 22.8,
    "humidity": 52.3,
    "message": "success"
  }
}

这个消息发布到 information 后，后端会沿用 POE 网关子设备逻辑：主设备是 08f9e08b6801，子设备可以按 08f9e08b6801_Serial3_1 进入状态、历史曲线、报警和大屏展示。

无线设备

无线设备当前以 ChirpStack 作为主要代码口径。它解决的是“电池供电、低频上报、远距离覆盖”的环境传感器接入，不走 POE 主控 / 子设备树，也不按 POE 设备 1 分钟在线规则判断状态。后端设备模型通过 sourceType = chirpstack 区分无线来源，配置里 dirty.deviceTimeout.byType.chirpstack 当前是 7200 秒，默认兜底也是 2 小时。

关注点	说明
来源类型	fit 是默认设备来源，chirpstack 表示无线设备来源
数据入口	ChirpStack MQTT application/# 消息解析后创建或更新设备
状态判断	无线设备按最后上报时间和无线设备超时策略判断在线
典型数据	温湿度、电量、电压、RSSI、SNR、网关 ID、频道等

接入链路

无线设备链路可以理解成两段：LoRaWAN 网络负责把传感器数据送到 ChirpStack，智档宝后端只消费 ChirpStack 转出的 MQTT JSON。

顺序	节点	作用
1	LoRaWAN 传感器	采集温湿度、光照、气体、电池等数据，并通过 LoRaWAN 上报
2	LoRa 网关	接收传感器无线数据，按 UDP Packet Forwarder 或 Basic Station 协议转发
3	ChirpStack Gateway Bridge	把网关协议转换成 ChirpStack 使用的 MQTT topic
4	ChirpStack	管理应用、设备、网关、设备配置和 uplink 解码
5	Mosquitto / MQTT	承载 ChirpStack integration 输出的 JSON 消息
6	智档宝后端	订阅 application/#，解析无线设备数据
7	设备表 / Redis	写入 source_type = chirpstack 设备，并刷新当前状态

环节	当前口径
传感器	ESP32 LoRaWAN 传感器固件上报 object.sensor_type_name 和业务数据
网关	支持 UDP Packet Forwarder 和 Basic Station，两种方式最终进入 Gateway Bridge
ChirpStack	使用 v4，区域配置重点看 CN470 子频段
MQTT	ChirpStack MQTT integration 输出 JSON，后端订阅 application/#
后端	ChirpStackMqttMessageHandler 解析消息，按 devEui 生成设备 SN

服务部署仓库

无线设备不是直接部署在主系统 compose 里，GitLab 上单独有服务部署 repo。现场如果要排查 LoRa 网关、CN470 频段、ChirpStack 页面或 MQTT 端口，优先看这个部署仓库。

仓库	用途	关键内容	当前口径
fit-archive/chirpstack-docker	ChirpStack 服务部署	docker-compose.yml、ChirpStack 配置、Gateway Bridge 配置、Mosquitto 配置、PostgreSQL 初始化脚本、网关配置模板	当前无线设备服务部署参考
IOT-FIRMWARE/esp-32-lorawan-sensors	LoRaWAN 传感器固件	传感器采集、LoRaWAN 上报、sensor_type_name payload 约定	当前无线传感器固件参考

服务	镜像 / 版本	端口 / 作用
chirpstack	chirpstack/chirpstack:4.13.0	Web / API 8080，管理应用、设备、网关和设备配置
chirpstack-rest-api	chirpstack/chirpstack-rest-api:4.2.0	REST API 8090，部署 repo 保留但官方更推荐 gRPC
chirpstack-gateway-bridge	chirpstack/chirpstack-gateway-bridge:4.0.11	UDP Packet Forwarder 1700/udp
chirpstack-gateway-bridge-basicstation	chirpstack/chirpstack-gateway-bridge:4.0.11	Basic Station 3001
chirpstack-gateway-bridge-cn470-*	chirpstack/chirpstack-gateway-bridge:4.0.11	CN470 子频段 Basic Station，3002 到 3013
mosquitto	eclipse-mosquitto:2	MQTT 1884，ChirpStack integration 和后端消费共用
postgres	postgres:14-alpine	ChirpStack 元数据
redis	redis:7-alpine	ChirpStack 缓存 / 队列

CN470 当前按 cn470_0 到 cn470_11 拆分。部署 repo 的 GATEWAY_CONNECTION_SUMMARY.md 里已经把 3002-3013 对应到各子频段，网关现场配置时要确认网关使用的子频段和 Basic Station 端口一致。

数据解析

后端启动时只有在 chirpstack.enable = true 时才初始化无线链路：先连接 chirpstack.mqttUrl，再订阅 application/#，然后加载数据库里已有的 source_type = chirpstack 设备到内存映射。

ChirpStack 字段	后端用途
deviceInfo.devEui	作为设备 SN
deviceInfo.deviceName	作为设备原始名称；当有 sensor_type_name 时页面名称会改成传感器中文名
deviceInfo.deviceProfileName	作为兜底设备型号
object.sensor_type_name	当前优先作为设备型号，例如 AHT30、ZE08B
object	作为设备状态数据写入 Redis / 页面当前状态
rxInfo[]	选 RSSI 最强的网关，把 rssi、snr、gatewayId、channel 注入到状态数据

sensor_type_name = NONE 和 LTR390_COMBO 当前会跳过处理。已存在设备如果型号变化，后端会删除旧设备后按新型号重建；所以现场调试固件时不要随意切换同一个 devEui 对应的传感器类型。

设备类型

sensor_type_name	页面名称	上报重点
LTR390_UV	紫外线传感器	紫外线指数、电池电压、电量、信号质量
LTR390_LUX	光照传感器	光照强度、电池电压、电量、信号质量
ZE08B	甲醛传感器	甲醛浓度、电池电压、电量、信号质量
AHT30	温湿度传感器	温度、湿度、电池电压、电量、信号质量
SGP30	TVOC传感器	TVOC、eCO2、电池电压、电量、信号质量
BMP30	大气压强传感器	气压、温度、电池电压、电量、信号质量
SGP30_ECO2_ONLY	二氧化碳传感器	eCO2、电池电压、电量、信号质量
SGP30_TVOC_ONLY	TVOC传感器	TVOC、电池电压、电量、信号质量

在线与排查

无线设备低频上报，不能用 POE 设备“短时间没消息就是离线”的判断方式。排查时按链路从下往上看，先确认无线网络，再看主系统。

顺序	检查项	判断方式
1	传感器	上电、电池、电压、固件烧录、devEui 是否与 ChirpStack 设备一致
2	LoRa 网关	ChirpStack 网关页面是否 Online，Last seen 是否更新
3	频段 / 端口	CN470 子频段、Basic Station 端口或 UDP 1700 是否和网关配置一致
4	ChirpStack uplink	ChirpStack 设备页面是否能看到 uplink 和 decoded object
5	MQTT	mosquitto 是否能看到 application/# JSON 消息
6	后端	chirpstack.mqttUrl 是否指向部署 repo 的 MQTT 地址，debug WS 是否出现 [ChirpStack] 日志
7	主系统设备	设备表是否生成 source_type = chirpstack，Redis / 页面当前状态是否更新

业务类型

环境控制业务类型按“设备数据最终用来做什么”组织。设备类型解决接入对象，业务类型解决展示、分析、控制和告警。

业务类型	说明
3D 库房对接	把设备状态、点位和摄像头映射到库房三维空间
历史数据	保存和查询设备历史状态，用于趋势分析和现场复盘
自动控制	根据环境状态、时间策略或人工指令控制现场设备
报警中心	处理报警规则、报警联动、当前报警和报警历史

3D 库房对接

3D 库房对接关注“设备状态如何落到空间里”。它不是单独的传感器协议，而是把库房、设备点位、摄像头、环境控制状态和巡检视图组合起来。

能力	说明
库房 3D 图	维护库房 3D 图文件或模型入口
点位映射	将设备、摄像头、门禁或报警点映射到库房空间
3D 巡检	通过三维视图展示现场状态、异常点和巡检入口
状态叠加	把温湿度、空气质量、报警、摄像头等状态叠加到 3D 视图

历史数据

能力	说明
当前状态	展示设备在线、温湿度、空气质量、漏水、继电器、空调、除湿等状态
历史曲线	通用设备历史查询和导出，用于趋势分析和现场复盘
环境评分	按温湿度或空气质量历史数据计算环境评分
数据导出	将设备历史数据导出为表格，用于现场验收、问题复盘和汇报

自动控制

能力	说明
手动控制	支持除湿机、新风、DO 输出、空调学习、空调控制、通用命令下发
自动策略	按温湿度范围、自动空调策略或安防定时设防做联动

报警中心

能力	说明
报警规则	按设备型号、表达式、事件和参数定义报警规则
报警联动	输入设备触发后，可联动声光报警、短信、电话、弹窗和大屏提示
报警历史	记录触发、解除、确认、原始消息和处理详情
当前报警	展示当前仍在触发中的报警状态，支持解除弹窗、静音和缓存同步

历史发展

环境控制的历史重点不是功能名称变化，而是底层消息中间件、时序数据存储和监控播放方案都换过几轮。现在看到的 POE、UDP、MQTT、历史曲线、报警中心和库房监控，背后主要由三条技术线支撑：MQTT broker 负责设备消息，时序数据库负责环境和设备历史数据，监控播放链路负责把现场摄像头稳定显示到网页和大屏。

MQTT Broker 演进

阶段	方案	典型仓库 / 线索	当前口径
早期 / 历史线	gmqtt	2024-new-screen/smart-doc-vault、hzg/smart-doc-vault 中存在 pkg/gmqtt 和 docker-compose.yml 的 gmqtt 服务	历史方案，不作为新部署优先口径
过渡期	后端仍用 Paho MQTT client，保留少量 GmqttAdminClient 注释或历史代码	fdmjj/smart-doc-vault 的 initialize/mqtt.go、iot/iot.go	业务代码关心 MQTT 协议，不应再依赖 gmqtt 管理接口
当前离线部署	EMQX	fdmjj/docker-install 使用 emqx/emqx:5.3.2，容器名 sdv-emqx	当前推荐 broker，现场服务和端口按 EMQX 维护

当前文档里的 UDP / MQTT 分工也要按这个口径理解：UDP 是 POE 设备初始化配置通道，MQTT broker 是设备运行期消息通道。设备端不应该关心后端曾经用过哪个 broker；只要 MQTT 地址、端口、topic 和 payload 约定稳定，broker 可以从 gmqtt 切到 EMQX。

时序数据库演进

阶段	方案	典型仓库 / 线索	当前口径
早期探索	QuestDB	后端存在 initialize/questdb.go，旧 docker-compose.yml 暴露 9000、9009、8812 等 QuestDB 相关端口	历史残留，不作为新环境控制历史数据主线
中间尝试	CeresDB	后端配置里曾有 ceresdb 的 host、http-port、grpc-port 字段，系统信息接口也留过 CeresDB 查询注释	历史残留，不作为当前部署依赖
当前主线	InfluxDB 2.x	fdmjj/smart-doc-vault 启动 initialize.InfluxDB()，iot/tsdb.go 的通用写入使用 InfluxDB client；fdmjj/docker-install 使用 influxdb:2.7，容器名 sdv-influxdb	当前环境控制历史曲线、通用设备历史和导出能力的主线

当前时序数据写入的核心已经收敛到 InfluxDB：设备 MQTT 消息进入后端后，通用 TSDB 写入会从 param 中提取可序列化字段，写入 InfluxDB bucket。温湿度、空气质量、设备状态、环境评分和历史曲线都应按 InfluxDB 口径维护。

监控播放方案演进

监控播放方案的变化，主要是被“浏览器不能直接播放 RTSP”和“库房大屏需要六路以上同屏播放”两个问题推动的。早期更关注单路能打开，后面才逐步转向低延迟、多路、可重连和低 CPU 占用。

阶段	方案	典型线索	当前口径
早期单路预览	RTSP / RTMP / HLS 地址直接暴露	后端和模型里一直保留 rstp、rtmp、hls、httpTs 等地址字段；推流盒子能同时生成多种播放地址	适合排查源流和兼容旧现场，但不是当前前端大屏主播放口径
文件 / 普通 FLV 尝试	flv.js / <video> 播 FLV 或本地视频	fit-archive-ng/src/views/bigdatascreen/index.vue 里有 flvjs.createPlayer、enableWorker、enableStashBuffer 等逻辑；依赖浏览器 MSE 和单个 video 元素	更像早期视频文件 / 单路 FLV 预览思路，六路以上同屏容易遇到性能和生命周期问题
推流盒子多协议输出	讯思维 xsw 把 RTSP 转成 HTTP-FLV、WS-FLV、RTMP、HLS、HTTP-TS	CameraModel.AfterFind 和大屏 WebSocket 会生成 httpFlv、wsFlv、rtmp、hls、httpTs、rstp	当前仍保留这些地址，便于不同终端调试；前端主线取 wsFlv
当前主线	ws-flv + Jessibuca + WASM / MSE / worker	fit-archive-ng/src/utils/jessiBucas.ts、monitorBigScreen.vue、IconCamera.vue 使用 cameraModel.wsFlv、Jessibuca.play()、useMSE、useSIMD、autoWasm、demuxUseWorker	当前库房监控大屏和多路预览主线，重点解决低延迟、六路以上同屏和异常重连

这条演进线里，wsFlv 不是“又多一个备用 URL”，而是当前前端监控播放的主入口。HLS 仍适合兼容性排查，但延迟通常不适合监控大屏；RTSP 仍是摄像头到推流盒子的源流，但浏览器不能直接播；普通 FLV / video 方案在单路预览时可用，多路同屏会更依赖实例管理和终端性能。

当前方案的关键是把压力拆开：推流盒子负责从摄像头拉 RTSP 并转出 WebSocket FLV，前端 Jessibuca 负责解封装和解码，demuxUseWorker 把解封装放到 worker，autoWasm 在浏览器解码能力不稳定时兜底，hasAudio: false 避免监控大屏为音频消耗额外 CPU。维护时如果看到旧分支里的 flv.js、xgplayer-flv 或 HLS 播放逻辑，要先判断它是在处理普通视频文件、旧大屏，还是当前监控通道。

维护判断原则

判断问题	当前建议
新部署 MQTT broker 怎么选	用 EMQX；文档、端口和容器名按 sdv-emqx 维护
看到 gmqtt 怎么处理	视为历史分支或旧部署线索；除非维护旧现场，不要在新文档里推荐
新部署时序库怎么选	用 InfluxDB 2.x；文档、备份和容器名按 sdv-influxdb 维护
看到 QuestDB / CeresDB 怎么处理	视为历史探索或残留配置；不要作为当前环境控制历史数据判断依据
新部署监控播放怎么选	前端按 wsFlv + Jessibuca 维护，确认 WebSocket FLV、WASM 解码资源、worker 和实例销毁逻辑
看到 HLS / RTMP / RTSP 怎么处理	视为推流盒子兼容地址或源流排查线索；当前网页多路监控不要默认按这些方案实现
看到 flv.js / xgplayer-flv 怎么处理	先判断是否普通视频文件或旧大屏逻辑；当前库房监控大屏主线看 Jessibuca
设备在线看哪里	在线链路仍看 MQTT 连接和最近上报；broker 实现变更不改变设备业务协议
历史曲线看哪里	当前按 InfluxDB 查询和导出能力维护，重点关注 bucket、token、org、数据目录和备份
监控卡顿看哪里	先看推流盒子通道和 wsFlv，再看前端 Jessibuca 实例数量、WASM / SIMD 支持、CPU 和销毁重连逻辑

产品边界

• 环境控制关注库房环境、现场安全、设备状态、设备控制和报警联动，不负责档案业务状态本身。
• 环境控制数据可以进入大屏、3D 库房、告警和运维页面，但档案借阅、上架、盘点等业务规则仍由主系统承载。
• 具体协议、网关型号、设备地址、MQTT payload、Modbus 点位、厂商 SDK 放到系统架构或设备接入文档。
• RFID 读写、标签识别、手持机、盘点车不属于环境控制，放到 RFID 页面维护。