163 lines
7.9 KiB
Markdown
163 lines
7.9 KiB
Markdown
|
||
|
||
|
||
一、前置准备（必须先完成）
|
||
- 必要资料（向设备方/平台方索取）
|
||
- 接入模式：设备直连 / 网关代理 / 平台采集（本平台去消费对方MQTT/HTTP）
|
||
- 协议与地址：MQTT/HTTP服务地址与端口
|
||
- 认证信息：账号/密码或密钥/签名算法、ClientId要求（若有）
|
||
- Topic清单：含层级规范与变量段说明（设备编码所在层级）
|
||
- 数据样例：真实上报JSON（至少包含设备编码、事件类型、事件时间、示例字段）
|
||
- 物模型草案：关键字段清单、字段类型、枚举值、时间戳格式
|
||
- 平台账号与权限
|
||
- 建议按项目或服务商使用独立账号；确认账号具备网络组件、产品、设备的增改权限
|
||
|
||
二、总体流程总览
|
||
1) 配置网络组件（MQTT/HTTP）
|
||
2) 创建产品与物模型
|
||
- 网关产品（如用网关或平台采集方案）
|
||
- 设备产品（真实设备）
|
||
- 发布产品（自动建表）
|
||
3) 创建设备实例
|
||
- 网关设备（如有）
|
||
- 子设备（N台）
|
||
4) 绑定网络与Topic
|
||
5) 启用与验证（数据入库校验）
|
||
说明：
|
||
- 直连设备：可不建网关产品/设备，设备产品直连绑定网络并上报
|
||
- 网关/平台采集：需先建网关产品/网关设备，再建子设备并绑定到网关
|
||
|
||
三、步骤详解（以“网关代理/平台采集”通用流程为例）
|
||
步骤1：配置网络组件
|
||
- 入口：平台-网络管理-新增网络组件
|
||
- 填写项
|
||
- 类型：MQTT（常用）或HTTP
|
||
- 地址/端口：对方提供
|
||
- 认证：账号/密码或密钥/签名（按文档要求）
|
||
- ClientId/连接参数：若对方有格式要求需按要求填写
|
||
- 备注：建议标注项目/厂商名称，便于后续识别
|
||
- 校验要点
|
||
- 先用MQTT客户端连通测试（能订阅到任意公开主题最佳）
|
||
- 认证失败优先检查账号状态、白名单、TLS/证书要求
|
||
|
||
步骤2：创建网关产品（如使用网关或平台采集）
|
||
- 入口：平台-产品管理-新增产品（类型：网关）
|
||
- 物模型设计建议
|
||
- 必含设备标识字段：如 deviceId 或 sip（用于路由到子设备）
|
||
- 事件类字段：type（枚举）、subType/desc（可选）、eventTime（long时间戳）
|
||
- 其它业务字段：按对方数据样例补充
|
||
- 发布产品
|
||
- 发布后平台自动在时序库创建超级表；未发布将导致后续入库失败
|
||
- 检查
|
||
- 确认字段名与对方数据一致，时间字段勾选为时间列
|
||
|
||
步骤3：创建设备产品（真实设备）
|
||
- 入口：平台-产品管理-新增产品（类型：设备）
|
||
- 物模型设计建议
|
||
- 不重复设备标识字段（已由网关路由确定）
|
||
- 保留设备侧关注的业务字段，如 type、alertSubType、eventTime 等
|
||
- 将 eventTime 设为时间列；枚举值与对方对齐
|
||
- 发布产品
|
||
- 发布后生成对应设备超级表
|
||
|
||
步骤4：创建设备实例-网关设备
|
||
- 入口：平台-设备管理-新增设备（选择网关产品）
|
||
- 关键配置
|
||
- 接入方式：网关记录 或 平台记录
|
||
- 网关记录：数据由“网关代理”上报至平台
|
||
- 平台记录：平台主动去对方平台消费（安全帽MQTT消费属此类）
|
||
- 协议：MQTT（并备注厂商/平台名称）
|
||
- 绑定网络组件：选择步骤1创建的网络组件
|
||
- 订阅Topic：填写对方提供的Topic；中间层级不确定用“+”通配
|
||
- 示例：/vendor/helmet/+/alarm
|
||
- 启用：保存后先不启用，待子设备创建完一起启用
|
||
- 校验要点
|
||
- 用MQTT客户端实测该Topic能收到与样例一致的数据
|
||
- Topic变量段确定设备编码位置，便于后续路由
|
||
|
||
步骤5：创建设备实例-子设备（N台）
|
||
- 入口：平台-设备管理-新增设备（选择步骤3的设备产品）
|
||
- 关键配置
|
||
- 设备编码：与上报数据中的设备标识一致，平台全局唯一
|
||
- 接入方式：网关记录（通过网关代理）
|
||
- 所属网关：选择步骤4的网关设备
|
||
- 其它信息：名称、位置、单位、行业分类等
|
||
- 批量建议
|
||
- 若数量大，先准备模板CSV后批量导入（如平台支持批量）
|
||
- 注意
|
||
- 子设备不绑定网络组件与Topic，由网关设备统一订阅与路由
|
||
|
||
步骤6：启用与联调
|
||
- 入口：设备列表/网关设备详情
|
||
- 操作
|
||
- 启用网关设备
|
||
- 启用子设备
|
||
- 观察监控页/日志：确认网关连接成功、订阅成功、消息接收正常
|
||
- 入库校验
|
||
- 在平台查询实时/历史数据或直连时序库查询对应表
|
||
- 核对字段映射是否正确、eventTime是否生效排序
|
||
|
||
四、直连设备（无网关）的差异化步骤
|
||
- 产品：仅需设备产品（可将设备编码作为辅助字段或不存储，视平台实现）
|
||
- 设备实例：接入方式选“直连”，直接绑定网络组件
|
||
- Topic：在设备实例上配置其专属Topic（若每台设备一个Topic），或采用平台方提供的统一Topic+设备编码路由
|
||
- 其余校验同上
|
||
|
||
五、平台推送（第三方向本平台推送HTTP/MQTT）
|
||
- 网络组件：配置为“平台接收”端点（若平台提供专属接入地址与认证）
|
||
- 安全策略：为对方创建独立账号与密钥，限制可见与写入范围
|
||
- 物模型与设备：与网关模式的设备侧一致
|
||
- 验证：让对方用真实报文调用接入地址，平台查收并入库
|
||
|
||
六、字段与物模型设计清单（避免入库失败）
|
||
- 必备
|
||
- 路由字段：deviceId/sip（在网关模型中必需）
|
||
- 时间字段：eventTime（long，设为时间列）
|
||
- 类型字段：type（枚举或字符串，保持与对方一致）
|
||
- 不建议
|
||
- 在设备模型中重复定义设备ID（已由路由确定）
|
||
- 使用平台保留关键字作为字段名
|
||
- 变更
|
||
- 发布后字段调整需评估对历史数据表结构影响，慎重变更；必要时新建版本产品
|
||
|
||
七、Topic与通配符配置指引
|
||
- 常见差异：文档与现场Topic中间多一层（如项目号/渠道号）
|
||
- 处理方法
|
||
- 优先使用“+”单层通配匹配中间层
|
||
- 样例：/v1/device/+/alarm 或 /org/+/helmet/+/event
|
||
- 验证
|
||
- 使用MQTT客户端先订阅通配符Topic，确认能收到期望设备的数据
|
||
|
||
八、启用后的自检与排障
|
||
- 收不到数据
|
||
- 网络组件未连通或认证失败：检查账号/密码/证书/白名单
|
||
- Topic错误：客户端验证；核对通配层级数量
|
||
- 未启用：确认网关与子设备均为启用状态
|
||
- 入库异常
|
||
- 物模型字段名不一致/类型不匹配：对照样例修正
|
||
- 未发布产品/表未生成：检查发布动作是否成功
|
||
- 时间列未设置：导致排序/查询异常
|
||
- 路由失败
|
||
- 网关模型中未正确解析设备编码
|
||
- 子设备未创建或设备编码不一致（唯一索引冲突或找不到匹配）
|
||
- 性能问题
|
||
- 平台主动采集负载高：优先引导改为对方推送
|
||
- 大批量设备：提前估算队列/缓存资源，必要时分批启用
|
||
|
||
九、最佳实践与建议
|
||
- 先证后配：先用客户端验证MQTT/HTTP链路与Topic，再在平台录入配置
|
||
- N+1建模：网关产品+网关设备（1）+子设备（N），清晰解耦
|
||
- 简化字段：设备模型只保留必要业务字段；网关模型承载路由与原始结构
|
||
- 命名一致：字段名与对方对齐；枚举提前对表
|
||
- 批量导入：产品发布后，再批量导入设备，减少重复劳动
|
||
- 审计与隔离：项目/厂商独立账号与密钥；便于问题定位与权限控制
|
||
|
||
十、快速清单（实施现场可打印）
|
||
- 我是否拿到：地址/端口、认证、Topic、真实样例、设备编码列表？
|
||
- 我是否：创建了网络组件、创建并发布了网关/设备产品？
|
||
- 我是否：创建了网关设备并配置了Topic与网络组件？
|
||
- 我是否：为每台设备创建了子设备并与网关绑定，设备编码一致？
|
||
- 我是否：启用设备与网关、用监控与日志确认已接收到消息？
|
||
- 我是否：在平台或库中查到实时/历史数据，字段与时间正确？
|
||
|