3. 租户管理核心实体：Tenant、Customer、User、Device、Asset、Dashboard 的层级关系

在 ThingsBoard 多租户架构中，实体（Entity）是构建物联网平台业务逻辑的基本单元。理解 Tenant、Customer、User、Device、Asset 和 Dashboard 这六大核心实体之间的层级关系，是掌握租户管理与资源隔离的关键。

这些实体遵循严格的树形层级结构：Tenant（租户）位于顶层，向下依次关联 Customer（客户）、User（用户）、Device（设备）、Asset（资产） 和 Dashboard（仪表板）。每个实体都通过 所有者（Owner） 机制实现数据隔离与权限控制。

核心原则： 每个实体都有一个 ownerId 字段，指向其所属的 Tenant 或 Customer。所有数据查询和操作都基于所有者进行过滤，确保租户间数据完全隔离。

3.1 实体层级总览

下图展示了 ThingsBoard 中核心实体的层级关系与数据流向：

ThingsBoard 核心实体层级关系图 Tenant（租户） Customer（客户） User（用户） Device（设备） Asset（资产） Dashboard（仪表板） 说明： 1. Tenant 是顶层容器，Customer 隶属于 Tenant。 2. User 可属于 Tenant 或 Customer，通过 ownerId 区分。 3. Device、Asset、Dashboard 可属于 Tenant 或 Customer，实现灵活的资源隔离。

3.2 核心实体定义与职责

实体 英文名称 核心职责 所有者（Owner）
租户 Tenant 顶层隔离单元，管理自己的客户、设备、资产、用户和仪表板 自身（Tenant）
客户 Customer 租户下的业务组织，可拥有自己的设备和用户 Tenant
用户 User 平台操作者，可以是租户管理员或客户用户 Tenant 或 Customer
设备 Device 物理或虚拟物联网设备，负责数据采集与指令执行 Tenant 或 Customer
资产 Asset 业务资产或逻辑对象，如生产线、仓库、车辆 Tenant 或 Customer
仪表板 Dashboard 数据可视化界面，展示设备数据与业务指标 Tenant 或 Customer
实践要点： 在创建实体时，务必明确指定 ownerId。如果设备属于某个客户，则 ownerId 应设置为该 Customer 的 ID；如果设备属于租户公共资源，则 ownerId 设置为 Tenant 的 ID。

3.3 实体层级关系详解

3.3.1 Tenant → Customer → User

这是最基础的层级链：

  • Tenant 创建并管理 Customer。一个 Tenant 可以有多个 Customer。
  • Customer 下可以创建 User，这些用户只能访问该 Customer 拥有的资源。
  • Tenant 也可以直接创建 User（租户级用户），拥有租户管理权限。

3.3.2 Device 与 Asset 的归属

Device 和 Asset 是物联网平台的核心数据实体，它们的归属决定了数据可见性：

  • 租户级设备/资产： 属于 Tenant，对所有 Customer 可见（需配置权限）。
  • 客户级设备/资产： 属于特定 Customer，仅该 Customer 的用户可见。

3.3.3 Dashboard 的共享机制

Dashboard 支持灵活的共享策略：

  • 私有仪表板： 属于 Tenant 或 Customer，仅所有者可见。
  • 共享仪表板： 可以跨 Customer 共享，实现多租户统一视图。
常见误区： 不要将 Customer 视为“子租户”。Customer 没有独立的资源配额管理能力，所有资源配额（如设备数量、消息速率）均由 Tenant 统一控制。Customer 只是逻辑分组，不是隔离单元。

3.4 实体关系对比表

关系类型 源实体 目标实体 关系说明 示例
拥有 Tenant Customer 租户创建并管理客户 Tenant-A 创建 Customer-B
拥有 Tenant/Customer User 用户属于租户或客户 Customer-B 创建用户 user1
拥有 Tenant/Customer Device 设备属于租户或客户 Customer-B 拥有设备 sensor-01
拥有 Tenant/Customer Asset 资产属于租户或客户 Tenant-A 拥有资产 factory-line-1
拥有 Tenant/Customer Dashboard 仪表板属于租户或客户 Customer-B 创建仪表板 overview
分配 Customer Device 客户可将设备分配给具体用户 Customer-B 将 sensor-01 分配给 user1

3.5 实体层级在 API 中的体现

在 ThingsBoard REST API 中，实体层级通过 ownerId 参数体现。以下是一个创建设备并指定所有者的示例：

POST /api/device
Content-Type: application/json

{
  "name": "温度传感器-01",
  "type": "temperature-sensor",
  "ownerId": {
    "entityType": "CUSTOMER",
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  "additionalInfo": {
    "description": "车间A温度监测设备"
  }
}

查询设备时，系统自动根据当前用户所属的 Tenant 和 Customer 过滤数据：

GET /api/tenant/devices?pageSize=10&page=0
# 返回当前租户下的所有设备（包括客户级设备）

GET /api/customer/{customerId}/devices?pageSize=10&page=0
# 返回指定客户下的设备
关键理解： 实体层级不仅是逻辑结构，更是权限控制的基础。ThingsBoard 的 角色管理（Role） 和 权限（Permission） 系统正是基于这种层级关系，实现精细化的数据访问控制。

3.6 实体层级与资源隔离实践

在实际部署中，合理利用实体层级可以实现不同粒度的资源隔离：

  • 租户级隔离： 不同租户之间完全隔离，无法访问对方的数据。
  • 客户级隔离： 同一租户下的不同客户，只能看到自己的设备和数据。
  • 用户级隔离： 通过分配不同的角色和权限，控制用户对设备、资产、仪表板的操作范围。

下表总结了不同隔离级别的适用场景：

隔离级别 适用场景 实现方式 示例
租户级 多租户 SaaS 平台，不同企业客户 每个企业一个 Tenant 企业A、企业B各自独立租户
客户级 同一企业下的不同部门或项目 每个部门一个 Customer 研发部、生产部各自独立客户
用户级 同一部门内的不同角色 角色权限控制 管理员、操作员、只读用户
← 上一章 📖 返回目录 下一章 →