管理后台 - Vben Admin

引用文件

本文引用的文件

简介

本项目为“Yudao Cloud”企业级微服务系统的一部分，提供基于 Vue3 + Vben Admin + Ant Design Vue 的管理后台实现思路与最佳实践。项目采用前后端分离架构，后端以 Spring Boot + Spring Cloud Alibaba 为核心，结合网关、注册中心、配置中心、缓存、数据库与时序库等中间件，形成完整的微服务生态。管理后台通过统一网关接入后端各业务模块，提供系统管理、基础设施、设备管理、运营、任务与OTA、规则引擎等业务能力。

项目结构

后端采用模块化设计，核心模块包括网关服务与多个业务模块（系统、基础设施、设备、运营、黑名单、任务、规则引擎等）。
前端提供多套模板（含 Vue3 vben 模板），并通过代码生成器一键生成前端页面与接口代码，降低重复开发成本。
项目内置统一异常处理、日志体系、监控与可观测性、消息队列集成、灰度发布机制等工程能力。

Mermaid Diagram Code:

graph TB
subgraph "前端(Vue3 + Vben Admin)"
FE_Admin["管理后台(Vue3 vben)"]
end
subgraph "后端(Spring Cloud Alibaba)"
Gateway["yudao-gateway 网关"]
System["yudao-module-system 系统模块"]
Infra["yudao-module-infra 基础设施模块"]
Device["yudao-module-device 设备模块"]
Launcher["yudao-module-launcher 运营模块"]
Blacklist["yudao-module-blacklist 黑名单模块"]
Task["yudao-module-task 任务/OTA模块"]
Rule["yudao-module-rule 规则引擎模块"]
end
subgraph "中间件"
Nacos["Nacos 注册/配置中心"]
Redis["Redis 缓存"]
MySQL["MySQL 业务库"]
TDengine["TDengine 时序库"]
Kafka["Kafka 消息队列"]
end
FE_Admin --> Gateway
Gateway --> System
Gateway --> Infra
Gateway --> Device
Gateway --> Launcher
Gateway --> Blacklist
Gateway --> Task
Gateway --> Rule
System -.-> Nacos
Device -.-> TDengine
Task -.-> TDengine
Blacklist -.-> Kafka
Gateway -.-> Redis

图示来源

章节来源

核心组件

网关与灰度发布：基于 Spring Cloud Gateway 的路由与灰度机制，支持按版本头进行流量分流。
统一异常处理：全局异常捕获与友好提示，避免未开启模块导致的不可用问题。
日志与监控：操作日志与 API 访问日志双轨记录；Prometheus 与 SkyWalking 集成。
消息队列：Kafka 用于日志上报与业务解耦。
数据存储：MySQL + TDengine 混合存储，满足 OLTP 与 OLAP 场景。
代码生成：内置代码生成器，支持 Vue3 vben 模板，一键生成前端页面与接口。

章节来源

架构总览

系统采用微服务架构，前端通过网关统一接入后端服务。核心服务包括网关、系统、基础设施、设备、运营、黑名单、任务与OTA、规则引擎等模块。中间件层提供注册与配置中心、缓存、业务数据库与时序数据库、消息队列等支撑能力。

Mermaid Diagram Code:

sequenceDiagram
participant Dev as 开发者
participant Maven as Maven构建工具
participant Gateway as yudao-gateway
participant Modules as 业务模块(System/Infra等)
participant Console as 控制台日志
Dev->>Maven : mvn clean install -Dmaven.test.skip=true
Maven-->>Dev : 构建完成
par 启动网关
Dev->>Gateway : java -jar yudao-gateway.jar
Gateway->>Console : 打印启动 Banner
Gateway->>Console : 输出文档地址 (接口/开发/视频)
and 启动业务模块
Dev->>Modules : IDE中运行 Application 类
Modules->>Console : 打印模块特定日志
end

图示来源

章节来源

README.md

详细组件分析

网关与灰度发布

灰度负载均衡：根据请求头中的版本号筛选匹配实例，若无匹配或缺失版本头则回退至全量实例。
灰度过滤器：在特定 URL Scheme 下触发灰度逻辑，基于权重随机选择实例。

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 : 获取所有可用服务实例列表 (含 metadata)
LB->>LB : 筛选 metadata[version] == 1.0.1 的实例
alt 存在匹配版本的实例
LB->>LB : 基于权重随机选择一个实例
else 无匹配或无版本头
LB->>LB : 在所有实例中基于权重选择
end
LB-->>Filter : 返回目标 ServiceInstance
Filter->>Instance : 转发请求
Instance-->>Client : 返回响应

图示来源

章节来源

日志与监控体系

操作日志：记录用户关键业务操作，便于审计与追踪。
API 访问日志：记录 HTTP 请求详情，支持链路追踪编号关联。
监控集成：Prometheus 服务发现与 SkyWalking Agent 注入，实现全链路观测。

Mermaid Diagram Code:

classDiagram
class OperateLogDO {
+Long id
+String traceId
+Long userId
+Integer userType
+String type
+String subType
+Long bizId
+String action
+String extra
}
class ApiAccessLogDO {
+Long id
+String traceId
+Long userId
+Integer userType
+String applicationName
+String requestMethod
+String requestUrl
+String requestParams
+String responseBody
+LocalDateTime beginTime
+Integer duration
+Integer resultCode
}

图示来源

章节来源

规则引擎(LiteFlow)

规则实体：定义规则链名称、作用域、EL 表达式、业务类型、路由、命名空间、生效状态等。
缓存策略：Redis 缓存 + 分布式锁 + 数据库兜底，防止缓存穿透与击穿。
业务绑定：规则与业务维度（如 MAC、渠道、地区）绑定，变更需经审批流程。

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"]

图示来源

yudao-module-rule/src/main/java/cn/iocoder/yudao/module/rule/util/RuleRunUtil.java

章节来源

任务与OTA数据模型

OTA 升级详情：包含升级包元数据、是否系统应用、是否自动启动、安装路径、有效性与草稿数据等字段，体现审批流与业务数据的结合。

Mermaid Diagram Code:

classDiagram
class UotaDetailDO {
+Long id "编号"
+String name "名称"
+Long infraFileId "文件表ID"
+Integer company "公司"
+String packageName "包名"
+Integer versionCode "版本号"
+String versionName "版本名称"
+String developer "开发者"
+String describeInfo "描述"
+Boolean isAutoStart "App是否自动启动"
+Boolean isSystemApp "是否系统App"
+String installPath "安装路径"
+Boolean valid "是否有效(0是1否)"
+String draft "草稿数据"
}
note for UotaDetailDO "表名 : task_uota_detail"

图示来源

yudao-module-task/src/main/java/cn/iocoder/yudao/module/task/dal/dataobject/uotadetail/UotaDetailDO.java

章节来源

yudao-module-task/src/main/java/cn/iocoder/yudao/module/task/dal/dataobject/uotadetail/UotaDetailDO.java

前端模板与代码生成

前端模板：项目内置 Vue3 vben 模板，通过代码生成器一键生成前端页面与接口代码。
生成文件类型：包含管理后台接口、业务逻辑实现、数据访问层、数据库实体类、视图对象、前端列表页、菜单与数据表 SQL 等。

章节来源

依赖分析

模块依赖：系统通过网关统一路由，核心模块包括系统、基础设施、设备、运营、黑名单、任务与OTA、规则引擎等。
基础设施依赖：JDK 17+、MySQL 8.0+、Redis 5.0+、Nacos 2.x、TDengine、Kafka。
配置管理：Nacos 作为统一配置中心，支持命名空间与多环境配置加载。

Mermaid Diagram Code:

graph TD
Root["yudao-cloud 项目根目录"]
Gateway["yudao-gateway<br/>网关服务"]
subgraph CoreModules ["核心业务模块"]
System["yudao-module-system<br/>系统基础模块<br/>用户/角色/菜单/字典"]
Infra["yudao-module-infra<br/>基础设施模块<br/>代码生成/文件/配置/监控"]
BPM["yudao-module-bpm<br/>工作流模块<br/>审批中心"]
Report["yudao-module-report<br/>报表模块<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模块<br/>事件上报"]
Rule["yudao-module-rule<br/>规则引擎模块"]
end
Root --> Gateway
Root --> CoreModules
Root --> IoTModules

图示来源

README.md

章节来源

性能考虑

缓存策略：Redis 作为默认缓存实现，默认过期时间为 1 小时，配合规则引擎的缓存与分布式锁策略，降低数据库压力。
数据库与时序库：MySQL 用于核心业务数据，TDengine 用于海量日志与监控数据，实现 OLTP 与 OLAP 的分离。
消息队列：Kafka 用于日志上报缓冲与业务异步解耦，减少请求延迟与峰值冲击。
监控与可观测性：Prometheus 服务发现与 SkyWalking Agent 注入，便于全链路性能分析与问题定位。

章节来源

故障排查指南

未开启模块异常：当访问未开启或未导入表结构的模块时，全局异常处理器会返回特定错误提示，引导开发者参考文档进行开启。
端口冲突：各模块默认端口不同，启动前需确认端口占用情况，避免启动失败。
配置中心：确认 Nacos 命名空间与配置加载顺序正确，确保应用级配置生效。

章节来源

结论

本项目以 Spring Cloud Alibaba 为基础，结合网关、注册中心、配置中心、缓存、数据库与时序库等中间件，构建了完整的微服务生态。管理后台通过统一网关接入后端模块，提供系统管理、基础设施、设备管理、运营、任务与OTA、规则引擎等核心能力。项目内置统一异常处理、日志体系、监控与可观测性、消息队列集成、灰度发布机制与代码生成器，具备良好的工程化与扩展性。

附录

快速开始：准备 JDK 17+、MySQL 8.0+、Redis 5.0+、Nacos 2.x、TDengine、Kafka，执行构建与启动流程。
端口概览：系统模块、黑名单模块、运营模块、设备模块等默认端口可在对应模块的配置文件中查看。
文档资源：项目在 doc_code/docs 目录下提供详尽的文档，涵盖系统设计、对接文档、数据分析、黑名单机制、设备接入等。

章节来源

目录​

简介​

项目结构​

核心组件​

架构总览​

详细组件分析​

网关与灰度发布​

日志与监控体系​

规则引擎(LiteFlow)​

任务与OTA数据模型​

前端模板与代码生成​

依赖分析​

性能考虑​

故障排查指南​

结论​

附录​

目录

简介

项目结构

核心组件

架构总览

详细组件分析

网关与灰度发布

日志与监控体系

规则引擎(LiteFlow)

任务与OTA数据模型

前端模板与代码生成

依赖分析

性能考虑

故障排查指南

结论

附录