跳到主要内容

系统架构设计

引用文件

本文引用的文件

目录​

  1. 引言
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 组件详解
  6. 依赖关系分析
  7. 性能考量
  8. 故障排查指南
  9. 结论
  10. 附录

引言​

本文件面向 yudao-cloud 的系统架构设计，聚焦于基于 Spring Cloud Alibaba 的微服务架构，覆盖服务治理、负载均衡、熔断限流、网关灰度发布、路由转发与安全认证等主题。文档同时阐述微服务间通信、数据一致性与分布式事务的挑战与实践建议，并提供架构拓扑图与组件交互时序图，帮助读者快速理解系统设计思路与落地要点。

项目结构​

yudao-cloud 采用多模块聚合工程，顶层 POM 定义了版本与依赖管理，核心模块包括网关服务与多个业务模块。项目通过 Nacos 进行注册与配置中心，结合 Spring Cloud Gateway 提供统一入口与动态路由能力。

Mermaid Diagram Code:

graph TB
Root["yudao-cloud 根 POM<br/>定义版本与模块聚合"] --> Deps["yudao-dependencies<br/>统一依赖管理"]
Root --> GW["yudao-gateway<br/>Spring Cloud Gateway 网关"]
Root --> Sys["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 --> Task["yudao-module-task<br/>任务与OTA模块"]
Root --> Rule["yudao-module-rule<br/>规则引擎模块"]
Root --> Blacklist["yudao-module-blacklist<br/>黑名单模块"]

图表来源

章节来源

核心组件​

  • 网关服务（yudao-gateway）：基于 Spring Cloud Gateway，提供统一入口、动态路由、跨域、灰度负载均衡、访问日志、安全认证（Token 校验）等能力。
  • 业务模块：系统、基础设施、工作流、报表、设备管理、运营、任务与OTA、规则引擎、黑名单等模块，通过 Nacos 注册与配置中心协同工作。
  • 中间件：Nacos（注册与配置）、Redis（缓存）、MySQL（业务库）、TDengine（时序/日志）、Kafka（消息队列）。

章节来源

架构总览​

整体采用“网关 + 微服务 + 中间件”的架构，网关负责路由、鉴权与灰度发布，后端服务按业务域拆分，中间件支撑注册与配置、缓存、消息与时序数据存储。

Mermaid Diagram Code:

graph TB
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

图表来源

章节来源

组件详解​

网关服务（yudao-gateway）设计理念与实现​

  • 统一入口与动态路由：通过 Nacos 配置中心监听路由变化，实现动态路由刷新。
  • 安全认证：TokenAuthenticationFilter 从请求头提取令牌，调用系统模块的 OAuth2 校验接口，校验通过后将用户信息注入请求头，转发给下游服务。
  • 灰度发布：GrayReactiveLoadBalancerClientFilter 与 GrayLoadBalancer 结合，基于请求头 version 与 tag 进行实例筛选，再按权重随机选择，实现灰度流量控制。
  • 访问日志：AccessLogFilter 统一采集请求与响应上下文，便于审计与问题定位。
  • 跨域处理：CorsResponseHeaderFilter 修复 Spring Cloud Gateway 2.x 跨域重复 Origin 的问题。

Mermaid Diagram Code:

sequenceDiagram
participant Client as 客户端
participant GW as 网关
participant Auth as TokenAuthenticationFilter
participant Sys as 系统模块(OAuth2)
participant LB as GrayReactiveLoadBalancerClientFilter
participant GLB as GrayLoadBalancer
participant Svc as 业务服务实例
Client->>GW : 发起请求(携带 Authorization/可选 version/tag)
GW->>Auth : 过滤器链进入
Auth->>Sys : 校验令牌(OAuth2TokenApi.check)
Sys-->>Auth : 返回校验结果
Auth-->>GW : 注入登录用户信息(若有效)
GW->>LB : 灰度负载均衡过滤器
LB->>GLB : 选择实例(基于 version/tag)
GLB-->>LB : 返回目标实例
LB-->>GW : 重写请求URL并转发
GW->>Svc : 转发请求
Svc-->>GW : 返回响应
GW-->>Client : 返回响应

图表来源

章节来源

灰度发布机制​

  • 策略：基于请求头 version 与 tag，优先匹配相同版本/标签的实例；若无匹配则回退至全部实例，仍按权重随机选择。
  • 实现：GrayReactiveLoadBalancerClientFilter 重写选择逻辑，GrayLoadBalancer 从 Nacos 元数据中筛选实例并使用 Nacos 权重选择。

Mermaid Diagram Code:

flowchart TD
Start(["请求进入"]) --> CheckScheme["检查URL Scheme是否为 grayLb"]
CheckScheme --> |否| PassThrough["直接放行"]
CheckScheme --> |是| GetInstances["获取服务实例列表"]
GetInstances --> HasVersion{"是否存在version头?"}
HasVersion --> |否| UseAll["使用全部实例"]
HasVersion --> |是| FilterByVersion["按metadata.version筛选"]
FilterByVersion --> Found{"是否有匹配实例?"}
Found --> |否| UseAll
Found --> |是| UseFiltered["使用筛选后的实例"]
UseAll --> FilterByTag["按tag进一步过滤(可选)"]
UseFiltered --> FilterByTag
FilterByTag --> WeightSelect["基于权重随机选择实例"]
WeightSelect --> End(["返回实例"])
PassThrough --> End

图表来源

章节来源

路由转发策略与动态路由​

  • 动态路由：基于 Nacos 配置中心，监听 gateway-server.yaml 的 spring.cloud.gateway.routes 变化，触发网关路由刷新。
  • 路由配置：通过 application.yaml 导入 Nacos 配置，结合本地 profile 与应用级配置，实现灵活的路由与开关控制。

章节来源

安全认证与租户隔离​

  • Token 校验：TokenAuthenticationFilter 从请求头提取 Authorization，调用系统模块 OAuth2 校验接口，解析用户信息并注入请求头。
  • 租户隔离：通过 Header 传递 tenant-id，实现多租户场景下的资源隔离与缓存键区分。
  • 缓存策略：本地缓存 LoginUser，降低频繁校验开销，过期后异步刷新。

章节来源

访问日志与可观测性​

  • 访问日志：AccessLogFilter 统一采集请求方法、URL、参数、头、Body、用户IP、路由等信息，便于审计与问题定位。
  • 监控集成：PrometheusController 暴露服务发现 Target 列表，配合 Prometheus 抓取指标；Docker 编排中为服务注入 SkyWalking Agent，实现全链路追踪。

章节来源

微服务间通信与数据一致性​

  • 通信方式：基于 Nacos 注册中心的服务发现与负载均衡，网关侧通过 GrayReactiveLoadBalancerClientFilter 实现灰度负载均衡；服务间通过 HTTP（WebClient）或消息队列（Kafka）交互。
  • 数据一致性：系统采用多数据源与混合存储（MySQL + TDengine），通过规则引擎与业务流程（BPM）实现强约束与审批闭环；对于跨服务一致性，建议结合 Saga 或 TCC 模式在业务层实现补偿与幂等。

章节来源

分布式事务处理​

  • 建议采用 Saga 模式：将长事务拆分为多个本地事务，通过事件驱动与补偿机制保证最终一致性；结合 Kafka 实现可靠消息传递与幂等消费。
  • 幂等设计：在接口层引入幂等键与去重表，避免重复提交导致的数据不一致。

[本节为通用架构建议，无需特定文件引用]

依赖关系分析​

  • 网关依赖：Spring Cloud Gateway、Nacos 注册与配置、LoadBalancer、监控与工具类。
  • 动态路由：通过 Nacos 配置中心监听路由配置变化，触发网关刷新。
  • 灰度负载均衡：基于 Nacos 元数据与权重，实现按版本/标签的实例筛选与选择。

Mermaid Diagram Code:

graph LR
GW["yudao-gateway"] --> SCG["Spring Cloud Gateway"]
GW --> Nacos["Nacos Discovery/Config"]
GW --> LB["LoadBalancer"]
GW --> Monitor["监控组件"]
GW --> Utils["工具类(Guava等)"]
DynRoute["动态路由(package-info)"] --> Nacos
GrayLB["灰度负载均衡(Filter/LoadBalancer)"] --> Nacos

图表来源

章节来源

性能考量​

  • 灰度负载均衡：基于 Nacos 权重与随机选择，减少热点实例压力；建议为不同版本/标签配置合理权重。
  • 缓存策略：Token 校验结果本地缓存，降低系统模块压力；注意缓存过期与异步刷新。
  • 日志与监控：访问日志按需落盘或远程上报，避免阻塞；Prometheus 与 SkyWalking 配置合理的抓取间隔与采样率。
  • 存储分层：业务数据走 MySQL，海量日志与时序数据走 TDengine，降低 OLTP 压力。

[本节提供通用指导，无需特定文件引用]

故障排查指南​

  • 网关启动与端口：确认 application.yaml 中 server.port 与本地端口冲突；查看 BannerApplicationRunner 输出的文档地址。
  • 动态路由不生效：检查 Nacos 配置中心 gateway-server.yaml 的 routes 配置是否正确，以及命名空间与分组设置。
  • 灰度不生效：确认请求 URL Scheme 是否为 grayLb，请求头是否包含 version/tag；核对服务实例 metadata 中的 version 与标签。
  • 认证失败：检查 Authorization 头是否正确传递，系统模块 OAuth2 校验接口是否可达，租户头 tenant-id 是否设置。
  • 访问日志缺失：确认 AccessLogFilter 是否启用，日志输出路径与级别配置。

章节来源

结论​

yudao-cloud 基于 Spring Cloud Alibaba 构建了高内聚、低耦合的微服务体系，网关作为统一入口承担路由、鉴权与灰度发布职责，结合 Nacos、Redis、MySQL、TDengine、Kafka 等中间件，形成“网关 + 微服务 + 中间件”的稳定架构。通过动态路由与灰度负载均衡，系统具备良好的可演进性；通过规则引擎与 BPM 审批，保障业务规则与流程的可控性。建议在分布式事务与数据一致性方面采用 Saga/TCC 等模式，并持续完善监控与可观测性体系。

[本节为总结性内容，无需特定文件引用]

附录​

  • 配置管理：Nacos 命名空间与分组、配置加载顺序与应用级配置。
  • 消息队列：Kafka 生产者示例（黑名单模块回调事件）。
  • 数据源常量：各模块针对 TDengine 的数据源命名与用途。

章节来源

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