跳到主要内容

快速开始

目录

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

简介

本指南面向新加入的开发者,帮助你在最短时间内完成 yudao-cloud 项目的本地环境准备、依赖安装、启动流程与常见问题排查。项目基于 Spring Boot 3.x + Spring Cloud Alibaba,采用 Nacos 注册与配置中心、MySQL、Redis、Kafka、TDengine 等中间件,提供网关统一入口与多业务模块协同。

项目结构

  • 顶层使用 Maven 多模块聚合,包含网关模块与多个业务模块(系统、基础设施、工作流、报表、设备、运营、黑名单、任务、规则等)。
  • 模块间通过 Nacos 进行服务注册与配置下发,网关统一对外暴露 48080 端口,各业务模块在本地开发时使用独立端口。

Mermaid Diagram Code:

graph TB
Root["yudao-cloud 根 POM<br/>Java 17+, Spring Boot 3.x"] --> Gateway["yudao-gateway<br/>网关服务"]
Root --> System["yudao-module-system<br/>系统模块"]
Root --> Infra["yudao-module-infra<br/>基础设施模块"]
Root --> BPM["yudao-module-bpm<br/>工作流模块"]
Root --> Report["yudao-module-report<br/>报表模块"]
Root --> Device["yudao-module-device<br/>设备模块"]
Root --> Launcher["yudao-module-launcher<br/>运营模块"]
Root --> Blacklist["yudao-module-blacklist<br/>黑名单模块"]
Root --> Task["yudao-module-task<br/>任务/OTA 模块"]
Root --> Rule["yudao-module-rule<br/>规则引擎模块"]

章节来源

核心组件

  • 网关服务:统一入口,负责路由、鉴权与灰度发布。
  • 业务模块:系统、基础设施、工作流、报表、设备、运营、黑名单、任务、规则等。
  • 中间件:Nacos(注册与配置)、MySQL(业务数据)、Redis(缓存)、Kafka(消息队列)、TDengine(时序日志)。

章节来源

架构总览

系统采用“网关 + 多业务模块 + 中间件”的微服务架构,流量经网关进入,业务模块通过 Nacos 进行服务治理,数据层采用 MySQL + TDengine 的混合存储。

Mermaid Diagram Code:

graph TB
subgraph "客户端"
Web["浏览器/移动端"]
end
subgraph "服务层"
GW["yudao-gateway<br/>48080 端口"]
SYS["system-server<br/>48081"]
INF["infra-server<br/>48082"]
BPM["bpm-server<br/>48083"]
DEV["device-server<br/>48091"]
BLK["blacklist-server<br/>48096"]
LCH["launcher-server<br/>48097"]
end
subgraph "中间件"
Nacos["Nacos 2.x"]
MySQL["MySQL 8.0+"]
Redis["Redis 5.0+"]
Kafka["Kafka"]
TDengine["TDengine"]
end
Web --> GW
GW --> SYS
GW --> INF
GW --> BPM
GW --> DEV
GW --> BLK
GW --> LCH
SYS -.-> Nacos
INF -.-> Nacos
BPM -.-> Nacos
DEV -.-> Nacos
BLK -.-> Nacos
LCH -.-> Nacos
SYS -.-> MySQL
DEV -.-> TDengine
BLK -.-> Kafka
LCH -.-> Redis

图表来源

章节来源

详细组件分析

环境准备与安装

  • JDK:17+(Spring Boot 3.x 要求)
  • MySQL:8.0+(业务数据)
  • Redis:5.0+(缓存)
  • Nacos:2.x(注册中心与配置中心)
  • TDengine:必须安装(时序日志)
  • Kafka:必须安装(日志上报缓冲)

章节来源

Maven 构建命令

  • 推荐跳过测试构建,缩短时间:mvn clean install -Dmaven.test.skip=true
  • 构建产物位于各模块 target 目录,如 yudao-gateway/target 下生成 yudao-gateway.jar

章节来源

网关服务启动

  • 本地开发:IDE 运行 yudao-gateway 模块的启动类,或使用 java -jar yudao-gateway.jar
  • Docker 方式:使用 yudao-gateway/Dockerfile 构建镜像并运行,容器暴露 48080 端口
  • 网关默认端口:48080

章节来源

业务模块启动

  • System 模块:48081 端口
  • BPM 模块:48083 端口
  • Device 模块:48091 端口
  • Blacklist 模块:48096 端口
  • Launcher 模块:48097 端口

启动方式:

  • 本地开发:在 IDE 中运行各模块的启动类
  • Docker 方式:可参考部署脚本 docker-run.md 中的容器运行示例(需先构建镜像)

章节来源

默认端口一览

  • yudao-gateway:48080
  • yudao-system:48081
  • yudao-infra:48082
  • yudao-bpm:48083
  • yudao-report:48084
  • yudao-device:48091
  • yudao-task:48092
  • yudao-launcher:48097
  • yudao-blacklist:48096

章节来源

配置中心与数据源

  • Nacos:开发环境命名空间 dev_v2,配置加载顺序包含本地与 Nacos 应用级配置
  • 数据源:datasource.yaml 中配置了 system 数据源(MySQL),并启用了 Druid 监控

章节来源

Docker 部署方式

  • 单机编排:使用 script/docker/docker-compose.yml,服务通过 host 网络模式运行,便于本地调试
  • Kafka 独立编排:使用 deploy/docker/kafka/docker-compose.yml,提供 Kafdrop UI
  • 测试脚本:deploy/docker/test/docker-run.md 提供了各服务的容器运行示例(需先构建镜像)

章节来源

本地开发环境最佳实践

  • 端口规划:确保各模块端口不冲突(网关 48080,业务模块 48081~48097)
  • Nacos:确认 dev_v2 命名空间与分组配置正确
  • 数据源:先初始化数据库与表结构,再启动业务模块
  • 缓存:Redis 保持可用,避免缓存相关异常
  • 消息队列:Kafka 与 TDengine 正常运行,避免日志上报失败

章节来源

依赖分析

  • 模块依赖:根 POM 聚合了网关与各业务模块,模块间通过 Nacos 进行服务发现与配置同步
  • 中间件依赖:Nacos、MySQL、Redis、Kafka、TDengine

Mermaid Diagram Code:

graph LR
POM["根 POM<br/>Java 17+, Spring Boot 3.x"] --> Deps["yudao-dependencies"]
POM --> Gateway["yudao-gateway"]
POM --> System["yudao-module-system"]
POM --> Infra["yudao-module-infra"]
POM --> BPM["yudao-module-bpm"]
POM --> Report["yudao-module-report"]
POM --> Device["yudao-module-device"]
POM --> Launcher["yudao-module-launcher"]
POM --> Blacklist["yudao-module-blacklist"]
POM --> Task["yudao-module-task"]
POM --> Rule["yudao-module-rule"]
Gateway --> Nacos
System --> Nacos
Infra --> Nacos
BPM --> Nacos
Device --> Nacos
Blacklist --> Nacos
Launcher --> Nacos
Task --> Nacos
Rule --> Nacos

图表来源

章节来源

性能考虑

  • 启动优化:使用 -Dmaven.test.skip=true 跳过测试,缩短构建时间
  • 缓存命中:合理配置 Redis TTL,避免缓存穿透与击穿
  • 数据库连接池:Druid 连接池参数已配置,建议结合压测调整
  • 监控:SkyWalking Agent 注入与 Prometheus 集成,便于定位性能瓶颈

章节来源

故障排查指南

常见问题与排查思路:

  • 网关无法访问:检查 yudao-gateway 是否启动成功,端口 48080 是否被占用
  • 业务模块启动失败:检查 Nacos 连通性与命名空间 dev_v2 配置,确认数据源连接正常
  • Kafka/TDengine 异常:确认 Kafka 服务与主题创建,TDengine 连接与写入权限
  • 端口冲突:根据模块默认端口调整本地端口或停止占用进程
  • 配置加载异常:核对 application.yaml 中的 config.import 顺序与 Nacos 配置是否存在

章节来源

结论

按照本指南完成环境准备、中间件安装与模块启动,即可在本地快速运行 yudao-cloud。建议优先启动网关与系统模块,再逐步启动业务模块,并结合 Nacos 与中间件状态进行联调。

附录

启动流程时序图(本地开发)

Mermaid Diagram Code:

sequenceDiagram
participant Dev as 开发者
participant Maven as Maven
participant Gateway as yudao-gateway
participant Modules as 业务模块
participant Nacos as Nacos
participant DB as MySQL/Redis/Kafka/TDengine
Dev->>Maven : mvn clean install -Dmaven.test.skip=true
Maven-->>Dev : 生成各模块 jar
Dev->>Gateway : 启动网关(48080)
Gateway->>Nacos : 注册/拉取配置
Gateway->>DB : 连接 Redis/MySQL/Kafka/TDengine
Dev->>Modules : 启动业务模块(48081~48097)
Modules->>Nacos : 注册/拉取配置
Modules->>DB : 连接 MySQL/Redis/Kafka/TDengine
Gateway-->>Dev : 网关健康检查与日志
Modules-->>Dev : 模块启动日志

图表来源

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