跳至主要內容

升级指南

码匠君2023年5月17日SASSpring Authorization ServerDante Cloud微服务领域驱动DDDSpring BootSpring CloudSpring SecuritySpring Cloud AlibabaSpring Cloud TencentOAuth2.1NacosSkywalkingSentinelSeata大约 12 分钟

前言

说明

本项目整处在快速迭代和不断完善丰富的阶段，加之新技术新组件也会不断被融入本系统，因此每个版本的发布，多少都会产生一些差异性变化。如果是全新安装部署，并不会产生任何影响；如果是已经在用的系统，就需要特别注意这些变化的细节。

虽然每次发布的 Release Note 都会说明本次更新的变化，但是比较零散也不容易引起关注，因此特别开辟本版块，用户汇总和说明版本更新的差异，以便使用者可以在原有系统基础之上快速升级为新的版本。

本版块内容会尽可能详细阐述每次版本升级需要特别注意的事项以及需要更改的内容，无法确保升级无误，特别是如果你本地已经对代码进行了修改和新增的情况。

提示

所有的代码更新都要注意代码的合并，特别是本地工程已经进行了较多代码修改的情况。(Git 的基本操作就不再赘述)

代码升级的通用操作：

  1. Dante Engine 依赖包：每次发布新版本，Dante Engine 所有包都会上传至 Maven 中央仓库，因为发布和同步存在时间差，可以稍微等待或者自己下载代码编译。
  2. Dante Cloud 主工程：
    • 代码更新完成之后，要重新编译之后再进行部署。如果是在 IDEA 中编译，在编译之前多点击几次 IDEA 右上角 Maven 面板中的刷新按钮，以保证新的依赖包可以完全载入。
    • 涉及需要手动变更数据库的操作，修改完数据库之后，一定注意要清理 Redis 缓存。(缓存是把双刃剑啊)
  3. Dante Cloud Athena 单体版：与 Dante Cloud 主工程的操作方式相同。注意要更新并重新编译完 Dante Cloud 主工程后，再编译单体版新代码才能生效。
  4. Dante Cloud UI：因每次版本发布前，都会对前端工程依赖包进行升级，以保证发布的代码都是全新可运行的。所以更新完代码要 yarn install 升级一下依赖包后再使用。

警告

  1. 当你更新代码后，发现版本号有变化，需要重新编译工程代码，进行重新部署后再使用。
  2. 因系统使用的多级缓存，如果手动改动过数据，一定要注意清理缓存。需要先停止服务、清理 Redis、再重新启动服务。

v3.2.0.0

本次更新主要是对 Spring Boot 3.2.0 和 Spring Cloud 2023.0.0 版本做了适配。但是相关的 Spring Cloud Tencent 和 Spring Cloud Alibaba 还没有对最新的版本进行适配，所以当前版本还存在以下问题

  1. Spring Cloud Tencent

适配 Spring Boot 3.2 后，在使用 Spring Cloud Tencent 时，目前发现两个问题：

  • Netty 最新的 4.1.101.Final 版本调用了一个 Grpc 组件不支持的方法，会导致 Spring Cloud Tencent 无法连接到Server，运行时出错。这个问题本身并不是“适配” 问题，而是 Spring Boot 2.7.18、3.1.6 和 3.2.0 都依赖了最新版本的 Netty，升级就会出错。
  • 因为 Spring Bean 和 Feign 代码存在变化，而 Spring Cloud Tencent 采用 uber.jar 打包方式，导致依赖当前版本会出现代码冲突。

解决办法：

  • 将 Netty 版本降至 4.1.100.Final，可解决无法 GRPC 无法连接Server 问题。
  • 去除对包 spring-cloud-starter-tencent-all 和 spring-cloud-starter-tencent-polaris-circuitbreaker 的依赖，即可运行但部分功能会不可用

相关问题已经提交至 Spring Cloud Tencent 社区。https://github.com/Tencent/spring-cloud-tencent/issues/1210。该问题已经修复，grpc-java也已经发布新版本。需要等待 Spring Cloud Tencent 新版本发布

  1. Spring Cloud Alibaba

因为 Feign 底层核心接口存在变化，所以原来可以使用的 Sentinel 全局 Fallback 代码无法使用。而且当前环境，依赖 Sentinel 相关组件，会出现自定义 Feign Contract 配置失效，导致使用 SpringMVC 注解的或者自定义注解的 Feign 代码抛错。

目前的临时解决办法就是去除 Sentinel 所有的依赖包。

额外说明

  1. Dante Cloud 3.2.0.0 虽然已经适配 Spring Boot 3.2 和 Spring Cloud 2023.0.0，但是因为部分功能并不可用（目前主要涉及流控、断容的内容都无法使用，涉及 Sentinel 和 Polaris Circuitbreaker），所以不建议用于生产。
  2. 虽说是“适配”，但是核心目的是对升级 Spring Boot 3.2 和 Spring Cloud 2023.0.0 的工作量和会遇到的问题做评估，有了合理的评估才好决定是否要升级。所以望理解
  3. 虽然前面的内容说的都是“问题”，但这并不是说组件本身有问题，而是放到当前 Dante Cloud 的环境中以及使用未进行版本适配遇到的小插曲，而且和具体自己代码的实现思路和逻辑有很大关系，不同的系统代码遇到问题也未必相同。

还是建议等相关组件完成代码适配后再进行尝试。Spring Cloud Tencent 社区已经在进行响应，等 1.13 版本发布后就会开展 Spring Cloud 2023.0.0 版本的适配工作。https://github.com/Tencent/spring-cloud-tencent/issues/1209

v3.1.3.6

本次更新主要涉及配置中心配置的更新，这会直接影响 WebSocket 多实例发送消息是否生效。

  1. 如果您现有工程没有修改过dante-cloud-kafka.yaml 中的内容，直接进行该配置文件内容的替换；如果现有工程对 dante-cloud-kafka.yaml 配置有过修改，请查看历史差异对比，针对性的小范围修改。
  2. 如果要开启 WebSocket 多实例支持，需要在 dante-cloud-message.yaml 配置中，开启以下配置
herodotus:
  message:
    websocket:
      mode: multiple

警告

如果不想使用多实例支持，一定要将该配置删除，或者将其值设置为 single

v3.1.3.3

v3.1.3.0

Nacos 配置文件

为解决在微服务环境下，OSS 大文件分片上传错误，修改了 dante-cloud-oss-ability.yaml 配置信息。请对比文件变化手动更新该配置文件。

数据库初始化脚本

为了保证数据一致性，数据库初始化脚本移动至 dante-cloud-oss-ability 服务中。

v3.1.2.4

本次更新主要涉及 Nacos 配置的更新。

  1. 数据库名称和 Redis 库变化，此变化不影响现有系统可以不用更新。
  2. OSS 对象存储配置变更，此内容必须更新否则会影响对象存储的使用。请对比 dante-cloud-oss-ability.yaml 中变化内容进行更新。
  3. 补充可外部化配置的 logback.xml 日志配置文件。包含 Skywalking 日志上报、ELK 日志中心日志收集、Skywalking TraceId 等支持。同时提供常规及 MDC 两种配置。按需添加即可

v3.1.1.3

  • 数据库变化

本次更新涉及数据库核心数据的变更。主要涉及 oauth2_application 和 oauth2_registered_client 两张表。新增条目有点多，请查看代码变更历史。

  • 配置中心配置变更
  1. 新增了 5 个在 Service 分组下的配置。
  2. dante-cloud-platform.yaml 中 resource server 相关内容需要删除

v3.1.0.0

  • 本次更新存在配置参数变化，所以在原有版本上升级需要注意按照新版本设置修改 Nacos 配置。
  • 本次更新存在数据库字段变化，其它变化可以自动更新，仅 oauth2_application 表中内容需要进行一定修改。
    • authorization_code_ttl 字段变更为 authorization_code_validity，新字段会自动生成注意手动迁移数据
    • device_code_time_to_live 字段变更为 device_code_validity，新字段会自动生成注意手动迁移数据

v3.0.5.5

  • 因仓库提交文件大小限制，所以本次发布不在上传 Skywalking Agent 相关 Jar 包，有需要请自行下载。
  • Camunda 7.19.0 尚未适配 Spring Boot 3，还无法正常使用，当前仅做依赖升级，

v3.0.4.1

本次更新存在“破坏”性升级，如在已有版本基础上升级，强烈建议先备份数据库。

  1. 升级存在数据库变更，对已有业务数据不会产生影响。
  2. 全新搭建不受影响。
  3. 已有系统建议重新建库后，手动对比合并有数据。

v3.0.0.0

因 Spring Boot 3.0 自身的变化，特别是部分配置参数的变化，升级 Dante Cloud 3.0.0.0 除代码本身的变化之外，还需要对配置文件进行修改。使用 Dante Cloud 2.X 原有配置服务将无法正常运行。

如果是全新部署 Dante Cloud，直接导入 Nacos 配置包即可。如果是从 Dante Cloud 2.X 进行升级，需要手动修改已有的 Nacos 配置。

主要修改内容如下：

  • dante-cloud-redis.yaml：Redis 相关配置全部移动到 data 属性节点下。(例如：spring.redis.database 变更为 spring.data.redis.database)
  • dante-cloud-database.yaml
    • spring.jpa.properties.hibernate.temp.use_jdbc_metadata_defaults 值修改为 true
    • spring.jpa.properties.hibernate.cache.region.factory_class 值修改为 cn.herodotus.engine.data.jpa.hibernate.spi.cache.HerodotusRegionFactory。（注意：...cache.spi... 修改为 ...spi.cache...）
  • dante-cloud-database-postgresql.yaml: org.hibernate.dialect.PostgreSQL10Dialect 变更为 org.hibernate.dialect.PostgreSQLDialect

v2.7.5.3

Spring Authorization Server 0.4.0 版本对一些基础类进行了包调整，同时增加了 Token 设置的参数。因 Token 相关参数均是以 JSON 形式(包含 Class 映射信息)存储在数据表中，所以升级使用该版本，需要对相关信息进行修改，否则将会出现 Token 解析、创建异常导致功能无法正常使用的问题。

本次更新需要对数据表oauth2_registered_client 中的 token_settings 字段值进行修改。

方式一

  1. 清空 oauth2_registered_client 表中的数据
  2. 找到 uaa-data-postgresql.sql 或 uaa-data-mysql.sql 数据初始化脚本
  3. 将 oauth2_registered_client 相关的数据重新导入至数据库中

方式二

该种方式是针对性的、小范围修改，请在熟练掌握数据库数据维护情况下采用

找到数据表oauth2_registered_client 中的 token_settings 字段，对该字段中的 JSON 数据，进行以下两点修改：

  1. 将 JSON 数据中的 org.springframework.security.oauth2.core.OAuth2TokenFormat 修改为 org.springframework.security.oauth2.server.authorization.settings.OAuth2TokenFormat
  2. 在 JSON 数据的末尾、} 之前，增加 ,"settings.token.authorization-code-time-to-live":["java.time.Duration",300.000000000]。注意不要漏掉前面的 ， 逗号，以保证 JSON 格式的正确性。

v2.7.4.3

增加 Opaque Token 支持，并将 Opaque Token 作为默认的 Token 格式，以规避原有 JWT Token 可以被解析的问题，同时解决在 JWT Token 模式下，Kick Out 不生效问题，以进一步提升系统的安全性。

  • 修改 dante-cloud-platform.yaml 配置，增加 Opaque Token 配置
spring:
  security:
    oauth2:
      resourceserver:
        ......
        opaquetoken:
          client-id: 14a9cf797931430896ad13a6b1855611
          client-secret: a05fe1fc50ed42a4990c6c6fc4bec398
  • 修改数据表 oauth2_registered_client 中的数据

找到该表中 token_settings 字段 JSON 数据，将其中 OAuth2TokenFormat 的值 “self-contained” 修改为 “reference”。

  • 修改数据表 oauth2_application 中的数据

找到该表中 access_token_format 字段的值，将其值从“0”改“1”

修改完成之后，需要停止服务，清理 Redis 缓存，然后重启服务生效。

提示

如果想维持原状，仍旧使用 JWT Token 模式，那么无须进行以上操作。在 dante-cloud-platform.yaml 配置中，增加以下配置即可

herodotus:
  security:
    validate: local

v2.7.4.4

  1. 修复 Session 共享不生效问题
  • 修改 dante-cloud-platform.yaml 配置，增加 Session 共享配置
spring:
  session:
    store-type: redis
  security:
    oauth2:
    ......

提示

如果不需要使用 Session 共享功能，可以忽略该操作。

  1. 前端增加授权码模式登录

前端使用授权码模式登录，需要修改前端当前使用 client_id 对应的 redirect_uris 信息，以保证回调地址的正确性

  • 找到数据表 oauth2_registered_client 和 oauth2_application，将其中与当前前端 client_id 对应的 redirect_uris 字段中的信息修改为：
// 具体的 IP 地址和端口，根据自己的实际修改
http://192.168.101.10:3000/authorization-code

注意

  1. redirect_uris 地址中，不支持 localhost，如果配置成 http://localhost:3000/authorization-code，Spring Authorization Server 将会抛出错误。可以配置成 127.0.0.1、任意 IP 或者域名。
  2. 因 redirect_uris 地址不支持 localhost，因此访问前端页面时也不能使用 localhost 访问。因为使用 localhost 访问前端，回调地址是 IP 地址，会导致前端存储的数据出错(浏览器存储数据，http://localhost:3000 和 http://xxx.xxx.xxx.xxx:3000 是不同的)。

v2.5.5.0 版本注意事项

v2.5.5.0 版本以前，Dante Cloud 数据库初始化主要采用业务表自动创建和 OAuth2 部分表手工创建的方式。为了让数据库初始化工作更加便捷，v2.5.5.0 版本将原有需要手工创建的 OAuth2 数据表，全部改造为自动创建。

OAuth2 中，涉及数据库操作部分的代码，完全采用纯JDBC,使用原生 SQL 的方式实现。原生 SQL 的方式导致 SQL 语句中各个数据库字段的名称，一定要与实际数据库表字段对应，而且大小写敏感。OAuth2 所有业务表中，90%的字段都是使用小写字母定义，剩余的字段中会存在大小写混合的情况。而使用Spring Data JPA的自动建表机制，会统一使用小写字母进行建表，这样就会导致 OAuth2 部分业务失效。

[1]一定要修改 Nacos 配置后再运行服务

如果您现在使用的系统，主要是为了研究和学习，没有实际应用的数据。那么建议在工程 ${project_home}/platform/dante-cloud-monitor/resources/imports 目录下找到最新版本的 Nacos 配置，重新导入 Nacos 的配置，这样就不会出现上述问题。

如果已经在使用本系统，建议以最小化的方式修改 Nacos 配置后再使用系统。

在 Nacos 中，找到dante-cloud-database.yaml，修改配置spring.jpa.hibernate.naming.physical-strategy。

修改前

spring:
  jpa:
    hibernate:
      naming:
        physical-strategy: org.hibernate.boot.model.naming.PhysicalNamingStrategyStandardImpl

修改后

spring:
  jpa:
    hibernate:
      naming:
        physical-strategy: cn.herodotus.dante.data.jpa.hibernate.HerodotusPhysicalNamingStrategy
编辑此页
上次编辑于: 2024/5/24 00:35:21
贡献者: 码匠君