vault backup: 2026-01-05 14:26:17

2026-01-05 14:26:17 +08:00
parent be7c6cdcc9
commit 40f3fe3eb8
290 changed files with 1947 additions and 282 deletions
@@ -0,0 +1,13 @@
+
+
+生产环境：
+```
+https://218.20.201.147/portal/#/login?backurl=%2F&local=true
+```
+
+
+物联网：https://wlw.panyu.gd.cn 
+账号：aiot  pyqzhsw@PYQ123
+
+
+
@@ -0,0 +1,4 @@
+
+http://10.100.100.210/portal/   
+
+aiot  aiot123@Admin
@@ -0,0 +1,162 @@
+
+
+
+一、前置准备（必须先完成）
+- 必要资料（向设备方/平台方索取）
+  - 接入模式：设备直连 / 网关代理 / 平台采集（本平台去消费对方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与网络组件？
+- 我是否：为每台设备创建了子设备并与网关绑定，设备编码一致？
+- 我是否：启用设备与网关、用监控与日志确认已接收到消息？
+- 我是否：在平台或库中查到实时/历史数据，字段与时间正确？
+
@@ -0,0 +1,10 @@
+
+# install
+
+```bash
+mkdir -p mytb-data && sudo chown -R 799:799 mytb-data
+mkdir -p mytb-logs && sudo chown -R 799:799 mytb-logs
+docker run -it -p 8080:9090 -p 7070:7070 -p 1883:1883 -p 5683-5688:5683-5688/udp -v mytb-data:/data \
+-v mytb-logs:/var/log/thingsboard --name mytb --restart unless-stopped thingsboard/tb-postgres
+```
+
@@ -0,0 +1,119 @@
+
+
+一、培训整体框架
+- 培训目的：面向实施/运维人员，讲解在物联网AIoT平台完成设备/网关/平台三种接入模式的配置与落地，包含账号与权限、网络组件、产品与物模型、设备创建与绑定、Topic订阅、数据入库与告警规则等完整流程。
+- 方法论：
+  - 优先原则：鼓励“设备/平台主动推送到本平台”（稳定、低耦合）；“平台主动采集/消费对方MQTT/HTTP”作为兜底方案，尽量少用以减少平台负载与复杂度。
+  - N+1思路：网关场景下，先建“网关产品与网关设备”，再为下挂的N台子设备分别建“设备产品与设备设备”。
+
+二、接入模式与术语
+- 接入模式（南向）：
+  1) 设备直连：设备自身具备网络能力（常见MQTT、HTTP），直接上报至平台。
+  2) 平台直连：第三方平台承接设备数据后，推送至本平台（HTTP/MQTT）或本平台主动去消费其MQTT/HTTP。
+  3) 网关接入：低功耗、无网设备通过网关汇聚后，网关推送或第三方平台转发到本平台；网关承担多设备数据的代理。
+- 北向分发：本平台将数据提供给上级或其它业务系统（省厅、市级平台等），作为北向系统输出。
+- 设备编码（deviceId）：数据路由的唯一关键；平台中需全局唯一，与上报数据字段一致；入库及路由依赖此字段，不能缺失或混用。
+- 物模型：定义产品数据结构（标准字段+业务字段）；产品发布时自动在时序库创建超级表（字段按物模型生成）。
+- Topic（MQTT）：消息主题的层级规范；实施过程中常出现“实际Topic有中间层级/示例不完整”的情况，需客户端校验并使用“+”通配符。
+
+三、账号与权限（运营起步）
+- 管理策略：
+  - 按项目、单位或技术服务商创建独立账号，实现数据隔离与便于运营管理（如番禺救援项目单独账号，城中村、水务局分别账号）。
+  - 管理员具备全局视图；生产环境严格管理账号与设备归属，避免混用。
+- 使用场景：
+  - 技术服务商自助入驻：提供平台账号与使用指引，由对方自行创建设备、配置网关与订阅。
+  - 项目维度管理：平台管理员创建项目账号并分配权限，项目侧仅可查看与管理自身设备与数据。
+
+四、网络组件配置（培训明确步骤）
+- 目标：配置与第三方平台/设备的网络连接（MQTT/HTTP）以便采集或接收数据。
+- 必备技术资料：
+  - 服务地址与端口、认证方式（账号/密码/密钥/签名）、Topic规范、数据结构示例（含设备编码）、是否需要脚本/加密。
+- 操作要点：
+  - MQTT常用：mqt协议为物联网常见；也支持HTTP（对方平台较老或仅支持HTTP上报时使用）。
+  - 对于“平台主动消费对方MQTT”的场景，需要在网络组件中保存对方服务与认证信息，并在网关设备中配置订阅Topic。
+  - ClientId、连接URL可按文档要求设置；数据转换通常不需额外配置，除非对方格式特殊。
+
+五、产品与物模型（网关/设备双模型）
+- 产品类型：
+  - 网关产品：用于承载“平台主动采集/消费”或“网关直推”的数据入口。
+  - 设备产品（物联设备）：真实现场设备的产品定义，用于建立设备实例与业务字段承载。
+- 发布动作：
+  - 产品发布会“动态建库”，在时序库创建超级表（字段来自物模型）；发布成功后方可创建设备并正常入库。
+- 物模型设计细节：
+  - 网关物模型：通常比设备物模型复杂，需包含设备ID（如“sip”或设备编码字段）与外层结构，用于路由解析；同时包含type（类型/事件枚举）、告警信息、时间戳等。
+  - 设备物模型：可不重复配置设备ID（网关路由已确定归属），保留业务核心字段即可（如告警类型、子类、事件时间等）。
+  - 类型字段建议使用枚举；时间戳字段需勾选时序时间属性（long）。
+  - 字段命名与对方对齐，避免与平台保留关键字冲突。
+
+六、设备创建与绑定（网关模式详解）
+- 网关设备（基于网关产品）：
+  - 接入方式：选择“平台记录”（平台主动消费）或“网关直推”；在培训2实例中为“网关记录”（表示设备数据通过网关代理上报）。
+  - 协议备注：标注MQTT（便于识别）；数据方向对网关产品通常为“采集”。
+  - 订阅Topic：配置对方提供的Topic；如文档与现场不一致，使用“+”通配符适配中间层级；实施前用MQTT客户端验证。
+- 子设备（N台设备）：
+  - 创建设备实例（基于设备产品），选择接入方式为“网关记录”（表示数据经网关代理到此设备）。
+  - 填写设备编码（与上报字段一致、平台唯一）；选择所属网关；保持必要业务信息（行业、位置等）。
+  - 数据方向：子设备为“上报”（通过网关代理上报）。
+- 简化原则（培训2强调）：
+  - 设备侧无需重复配置设备ID（路由已确定）；避免冗余存储无用字段。
+  - 枚举值保持一致性；时间字段规范化。
+
+七、真实案例与操作脉络（安全帽案例）
+- 技术方案：安全帽设备→推到其自有MQTT服务→本平台作为消费者订阅其MQTT（平台主动采集）。
+- 实施步骤：
+  1) 获取技术文档与账号（MQTT地址、认证、Topic规范、数据示例）。
+  2) 管理员创建项目或服务商账号，分配权限。
+  3) 在平台网络组件中配置对方MQTT连接。
+  4) 建立网关产品，发布（建表）。
+  5) 建立网关设备，绑定网络组件，配置订阅Topic（必要时使用“+”通配符）。
+  6) 建立设备产品（与网关物模型一致或适当简化），发布。
+  7) 为每个安全帽创建设备实例（选择“网关记录”），填写设备编码，与网关关联。
+  8) 启用网关与设备，开始接收并入库。
+- 实施建议：
+  - 此“平台主动采集”方案为兜底，不建议作为默认；优先引导“设备/平台主动推送到本平台”。
+
+八、规则配置与工作量（培训1说明）
+- 告警规则并非统一套用到所有设备：
+  - 同一产品在不同部署场景要求不一，规则需按设备维度配置。
+  - 批量设备多时，需逐台配置（可考虑后续优化工具/模板导入）。
+- 实操建议：
+  - 先“学会怎么用”，工作量问题后续再评估；规则配置入口位于设备维度。
+
+九、常见问题与排障清单
+- 未收到数据：
+  - 检查网络组件连通与认证（地址、端口、账号/密钥/签名）。
+  - 检查订阅Topic是否正确；使用MQTT客户端现场验证真实Topic与数据样例。
+- 路由不正确：
+  - 网关物模型中设备ID解析是否正确；
+  - 子设备是否绑定对应网关；
+  - 通配符“+”是否覆盖中间层级。
+- 入库异常：
+  - 物模型字段名/类型是否与实际数据对齐；
+  - 时间字段是否设为时序时间；
+  - 设备编码与上报是否一致，平台唯一索引是否冲突。
+- 性能与稳定性：
+  - 尽量使用设备/平台主动推送；平台主动采集会增加任务负载；
+  - 大量设备接入需评估服务器资源（示例提到当前仅32G内存），必要时扩容。
+
+十、实施与管理建议
+- 接入前置清单：必须先拿到技术文档、真实数据样例、Topic清单与认证信息；先用客户端验证再在平台配置。
+- 账号治理：生产环境严控账号与设备归属；按项目或服务商进行隔离。
+- 模型与字段规范：保持与对方对齐命名与枚举；避免保留字；时间统一为long。
+- 批量导入：产品发布后，再批量导入设备，减少手工工作量。
+- 通配符使用：在订阅中用“+”处理中间层级差异，降低实施摩擦。
+
+十一、培训中的关键原话要点（摘录式复原）
+- “两种模式：别人平台推、我们去消费别人数据（安全帽案例为我们消费对方MQTT）。”
+- “网关模式是N+1：网关产品+设备产品；网关设备承载多台子设备。”
+- “设备编码是数据路由核心，平台唯一，数据包必须携带，不支持一个数据包混入多设备。”
+- “设备产品侧可不再配置设备ID（已由网关路由确定），避免冗余。”
+- “平台主动采集是备选兜底方案，为减少平台负载不建议默认采用。”
+- “同产品不同现场规则不一，规则需按设备维度配置。”
+
+十二、可输出的交付物（如需请告知）
+- 设备/网关接入操作手册（带步骤截图与示例字段表）
+- 接入资料清单模板（对方需提供的地址、认证、Topic、示例数据）
+- 网关订阅与通配符指南（含常见Topic偏差案例）
+- 物模型设计规范与示例（网关与设备双模型、枚举/时间字段设置）
+- 排障速查表（采集-解析-路由-入库）
+