TDengine时序数据库集成

引用文件

本文档引用的文件

简介

本文件面向在本项目中集成TDengine时序数据库的技术人员，系统性阐述时序数据建模设计（时间戳、标签、数值字段组织）、SQL查询优化策略（时间窗口过滤、聚合函数、索引与分区）、数据导入导出机制（批量写入、增量同步、数据压缩与存储优化）、完整时序分析示例（趋势分析、峰值检测、异常识别、预测建模）以及性能调优与故障排查方法。文档以仓库中现有的TDengine建库建表SQL、Java集成代码、归档脚本与配置为依据，提供可落地的实施建议。

项目结构

本项目在模块化架构下对TDengine进行了多场景集成：

数据建模与库表：位于sql/tdengine目录，包含APP运行记录、设备运行时长、访问统计等超级表与数据库定义。
Java集成与DAO：位于各业务模块的dal/tdengine与service目录，封装MyBatis Mapper与批量写入逻辑。
归档与ETL：位于yudao-module-task/resources/appruntime目录，提供按天导出、压缩与批量有序重写的Python脚本。
配置与路由：位于deploy/yml/prod/datasource.yaml，定义多数据源（含TDengine Restful JDBC）。
查询与可视化：位于yudao-module-report模块，通过JDBC直连TDengine执行SQL并返回结果。

Mermaid Diagram Code:

graph TB
subgraph "前端/业务服务"
UI["前端/报表"]
Biz["业务服务"]
end
subgraph "数据接入层"
MQ["消息队列/Kafka"]
SDK["设备SDK/HTTP上报"]
end
subgraph "存储层"
TD["TDengine(REST/JDBC)"]
subgraph "库与超级表"
AR["app_runtime_2025120.flow_app_runtime"]
DR["device_runtime.device_runtime"]
MON["monitor.visit_minute"]
end
end
subgraph "归档与ETL"
SH["Shell脚本(app_runtime_backup.sh)"]
PY["Python脚本(app_runtime_restore.py)"]
XXL["XXL-Job调度"]
end
UI --> Biz
SDK --> Biz
MQ --> Biz
Biz --> TD
TD --> AR
TD --> DR
TD --> MON
Biz --> SH
SH --> PY
PY --> TD
XXL --> SH

图表来源

章节来源

核心组件

TDengine库表与建模
- APP运行记录超级表：包含时间戳、主键、设备标识、CPU标识、数值字段（版本号、时长、打开次数、创建时间）与标签（包名、day）。
- 设备运行时长超级表：包含时间戳、主键、设备标识、CPU标识、结束时间、设备时长等字段与标签（record_time）。
- 访问统计超级表：包含时间戳、主键、URL、服务器IP、域名、访问/成功/失败计数、创建时间与标签（URL别名、month）。
Java集成与批量写入
- Mapper接口与批量插入：通过BaseMapperX的insertBatch实现大批量写入，支持自定义批次大小。
- 设备活跃统计服务：按日/月/年维度聚合写入，支持Redis去重后批量导入。
- 黑名单APP杀死记录：通过专用数据源路由至TDengine，支持时间范围查询。
归档与ETL
- Shell导出：按day字段分天导出CSV并压缩。
- Python恢复：多线程并发、批量有序插入，重获时间有序性以激活列式压缩。
配置与路由
- 多数据源配置：包含TDengine REST/JDBC连接信息，按业务模块路由。
- 动态切换：支持统计库后缀切换与影子库热切。

章节来源

架构总览

TDengine在本项目中的使用贯穿“采集-接入-存储-归档-查询”全链路，强调时间有序写入与冷热分层策略，通过归档ETL将乱序热数据转化为有序历史数据，最大化压缩比与查询效率。

Mermaid Diagram Code:

sequenceDiagram
participant Dev as "设备/SDK"
participant Biz as "业务服务"
participant TD as "TDengine"
participant Arch as "归档库"
participant Vis as "可视化/报表"
Dev->>Biz : 上报APP运行记录/设备运行记录
Biz->>TD : 批量写入(热表)
Note over TD : 保持时间有序写入
TD-->>Biz : 写入确认
Biz->>Arch : 触发归档(按天导出CSV并压缩)
Arch->>Arch : Python多线程批量有序插入
Arch-->>Biz : 归档完成
Vis->>TD : 查询近期热数据
Vis->>Arch : 查询历史归档数据

图表来源

章节来源

docs/test/tdengine.md

详细组件分析

1) 时序数据建模设计

时间戳字段
- APP运行记录：record_time（timestamp），作为超级表主键，确保时间有序写入。
- 设备运行时长：ts（timestamp），记录事件发生时间。
- 访问统计：ts（timestamp），按分钟粒度统计。
标签字段
- APP运行记录：package_name（包名）、day（日期整型）。
- 设备运行时长：record_time（整型日期）。
- 访问统计：url_alias（URL别名）、month（年月整型）。
数值字段
- APP运行记录：version_code、duration、open_time、create_time。
- 设备运行时长：device_duration。
- 访问统计：visit_count、sucess_count、fail_count。

Mermaid Diagram Code:

erDiagram
FLOW_APP_RUNTIME {
timestamp record_time PK
varchar data_key PK
varchar mac
varchar cpu_id
int version_code
int duration
int open_time
timestamp create_time
}
DEVICE_RUNTIME {
timestamp ts PK
varchar data_key PK
varchar mac
varchar cpu
timestamp end_time
int device_duration
}
VISIT_MINUTE {
timestamp ts PK
varchar data_key PK
varchar url
varchar server_ip
varchar domain
int visit_count
int sucess_count
int fail_count
timestamp create_time
}

图表来源

章节来源

2) SQL查询优化策略

时间窗口过滤
- 使用 BETWEEN/时间范围条件限制扫描范围，避免全表扫描。
- 示例：黑名单APP杀死记录查询支持ts与create_time的范围过滤。
聚合函数与分组
- 按日/月/年维度统计活跃设备数，使用GROUP BY与COUNT聚合。
- 示例：设备活跃统计服务按日期集合进行分组统计。
索引与分区
- TDengine基于时间主键与标签建立索引与分块，查询时尽量利用PRIMARY KEY与TAGS过滤。
- 访问统计超级表已存在接口索引，便于按接口维度查询。
批量写入与有序性
- 通过批量插入与时间有序写入，提升压缩比与查询效率。
- 归档阶段将乱序热数据有序重写，恢复列式压缩优势。

章节来源

3) 数据导入导出机制

批量写入
- Java侧通过BaseMapperX的insertBatch实现大批量写入，支持自定义批次大小。
- 设备活跃统计服务支持Redis去重后批量导入，避免重复写入。
增量同步
- 归档脚本按自然日导出，确保时间维度纯净；支持自动重试与失败补偿。
数据压缩与存储优化
- 导出后立即压缩，减少中间文件占用；Python恢复阶段多线程批量有序插入，恢复压缩优势。
冷热分层
- 热表保存近期数据，归档库保存历史数据；通过XXL-Job调度实现自动化。

Mermaid Diagram Code:

flowchart TD
Start(["开始"]) --> Gen["生成日期范围"]
Gen --> Export["按天导出CSV"]
Export --> Zip["压缩为ZIP"]
Zip --> Upload["上传至TDengine节点"]
Upload --> Unzip["解压"]
Unzip --> BatchInsert["多线程批量有序插入"]
BatchInsert --> Clean["清理临时文件"]
Clean --> End(["结束"])

图表来源

章节来源

4) 时序数据分析示例

趋势分析
- 按日/月/年统计活跃设备数，观察趋势变化。
- 使用GROUP BY与SUM/COUNT聚合，结合时间窗口过滤。
峰值检测
- 通过MAX/PERCENTILE聚合识别访问高峰时段。
- 结合标签（URL别名、域名）定位热点接口。
异常识别
- 统计失败计数与成功率，识别异常波动。
- 黑名单APP杀死记录按时间范围查询，定位异常事件。
预测建模
- 基于历史趋势与周期性特征，结合外部因子（节假日、活动）进行预测。
- TDengine支持降采样与聚合，为预测模型提供高质量输入。

章节来源

5) Java集成与数据源路由

Mapper接口与批量写入
- BaseDeviceActivityMapper提供分页、列表、批量插入等通用能力。
- AppKillRecordMapper通过数据源注解路由至TDengine专用数据源。
动态数据源与后缀切换
- 统计库支持后缀切换与影子库热切，便于重构与灰度发布。
可视化查询
- GoViewTDEngineDataServiceImpl通过JDBC直连TDengine执行SQL并返回结果。

Mermaid Diagram Code:

classDiagram
class BaseDeviceActivityMapper {
+selectPage(reqVO, dates)
+list(po, dates)
+countActivityByRecordTime(dates)
+insertBatch(list)
}
class AppKillRecordMapper {
+selectPage(pageReqVO)
+selectListByPageVO(pageReqVO)
}
class DeviceActivityDetailServiceImpl {
+getActivityDetailPage(pageReqVO)
+selectActivityStatistics(reqVO)
+insert(deviceActivityDetailBO)
+redisToTDengineByKeys(keys)
}
class GoViewTDEngineDataServiceImpl {
+getDataBySQL(reqVO)
}
DeviceActivityDetailServiceImpl --> BaseDeviceActivityMapper : "使用"
AppKillRecordMapper ..> BaseMapperX : "继承"
GoViewTDEngineDataServiceImpl --> JdbcTemplate : "使用"

图表来源

章节来源

依赖关系分析

数据源配置
- 多数据源（TDengine REST/JDBC）通过datasource.yaml统一管理，按模块路由。
动态数据源
- RuntimeCountRefactorProperties支持统计库后缀切换与影子库热切。
DAO与Mapper
- BaseMapperX提供批量插入、更新等通用能力；业务Mapper通过注解路由至TDengine。

Mermaid Diagram Code:

graph TB
DS["datasource.yaml"] --> TD1["td_app_runtime"]
DS --> TD2["td_device_runtime"]
DS --> TD3["td_api_visit"]
Props["RuntimeCountRefactorProperties"] --> DB["统计库(含后缀/影子库)"]
Mapper["BaseDeviceActivityMapper"] --> TDengine["TDengine"]
AppKill["AppKillRecordMapper"] --> TDengine
Report["GoViewTDEngineDataServiceImpl"] --> TDengine

图表来源

章节来源

性能考量

写入顺序与压缩
- 严格保持时间有序写入，避免乱序导致压缩比恶化与磁盘占用暴涨。
- 归档阶段将乱序热数据有序重写，恢复列式压缩优势。
批量写入与批次大小
- 使用insertBatch并根据数据量调整批次大小，平衡吞吐与内存占用。
索引与分区
- 利用PRIMARY KEY与TAGS过滤，减少扫描范围；按日/月/年分区，提升查询效率。
冷热分层
- 最近N天热数据在线查询，历史数据归档至独立库，降低热表压力。
监控与告警
- 持续监控压缩比、磁盘占用与查询延迟，建立异常告警与优化闭环。

章节来源

故障排查指南

写入异常
- 检查时间戳是否正确、是否存在重复主键；确认批次大小与网络稳定性。
- 使用Redis去重避免重复写入。
查询异常
- 确认时间范围过滤条件是否合理；检查索引与标签使用是否正确。
- 通过GoViewTDEngineDataServiceImpl直连TDengine执行SQL验证。
归档失败
- 检查Shell导出与Python恢复脚本的路径、权限与参数；确认XXL-Job调度状态。
- 核对压缩比与磁盘占用，必要时人工干预重试。
数据源问题
- 核对datasource.yaml中的URL、用户名、密码；确认TDengine服务可达性。

章节来源

结论

TDengine在本项目中通过严格的建模设计、有序写入策略、冷热分层与归档ETL，实现了高压缩比与高效查询。建议在采集、传输、写入三个环节控制时间有序性，配合批量写入与索引利用，持续监控压缩比与磁盘占用，确保长期存储成本可控与查询性能稳定。

附录

建库建表参考
- APP运行记录超级表：app_runtime.sql
- 设备运行时长超级表：device_runtime.sql
- 访问统计超级表：monitor.sql
归档脚本
- Python恢复脚本：app_runtime_restore.py
配置参考
- 数据源配置：datasource.yaml

目录​

简介​

项目结构​

核心组件​

架构总览​

详细组件分析​

1) 时序数据建模设计​

2) SQL查询优化策略​

3) 数据导入导出机制​

4) 时序数据分析示例​

5) Java集成与数据源路由​

依赖关系分析​

性能考量​

故障排查指南​

结论​

附录​

目录

简介

项目结构

核心组件

架构总览

详细组件分析

1) 时序数据建模设计

2) SQL查询优化策略

3) 数据导入导出机制

4) 时序数据分析示例

5) Java集成与数据源路由

依赖关系分析

性能考量

故障排查指南

结论

附录