跳到主要内容

版本更新日志

引用文件

本文引用的文件

目录​

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

简介​

本文件为 yudao-cloud 项目的版本更新日志与升级指南。当前仓库中未包含正式的版本历史记录文件，但通过项目 POM 配置、模块化结构与部署文档，可以梳理出版本号命名规则、发布周期、升级步骤、兼容性策略与安全补丁流程，并提供回滚与风险评估建议。

项目结构​

yudao-cloud 采用多模块 Maven 聚合工程，顶层 POM 管理版本与模块聚合；yudao-dependencies 作为 BOM 统一依赖版本；yudao-framework 提供通用技术组件；yudao-gateway 为网关服务；各 yudao-module-* 为业务模块。

Mermaid Diagram Code:

graph TB
Root["yudao-cloud 根 POM<br/>版本: ${revision}"] --> Deps["yudao-dependencies<br/>BOM 统一依赖"]
Root --> GW["yudao-gateway<br/>API 网关"]
Root --> FW["yudao-framework<br/>通用组件"]
Root --> MOD_SYS["yudao-module-system<br/>系统模块"]
Root --> MOD_INFRA["yudao-module-infra<br/>基础设施模块"]
Root --> MOD_BPM["yudao-module-bpm<br/>工作流模块"]
Root --> MOD_REPORT["yudao-module-report<br/>报表模块"]
Root --> MOD_DEVICE["yudao-module-device<br/>设备管理模块"]
Root --> MOD_LAUNCHER["yudao-module-launcher<br/>运营模块"]
Root --> MOD_TASK["yudao-module-task<br/>任务与OTA模块"]
Root --> MOD_RULE["yudao-module-rule<br/>规则引擎模块"]
Root --> MOD_BLACKLIST["yudao-module-blacklist<br/>黑名单模块"]

图表来源

章节来源

核心组件​

  • 版本号与发布周期
    • 版本号：采用 Maven 属性 ${revision}，当前为 2.4.1-SNAPSHOT。
    • 发布周期：未在仓库中明确声明固定周期，当前为快照版本，适合持续集成与测试。
  • 技术栈与依赖
    • Spring Boot 3.4.1、Spring Cloud 2024.0.0、Spring Cloud Alibaba 2023.0.3.2。
    • 依赖统一由 yudao-dependencies 管理，便于跨模块一致性。
  • 网关与灰度发布
    • 网关基于 Spring Cloud Gateway，支持基于请求头 version 的灰度分流。
  • 数据存储与日志
    • MySQL 业务库 + TDengine 时序库混合架构；Kafka 用于日志上报缓冲；Elasticsearch 用于报表模块的 APK 推送历史检索。

章节来源

架构总览​

系统采用微服务架构，网关统一入口，后端服务通过 Nacos 注册与配置管理，流量统一通过 Spring Cloud Gateway 接入。核心服务包括系统、基础设施、设备、运营、黑名单、任务/OTA、规则引擎等模块。数据层采用 MySQL + TDengine 的混合架构，Redis 作为缓存，Kafka 用于日志上报缓冲，Prometheus/SkyWalking 用于监控与链路追踪。

Mermaid Diagram Code:

graph TD
User["Web/App 用户"] --> GW["yudao-gateway 网关"]
Device["智能终端设备"] --> GW
subgraph "微服务集群 (Spring Cloud Alibaba)"
GW --> SYS["yudao-system 系统服务"]
GW --> INFRA["yudao-infra 基础服务"]
GW --> DEV["yudao-device 设备服务"]
GW --> LAUNCH["yudao-launcher 运营服务"]
GW --> BLK["yudao-blacklist 黑名单服务"]
GW --> TASK["yudao-task 任务/OTA服务"]
GW --> RULE["yudao-rule 规则引擎"]
end
subgraph "中间件 & 存储"
Nacos["Nacos 注册/配置中心"]
Redis["Redis 缓存"]
MySQL["MySQL 业务库"]
TDengine["TDengine 时序库"]
Kafka["Kafka 消息队列"]
end
SYS -.-> Nacos
DEV -.-> TDengine
TASK -.-> TDengine
BLK -.-> Kafka
GW -.-> Redis

图表来源

章节来源

详细组件分析​

版本号命名规则与发布策略​

  • 命名规则
    • 采用 Maven 属性 ${revision}，当前值为 2.4.1-SNAPSHOT。
    • 快照版本后缀 -SNAPSHOT 表示不稳定版本，适合开发与测试。
  • 发布策略
    • 未在仓库中发现正式的版本发布记录文件，建议遵循语义化版本：主版本号.次版本号.修订号[-SNAPSHOT]。
    • 建议在稳定分支打 Tag 并发布 Release 版本，同时维护 Changelog。

章节来源

网关灰度发布机制​

  • 灰度逻辑
    • 基于请求头 version 字段匹配服务实例的元数据 version，实现按版本分流。
    • 若无匹配或无版本头，则回退到所有可用实例。
  • 实现要点
    • GrayLoadBalancer 与 GrayReactiveLoadBalancerClientFilter 负责实例选择与过滤。
    • Nacos 元数据中 version 字段决定实例归属。

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 : 返回响应

图表来源

章节来源

报表模块 APK 推送历史处理​

  • 功能概述
    • 通过 Kafka 消费 APK 推送历史事件，保存或更新历史记录；支持补充 cpuid 与卸载时间。
  • 数据模型与流程
    • ApkPushHistoryConsumer 接收事件并调用 ApkPushHistoryService.saveOrUpdate。
    • 逻辑包含版本号比较与 ES 同步（索引映射见 apk_push_history.json）。

Mermaid Diagram Code:

flowchart TD
Start(["事件进入"]) --> Parse["解析事件为 ApkPushHistoryDO"]
Parse --> SaveOrUpdate["调用 Service.saveOrUpdate"]
SaveOrUpdate --> Exists{"记录是否存在?"}
Exists --> |否| Insert["插入新记录"]
Exists --> |是| Compare["比较版本号"]
Compare --> Newer{"新版本更高?"}
Newer --> |是| Update["更新记录"]
Newer --> |否| Skip["跳过处理"]
Insert --> ES["同步到 Elasticsearch"]
Update --> ES
Skip --> End(["结束"])
ES --> End

图表来源

章节来源

数据存储与多数据源​

  • 存储架构
    • 业务数据（用户、字典等）存储于 MySQL。
    • 设备心跳、运行记录等时序数据存储于 TDengine。
    • 缓存使用 Redis。
  • 多数据源配置
    • 不同模块通过常量类定义数据源，如 TD_API_VISIT、TD_ENGINE_APP_RUNTIME 等。

章节来源

依赖分析​

  • 顶层 POM 与 BOM
    • 顶层 POM 聚合模块并管理版本；yudao-dependencies 作为 BOM 导入 Spring Boot、Spring Cloud、Spring Cloud Alibaba 与各类组件版本。
  • 网关依赖
    • 引入 Spring Cloud Gateway、Nacos 注册与配置、监控组件等。
  • 模块依赖
    • 各业务模块依赖 yudao-dependencies 提供的统一版本与组件。

Mermaid Diagram Code:

graph TB
Root["yudao-cloud 根 POM"] --> Deps["yudao-dependencies BOM"]
Root --> GW["yudao-gateway"]
GW --> Deps
Root --> SYS["yudao-module-system"]
SYS --> Deps
Root --> INFRA["yudao-module-infra"]
INFRA --> Deps
Root --> OTHER["其他业务模块"]
OTHER --> Deps

图表来源

章节来源

性能考虑​

  • 灰度发布
    • 基于请求头 version 的灰度分流，避免全量切换带来的性能冲击。
  • 缓存与降级
    • Redis 缓存热点数据，降低数据库压力；规则引擎采用 Redis 缓存 + 分布式锁 + 数据库兜底策略。
  • 日志与监控
    • Kafka 缓冲日志上报，减轻实时写入压力；Prometheus/SkyWalking 提供可观测性。

章节来源

故障排查指南​

  • 网关灰度不生效
    • 检查请求头是否携带 version；确认 Nacos 实例元数据中 version 字段配置；核对 URL Scheme 是否为 grayLb。
  • Kafka 消费异常
    • 查看 ApkPushHistoryConsumer 的异常日志，确认事件格式与 Topic 配置；检查 Kafka 服务状态。
  • 数据库连接问题
    • 检查 datasource.yaml 中的连接参数与账号权限；确认 MySQL 服务可达。
  • 规则引擎缓存穿透
    • 检查 Redis 缓存与分布式锁逻辑；确认数据库中是否存在对应规则；必要时清理缓存并重试。

章节来源

结论​

  • 当前仓库未包含正式版本历史记录，版本号为 2.4.1-SNAPSHOT，建议在稳定分支打 Tag 并维护 Changelog。
  • 灰度发布、多数据源与消息队列等特性为系统提供了良好的可扩展性与稳定性。
  • 升级时应关注依赖版本兼容性、配置文件变更与数据库/ES 索引迁移。

附录​

版本升级指南​

  • 依赖版本兼容性检查
    • 基于 yudao-dependencies 的版本清单，核对 Spring Boot、Spring Cloud、Spring Cloud Alibaba 与第三方组件版本是否兼容。
  • 配置文件变更
    • 检查 datasource.yaml、application.yaml、Nacos 配置命名空间与分组是否一致。
  • 数据库与索引迁移
    • MySQL：执行对应模块的 SQL 脚本；TDengine：确认时序表结构与分区策略；Elasticsearch：根据 apk_push_history.json 更新索引映射。
  • 灰度发布验证
    • 通过请求头 version 验证灰度分流逻辑；检查日志输出与实例元数据匹配情况。

章节来源

向后兼容性政策与废弃功能处理​

  • 向后兼容性
    • 采用语义化版本，主版本号变更表示破坏性改动；次版本号变更表示新增功能但兼容；修订号变更表示修复。
  • 废弃功能
    • 未开启或未导入表结构的模块（如 ERP、CRM、Pay、AI、IoT）会在访问时返回特定错误提示，建议参考文档进行开启或迁移。

章节来源

安全漏洞修复与补丁发布流程​

  • 流程建议
    • 发现漏洞后，先在内部分支修复并测试；通过安全扫描与回归测试；在稳定分支打 Tag 并发布补丁版本；更新 Changelog 并通知用户。
  • 依赖加固
    • 定期更新 yudao-dependencies 中的组件版本，修复已知漏洞。

章节来源

版本回滚操作指南与风险评估​

  • 回滚步骤
    • 停止新版本服务；回滚数据库与索引至备份；恢复旧版本配置；重启服务并验证。
  • 风险评估
    • 数据库回滚可能影响新版本产生的增量数据；灰度发布回滚需同步调整 Nacos 元数据与请求头策略；监控与日志用于快速定位问题。

章节来源

新版本特性预览与迁移成本分析​

  • 特性预览
    • 规则引擎 LiteFlow：动态规则编排与缓存；灰度发布：基于版本头的流量分流；多数据源：MySQL + TDengine 混合存储。
  • 迁移成本
    • 依赖升级：需评估 Spring Boot 3.x 与相关组件的兼容性；配置迁移：Nacos 配置加载顺序与命名空间；数据迁移：MySQL/ES/TDengine 的结构与索引变更。

章节来源

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