TDengine时序数据库

引用文件

本文引用的文件

简介

本文件面向yudao-cloud项目中的TDengine时序数据库应用，系统性阐述其在设备活动明细、应用活动统计、监控数据等场景下的存储与查询实践，解释TDengine相较传统关系型数据库在高写入、数据压缩、时间序列特化方面的优势，并给出超级表设计、标签与时间戳设计、数据分区策略、SQL示例、与MySQL协同机制以及运维实践（性能调优、容量规划、备份恢复）。

项目结构

TDengine相关实现分布于以下模块与资源：

SQL初始化脚本：位于sql/tdengine目录，定义数据库、超级表与标签字段
设备侧统计重构作业：DeviceRuntimeCountJob负责“影子库+热切换+ETL重写”
系统侧监控数据对象：VisitMinuteDO定义监控表的标签字段生成规则
报表侧TDengine访问：TDEngineBaseMapper与GoViewTDEngineDataServiceImpl提供数据源路由与查询
文档与测试：tdengine.md记录乱序写入与归档方案；TDengineTagTests演示标签查询

Mermaid Diagram Code:

graph TB
subgraph "SQL脚本"
A1["device_activity_detail.sql"]
A2["app_activity.sql"]
A3["monitor.sql"]
end
subgraph "设备模块"
B1["DeviceRuntimeCountJob.java"]
B2["RuntimeCountRefactorProperties.java"]
end
subgraph "系统模块"
C1["VisitMinuteDO.java"]
end
subgraph "报表模块"
D1["TDEngineBaseMapper.java"]
D2["GoViewTDEngineDataServiceImpl.java"]
end
subgraph "文档与测试"
E1["tdengine.md"]
E2["TDengineTagTests.java"]
end
A1 --> B1
A2 --> B1
A3 --> C1
B1 --> D1
C1 --> D2
E1 --> B1
E2 --> A2

图表来源

章节来源

核心组件

TDengine数据库与超级表
- 设备活跃明细：按日/月/年分库，超级表device_activity_detail，标签record_time
- 应用活跃明细：按日/月/年分库，超级表app_activity_detail，标签record_time、package_name
- 访问统计：监控库monitor，超级表visit_minute，标签url_alias、month
设备统计重构作业
- 影子库方案：创建影子库→切换数据源→导出旧库→导入到影子库→重置旧库
- 支持多统计库（日/月/年）与KEEP、DURATION等参数配置
监控数据对象
- VisitMinuteDO定义data_key与month标签生成规则，便于TDengine标签分区与查询
报表与数据源路由
- TDEngineBaseMapper标注@DS(DataSourceConstants.TDENGINE)，固定走TDengine数据源
- GoViewTDEngineDataServiceImpl通过JDBC路由至TDengine，支持SQL查询
文档与测试
- tdengine.md系统阐述乱序写入导致压缩膨胀的原因与归档方案
- TDengineTagTests演示REST查询与标签字段更新

章节来源

架构总览

TDengine在yudao-cloud中的应用架构围绕“热库+归档库+ETL清洗+查询路由”展开，核心流程如下：

Mermaid Diagram Code:

flowchart TD
Dev["设备/应用上报"] --> HotDB["TDengine 热库(日/月/年分库)"]
HotDB --> |乱序写入风险| ArchPlan["归档方案(ETL重写)"]
ArchPlan --> |按天导出CSV并压缩| Backup["备份文件(zip)"]
Backup --> |多线程批量有序写入| ColdDB["TDengine 归档库"]
Query["报表/系统查询"] --> Route["数据源路由(固定TDengine)"]
Route --> HotDB
Route --> ColdDB
MySQL["MySQL(系统数据源)"] -.-> Route

图表来源

组件详解

设备活跃明细与应用活跃明细（超级表设计）

设备活跃明细
- 分库：device_activity_day、device_activity_month、device_activity_year
- 超级表：device_activity_detail
- 标签：record_time（整型，如yyyyMMdd）
- 字段：ts（时间戳）、data_key（主键）、mac、cpu
应用活跃明细
- 分库：app_activity_day、app_activity_month、app_activity_year
- 超级表：app_activity_detail
- 标签：record_time、package_name
- 字段：ts、data_key、mac、cpu、version_code、duration、ip、country

Mermaid Diagram Code:

erDiagram
DEVICE_ACTIVITY_DAY ||--o{ DEVICE_ACTIVITY_DETAIL : "超级表"
DEVICE_ACTIVITY_MONTH ||--o{ DEVICE_ACTIVITY_DETAIL : "超级表"
DEVICE_ACTIVITY_YEAR ||--o{ DEVICE_ACTIVITY_DETAIL : "超级表"
APP_ACTIVITY_DAY ||--o{ APP_ACTIVITY_DETAIL : "超级表"
APP_ACTIVITY_MONTH ||--o{ APP_ACTIVITY_DETAIL : "超级表"
APP_ACTIVITY_YEAR ||--o{ APP_ACTIVITY_DETAIL : "超级表"
DEVICE_ACTIVITY_DETAIL {
timestamp ts
varchar data_key PK
varchar mac
varchar cpu
int record_time
}
APP_ACTIVITY_DETAIL {
timestamp ts
varchar data_key PK
varchar mac
varchar cpu
int version_code
int duration
int record_time
varchar package_name
}

图表来源

章节来源

监控数据（访问统计）

监控库：monitor
超级表：visit_minute
标签：url_alias、month（整型，如202408）
字段：ts（分钟级）、data_key（主键）、url、server_ip、domain、visit_count、success_count、fail_count、create_time

Mermaid Diagram Code:

erDiagram
MONITOR ||--o{ VISIT_MINUTE : "超级表"
VISIT_MINUTE {
timestamp ts
varchar data_key PK
varchar url
varchar server_ip
varchar domain
int visit_count
int success_count
int fail_count
timestamp create_time
int month
varchar url_alias
}

图表来源

monitor.sql

章节来源

设备统计重构作业（影子库+热切换+ETL）

目标：解决乱序写入导致的磁盘膨胀，实现零停机切换
步骤：
1. 创建影子库（结构与主库一致，含数据库、超级表、KEEP/DURATION等参数）
2. 切换数据源（通过Nacos配置activeSuffix，新写入进入影子库）
3. 导出旧库（taosdump）
4. 导入到影子库（-W重映射）
5. 重置旧库（DROP并重建，释放磁盘）

Mermaid Diagram Code:

sequenceDiagram
participant Job as "重构作业"
participant Nacos as "配置中心"
participant TD as "TDengine"
participant SSH as "远程执行"
participant MySQL as "MySQL(记录表)"
Job->>TD : "创建影子库(数据库+超级表)"
Job->>Nacos : "更新activeSuffix(切换数据源)"
Job->>SSH : "taosdump导出旧库"
SSH-->>Job : "备份文件(zip)"
Job->>SSH : "Python脚本批量有序写入"
SSH-->>Job : "导入统计"
Job->>TD : "DROP并重建旧库"
Job->>MySQL : "更新归档记录状态"

图表来源

章节来源

乱序写入与归档方案（技术原理与实践）

乱序写入导致压缩比飙升、索引膨胀、碎片增多
归档方案：按天导出CSV→压缩→多线程批量有序写入归档库
冷热分离：保留最近N天热数据在线查询，历史数据归档

Mermaid Diagram Code:

flowchart TD
Start["开始"] --> Collect["收集热数据(按天)"]
Collect --> Export["导出CSV并压缩(zip)"]
Export --> Reorder["按时间排序(内存/本地)"]
Reorder --> BatchWrite["批量有序写入归档库"]
BatchWrite --> Verify["校验与统计"]
Verify --> End["结束"]

图表来源

tdengine.md

章节来源

tdengine.md

报表与查询路由（TDengine数据源）

固定数据源：TDEngineBaseMapper通过@DS(DataSourceConstants.TDENGINE)强制走TDengine
动态路由：GoViewTDEngineDataServiceImpl根据请求切换数据源并执行SQL
与MySQL协同：datasource.yaml配置MySQL数据源，TDengine独立数据源

Mermaid Diagram Code:

graph LR
Req["报表/前端请求"] --> Router["数据源路由"]
Router --> |固定TDengine| TD["TDEngineBaseMapper"]
Router --> |动态TDengine| JDBC["GoViewTDEngineDataServiceImpl"]
Router --> MySQL["MySQL(系统数据源)"]

图表来源

章节来源

标签字段与查询（标签设计与更新）

标签字段设计：record_time（整型，如yyyyMMdd）、package_name、url_alias、month
查询示例：DISTINCT TBNAME、按标签过滤、按ad_play_type更新
标签更新：通过REST接口批量更新标签字段

Mermaid Diagram Code:

sequenceDiagram
participant Test as "标签测试"
participant REST as "TDengine REST"
participant TD as "TDengine"
Test->>REST : "查询标签(ADISTINCT TBNAME)"
REST-->>Test : "返回表清单"
Test->>REST : "更新标签(SET TAG ...)"
REST-->>TD : "ALTER TABLE ... SET TAG ..."
TD-->>REST : "更新成功"
REST-->>Test : "更新完成"

图表来源

TDengineTagTests.java

章节来源

TDengineTagTests.java

依赖关系分析

模块耦合
- 设备模块依赖TDengine脚本与重构作业，保障统计库健康
- 系统模块通过VisitMinuteDO与monitor超级表提供监控数据
- 报表模块通过数据源注解与JDBC路由访问TDengine
外部依赖
- TDengine服务端（host/port/认证）
- SSH远程执行taosdump与Python脚本
- Nacos配置中心用于热切换

Mermaid Diagram Code:

graph TB
Device["设备模块"] --> TDScript["TDengine脚本"]
Device --> Refactor["重构作业"]
System["系统模块"] --> Monitor["监控超级表"]
Report["报表模块"] --> DSRoute["数据源路由"]
Refactor --> SSH["SSH执行"]
Refactor --> Nacos["Nacos配置"]
DSRoute --> TDengine["TDengine服务"]

图表来源

章节来源

性能考量

写入顺序
- 保持时间有序写入，避免乱序导致压缩比飙升与碎片增多
数据库参数
- KEEP/DURATION/BUFFER/CACHESIZE/MINROWS/MAXROWS等参数需结合数据生命周期与查询模式调优
分区与标签
- 合理使用record_time、month、package_name等标签，提升查询局部性
归档策略
- 热数据在线查询，历史数据归档并有序重写，降低存储与查询成本

章节来源

故障排查指南

乱序写入导致空间膨胀
- 现象：压缩比异常升高、磁盘占用激增
- 处理：启用归档方案，按天导出并有序重写
数据源切换失败
- 检查Nacos配置项与activeSuffix是否生效
- 确认SSH可达与taosdump权限
查询路由问题
- 确认@DS(DataSourceConstants.TDENGINE)与JDBC路由配置
- 校验SQL语法与标签字段是否存在

章节来源

结论

TDengine在yudao-cloud中通过“分库分表+超级表+标签分区+归档ETL”的组合，实现了设备活跃明细、应用活跃统计与监控数据的高写入、低存储与高效查询。配合严格的写入顺序控制与定期归档，可显著降低存储成本并提升系统稳定性。报表侧通过数据源路由统一访问TDengine，与MySQL形成互补的数据协同体系。

附录

SQL示例（路径引用）

创建数据库与超级表
数据插入（示例路径）
- 设备活跃明细插入：参考设备模块统计写入流程
- 应用活跃明细插入：参考应用模块统计写入流程
查询与聚合
- 按标签查询：参考标签测试用例
  - 标签查询示例
- 访问统计查询：参考监控超级表定义
  - 监控查询示例

与MySQL协同机制

MySQL作为系统数据源，承载业务主数据与控制台监控
TDengine专司时序数据的高写入与压缩存储
通过数据源路由与配置中心实现动态切换与热备

章节来源

目录​

简介​

项目结构​

核心组件​

架构总览​

组件详解​

设备活跃明细与应用活跃明细（超级表设计）​

监控数据（访问统计）​

设备统计重构作业（影子库+热切换+ETL）​

乱序写入与归档方案（技术原理与实践）​

报表与查询路由（TDengine数据源）​

标签字段与查询（标签设计与更新）​

依赖关系分析​

性能考量​

故障排查指南​

结论​

附录​

SQL示例（路径引用）​

与MySQL协同机制​

目录

简介

项目结构

核心组件

架构总览

组件详解

设备活跃明细与应用活跃明细（超级表设计）

监控数据（访问统计）

设备统计重构作业（影子库+热切换+ETL）

乱序写入与归档方案（技术原理与实践）

报表与查询路由（TDengine数据源）

标签字段与查询（标签设计与更新）

依赖关系分析

性能考量

故障排查指南

结论

附录

SQL示例（路径引用）

与MySQL协同机制