2. ThingsBoard 核心实体：概念与层级
ThingsBoard 平台采用多租户架构，其数据模型围绕五个核心实体构建：租户 (Tenant)、客户 (Customer)、用户 (User)、资产 (Asset) 和 设备 (Device)。理解这些实体的定义及其层级关系，是进行实体关系建模与数据链路设计的基础。
2.1 核心实体定义
下表从业务视角和技术视角对五个核心实体进行定义：
| 实体 | 业务含义 | 技术角色 | 关键属性 |
|---|---|---|---|
| 租户 (Tenant) | 独立的组织或企业，拥有完整的 IoT 业务域 | 顶级隔离单元，管理所有下级实体 | 租户 ID、名称、地区、配置 |
| 客户 (Customer) | 租户的下级业务单元，如部门、项目或终端客户 | 资产与设备的逻辑归属方 | 客户 ID、租户 ID、邮箱、地址 |
| 用户 (User) | 平台的操作者，可以是租户管理员或客户成员 | 认证与授权主体，拥有角色和权限 | 用户 ID、邮箱、角色、所属实体 |
| 资产 (Asset) | 物理世界中的有价值对象，如建筑、车辆、生产线 | 数据聚合与业务逻辑的载体 | 资产 ID、类型、标签、属性 |
| 设备 (Device) | 连接网络的物理传感器或执行器 | 数据采集与指令下发的最小单元 | 设备 ID、凭证、遥测、属性 |
关键区分：资产 (Asset) 是静态业务对象，通常不直接产生数据流；设备 (Device) 是动态数据源，负责上报遥测和接收指令。资产可以包含多个设备，但设备只能属于一个资产。
2.2 实体层级结构
ThingsBoard 的实体层级遵循严格的树形结构，从顶层租户向下逐级展开。层级关系决定了数据可见性、权限范围和实体管理方式。
层级规则：
- 一个 租户 拥有多个 客户、多个 用户、多个 资产 和多个 设备。
- 一个 客户 属于一个 租户，并拥有该租户下的部分 资产 和 设备。
- 一个 用户 属于一个 租户 或一个 客户，不能同时属于两者。
- 资产 和 设备 可以属于 租户 或 客户，通过关系链实现归属。
2.3 实体关系矩阵
实体之间的关联关系通过 ThingsBoard 的关系引擎 (Relation Engine) 管理。以下是核心实体间的标准关系矩阵：
| 源实体 | 目标实体 | 关系类型 | 关系方向 | 典型场景 |
|---|---|---|---|---|
| 租户 | 客户 | Contains | 1:N | 租户管理多个客户项目 |
| 租户 | 用户 | Contains | 1:N | 租户管理员、运维人员 |
| 客户 | 用户 | Contains | 1:N | 客户方操作员、查看者 |
| 客户 | 资产 | Owns | 1:N | 客户拥有的建筑、车辆 |
| 客户 | 设备 | Owns | 1:N | 客户购买的传感器 |
| 资产 | 设备 | Contains | 1:N | 建筑内的温湿度传感器 |
| 资产 | 资产 | Contains | 1:N | 工厂包含车间，车间包含产线 |
| 设备 | 设备 | Connects | 1:1 | 网关设备连接子设备 |
设计注意：资产与设备的关系是非强制的。设备可以独立存在而不属于任何资产，资产也可以没有关联设备。但在实际 IoT 项目中，建议为每个设备指定所属资产，以形成完整的数据链路。
2.4 实体标识与数据隔离
每个实体在 ThingsBoard 中都有一个全局唯一的 UUID 作为主键。数据隔离通过实体所属的租户 ID 实现：
- 租户级隔离：不同租户的数据完全隔离，无法互相访问。
- 客户级隔离：客户只能看到自己拥有的资产和设备，以及被授权的用户。
- 用户级权限：用户通过角色 (Role) 和权限 (Permission) 控制对资产和设备的操作范围。
2.5 实体创建与生命周期
在 ThingsBoard 中，实体的创建遵循自上而下的顺序：
- 创建租户：由系统管理员在租户管理页面创建，或通过 REST API 调用。
- 创建客户：租户管理员在客户管理页面创建，指定所属租户。
- 创建用户：租户管理员或客户管理员创建，分配角色和权限。
- 创建设备：租户或客户管理员创建设备，生成访问凭证（Access Token、X.509 证书等）。
- 创建资产：租户或客户管理员创建资产，并建立与设备的关联关系。
最佳实践：
- 先定义资产结构（如工厂 → 车间 → 产线），再创建设备并关联到对应资产。
- 使用资产类型 (Asset Type) 和设备类型 (Device Type) 对实体进行分类，便于后续规则链和仪表板设计。
- 为每个设备分配唯一的凭证，避免跨租户或跨客户的凭证泄露。
2.6 实体关系在数据链路中的作用
实体关系是构建数据链路的核心。在 ThingsBoard 中，数据从设备产生，经过规则链处理，最终关联到资产和客户：
- 设备 → 遥测数据：设备上报的遥测数据直接存储在设备名下。
- 设备 → 资产：通过关系，设备数据可以聚合到资产层面，实现按资产维度的数据查看。
- 资产 → 客户：客户通过拥有的资产，间接查看其下所有设备的数据。
- 客户 → 租户：租户可以查看所有客户的数据，但客户只能查看自己的数据。
这种层级关系使得 ThingsBoard 能够实现多租户数据隔离和灵活的数据聚合，是构建企业级 IoT 平台的基础。