ThingsBoard 从零入门：15 分钟部署平台并接入第一台设备
【免费下载链接】thingsboardAll-in-one IoT Platform - Device management, data collection, processing and visualization.项目地址: https://gitcode.com/GitHub_Trending/th/thingsboard
ThingsBoard 是一个开源物联网平台，负责设备管理、数据采集、处理与可视化。这篇 ThingsBoard 部署入门指南带你跑通完整链路：本地起一个实例，让一台模拟设备上报遥测数据，再把它画成实时仪表盘。
环境自检清单
开工前逐条打勾，后面不会卡：
- 一台至少 8GB 内存的机器，Linux 或 macOS（Windows 走 WSL2）；
- JDK 25 已安装，
java -version能正常输出； - Maven 3.9 及以上，首次构建会拉取大量依赖，网络别掐断；
- 8080、1883 两个端口未被占用（分别是 Web/API 与 MQTT 入口）；
- Python 3 加上
pip install paho-mqtt，用于里程碑二的设备模拟脚本。
里程碑一：两条命令把 ThingsBoard 服务跑起来
先说清楚本仓库的部署形态：没有开箱即用的docker-compose.yml，msa/ 下每个微服务带Dockerfile（如 msa/tb-node/docker/），完整微服务栈需要外部编排；最快看到数据的方式是直接构建并运行单体应用，配置模板在 application/src/main/conf/。
先用 Maven 把全部模块编译出来（约 10–30 分钟，跳过测试）：
mvn clean install -DskipTests构建成功判定：最后一行输出BUILD SUCCESS。
初始化内置数据库和演示账号：
cd application java -jar thingsboard-4.4.0.1-SNAPSHOT.jar -Dloader.main=org.thingsboard.server.ThingsboardInstallApplication -Dplatform=local看到Installation process finished之类的完成提示即成功。
然后启动服务：
java -Dplatform=local -DNON_PRODUCTION_USE=true \ -jar thingsboard-4.4.0.1-SNAPSHOT.jar日志出现Started ThingsboardServerApplication后，浏览器打开http://localhost:8080，出现登录页即部署成功。用sysadmin@thingsboard.org/sysadmin登录，进入租户后切到tenant@thingsboard.org/tenant视角看业务数据。
里程碑二：MQTT 遥测上报最小示例
登录后进入设备 → 创建设备，协议选 MQTT，创建后复制访问令牌（Access Token）——它就是设备的登录密码。
仓库自带 tools/src/main/python/mqtt-send-telemetry.py 可以改成自己的联调脚本。最小可运行版本如下，用户名填令牌、密码留空，主题固定为v1/devices/me/telemetry：
import paho.mqtt.client as mqtt client = mqtt.Client() client.username_pw_set("你的访问令牌") client.connect("localhost", 1883, 60) client.publish("v1/devices/me/telemetry", '{"temperature": 25.5, "humidity": 60}')脚本静默退出、无报错就是发出去了。成功判定：刷新设备详情页，Latest Telemetry出现 temperature 和 humidity 两个键值，设备状态变为 Active。到此，采集链路已跑通。
里程碑三：给遥测数据配一块实时仪表盘
回到 Web 控制台，仪表盘 → 新建，命名后进入编辑器。
第一步添加实体别名：给一组设备起名字，Widget 里用别名引用，不写死设备 ID；别名可按实体列表或查询条件匹配。效果类似这样：
第二步从 Widget 库拖一个最新值小部件，绑定刚创建的别名和temperature、humidity两个键，保存。成功判定：刷新页面，卡片数值随每次上报自动更新，不再需要手动刷新。
顺路说一句：IoT Hub 里还有现成的方案模板，装一个等于拿到配好的设备定义、规则链和仪表盘：
机制回看：一条消息的旅程
数据并不直接落库，排障时心里要有这张链路图：
- MQTT 传输服务：监听 1883，校验访问令牌并接收设备消息；
- Kafka 消息队列：传输层与核心服务解耦，消息先入队再消费，服务间互不阻塞；
- tb-core 核心服务：负责鉴权、设备与属性管理，承载 8080 的 REST API；
- 规则链（规则引擎）：消息按节点连线流转，默认路径保存时序数据，也可加分流、告警节点；
- 时序存储 + Web 前端：仪表盘通过 REST 接口拉取时序数据，拼成你看到的曲线和卡片。
一句话：设备 → 传输层 → Kafka → 规则链 → 时序库 → 仪表盘。
避坑与自救
- 构建期
ui-ngx编译 OOM→ 前端模块吃内存 → 在命令前加MAVEN_OPTS="-Xmx2g"和NODE_OPTIONS=--max_old_space_size=4096重试。 - 启动报 License 异常→ 4.4 起采用 BUSL 许可，开发环境需显式声明 → 启动参数加
-DNON_PRODUCTION_USE=true（实例会带非生产水印，累计运行 30 天后自动停机）。 - MQTT 连接被拒绝→ 90% 是令牌或主题写错 → 确认用户名是访问令牌、密码留空、主题为
v1/devices/me/telemetry，且客户端连的是 1883。 - 仪表盘没数据→ 别名没绑到设备或 Widget 键名拼错 → 打开设备页确认 Latest Telemetry 有值，再核对 Widget 里填的键名与上报键名完全一致。
下一步路线
- 如果你想让"温度高于 30℃ 自动告警"，进规则链拖一个 Switch 加一个 Alarm 节点，打开 Debug 模式看单条消息的流向——详见 ui-ngx/src/assets/help/en_US/ 内置文档。
- 如果你想换 PostgreSQL 存数据、或用 msa/ 下的镜像做 Docker 微服务部署，从 application/src/main/conf/thingsboard.conf 的配置模板入手。
- 如果你想批量联调多台设备，把 tools/src/main/python/ 下的脚本改造成自己的设备模拟器。
【免费下载链接】thingsboardAll-in-one IoT Platform - Device management, data collection, processing and visualization.项目地址: https://gitcode.com/GitHub_Trending/th/thingsboard
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
