跳到主要内容

项目介绍

引用文件

本文引用的文件

目录​

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

引言​

yudao-cloud 智能设备管理平台是基于 Spring Boot 3.4.1 与 Spring Cloud Alibaba 的现代化微服务架构，面向机顶盒（STB）与智能终端的全生命周期管理而深度定制。平台围绕设备监控、Launcher 运营、广告投放、黑名单风控、OTA 固件升级等核心业务场景，构建了高可用、可扩展、可观测的云原生系统。

平台采用“网关 + 多业务模块”的微服务组织方式，结合 Nacos 注册与配置中心、Redis 缓存、MySQL 关系库、Kafka 消息队列以及 TDengine 时序库，形成“OLTP + OLAP + 实时/异步”的混合存储与处理架构。同时，平台引入 LiteFlow 规则引擎，支持复杂业务规则的可视化编排与高性能匹配；并通过网关灰度发布机制，实现版本流量的精细化控制。

本项目旨在为初学者与一线工程师提供一份“从架构到业务、从设计到落地”的全景式文档，帮助快速理解系统定位、业务价值与技术要点。

项目结构​

yudao-cloud 采用多模块聚合工程，顶层 POM 管理版本与插件，子模块按“框架层 + 网关 + 核心业务 + 扩展业务”分层组织。核心模块包括：

  • 网关服务：yudao-gateway
  • 核心业务：yudao-module-system、yudao-module-infra、yudao-module-bpm、yudao-module-report
  • 物联网/IoT 核心：yudao-module-device、yudao-module-launcher、yudao-module-blacklist、yudao-module-task、yudao-module-rule

Mermaid Diagram Code:

graph TB
Root["yudao-cloud 项目根目录"]
Gateway["yudao-gateway<br/>网关服务"]
subgraph CoreModules["核心业务模块"]
System["yudao-module-system<br/>系统基础模块"]
Infra["yudao-module-infra<br/>基础设施模块"]
BPM["yudao-module-bpm<br/>工作流模块"]
Report["yudao-module-report<br/>报表模块"]
end
subgraph IoTModules["IoT核心业务"]
Device["yudao-module-device<br/>设备管理模块"]
Launcher["yudao-module-launcher<br/>Launcher运营模块"]
Blacklist["yudao-module-blacklist<br/>黑名单模块"]
Task["yudao-module-task<br/>任务与OTA模块"]
Rule["yudao-module-rule<br/>规则引擎模块"]
end
Root --> Gateway
Root --> CoreModules
Root --> IoTModules

图表来源

章节来源

核心组件​

  • 网关与灰度发布：基于 Spring Cloud Gateway 的灰度负载均衡，支持按请求头 version 与 tag 精准分流。
  • 规则引擎（LiteFlow）：提供可视化规则编排、Redis 多级缓存、业务类型隔离与高性能匹配。
  • 混合存储架构：MySQL 用于业务主数据，TDengine 用于海量日志与监控数据，Kafka 用于异步解耦与事件上报。
  • 业务域模块：设备管理、Launcher 运营、黑名单风控、任务与 OTA、规则引擎等。

章节来源

架构总览​

系统采用“前端 + 网关 + 微服务集群 + 中间件”的整体架构。前端通过网关访问后端服务，服务间通过 Nacos 注册与配置中心协同，数据层采用 MySQL + TDengine + Redis 的混合策略，消息层通过 Kafka 实现异步解耦。

Mermaid Diagram Code:

graph TB
User["Web/App 用户"] --> Gateway["yudao-gateway 网关"]
Device["智能终端设备"] --> Gateway
subgraph "微服务集群 (Spring Cloud Alibaba)"
Gateway --> System["yudao-system 系统服务"]
Gateway --> Infra["yudao-infra 基础服务"]
Gateway --> DeviceSvc["yudao-device 设备服务"]
Gateway --> Launcher["yudao-launcher 运营服务"]
Gateway --> Blacklist["yudao-blacklist 黑名单服务"]
Gateway --> Task["yudao-task 任务/OTA服务"]
Gateway --> Rule["yudao-rule 规则引擎"]
end
subgraph "中间件 & 存储"
Nacos["Nacos 注册/配置中心"]
Redis["Redis 缓存"]
MySQL["MySQL 业务库"]
TDengine["TDengine 时序库"]
Kafka["Kafka 消息队列"]
end
System -.-> Nacos
DeviceSvc -.-> TDengine
Task -.-> TDengine
Blacklist -.-> Kafka
Gateway -.-> Redis

图表来源

章节来源

详细组件分析​

网关与灰度发布机制​

  • 灰度负载均衡：根据请求头 version 与 tag，从 Nacos 元数据中筛选匹配实例，再基于权重随机选择。
  • 回退策略：若无匹配实例或未携带版本头，则回退至全量实例列表。
  • 过滤逻辑：支持 tag 过滤与版本过滤的组合。

Mermaid Diagram Code:

sequenceDiagram
participant Client as 客户端
participant Filter as GrayReactiveLoadBalancerClientFilter
participant LB as GrayLoadBalancer
participant Nacos as Nacos注册中心
participant Instance as 服务实例
Client->>Filter : 发起请求 (Header : version=1.0.1)
Filter->>Filter : 检查 URL Scheme 是否为 grayLb
Filter->>LB : 调用 choose() 选择实例
LB->>Nacos : 获取所有可用服务实例列表
Nacos-->>LB : 返回实例列表 (含 metadata)
LB->>LB : 筛选 metadata[version] == 1.0.1 的实例
alt 存在匹配版本的实例
LB->>LB : 基于权重随机选择一个实例
else 无匹配或无版本头
LB->>LB : 在所有实例中基于权重选择
end
LB-->>Filter : 返回目标 ServiceInstance
Filter->>Instance : 转发请求
Instance-->>Client : 返回响应

图表来源

章节来源

规则引擎（LiteFlow）​

  • 能力概述：支持多维设备属性匹配（AND/OR）、可视化编排、Redis 多级缓存、业务隔离（BusinessType）。
  • 业务接入：任务推送、Launcher 广告、黑名单管理、UOTA 升级、域名分发等。
  • 技术架构：后端核心为 LiteFlow + Redis 缓存 + MySQL 存储 + Feign/Kafka 交互；前端提供 RuleBusinessTabs 与可视化编辑器。

Mermaid Diagram Code:

flowchart TD
Start["开始: getRuleDetail(ruleId)"] --> CheckParam{"ruleId 是否为空?"}
CheckParam -- 是 --> Error["抛出异常"]
CheckParam -- 否 --> QueryRedis["查询 Redis 缓存"]
QueryRedis --> CacheHit{"缓存命中?"}
CacheHit -- 是 --> CheckEmpty{"是否为空占位符?"}
CheckEmpty -- 是 --> ReturnNull["返回 null"]
CheckEmpty -- 否 --> ReturnResult["返回规则 DTO"]
CacheHit -- 否 --> AcquireLock["尝试获取分布式锁"]
AcquireLock --> LockSuccess{"获取成功?"}
LockSuccess -- 否 --> ReturnNullLock["返回 null"]
LockSuccess -- 是 --> DoubleCheckRedis["再次查询 Redis"]
DoubleCheckRedis --> DoubleHit{"缓存命中?"}
DoubleHit -- 是 --> ReturnResult
DoubleHit -- 否 --> QueryDB["查询数据库 RuleBusinessApi"]
QueryDB --> DBHit{"数据库存在?"}
DBHit -- 是 --> SetCache["写入 Redis 缓存"]
SetCache --> ReturnDBResult["返回 DB 数据"]
DBHit -- 否 --> SetEmptyCache["写入防穿透空值"]
SetEmptyCache --> ReturnNullDB["返回 null"]

图表来源

章节来源

混合存储架构（MySQL + TDengine）​

  • 数据源常量：模块通过常量类定义多数据源，如 TDengine 的日活、运行记录、归档库等。
  • 数据流：业务主数据走 MySQL，设备心跳与日志等海量时序数据走 TDengine，Kafka 用于异步上报与解耦。

Mermaid Diagram Code:

graph TD
subgraph "业务数据 (OLTP)"
App["业务应用"] --> |CRUD| MySQL["MySQL 8.0+"]
end
subgraph "时序/日志数据 (OLAP)"
Device["设备端"] --> |心跳/日志| Gateway["网关"]
Gateway --> |转发| TaskSvc["Task/Device 服务"]
TaskSvc --> |写入| TDengine["TDengine 时序库"]
TaskSvc --> |归档| TDArchive["TDengine 归档库"]
end
subgraph "缓存层"
Service --> |Cache| Redis["Redis 5.0+"]
end

图表来源

章节来源

业务场景：设备监控、Launcher 运营、广告投放、黑名单风控、OTA 固件升级​

  • 设备监控

    • 心跳与运行记录：通过 TDengine 存储设备运行时序数据，支持日活、运行时长等分析。
    • 心跳配置与连通性检查：提供心跳周期配置与连通性检测文档。
    • 统计面板：设备活跃度、运行时长等指标可视化。

  • Launcher 运营与广告投放

    • 广告资源下载流量估算：提供接口请求示例与流量分析，便于评估带宽与成本。
    • 广告策略：结合规则引擎实现按渠道、地区、设备型号等维度的精准投放。

  • 黑名单风控

    • APP 卸载黑名单：支持与渠道、MAC、地区关联，结合审批流程进行管控。
    • 回调事件：通过 Kafka 发送黑名单回调事件，实现跨系统联动。

  • OTA 固件升级

    • 升级包管理：支持版本号、包名、系统应用路径等字段管理。
    • 策略匹配：结合规则引擎与传统渠道维度，实现灰度发布与定向升级。
    • 请求处理流程：设备侧发起升级检查，服务端进行版本筛选与策略匹配，返回最优升级包。

Mermaid Diagram Code:

sequenceDiagram
participant STB as "机顶盒/设备"
participant Biz as "UOTA模块"
participant Rule as "规则引擎 (RuleRunUtil)"
participant Legacy as "传统逻辑 (渠道)"
STB->>Biz : "1. 请求升级检查 (版本号, 平台, MAC)"
Biz->>Biz : "2. 查询该平台下所有更高版本的 UOTA包"
loop "3. 遍历候选升级包"
Note right of Biz : "规则匹配"
par "并行计算"
Biz->>Rule : "3a. 规则引擎匹配 (matchBusinessIds)"
Rule-->>Biz : "是否命中"
and "传统逻辑"
Biz->>Legacy : "3b. 匹配渠道白名单"
Legacy-->>Biz : "是否命中"
end
alt "任意条件命中"
Biz->>Biz : "4. 加入可用升级列表"
end
end
Biz->>Biz : "5. 选择最新版本 (通常)"
Biz-->>STB : "6. 返回升级包详情 (URL, MD5, 更新说明)"

图表来源

章节来源

依赖分析​

  • 技术栈与版本
    • Spring Boot: 3.4.1
    • JDK: 17+
    • 中间件：Nacos、Redis、MySQL、TDengine、Kafka
  • 模块依赖
    • 网关依赖各业务模块，业务模块之间通过 RPC/消息进行协作。
    • 规则引擎为多业务模块共享能力，通过业务类型隔离与缓存优化提升性能。

Mermaid Diagram Code:

graph TB
Gateway["yudao-gateway"] --> Device["yudao-device"]
Gateway --> Launcher["yudao-launcher"]
Gateway --> Blacklist["yudao-blacklist"]
Gateway --> Task["yudao-task"]
Gateway --> Rule["yudao-rule"]
Rule --> MySQL["MySQL"]
Rule --> Redis["Redis"]
Task --> TDengine["TDengine"]
Blacklist --> Kafka["Kafka"]

图表来源

章节来源

性能考虑​

  • 规则引擎缓存：Redis 多级缓存 + 分布式锁，避免缓存穿透与击穿，保障毫秒级响应。
  • 灰度发布：基于 Header 的版本与 Tag 精准分流，降低风险与回滚成本。
  • 存储分层：MySQL 负责高并发事务，TDengine 负责海量时序数据写入与查询，Kafka 解耦异步事件。
  • 监控可观测：SkyWalking 与 Prometheus 集成，辅助性能分析与故障定位。

故障排查指南​

  • 网关灰度不生效
    • 检查请求头是否包含 version 或 tag；确认 Nacos 实例 metadata 是否匹配。
    • 参考灰度负载均衡实现与回退逻辑。
  • 规则引擎命中异常
    • 核对 Redis 缓存是否命中、是否存在空值占位；检查数据库规则定义与绑定关系。
  • 数据存储异常
    • 确认 TDengine 连接与写入权限；核对数据源常量与实际库名。
  • 黑名单回调失败
    • 检查 Kafka Topic 配置与消费者状态；验证回调事件结构与签名。

章节来源

结论​

yudao-cloud 智能设备管理平台以 Spring Cloud Alibaba 为基础，结合 LiteFlow 规则引擎与 TDengine 时序库，构建了覆盖设备全生命周期的现代化微服务系统。通过网关灰度发布、混合存储与可观测性体系，平台在保证高并发与稳定性的同时，提供了灵活的业务编排能力，能够高效支撑设备监控、Launcher 运营、广告投放、黑名单风控与 OTA 升级等核心业务场景。

附录​

  • 快速开始与端口配置：各模块默认端口与启动流程详见项目文档。
  • 文档资源：系统设计、对接文档、数据分析、黑名单机制、设备接入等文档目录。

章节来源

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