TDengine时序数据库

引用文件

本文档引用的文件

简介

本专项文档聚焦 yudao-cloud 项目中 TDengine 时序数据库的应用实践，围绕设备监控、日志存储、性能指标统计三大场景，系统阐述时序数据建模策略、超级表设计原则、数据分区与时间范围优化、SQL 查询语法与聚合分析、数据导入导出与归档、集群部署与运维调优，并解释与 MySQL 的数据同步机制与一致性保障方案。

项目结构

TDengine 相关内容分布在以下位置：

SQL 定义与分析脚本：sql/tdengine/
文档与测试实践：docs/test/tdengine.md
应用侧 Mapper 接口：yudao-module-device、yudao-module-blacklist 模块
配置文件：deploy/yml/prod/datasource.yaml、application-common.yaml

Mermaid Diagram Code:

graph TB
subgraph "TDengine SQL 定义"
M1["monitor.sql"]
DR["device_runtime.sql"]
AR["app_runtime.sql"]
MAD["monitor_analysis.sql"]
DAD["device_activity_detail.sql"]
end
subgraph "应用模块"
DM["BaseDeviceActivityMapper.java"]
BM["AppKillRecordMapper.java"]
RC["RuntimeCountRefactorProperties.java"]
end
subgraph "配置"
DS["datasource.yaml"]
AC["application-common.yaml"]
end
M1 --> DM
DR --> DM
AR --> BM
MAD --> DM
DAD --> DM
DS --> DM
DS --> BM
AC --> RC

图表来源

章节来源

核心组件

设备活跃明细与运行时长统计：通过多库（日/月/年）与超级表（device_runtime_count、device_activity_detail）实现时间维度分区与标签化组织，支持按 record_time、data_key 等字段进行高效查询与聚合。
APP 运行记录与 API 访问监控：APP 运行记录采用高保留周期与高压缩参数的数据库配置，监控表按分钟粒度统计接口访问量、成功率与失败率，便于趋势分析与告警。
黑名单杀死回调：通过独立 TDengine 数据源接入，基于 Kafka 消费后写入 TDengine，实现事件型数据的时序化存储与查询。
应用侧 Mapper 接口：提供分页查询、批量插入、按时间区间与标签过滤等能力，支撑前端统计与报表展示。
配置与运维：通过 datasource.yaml 定义多数据源（含 TDengine Restful JDBC），application-common.yaml 提供 Kafka、XXL-Job 等调度与消息队列配置，支撑数据采集、清洗与归档。

章节来源

架构概览

TDengine 在 yudao-cloud 中承担时序数据的采集、存储与分析职责，典型数据流包括：

设备/APP 事件通过 Kafka/HTTP 上报至业务服务，经应用层写入 TDengine 热表；
通过 XXL-Job 定时任务执行数据归档：从热表导出、压缩、有序重写入归档库；
前端/报表通过 MyBatis 查询 TDengine 超级表，结合聚合分析 SQL 进行可视化展示。

Mermaid Diagram Code:

sequenceDiagram
participant 设备 as "设备/APP"
participant 服务 as "业务服务"
participant TD热 as "TDengine 热表"
participant 归档 as "归档任务(XXL-Job)"
participant TD归 as "TDengine 归档库"
设备->>服务 : "事件/指标上报"
服务->>TD热 : "批量写入(热表)"
归档->>TD热 : "按天导出CSV"
TD热-->>归档 : "导出结果"
归档->>归档 : "压缩/本地暂存"
归档->>TD归 : "有序批量重写入(归档库)"
服务-->>TD热 : "查询/聚合分析"

图表来源

章节来源

详细组件分析

设备活跃与运行时长统计

数据库与超级表设计
- device_runtime_count_day/month/year：按日/月/年分区，保留周期分别为 90/395/2190 天，配合高压缩参数与合适的 MINROWS/MAXROWS，平衡写入吞吐与查询性能。
- device_activity_detail：按 record_time 标签区分不同时间粒度，支持按 MAC/CPU 等维度聚合。
查询与聚合
- 支持按时间范围、标签过滤的分组聚合，如按分钟/小时/天统计设备活跃度、CPU 使用情况。
- Mapper 接口提供分页查询、批量插入、按 record_time 列表筛选等能力，满足报表与前端展示需求。

Mermaid Diagram Code:

flowchart TD
Start(["开始"]) --> BuildQuery["构建查询条件<br/>时间范围 + 标签过滤"]
BuildQuery --> GroupAgg["按时间粒度分组聚合"]
GroupAgg --> SelectCols["选择聚合列<br/>sum/count/avg"]
SelectCols --> Exec["执行查询"]
Exec --> End(["结束"])

图表来源

章节来源

APP 运行记录与 API 访问监控

APP 运行记录
- 使用高保留周期与压缩参数的数据库配置，超级表包含 MAC、CPU、版本号、持续时间等字段，标签按 package_name/day 维度组织，便于按应用维度统计与趋势分析。
API 访问监控
- monitor.visit_minute 超级表按分钟统计接口访问量、成功/失败次数，支持按服务器 IP、域名别名等维度聚合，满足访问趋势与异常告警需求。

Mermaid Diagram Code:

sequenceDiagram
participant 采集 as "采集/上报"
participant TD as "TDengine"
participant 分析 as "分析/报表"
采集->>TD : "写入APP运行记录/访问监控"
TD-->>分析 : "按分钟/按接口维度聚合"
分析-->>分析 : "趋势图/占比/异常检测"

图表来源

章节来源

黑名单杀死回调

数据源与写入
- 通过独立 TDengine 数据源（td_blacklisted_kill_callback）接入，Mapper 接口支持按时间范围、MAC、CPU 等条件过滤，满足事件回溯与审计需求。
与 Kafka 集成
- application-common.yaml 中定义了黑名单相关主题，结合业务模块的消费者实现事件驱动写入。

Mermaid Diagram Code:

classDiagram
class AppKillRecordMapper {
+selectPage(pageReqVO)
+selectListByPageVO(pageReqVO)
+builderLambdaQueryWrapperX(pageReqVO)
}

图表来源

章节来源

数据归档与存储优化

归档策略
- 采用“热数据乱序写入 → 定期 ETL 清洗 → 归档数据有序重写”的方案，通过 XXL-Job 调度，按天导出 CSV、压缩、多线程批量有序写入归档库，显著降低存储成本与提升压缩比。
有序写入的重要性
- 文档明确指出：在相同数据量级下，有序写入的磁盘占用约为乱序写入的 1/7；乱序写入会破坏列式压缩与时间索引优势，导致压缩比从约 5% 恶化到 30%+。

Mermaid Diagram Code:

flowchart TD
S(["开始归档"]) --> CalcRange["计算归档日期区间"]
CalcRange --> Export["按天导出CSV"]
Export --> Compress["压缩为ZIP"]
Compress --> Upload["上传至TDengine节点"]
Upload --> Restore["Python脚本有序批量重写"]
Restore --> Update["更新归档状态(写回MySQL)"]
Update --> E(["结束"])

图表来源

章节来源

docs/test/tdengine.md

配置与数据源

多数据源配置
- datasource.yaml 定义了 TDengine 的多个数据源（app/activity/device/runtime 等），均使用 Restful JDBC 驱动，便于通过统一的 MyBatis/动态数据源框架进行访问。
运行时配置
- RuntimeCountRefactorProperties 提供 TDengine 连接参数（host/port/username/password）与归档相关配置（如 activeSuffix、baseNames、keep 周期等），支持运行时切换与热更新。

Mermaid Diagram Code:

graph TB
AC["application-common.yaml"] --> K["Kafka配置"]
AC --> XXL["XXL-Job配置"]
DS["datasource.yaml"] --> TDRS["TDengine Restful数据源"]
RC["RuntimeCountRefactorProperties"] --> TDRS

图表来源

章节来源

依赖关系分析

模块耦合
- 设备模块与黑名单模块分别通过独立 Mapper 接口访问 TDengine，降低耦合度；公共配置集中在 datasource.yaml 与 application-common.yaml。
外部依赖
- TDengine 通过 Restful JDBC 驱动访问；Kafka 用于事件驱动的数据采集；XXL-Job 用于定时归档任务编排。
数据一致性
- 通过 Kafka 消费与应用层事务控制，结合 TDengine 的幂等写入策略，确保事件型数据的一致性与可追溯性。

Mermaid Diagram Code:

graph TB
DeviceBiz["设备模块biz"] --> TDDev["TDengine设备库"]
BlackBiz["黑名单模块biz"] --> TDBlack["TDengine黑名单库"]
Kafka["Kafka"] --> DeviceBiz
Kafka --> BlackBiz
XXL["XXL-Job"] --> TDDev
XXL --> TDBlack

图表来源

章节来源

性能考量

写入顺序优化
- 严格控制写入顺序，避免时间乱序导致的压缩比劣化与磁盘占用膨胀；对“隔天汇总上报”类数据采用归档重写策略，恢复时间有序性。
数据库参数调优
- 合理设置 KEEP、DURATION、BUFFER、CACHESIZE、MINROWS/MAXROWS 等参数，平衡写入吞吐与查询性能；对高保留周期场景启用压缩与页面大小优化。
查询优化
- 利用超级表的标签过滤与时间范围限定，减少扫描范围；聚合查询中优先使用时间分组与标签分桶，避免全表扫描。
归档与冷热分离
- 保留近期热数据在线查询，历史数据归档至有序库，降低查询延迟与存储成本。

章节来源

故障排查指南

存储膨胀排查
- 检查是否存在大量乱序写入；确认归档任务是否按时执行；核对 KEEP 与 DURATION 配置是否合理。
查询性能问题
- 确认查询条件是否包含时间范围与标签过滤；检查是否使用了合适的分组与聚合；评估是否需要增加索引或调整分区策略。
数据源连通性
- 核对 datasource.yaml 中的 URL、用户名、密码；确认 TDengine 服务端口与网络可达性；验证 Restful JDBC 驱动版本兼容性。
归档任务异常
- 查看 XXL-Job 调度日志与任务状态；确认导出/压缩/重写过程中的错误信息；检查 SSH 远程执行权限与脚本可用性。

章节来源

结论

TDengine 在 yudao-cloud 中为设备监控、日志存储与性能指标统计提供了高效的时序数据解决方案。通过合理的超级表设计、时间分区与标签组织、严格的写入顺序控制以及完善的归档与运维体系，项目实现了高吞吐写入、低成本存储与高性能查询的统一。建议在后续实践中持续优化写入策略、完善监控告警，并根据业务增长动态调整数据库参数与归档策略。

附录

SQL 查询要点
- 时间范围限定：使用 BETWEEN 限定 ts 字段，结合 GROUP BY 按分钟/小时/天聚合。
- 标签过滤：通过 TAGS 字段（如 package_name、day、record_time）进行维度过滤。
- 聚合函数：常用 SUM、COUNT、AVG、MAX/MIN 等，结合 CASE WHEN 实现复杂指标计算。
归档配置示例
- XXL-Job 参数：backup/write/forceArchiveTwoMonthsAgo/archiveDayConfigs 等，用于控制归档窗口与重试策略。

章节来源

目录​

简介​

项目结构​

核心组件​

架构概览​

详细组件分析​

设备活跃与运行时长统计​

APP 运行记录与 API 访问监控​

黑名单杀死回调​

数据归档与存储优化​

配置与数据源​

依赖关系分析​

性能考量​

故障排查指南​

结论​

附录​

目录

简介

项目结构

核心组件

架构概览

详细组件分析

设备活跃与运行时长统计

APP 运行记录与 API 访问监控

黑名单杀死回调

数据归档与存储优化

配置与数据源

依赖关系分析

性能考量

故障排查指南

结论

附录