快速开始

引用文件

本文引用的文件

简介

本指南面向新加入的开发者，帮助你在最短时间内完成 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/>规则引擎模块"]

章节来源

pom.xml

核心组件

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

章节来源

README.md

架构总览

系统采用“网关 + 多业务模块 + 中间件”的微服务架构，流量经网关进入，业务模块通过 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

图表来源

章节来源

README.md

详细组件分析

环境准备与安装

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

章节来源

README.md

Maven 构建命令

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

章节来源

README.md

网关服务启动

本地开发：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

章节来源

README.md

配置中心与数据源

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 正常运行，避免日志上报失败

章节来源

README.md

依赖分析

模块依赖：根 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

图表来源

章节来源

pom.xml

性能考虑

启动优化：使用 -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 : 模块启动日志

图表来源

目录​

简介​

项目结构​

核心组件​

架构总览​

详细组件分析​

环境准备与安装​

Maven 构建命令​

网关服务启动​

业务模块启动​

默认端口一览​

配置中心与数据源​

Docker 部署方式​

本地开发环境最佳实践​

依赖分析​

性能考虑​

故障排查指南​

结论​

附录​

启动流程时序图（本地开发）​

目录

简介

项目结构

核心组件

架构总览

详细组件分析

环境准备与安装

Maven 构建命令

网关服务启动

业务模块启动

默认端口一览

配置中心与数据源

Docker 部署方式

本地开发环境最佳实践

依赖分析

性能考虑

故障排查指南

结论

附录

启动流程时序图（本地开发）