跳至主要內容

升级指南

码匠君大约 8 分钟

升级指南

前言

说明

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

虽然每次发布的 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.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，Springopen in new window Authorization Server 将会抛出错误。可以配置成 127.0.0.1、任意 IP 或者域名。
  2. 因 redirect_uris 地址不支持 localhost，因此访问前端页面时也不能使用 localhost 访问。因为使用 localhost 访问前端，回调地址是 IP 地址，会导致前端存储的数据出错(浏览器存储数据，http://localhost:3000open in new window 和 http://xxx.xxx.xxx.xxx:3000open in new window 是不同的)。

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