thingsboard2.5 CE版本数据库设计说明

 

Thingsboard 2.5 CE

数据库设计说明（DBDD）

 

 

 

文档修订历史记录

 

版本	日期	AMD	修订者	说明
1.0	2018-07-08	A	琉璃	初稿

（A-添加，M-修改，D-删除）

 

数据库设计说明

本文描述的是Thingsboard2.5 CE版本的数据库设计说明。

数据库概述：

本系统使用postgreSQL+Cassandra数据库。

本系统是以局域网为基础开发的，网络带宽可以满足数据库系统的实时操作要求。

文档概述：

本文档的目的是明确“Thingsboard”中各项功能和非功能性需求实现时所需要的数据类型，数据关系，数据流程，并用于指导设计人员对数据库的设计。

 

 

1. 数据表和程序模块的分类

根据“处理特点”，将数据表和程序模块进行分类如下： 

数据表分类：实体表、实体关系表、数据存储表、实时数据表、日志表、设置表、验证凭据表、规则链表。 

程序模块分类：初始化、业务处理、完整性检测与修正、结算处理、统计处理。

1. 1. 1. 数据表分类说明 

实体表：存放各个类型的实体。如，设备、设施、实体视图、用户、租户、管理人员、部件等。

实体关系表：记录实体之间的关系。如，设备和设施之间的关联关系或者租户与设施之间的关系等。

数据存储表：存放各个实体数据的具体数据。如，设备、设施、实体视图、用户、租户、规则链、部件等。

实时数据表：存放设备或者设施等的实时数据。如，设备的遥测数据或属性、设施的属性等。

日志表：描述操作日志或者审计日志等等。如，设备设施的增删改查、权限的修改等。 

设置表：存放一些系统。如，邮件服务器、国家语言等。

验证凭据表：实时存放当前设备或者用户的验证凭据。

规则链表：描述规则节点及规则链的流数据等。如，规则链数据保存、规则节点的描述等。

1. 1. 1. 程序模块分类说明

核心框架  如：数据采集、处理、仪表板展示

扩展业务模块 如：api发布、设备接入、告警发布等

1. 1. 1. 数据表间的关系

实体表<-->实体关系表：主-外键关系。如，实体表<-->实体关系表; 

数据存储表<-->实体关系表：主-外键关系。如，设施表<-->关系表; 

数据存储表<-->验证凭据表： 主-外键关系。如，用户表<-->用户凭据表; 

数据存储表<-->日志表： 主-外键关系。如，用户表<-->按用户ID审核日志表; 

数据存储表<-->规则链表： 主-外键关系。如，规则节点表<-->规则链表; 

1. 1. 数据库结构原则

规定除数据库设计所遵循的范式外的一些适用原则，在遵循数据库设计范式的基础上，合理地划分表，添加状态和控制字段等。 

1. 1. 1. 数据存储表的设计规则 

为了使数据存储表能起到预期的效能，又不因过多的数据存储表难以管理，故对数据存储表的使用作如下规定： 

当某数据存储表的主键允许被其他表当做外键，并且该表中存在大量的元数据时，应设计成有主键ID的数据存储表。 

数据存储表与其他相关联表的列采用主-外约束保证列数据完整性。 

1. 1. 1. 实体关系表的设计规则 

实体关系表表可以有如下的标识列：从ID、从类型、到ID、到类型、关系类型。

从ID与到ID组成联合主键，并且匹配从类型和到类型，生成唯一的一条实体关系对应数据。

关系类型定义两个实体之间的关系的关联类型，从而让仪表板调用变得方便，符合数据库表的易用性。

这里规定，当数据存储表中的两个实体存在一定的关联关系时，设计者可以按照此处规定，建立新的实体关系表，表中应有以上说明的标识列，也可增加相应字段，用以说明关系类型明细。

1. 1. 1. 实时数据表 

实时数据表用以存储各个可能实时变化数据，如：设备状态、传感器设备的遥测数据、地图坐标、外部实时获取的数据、各个实体的属性等。

当设计者新增实体（数据存储表）时，若存在可能实时变化的数据时，可将其设计为实时数据表。

实时数据表固有字段：实体ID、时间戳、键名、值。

新增实时数据表时，必须遵循以上字段设计，也可新增其他字段，用以说明该实时数据的详细信息。

1. 1. 1. 日志表

日志表旨在记录系统的操作日志，如：实体的增删改查、实体信息的更新、规则链的修改、RPC请求的连接断开日志等等。

设计者若需要新建日志表，则需要关联相关数据存储表，用实体的主键ID当做该表的外键，用以表示该实体在某时某刻发生了什么事件。

1. 1. 1. 数据库结构设计约定

实体表创建一个程序编码主键，关系表根据情况决定是否创建一个程序编码主键。

所有键值必须使用UUID当做值。

数据量大的表（上万条）所有外键加入索引。

数据量大的表注意聚簇索引。

对于整数类型的字段，没有特殊要求时，统一使用bigint类型，非空。

大型数据如：日志内容、json数据、事件等等，统一使用blod类型，允许空。

普通数据值使用text类型，允许空。

条件数据使用Boolean类型，非空。

浮点值使用double类型，允许空。

时间戳使用bigint类型，不为空。

特殊要求时按特殊要求进行定义。

统一编码

所有表的ID字段，在全局范围内统一进行维护，插入记录时先提出申请，并自动生成一条UUID数据，且将操作记录写入日志表中。

历史表中作充分冗余，不做关联。

1. 1. 数据库命名原则 

通用原则一：数据库对象名与java类命名方法一致。

通用原则二：【对象类型前缀】_对象名，数据库表除外（不带前缀和-）。

1. 1. 1. 表名 

对于基础框架部分：实体名_[表内容]

对于业务系统： [业务模块缩写]_[表内容]

1. 1. 1. 物化视图 

物化视图的分类方法可参考数据表的分类，命名方法参考如下原则：

实体_by_实体_[业务模块缩写] 

1. 1. 1. 数据表字段

字段名取含义明确的英文单词，除非有特殊的要求，否则不要使用汉语拼音，字段名尽可能把字段的含义描述得清楚些，当然，也别做过头了，比如Customer_Shipping_Address_Street_Line_1虽然很富有说明性，但没人愿意键入这么长的名字，具体尺度，请根据实际情况把握。

书写字段名时，每个单词及简写都应小写。如：实体类型entity_type，关系类型组relation_type_group等。

1. 数据库详细设计

概念模型设计采用E-R图形式，针对物联网平台中所涉及的各类对象属性进行描述，包括租户、用户、设备、实体视图、设施、部件、部件库、规则节点、规则链、仪表板、关系、消息、告警、遥测数据、日志等。以下是thingsboard2.5 CE版本数据库的PDM图：

1. 用于数据库访问或操纵的软件单元的详细设计
   1. 数据库表清单

表 1数据库表清单

Table Name	Comment
tenant	租户表
customer	用户表
device	设备表
asset	设施表
entity_view	实体视图表
widgets_bundle	部件表
widget_type	部件库表
rule_node	规则节点表
rule_chain	规则链表
dashboard	仪表板表
relation	关系表
alarm	告警表
ts_kv_cf	遥测数据表
audit_log_by_tenant_id	按租户ID审核日志表
audit_log_by_customer_id	按用户ID审核日志表
audit_log_by_entity_id	按实体ID审核日志表
admin_settings	管理员设置表
device_credentials	设备凭据表
user_credentials	用户凭据表
event	事件表
entity_view	实体视图表

1. 1. 数据库表结构详情

表 2 租户表

Columns in Table tenant
Col ID	Column Name	Data Type	Not Null	Data Def.	Comments
1	Id	Text	N	UUID	租户ID
2	region	Text	N		权限
3	additional_info	Text	Y		附加信息
4	address	Text	Y		地址
5	address2	Text	Y		地址2
6	city	Text	Y		市
7	country	Text	Y		国家
8	email	Text	N		邮箱
9	phone	Text	Y		电话
10	search_text	Text	N		搜索文本
11	state	Text	Y		省
12	title	Text	Y		标签
13	zip	Text	Y		邮编

表 3用户表

Columns in Table customer
Col ID	Column Name	Data Type	Not Null	Data Def.	Comments
1	Id	Text	N	UUID	用户ID
2	tenant_id	Text	N		租户ID
3	additional_info	Text	Y		附加信息
4	address	Text	Y		地址
5	address2	Text	Y		地址2
6	city	Text	Y		市
7	country	Text	Y		国家
8	email	Text	N		邮箱
9	phone	Text	Y		电话
10	search_text	Text	N		搜索文本
11	state	Text	Y		省
12	title	Text	Y		标签
13	zip	Text	Y		邮编

表 4设备表

Columns in Table device
Col ID	Column Name	Data Type	Not Null	Data Def.	Comments
1	Id	Text	N	UUID	设备ID
2	tenant_id	Text	N	UUID	租户ID
3	customer_id	Text	N	UUID	用户ID
4	type	Text	N		设备类型
5	additional_info	Text	Y		附加信息
6	name	Text	N		设备名称
7	search_text	Text	N		搜索文本

表 5设施表

Columns in Table asset
Col ID	Column Name	Data Type	Not Null		Data Def.		Comments
1	Id	Text		N		UUID	设施ID
2	tenant_id	Text		N		UUID	租户ID
3	customer_id	Text		N		UUID	用户ID
4	type	Text		N			设施类型
5	additional_info	Text		Y			附加信息
6	name	Text		N			设施名称
7	search_text	Text		N			搜索文本

表 6部件表

Columns in Table widgets_bundle
Col ID	Column Name	Data Type	Not Null	Data Def.	Comments
1	Id	Text	N		部件ID
2	tenant_id	Text	N		租户ID
3	alias	Text	N		别名
4	image	blob	Y		图片
5	search_text	Text	N		搜索文本
6	title	Text	Y		标签

表 7部件库表

Columns in Table widget_type
Col ID	Column Name	Data Type	Not Null	Data Def.	Comments
1	Id	Text	N		部件库ID
2	tenant_id	Text	N		租户ID
3	bundle_alias	Text	N		部件别名
4	alias	Text	N		别名
5	descriptor	Text	Y		描述
6	name	Text	N		部件库名称

表 8规则节点表

Columns in Table rule_node
Col ID	Column Name	Data Type	Not Null	Data Def.	Comments
1	Id	Text	N		节点ID
2	additional_info	Text	Y		ID
3	configuration	Text	Y		配置内容
4	debug_mode	boolean	Y		调试模块
5	name	Text	N		节点名称
6	rule_chain_id	Text	N	UUID	规则链ID
7	search_text	Text	N		搜索文本
8	type	Text	N		节点类型

表 9规则链表

Columns in Table rule_chain
Col ID	Column Name	Data Type	Not Null	Data Def.	Comments
1	id	Text	N	UUID	ID
2	tenant_id	Text	N	UUID	租户ID
3	additional_info	DATE	N		附加信息
4	configuration	Text	N		配置内容
5	debug_mode	boolean	Y		调试模块
6	first_rule_node_id	Text	N	UUID	第一个规则节点ID
7	name	Text	N		规则链名称
8	root	boolean	N		是否为根规则链
9	search_text	Text	N		搜索文本

表 10仪表板表

Columns in Table dashboard
Col ID	Column Name	Data Type	Not Null	Data Def.	Comments
1	id	Text	N	UUID	ID
2	tenant_id	Text	N	UUID	租户ID
3	assigned_customers	Text	Y		指定用户
4	configuration	Text	N		配置内容
5	search_text	Text	N		搜索文本
6	title	Text	Y		标签

表 11关系表

Columns in Table relation
Col ID	Column Name	Data Type	Not Null	Data Def.	Comments
1	from_id	Text	N	UUID	从ID
2	from_type	Text	N		从类型
3	relation_type_group	Text	N		关联类型组
4	relation_type	Text	N		关联类型
5	to_id	Text	N	UUID	到ID
6	to_type	Text	N		到类型
7	additional_info	Text	Y		附加信息

表 12告警表

Columns in Table alarm
Col ID	Column Name	Data Type	Not Null	Data Def.	Comments
1	tenant_id	Text	N	UUID	租户ID
2	originator_id	Text	N	UUID	发起者ID
3	originator_type	Text	N		发起者类型
4	type	Text	N		告警类型
5	id	Text	N	UUID	ID
6	ack_ts	bigint	N		确认时间
7	clear_ts	bigint	N		清除时间
8	details	Text	Y		详情
9	end_ts	bigint	N		结束时间
10	propagate	boolean	N		传播
11	severity	Text	Y		严重程度
12	start_ts	bigint	N		开始时间
13	status	Text	N		状态

表 13遥测数据表

Columns in Table ts_kv_cf
Col ID	Column Name	Data Type	Not Null	Data Def.	Comments
1	entity_type	Text	N		实体类型
2	entity_id	Text	N	UUID	实体ID
3	key	Text	N		键
4	partition	Text	N		权限
5	ts	bigint	N		时间戳
6	bool_v	boolean	Y		布尔型数据
7	dbl_v	double	Y		浮点型数据
8	long_v	bigint	Y		长整型数据
9	str_v	Text	Y		字符型数据

表 14按租户ID审核日志表

Columns in Table audit_log_by_tenant_id
Col ID	Column Name	Data Type	Not Null	Data Def.	Comments
1	tenant_id	Text	N	UUID	租户ID
2	partition	Text	N		权限
3	id	Text	N	UUID	ID
4	action_data	Text	Y		日志数据
5	action_failure_details	Text	Y		操作失败详细信息
6	action_status	Text	N		结果状态
7	action_type	Text	N		日志类型
8	customer_id	Text	N	UUID	用户ID
9	entity_name	Text	N		实体名
10	user_id	Text	N	UUID	管理ID
11	user_name	Text	N		管理名称
12	entity_type	Text	N		实体类型
13	entity_id	Text	N	UUID	实体ID

表 15按用户ID审核日志表

Columns in Table audit_log_by_customer_id
Col ID	Column Name	Data Type	Not Null	Data Def.	Comments
1	tenant_id	Text	N	UUID	租户ID
2	customer_id	Text	N	UUID	用户ID
3	id	Text	N	UUID	ID
4	action_data	Text	Y		日志数据
5	action_failure_details	Text	Y		操作失败详细信息
6	action_status	Text	N		结果状态
7	action_type	Text	N		日志类型
8	customer_id	Text	N	UUID	用户ID
9	entity_name	Text	N		实体名
10	user_id	Text	N	UUID	管理ID
11	user_name	Text	N		管理名称

表 16按实体ID审核日志表

Columns in Table audit_log_by_entity_id
Col ID	Column Name	Data Type	Not Null	Data Def.	Comments
1	tenant_id	Text	N	UUID	租户ID
2	entity_id	Text	N	UUID	实体ID
3	entity_type	Text	N		实体类型
4	id	Text	N	UUID	ID
5	action_data	Text	Y		日志数据
6	action_failure_details	Text	Y		操作失败详细信息
7	action_status	Text	N		结果状态
8	action_type	Text	N		日志类型
9	customer_id	Text	N	UUID	用户ID
10	entity_name	Text	N		实体名
11	user_id	Text	N	UUID	管理ID
12	user_name	Text	N		管理名称

表 17管理员设置表

Columns in Table admin_settings
Col ID	Column Name	Data Type	Not Null	Data Def.	Comments
1	Id	Text	N	UUID	设置ID
2	json_value	Text	N		配置内容
3	key	Text	N		配置键

表 18设备凭据表

Columns in Table device_credentials
Col ID	Column Name	Data Type	Not Null	Data Def.	Comments
1	Id	Text	N	UUID	ID
2	credentials_id	Text	N	UUID	凭证ID
3	credentials_type	Text	N		凭证类型
4	credentials_value	Text	N		凭证值
5	device_id	Text	N	UUID	设备ID

表 19用户凭据表

Columns in Table user_credentials
Col ID	Column Name	Data Type	Not Null	Data Def.	Comments
1	Id	Text	N	UUID	凭证ID
2	activate_token	Text	N		凭证token
3	enabled	Text	N		是否有效
4	password	Text	N		密码
5	reset_token	Text	N		刷新token
6	user_id	Text	N	UUID	租户ID/用户ID

表 20事件表

Columns in Table event
Col ID	Column Name	Data Type	Not Null	Data Def.	Comments
1	tenant_id	Text	N	UUID	租户ID
2	entity_type	Text	N		实体类型
3	entity_id	Text	N	UUID	实体ID
4	event_type	Text	N		事件类型
5	event_uid	Text	N	UUID	事件UID
6	body	Text	Y		事件内容
7	Id	Text	N	UUID	事件ID

表 22实体视图表

Columns in Table entity_view
Col ID	Column Name	Data Type	Not Null	Data Def.	Comments
1	tenant_id	Text	N	UUID	租户ID
2	entity_type	Text	N		实体类型
3	entity_id	Text	N	UUID	实体ID
4	type	Text	N		实体视图类型
5	name	Text	N	UUID	实体视图名称
6	keys	Text	Y		键
7	Id	Text	N	UUID	实体视图ID
8	customer_id	Text	N		用户ID
9	start_ts	bigint	N		开始时间
10	end_ts	bigint	N		结束时间
11	search_text	Text	N		搜索文本
12	additional_info	Text	N		附加信息

1. 需求可追踪性

表 21需求可追踪性

需求	数据库表
规则链库是一个高度可定制和可配置的模块，用于复杂的事件处理。	rule_node、 rule_chain、 tenant
系统支持多租户开箱即用。您可以将系统租户视为独立的业务实体：拥有或生产设备的个人或组织。	tenant、 customer、 user、 relation
提供注册和管理设施的能力。允许配置服务器端资产属性 并监视相关警报。	asset、 admin_settings、 alarm、 tenant
提供注册和管理设备的功能。允许监视客户端和配置服务器端设备属性。为服务器端应用程序提供API，以将RPC命令发送到设备，反之亦然。	device、 relation、 tenant
所有仪表板都是使用部件库中定义的系统小部件构建的。每个小部件都提供最终用户功能，如数据可视化，远程设备控制，报警管理和显示静态自定义html内容。	widgets_bundle、 widget_type、 dashboard、 asset、 device、 entity_view、 alarm
所有仪表板都是使用部件库中定义的系统小部件构建的，系统允许您创建丰富的物联网仪表板，实现数据可视化和远程设备控制。超过30个可自定义的小部件允许您为大多数物联网用例构建最终用户自定义仪表板。	widgets_bundle、 widget_type、 dashboard、 event

*注释

PostgreSQL：PostgreSQL是一种特性非常齐全的自由软件的对象-关系型数据库管理系统（ORDBMS），是以加州大学计算机系开发的POSTGRES，4.2版本为基础的对象关系型数据库管理系统。POSTGRES的许多领先概念只是在比较迟的时候才出现在商业网站数据库中。PostgreSQL支持大部分的SQL标准并且提供了很多其他现代特性，如复杂查询、外键、触发器、视图、事务完整性、多版本并发控制等。同样，PostgreSQL也可以用许多方法扩展，例如通过增加新的数据类型、函数、操作符、聚集函数、索引方法、过程语言等。另外，因为许可证的灵活，任何人都可以以任何目的免费使用、修改和分发PostgreSQL。

Cassandra:Cassandra是一个混合型的非关系的数据库，类似于Google的BigTable。其主要功能比Dynamo （分布式的Key-Value存储系统）更丰富，但支持度却不如文档存储MongoDB（介于关系数据库和非关系数据库之间的开源产品，是非关系数据库当中功能最丰富，最像关系数据库的。支持的数据结构非常松散，是类似json的bjson格式，因此可以存储比较复杂的数据类型）。Cassandra最初由Facebook开发，后转变成了开源项目。它是一个网络社交云计算方面理想的数据库。以Amazon专有的完全分布式的Dynamo为基础，结合了Google BigTable基于列族（Column Family）的数据模型。P2P去中心化的存储。很多方面都可以称之为Dynamo 2.0