跳到主要内容

黑名单统计表

引用文件

本文引用的文件

目录​

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构概览
  5. 详细组件分析
  6. 依赖分析
  7. 性能考虑
  8. 故障排查指南
  9. 结论
  10. 附录

简介​

本文件聚焦于“黑名单统计表”的结构与实现，围绕统计数据字段、统计维度、实时与定时统计机制、查询优化与索引设计、以及可视化与趋势分析方法展开，帮助读者快速理解并高效使用黑名单相关统计能力。

项目结构​

黑名单统计涉及的关键文件分布如下：

  • TDengine 数据库脚本：定义超级表与标签字段，支撑按黑名单维度的子表拆分与高频写入
  • DO/DAO/Service/Consumer：定义数据对象、数据访问、业务服务与消息消费链路
  • 文档：提供处理流程、明细查询与技术架构说明

Mermaid Diagram Code:

graph TB
subgraph "TDengine"
TSQL["blacklisted.sql<br/>超级表与标签定义"]
end
subgraph "应用模块"
DO["AppKillRecordDO<br/>数据对象"]
MAPPER["AppKillRecordMapper<br/>TDengine访问"]
SERVICE["AppKillRecordServiceImpl<br/>统计与查询"]
CONSUMER["BlackKillCallbackConsumer<br/>Kafka消费入库"]
JOB["BlacklistedJob<br/>定时任务占位"]
end
subgraph "文档"
DOC1["uninstall-detail.md<br/>明细与架构"]
DOC2["app-blacklisted.md<br/>处理流程"]
end
TSQL --> DO
DO --> MAPPER
MAPPER --> SERVICE
CONSUMER --> SERVICE
DOC1 --> SERVICE
DOC2 --> SERVICE
JOB -.-> SERVICE

图表来源

章节来源

核心组件​

  • 数据模型与字段
    • 统计日期：ts（timestamp），用于按天粒度统计
    • 黑名单标识：black_list_id（tag），用于按黑名单维度聚合
    • 设备标识：mac（varchar）、cpu_id（varchar），唯一标识设备
    • 次数：frequency（int），记录某天内对某设备的处理次数
    • 主键：data_key（varchar，PRIMARY KEY），由 mac+cpu_id 组成
    • 创建时间：create_time（timestamp），用于审计与排序
  • 统计口径
    • 黑名单数量：以 black_list_id 为维度的记录条数
    • 影响设备数量：按 black_list_id 分组后 distinct(mac) 数量
    • 处理成功率：按天/按黑名单维度，成功处理次数 / 总处理次数
    • 平均处理时间：按天/按黑名单维度，处理耗时的加权平均（需结合业务埋点）

章节来源

架构概览​

黑名单统计采用“事件驱动 + 异步入库 + TDengine 超级表”的架构，实现高吞吐、低延迟的实时统计。

Mermaid Diagram Code:

sequenceDiagram
participant Device as "终端设备"
participant MQ as "Kafka"
participant Consumer as "BlackKillCallbackConsumer"
participant Service as "AppKillRecordServiceImpl"
participant TD as "TDengine 超级表"
Device->>MQ : "上报黑名单处理结果"
MQ-->>Consumer : "拉取消息"
Consumer->>Service : "转换为AppKillRecordDO并入库"
Service->>TD : "插入超级表记录"
TD-->>Service : "写入成功"
Service-->>Consumer : "处理完成"

图表来源

章节来源

详细组件分析​

数据模型与字段定义​

  • 超级表与标签
    • 超级表名：app_kill_record
    • 主键：data_key（PRIMARY KEY）
    • 标签：black_list_id（int），用于按黑名单维度拆分子表
    • 时间字段：ts（timestamp），用于按天统计
  • 关键字段说明
    • ts：YYYY-MM-DD 格式的日期，映射设备上报的 date 字段
    • black_list_id：黑名单配置项 ID，决定子表归属
    • mac/cpu_id：设备唯一标识
    • frequency：当日处理次数
    • create_time：记录创建时间，便于审计与排序

Mermaid Diagram Code:

erDiagram
APP_KILL_RECORD {
timestamp ts
varchar data_key PK
varchar mac
varchar cpu_id
int frequency
timestamp create_time
int black_list_id TAG
}

图表来源

章节来源

统计维度与口径​

  • 时间维度
    • 按 ts（天）统计：每日黑名单数量、影响设备数量、处理次数、成功率、平均处理时间
  • 黑名单维度
    • 按 black_list_id 维度统计：各黑名单配置的命中次数、覆盖设备数、成功率
  • 设备维度
    • 按 mac 维度统计：单设备被处理次数、最近处理时间、成功率

章节来源

实时统计与定时统计​

  • 实时统计
    • 事件驱动：设备上报处理结果 → Kafka 消费 → 写入 TDengine 超级表
    • 优点：低延迟、高吞吐；缺点：统计聚合需在查询侧完成
  • 定时统计
    • 当前模块存在定时任务占位类，可扩展为：
      • 增量更新：基于 create_time 或 ts 的增量扫描，更新汇总表
      • 全量重算：周期性全表扫描，重建统计快照
    • 建议：结合业务峰值时段，避免与高峰期冲突

Mermaid Diagram Code:

flowchart TD
Start(["开始"]) --> Realtime["实时写入<br/>Kafka -> TDengine"]
Start --> Scheduled["定时任务<br/>增量/全量统计"]
Realtime --> Query["查询侧聚合<br/>按天/按黑名单/按设备"]
Scheduled --> Agg["生成统计快照"]
Query --> Report["报表/看板"]
Agg --> Report
Report --> End(["结束"])

图表来源

章节来源

查询优化与索引设计建议​

  • TDengine 超级表索引
    • data_key（主键）：天然索引，适合按主键查询
    • black_list_id（tag）：按标签过滤，适合按黑名单维度聚合
    • ts（时间）：按天统计时建议建立时间索引
  • 查询优化要点
    • 使用标签过滤（black_list_id）减少扫描范围
    • 使用时间范围过滤（ts）缩小统计窗口
    • 聚合时优先使用 group by black_list_id/mac/ts
  • 索引与分区建议
    • 按天分区：提升时间范围查询效率
    • 按黑名单 ID 分桶：提升多维度聚合性能

章节来源

可视化与趋势分析​

  • 指标面板建议
    • 黑名单数量趋势（按天）
    • 影响设备数量趋势（按天）
    • 处理成功率（按天/按黑名单）
    • 平均处理时间（按天/按黑名单）
  • 趋势分析方法
    • 滚动窗口：7/30 天滚动均值
    • 同比/环比：对比上周/上月同时期
    • 异常检测：基于标准差或阈值告警

章节来源

依赖分析​

  • 组件耦合
    • Consumer 依赖 Service，Service 依赖 Mapper，Mapper 依赖 TDengine
    • 文档与流程图指导统计口径与查询路径
  • 外部依赖
    • Kafka：事件传输
    • TDengine：高性能时序存储
    • MyBatis-Plus：简化数据访问

Mermaid Diagram Code:

graph LR
Consumer["BlackKillCallbackConsumer"] --> Service["AppKillRecordServiceImpl"]
Service --> Mapper["AppKillRecordMapper"]
Mapper --> TD["TDengine 超级表"]
Docs["uninstall-detail.md / app-blacklisted.md"] --> Service

图表来源

章节来源

性能考虑​

  • 写入性能
    • TDengine 超级表适合高并发写入，建议批量提交
    • 合理设置子表数量，避免单表过大
  • 查询性能
    • 使用标签过滤与时间范围过滤
    • 聚合查询尽量使用 group by + limit
  • 存储与保留策略
    • 按天/按月归档历史数据
    • 设置合理的数据保留周期

故障排查指南​

  • Kafka 消费异常
    • 检查主题与消费者组配置
    • 查看日志错误堆栈，定位解析失败或入库异常
  • TDengine 写入失败
    • 校验字段类型与主键约束
    • 检查数据库连接与权限
  • 统计结果异常
    • 核对 ts 与 black_list_id 的过滤条件
    • 确认查询聚合逻辑与分组键

章节来源

结论​

黑名单统计通过 TDengine 超级表与事件驱动架构实现了高吞吐、低延迟的实时统计能力。建议在现有基础上完善定时统计与索引优化，并结合可视化看板持续监控关键指标，以支撑业务决策与运营分析。

附录​

  • 相关流程参考
    • 黑名单处理流程（用户视角与技术视角）
    • 明细查询与导出说明

章节来源

用户文档
AI 助手
Agent 列表
请选择一个 Agent 开始对话
AI 问答