- 项目介绍
- 项目结构
- 核心组件
- 架构概览
- 详细组件分析
- 依赖分析
- 性能考虑
- 故障排除指南
- 结论
项目介绍
yudao-cloud 是一个基于 Spring Boot 的现代化微服务/单体架构开发框架。它集成了网关、系统基础模块、基础设施模块以及多个垂直业务模块（如工作流、报表、设备管理、任务管理等）。该项目旨在提供一套完整的后端解决方案，涵盖了从代码生成、文档管理到具体业务逻辑实现的各个方面。
项目采用模块化设计，核心组件包括网关（yudao-gateway）和各个业务模块（yudao-module-*）。系统内置了对多种中间件（Redis, MySQL, Kafka, TDengine）的支持，并提供了详细的开发文档和接口文档集成。
项目结构
核心模块组织
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
图表来源
模块依赖关系
项目采用 Maven 多模块架构，根 pom.xml 定义了所有子模块：
- yudao-dependencies: 依赖管理模块
- yudao-gateway: 网关服务模块
- yudao-framework: 框架基础模块
- 业务模块: system, infra, bpm, report, blacklist, launcher, device, task, rule
章节来源
核心组件
网关服务配置
网关服务是整个微服务架构的统一入口，负责路由转发、鉴权和灰度发布。
网关配置文件结构
Mermaid Diagram Code:
flowchart TD
Start[网关启动] --> LoadConfig[加载配置文件]
LoadConfig --> ImportCommon[导入公共配置<br/>application-common.yaml]
ImportCommon --> ImportDatasource[导入数据源配置<br/>datasource.yaml]
ImportDatasource --> ImportLocal[导入本地配置<br/>application-${profile}.yaml]
ImportLocal --> ImportNacos[导入Nacos配置]
ImportNacos --> InitServices[初始化服务]
InitServices --> RegisterCenter[注册到Nacos]
RegisterCenter --> Ready[服务就绪]图表来源
网关核心配置
| 配置项 | 值 | 说明 |
|---|
| 应用名称 | gateway-server | 网关服务标识 |
| 激活配置 | dev | 开发环境配置 |
| 端口 | 48080 | 网关监听端口 |
| Arthas端口 | 48308/48309 | 远程诊断端口 |
章节来源
数据库配置
项目支持多种数据库配置方式，包括本地配置和 Nacos 配置中心。
开发环境数据库配置
Mermaid Diagram Code:
graph LR
subgraph LocalConfig[本地配置]
LocalDS[本地数据源配置]
LocalRedis[本地Redis配置]
LocalMQ[Kafka配置]
end
subgraph NacosConfig[Nacos配置中心]
NacosDS[Nacos数据源配置]
NacosRedis[Nacos Redis配置]
NacosMQ[Nacos Kafka配置]
end
subgraph Production[生产环境]
ProdDS[生产数据源配置]
ProdRedis[生产Redis配置]
ProdMQ[生产Kafka配置]
end
LocalConfig --> NacosConfig
NacosConfig --> Production
图表来源
多数据源配置
项目支持多数据源配置，包括系统、基础设施、工作流、报表等模块的数据源。
章节来源
架构概览
微服务架构设计
Mermaid Diagram Code:
graph TD
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
图表来源
灰度发布机制
系统网关基于 Spring Cloud Gateway 实现了灰度发布机制，允许基于请求头中的版本号将流量路由到特定版本的服务实例。
灰度负载均衡实现
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 : 返回响应
图 表来源
章节来源
详细组件分析
系统模块配置
系统模块是项目的核心基础模块，提供用户、角色、菜单、字典等基础功能。
系统模块端口配置
| 模块 | 配置文件路径 | 默认端口 |
|---|
| System (系统模块) | yudao-module-system-biz/.../application.yaml | 48081 |
| BPM (工作流) | yudao-module-bpm-biz/.../application.yaml | 48083 |
| Device (设备管理) | yudao-module-device-biz/.../application.yaml | 48091 |
| Blacklist (黑名单) | yudao-module-blacklist-biz/.../application.yaml | 48096 |
| Launcher (运营) | yudao-module-launcher-biz/.../application.yaml | 48097 |
章节来源
基础设施模块配置
基础设施模块承担了运维管理和研发工具两大核心职责。
基础设施模块特性
- 运维管理: 支撑上层业务的通用能力，如定时任务管理、服务器信息监控
- 研发工具: 提升研发效率，包括代码生成器、接口文档管理
命名规范:
- Controller URL: 以
/infra/ 开头
- 数据库表名: 以
infra_ 开头
章节来源
规则引擎模块
规则引擎模块基于 LiteFlow 框架实现，支持规则的定义、编排、缓存以及与具体业务的绑定。
规则引擎核心组件
Mermaid Diagram Code:
classDiagram
class RuleLiteflowChainDO {
+Long id
+String applicationName
+String name
+String chainName
+Integer scope
+String elData
+Integer businessType
+String route
+Integer enable
+Integer valid
}
class RuleLiteflowChainCacheDTO {
+Long id
+String chainName
+String elData
+String jsonData
+Long ttl
}
class DeviceTrueCmp {
+execute() boolean
}
class DeviceFalseCmp {
+execute() throws RuntimeException
}
RuleLiteflowChainDO --> RuleLiteflowChainCacheDTO : "缓存转换"
DeviceTrueCmp --> RuleLiteflowChainDO : "规则执行"
DeviceFalseCmp --> RuleLiteflowChainDO : "规则执行"图表来源
章节来源
依赖分析
技术栈与框架概览
项目采用现代化技术栈，集成了众多主流技术组件。
核心技术组件
| 组件 | 版本要求 | 用途 |
|---|
| JDK | 17+ | 开发语言基础环境 |
| MySQL | 8.0+ | 关系型数据库存储 |
| Redis | 5.0+ | 缓存与消息中间件 |
| Nacos | 2.x | 注册中心与配置中心 |
| TDengine | 必须安装 | 时序数据库，用于日志存储 |
| Kafka | 必须安装 | 消息队列，用于日志上报缓冲 |
章节来源
Maven 依赖管理
项目使用 Maven 进行依赖管理，统一版本控制和插件配置。
核心依赖配置
Mermaid Diagram Code:
graph TD
subgraph MavenConfig[Maven配置]
Properties[项目属性<br/>Java 17, Spring Boot 3.4.1]
Profiles[环境配置<br/>dev/prod profile]
Repositories[Maven仓库<br/>华为云/阿里云镜像]
end
subgraph Dependencies[核心依赖]
SpringBoot[Spring Boot Starter]
Lombok[Lombok注解]
MapStruct[MapStruct映射]
P6Spy[P6Spy监控]
end
Properties --> Dependencies
Profiles --> Dependencies
Repositories --> Dependencies
图表来源
章节来源
性能考虑
缓存策略
项目采用多级缓存策略，包括 Redis 缓存、分布式锁和数据库兜底。
缓存获取流程
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]图表来源
监控与可观测性
系统集成了 SkyWalking 和 Prometheus 进行全链路监控。
监控组件集成
- SkyWalking: 在 docker-compose.yml 中，各个服务通过 JAVA_TOOL_OPTIONS 注入了 SkyWalking Agent
- Prometheus: yudao-infra 模块提供了 PrometheusController，通过 /actuator/prometheus/sd 接口暴露服务发现信息
章节来源
故障排除指南
常见初始化问题及解决方案
1. 端口占用问题
问题现象: 启动服务时报端口被占用错误
解决方案:
- 修改 application.yaml 中的 server.port 配置
- 检查系统中是否有其他进程占用相同端口
- 使用 netstat 命令查看端口占用情况
2. 依赖冲突问题
问题现象: Maven 构建时报依赖冲突或版本不兼容
解决方案:
- 清理 Maven 本地仓库中的冲突依赖
- 更新项目依赖版本到兼容版本
- 检查 pom.xml 中的 dependencyManagement 配置
3. 配置错误问题
问题现象: 服务启动后出现配置加载失败或连接异常
解决方案:
- 检查 application.yaml 配置文件语法
- 验证 Nacos 配置中心连接信息
- 确认数据库连接字符串和凭据正确性
4. 数据库初始化问题
问题现象: 服务启动时报数据库表结构缺失
解决方案:
- 执行 sql/mysql/ik_yudao_base.sql 初始化基础表结构
- 检查数据库连接配置和权限
- 验证表结构导入是否完整
章节来源
环境准备清单
启动项目之前必须确保以下基础环境已经安装并配置完毕：
- JDK: 17+
- MySQL: 8.0+
- Redis: 5.0+
- Nacos: 2.x (注册中心与配置中心)
- TDengine: 必须安装 (用于日志存储)
- Kafka: 必须安装 (用于日志上报缓冲)
章节来源
yudao-cloud 项目提供了一套完整的微服务开发框架，具有以下特点：
- 模块化设计: 采用 Maven 多模块架构，清晰的模块职责划分
- 技术先进: 集成 Spring Boot 3.4.1、Spring Cloud Alibaba 等最新技术栈
- 功能完善: 涵盖从基础服务到业务模块的完整功能体系
- 配置灵活: 支持本地配置和 Nacos 配置中心，便于环境切换
- 监控完备: 集成 SkyWalking 和 Prometheus，提供全链路监控能力
通过遵循本文档的初始化配置指南，开发者可以快速搭建和启动项目，为后续的业务开发奠定坚实基础。