ThingsBoard 快速上手：从克隆到第一块监控面板的实战指南

ThingsBoard 快速上手：从克隆到第一块监控面板的实战指南

【免费下载链接】thingsboardOpen-source IoT Platform - Device management, data collection, processing and visualization.项目地址: https://gitcode.com/GitHub_Trending/th/thingsboard

ThingsBoard 是一个开源的 IoT 平台，一次性解决设备接入、数据收集、规则处理和可视化这整条链路的问题。这篇文章的目标很直接：先让它跑起来，再按你实际要干的三件事——把数据接进来、让规则引擎处理、把面板搭出来——逐一说清楚。

跑起来：Docker 一条命令拉起完整集群

ThingsBoard 的 Docker Compose 部署默认就是一套微服务集群：两个核心节点（tb-core1/tb-core2）、两个规则引擎节点、两套 MQTT/HTTP 传输、两套 Web UI，外加 ZooKeeper 和 JS 脚本执行器，定义都在 docker/docker-compose.yml 里。你不需要逐个理解它们，装完能登录就行。

克隆仓库并执行安装脚本

git clone https://gitcode.com/GitHub_Trending/th/thingsboard cd thingsboard/docker ./docker-install-tb.sh --loadDemo

--loadDemo会额外加载演示数据（示例设备、面板、规则链），建议第一次就带上，后面看面板时有东西可看。⚠️ 如果脚本提示权限问题，先执行一次./docker-create-log-folders.sh，它会为各服务创建日志目录并改属主，需要 sudo。

数据库和缓存类型在 docker/.env 里选：DATABASE=postgres（默认）或hybrid（实体数据走 PostgreSQL、时序数据走 Cassandra），CACHE可选 valkey 单机/集群/sentinel 三种模式。改完再跑安装脚本即可。

看到登录页就算成功

浏览器打开http://localhost，出现 ThingsBoard 登录页说明集群就绪。默认账号：

• 系统管理员：sysadmin@thingsboard.org/sysadmin
• 租户管理员（带 demo 数据时）：tenant@thingsboard.org/tenant

用租户账号登录后，你能看到 demo 设备、现成的仪表盘和默认规则链，可以直接进入下一节动手。

核心能力拆解：接入、处理、可视化

用 MQTT 把传感器数据推上来

MQTT 是最常用的接入方式，连接地址localhost:1883，用户名填设备 Access Token（在 设备 → 选中某设备 → Credentials 标签页里拿到），Token 就是认证凭证，密码不用管。

最小 payload 就是一个 JSON 对象，发往主题v1/devices/me/telemetry：

import paho.mqtt.client as mqtt import json ACCESS_TOKEN = '从设备Credentials页复制的Token' client = mqtt.Client() client.username_pw_set(ACCESS_TOKEN) client.connect('localhost', 1883, 60) telemetry = {"temperature": 25.5, "humidity": 60, "pressure": 1013} client.publish('v1/devices/me/telemetry', json.dumps(telemetry))

发完之后不用做任何配置，设备详情页的 Telemetry 标签下立刻能看到这三条数据——传输层收到后直接入库，这是 ThingsBoard 的默认行为。仓库里 tools/src/main/python/mqtt-send-telemetry.py 有一个可运行的类似脚本可参考。💡 其他协议也各占一个端口：HTTP 是 8081（POSThttp://<host>:8081/api/<token>/telemetry），CoAP/LWM2M/SNMP 见文末端口表，认证方式类似。

给遥测数据挂一条告警规则链

设备数据进来后默认落库，但"温度过高就报警"这类逻辑要交给规则引擎。每个租户自带一条 Default 规则链，新设备的所有遥测、属性更新、连接事件都会先经过它。

典型做法是在规则链编辑器里往链路上加两个节点：

1. Filter / 脚本节点：判断temperature > 30；
2. Alarm 节点：满足条件时创建一条 Alarm，再往下接 Email/SMS 等通知节点。

规则节点之间的连线用"success/failure"两条出口表达分支，下图是规则节点编辑器的实际界面，每个节点右侧能看到输入字段的映射：

💡 写过滤逻辑时，遥测值取msg.temperature这种字段路径（来自消息体），实体属性用device.temperature前缀区分。调试时开着规则链编辑器底部的日志面板，每条消息走到哪个节点都看得到，比自己猜快得多。

三步搭出第一块监控面板

数据已经在库里了，把它画出来只需三步：

1. 新建 Dashboard：Dashboard 菜单 → 新建，命名如"设备监控"；
2. 加 Widget：拖入 Chart（曲线图）或 Latest Value（最新值卡片），数据源选刚才那台设备，key 填temperature、humidity；
3. 保存：曲线开始实时刷新，再配一个 Alarm Widget 把告警状态也摆上桌面。

仓库帮助文档里有一批 Widget 示例图，比如告警类 Widget 长这样：

如果不想从零搭，租户界面里的 Solution Templates 有智能能源、车队跟踪等现成模板，导入后把设备绑定换掉就能用。

生产要点与延伸

关键配置

常用端口

日志位置：各服务日志映射到宿主机，核心节点在docker/tb-node/log（容器内/var/log/thingsboard），MQTT 传输在docker/tb-transports/mqtt/log，格式由各自的logback.xml控制。快速排查用docker-compose logs -f tb-core1 tb-mqtt-transport1。

下一步方向

• 换hybrid数据库 + Kafka 队列（docker/docker-compose.kafka.yml），把时序写入和解耦处理撑到生产量级
• 上 Prometheus + Grafana 监控集群自身（docker/monitoring/）
• 评估 Edge 网关模式，把部分规则下放到远端节点

到这里，日常接入一台设备、配一条告警、看一块面板的路径就齐了；再深的集群调优和 Edge 部署，翻 docker/README.md 和官方文档即可。许可证：LICENSE（Apache 2.0）。

【免费下载链接】thingsboardOpen-source IoT Platform - Device management, data collection, processing and visualization.项目地址: https://gitcode.com/GitHub_Trending/th/thingsboard