跳到主要内容

快速开始

引用文件

本文引用的文件

目录​

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

简介​

本指南面向首次接触 yudao-cloud 的开发者，帮助你在本地快速完成环境准备、编译打包、服务启动与验证，涵盖网关与核心业务模块的启动流程、端口配置与占用注意事项、Docker 部署方案与最佳实践，以及常见问题排查思路。

项目结构​

yudao-cloud 采用多模块 Maven 工程，顶层 POM 定义了 JDK 17+、Spring Boot 3.4.1、统一依赖管理与开发/生产 Profile。核心模块包括网关与多个业务模块（系统、基础设施、工作流、设备、运营、黑名单、任务、规则等）。

Mermaid Diagram Code:

graph TB
Root["yudao-cloud 顶层 POM<br/>JDK 17+, Spring Boot 3.4.1"]
GW["yudao-gateway<br/>网关服务"]
SYS["yudao-module-system<br/>系统模块"]
INFRA["yudao-module-infra<br/>基础设施模块"]
BPM["yudao-module-bpm<br/>工作流模块"]
DEV["yudao-module-device<br/>设备模块"]
LAUNCH["yudao-module-launcher<br/>运营模块"]
BLACK["yudao-module-blacklist<br/>黑名单模块"]
TASK["yudao-module-task<br/>任务/OTA 模块"]
RULE["yudao-module-rule<br/>规则引擎模块"]
Root --> GW
Root --> SYS
Root --> INFRA
Root --> BPM
Root --> DEV
Root --> LAUNCH
Root --> BLACK
Root --> TASK
Root --> RULE

图表来源

章节来源

核心组件​

  • 网关服务：统一入口、路由、鉴权与灰度发布。
  • 系统模块：用户/角色/菜单/字典等基础能力。
  • 基础设施模块：代码生成、监控、配置与定时任务。
  • 工作流模块：Flowable 审批流程。
  • 设备模块：设备全生命周期管理与心跳监控。
  • 运营模块：Launcher 广告位与策略资源管理。
  • 黑名单模块：应用卸载管控与拦截。
  • 任务/OTA 模块：事件上报、OTA 升级管理。
  • 规则引擎模块：基于 LiteFlow 的动态规则链。

章节来源

架构总览​

系统采用 Spring Cloud Alibaba 微服务架构，Nacos 作为注册与配置中心，网关统一接入，业务模块按域拆分。时序/日志数据通过 TDengine 存储，Kafka 用于日志上报缓冲，Redis 提供缓存与部分消息能力。

Mermaid Diagram Code:

graph TB
User["Web/App 用户"] --> GW["yudao-gateway 网关"]
Device["智能终端设备"] --> GW
subgraph "微服务集群"
GW --> SYS["yudao-system"]
GW --> INFRA["yudao-infra"]
GW --> DEV["yudao-device"]
GW --> LAUNCH["yudao-launcher"]
GW --> BLACK["yudao-blacklist"]
GW --> TASK["yudao-task"]
GW --> RULE["yudao-rule"]
end
subgraph "中间件与存储"
Nacos["Nacos 注册/配置中心"]
Redis["Redis 缓存"]
MySQL["MySQL 业务库"]
TDengine["TDengine 时序库"]
Kafka["Kafka 消息队列"]
end
SYS -.-> Nacos
DEV -.-> TDengine
TASK -.-> TDengine
BLACK -.-> Kafka
GW -.-> Redis

图表来源

章节来源

详细组件分析​

环境准备与安装​

  • JDK：17+
  • MySQL：8.0+
  • Redis：5.0+
  • Nacos：2.x（注册中心与配置中心）
  • TDengine：必须安装（用于日志与时序数据存储）
  • Kafka：必须安装（用于日志上报缓冲）

以上要求来自项目文档与模块配置，确保中间件版本满足系统依赖。

章节来源

Maven 编译与打包​

  • 使用 Maven 清理并安装，跳过测试以加速构建。
  • 构建产物包含各模块的 Jar 包与网关可执行包，便于后续启动。

章节来源

网关启动​

  • 网关注默认端口为 48080，配置了 Arthas 端口（HTTP 48308、Telnet 48309）。
  • 启动方式：直接运行 Jar 或在 IDE 中运行 Application 类。
  • 配置加载顺序：公共配置 → 数据源配置 → 本地 profile → Nacos 应用级配置。

章节来源

业务模块启动​

  • 系统模块：默认端口 48081
  • 工作流模块：默认端口 48083
  • 设备模块：默认端口 48091
  • 黑名单模块：默认端口 48096
  • 运营模块：默认端口 48097

启动方式：在 IDE 中运行各模块 Application 类，或使用打包后的 Jar 启动。

章节来源

端口配置与占用注意事项​

  • 网关：48080
  • 系统：48081
  • 工作流：48083
  • 设备：48091
  • 黑名单：48096
  • 运营：48097

开发时请确保上述端口未被占用，或在各自模块的 application.yaml 中调整 server.port。

章节来源

Docker 部署方案​

  • 本地开发/测试可使用 Docker Compose 启动网关与核心业务模块，容器以 host 网络模式运行，便于与宿主机中间件交互。
  • Kafka 提供独立的 Compose 文件，包含 broker 与 UI（Kafdrop）。
  • SkyWalking Agent 通过环境变量注入，日志挂载至宿主机目录。

Mermaid Diagram Code:

graph TB
subgraph "Docker Compose 服务"
GW["yudao-gateway"]
SYS["yudao-system"]
INFRA["yudao-infra"]
REPORT["yudao-report"]
BPM["yudao-bpm"]
PAY["yudao-pay"]
MP["yudao-mp"]
end
subgraph "中间件"
Nacos["Nacos"]
Redis["Redis"]
MySQL["MySQL"]
TDengine["TDengine"]
Kafka["Kafka"]
end
GW --> Nacos
SYS --> Nacos
INFRA --> Nacos
REPORT --> Nacos
BPM --> Nacos
PAY --> Nacos
MP --> Nacos
GW --> Redis
SYS --> MySQL
INFRA --> MySQL
REPORT --> MySQL
BPM --> MySQL
PAY --> MySQL
MP --> MySQL
SYS --> TDengine
TASK --> TDengine
BLACK --> Kafka

图表来源

章节来源

本地开发环境最佳实践​

  • 使用 IDE 直接运行各模块 Application 类，便于调试与热更新。
  • 通过 Nacos 管理配置，建议在本地使用 dev profile，命名空间 dev_v2。
  • 数据源配置集中在 datasource.yaml，确保连接串、账号密码正确。
  • 启动顺序建议：先启动网关，再启动业务模块；Kafka/Redis/MySQL/Redis/TDengine 等中间件按需启动。

章节来源

依赖分析​

  • 构建与运行环境：JDK 17+、Maven、Nacos、MySQL、Redis、Kafka、TDengine。
  • 模块间依赖：网关统一路由，业务模块通过 Nacos 注册与发现。
  • 配置加载：优先级为公共配置 → 数据源配置 → 本地 profile → Nacos 应用级配置。

Mermaid Diagram Code:

graph LR
POM["顶层 POM<br/>JDK 17+, Spring Boot 3.4.1"]
GW["yudao-gateway"]
SYS["yudao-module-system"]
INFRA["yudao-module-infra"]
BPM["yudao-module-bpm"]
DEV["yudao-module-device"]
LAUNCH["yudao-module-launcher"]
BLACK["yudao-module-blacklist"]
TASK["yudao-module-task"]
RULE["yudao-module-rule"]
POM --> GW
POM --> SYS
POM --> INFRA
POM --> BPM
POM --> DEV
POM --> LAUNCH
POM --> BLACK
POM --> TASK
POM --> RULE

图表来源

章节来源

性能考虑​

  • 缓存：各模块默认使用 Redis 作为缓存，建议合理设置过期时间与容量。
  • 日志：接口文档与日志路径在各模块中均有配置，建议统一日志目录与轮转策略。
  • 监控：可结合 SkyWalking 与 Prometheus 进行全链路监控与指标采集。

章节来源

故障排查指南​

  • 启动失败（端口占用）：检查本地端口 48080/48081/48083/48091/48096/48097 是否被占用，必要时在 application.yaml 中修改 server.port。
  • 中间件连接失败：确认 Nacos、MySQL、Redis、Kafka、TDengine 的地址与凭据正确，参考 datasource.yaml 与各模块 application.yaml。
  • 配置未生效：确认 Nacos 命名空间与分组配置一致，且加载顺序正确（公共 → 数据源 → 本地 → 应用级）。
  • Kafka 相关问题：检查 Kafka 服务连通性与主题是否存在，必要时使用 Kafdrop 查看与管理。
  • 灰度发布/路由异常：核对网关灰度过滤器与负载均衡逻辑，确保请求头版本信息正确。

章节来源

结论​

通过本指南，你可以在本地快速完成 yudao-cloud 的环境准备、编译与启动，并掌握各模块默认端口、Docker 部署方案与常见问题排查方法。建议在开发过程中结合 Nacos 配置中心与中间件监控，持续优化系统稳定性与性能。

附录​

  • 启动命令示例（概念性说明，非代码片段）
    • Maven 构建：mvn clean install -Dmaven.test.skip=true
    • 网关启动：java -jar yudao-gateway.jar
    • 业务模块启动：在 IDE 中运行各模块 Application 类
  • 端口一览（默认）
    • 网关：48080
    • 系统：48081
    • 工作流：48083
    • 设备：48091
    • 黑名单：48096
    • 运营：48097
用户文档
AI 助手
Agent 列表
请选择一个 Agent 开始对话
AI 问答