ThingsBoard 如何判断设备的在线/离线状态
如下三个配置项协同工作，共同决定了 ThingsBoard 如何判断设备的在线/离线状态（即服务端属性active）。它们分别扮演“标准制定者”、“定期执行者”和“信息上报者”的角色。
1. 核心参数详解
| 配置项 (参数名) | 作用 (一句话概括) | 技术解释 | ThingsBoard 默认值 |
|---|---|---|---|
defaultInactivityTimeoutInSec | 制定“多久没消息算离线”的等待标准。 | 设备在没有任何活动（如上传数据、更新属性）后，被判定为“不活跃”（active变为false）的等待总时长。 | 600 秒(10 分钟) |
defaultStateCheckIntervalInSec | 规定“每隔多久检查一次”状态。 | Device State 服务执行周期性扫描，检查并更新所有设备在线状态的间隔时间。 | 60 秒(1 分钟) |
transport.sessions.report_timeout | 决定“多久上报一次设备活动”。 | Transport 服务将设备的活动信号（如心跳、数据）上报给 State 服务的周期时长。它也定义了 Transport 服务自身上报活动的“时间段”。 | 3000 毫秒(3 秒) |
2. 三者如何协同工作
用一个比喻可以帮你更好地理解这三者的关系：
- Transport 服务：像一个“记分员”，它负责时刻留意设备的一举一动。
- Device State 服务：像一个“裁判”，它负责最终判定设备是“活跃”还是“不活跃”。
report_timeout(3秒)：是“记分员”向“裁判”喊话汇报的频率。每隔3秒，记分员就会把看到的设备活动情况告诉裁判。defaultInactivityTimeoutInSec(10分钟)：是“裁判”的耐心。如果裁判在整整10分钟内没收到任何关于某个设备的活动报告，他就会判定该设备“不活跃”。defaultStateCheckIntervalInSec(1分钟)：是“裁判”低头看表、做出判决的频率。即便设备已经沉默了10分钟，裁判也要等到自己每1分钟一次的“检查时刻”，才会正式宣布该设备“不活跃”，并更新状态。
3. 关键约束与逻辑关系
三者之间存在一个强制的逻辑约束，以确保状态判断的准确性：
约束条件：transport.sessions.report_timeout必须小于defaultInactivityTimeoutInSec
这是 ThingsBoard 官方在配置文件中明确要求的。这个条件的核心目的是确保“裁判”在宣布结果前，一定能收到“记分员”的最新报告。
- 正确示例 ✅：记分员每3 秒汇报一次，裁判的耐心是600 秒。裁判每次都能在耐心耗尽前收到“续命信号”，判断准确。
- 错误示例 ❌：假设你错误地将
report_timeout设为600 秒，而defaultInactivityTimeoutInSec设为60 秒。那么，裁判在第 60 秒时就会因没收到报告而误判设备离线。直到 600 秒后，记分员才慢悠悠地送来报告，裁判又会将状态改回在线。这会导致active状态频繁错误震荡。
4. 配置调优建议
了解这些参数的关系后，你可以根据业务需求进行调整：
| 你的需求 | 推荐做法 | 注意点 |
|---|---|---|
| 快速检测设备离线 | 同时调低三个值，例如： • report_timeout:3000 毫秒(保持默认)• defaultInactivityTimeoutInSec:60 秒• defaultStateCheckIntervalInSec:30 秒 | 这会增加系统负载，需要评估服务器性能。 |
| 大规模部署，优先保证性能 | 适当放宽检测时间，例如： • defaultInactivityTimeoutInSec:1200 秒(20分钟)• defaultStateCheckIntervalInSec:120 秒(2分钟) | 可以显著降低数据库和服务器的压力。 |
| 为单个设备定制策略 | 无需修改全局配置。在设备的“服务端属性”中添加键值对：inactivityTimeout: 300000(单位是毫秒，此处示例为5分钟) | 该设备将使用 5 分钟的超时时间，而不是全局的 10 分钟。 |
5. 重要说明
active≠ 实时连接状态：active代表的是业务活跃度。即使设备物理断开，只要没超过inactivityTimeout，其状态依然可能显示为active。要获取实时连接事件，应使用规则链处理Connect和Disconnect事件。- 状态更新存在延迟：由于
defaultStateCheckIntervalInSec的存在，设备从达到“不活跃”条件到页面状态更新，最多会有1个检查周期的延迟（实际状态变更延迟 = 超时 + 最多一个检查周期）。