第 3 章 升级 Red Hat Single Sign-On 服务器
Red Hat Single Sign-On 服务器的升级或迁移流程取决于软件的旧版本。
- 如果您要升级到新的次版本，例如从 7.0.0 到 7.1.0，请遵循 Minor Upgrades 中的步骤。
- 如果您要从 Keycloak 15.0.2 迁移，请按照 Minor Upgrades 中的步骤操作。
- 如果您要升级到新的微版本，例如从 7.1.0 升级到 7.1.1，请遵循 Micro Upgrades 中的步骤。
3.1. 执行次要升级
3.1.1. 准备升级
在升级前，请了解执行升级步骤所需的顺序。特别是，在升级适配器前，请务必升级 Red Hat Single Sign-On 服务器。
在 Red Hat Single Sign-On 的次要升级中，所有用户会话都会丢失。升级后，所有用户都必须再次登录。
流程
- 备份旧安装（配置、主题等）。
- 使用相关数据库文档中的说明备份数据库。
升级红帽单点登录服务器。
升级后，数据库将不再与旧服务器兼容。
- 如果您需要恢复升级，请先恢复旧的安装，然后从备份副本恢复数据库。
- 升级适配器。
3.1.2. 升级 Red Hat Single Sign-On 服务器
按照以下步骤确保服务器升级成功：
- 首先在非生产环境中测试升级，以防止生产环境中的任何安装问题。
- 在升级适配器前，升级 Red Hat Single Sign-On 服务器。另外，在升级适配器前确保升级的服务器可以在生产环境中正常工作。
这个升级步骤可能需要根据特定于安装的手动更改而修改。有关可能会影响升级的手动更改的详情，请参阅 特定于版本的更改。
根据您用于安装的方法从 ZIP 文件或 RPM 升级服务器。
3.1.2.1. 从 ZIP 文件升级服务器
前提条件
- 处理任何开放的事务，并删除 data/tx-object-store/ 事务目录。
流程
- 下载新服务器存档。
- 将下载的存档移到所需的位置。
- 解压存档。此步骤安装最新的 Red Hat Single Sign-On 发行版本的干净实例。
对于单机安装，请将之前安装的
RHSSO_HOME/standalone/目录复制到新安装的 目录中。对于域安装，请将之前安装的
RHSSO_HOME/domain/目录复制到新安装的 目录中。对于域安装，请创建
RHSSO_HOME/domain/deployments的空目录。注意：bin 目录中的文件不应被之前版本中的文件覆盖。更改应手动进行。
- 复制添加到模块目录中的任何自定义模块。
- 继续 部分，运行服务器升级脚本。
3.1.2.2. 从 RPM 升级服务器
前提条件
- 处理任何开放的事务，并删除 /var/opt/rh/rh-sso7/lib/keycloak/standalone/data/tx-object-store/ 事务。
流程
订阅含有 JBOSS EAP 和红帽单点登录的相应存储库。
Red Hat Enterprise Linux 7：
subscription-manager repos --enable=rh-sso-7.5-for-rhel-7-server-rpms
Red Hat Enterprise Linux 8：
subscription-manager repos --enable=rh-sso-7.5-for-rhel-8-x86_64-rpms
为 JBOSS EAP 和 Red Hat Single Sign-On 禁用旧的产品存储库：
subscription-manager repos --disable=jb-eap-7.3-for-rhel-8-x86_64-rpms subscription-manager repos --disable=rh-sso-7.4-for-rhel-8-x86_64-rpms
检查软件仓库列表：
dnf repolist
Updating Subscription Management repositories. repo id repo name rh-sso-7.5-for-rhel-8-x86_64-rpms Single Sign-On 7.5 for RHEL 8 x86_64 (RPMs) rhel-8-for-x86_64-appstream-rpms Red Hat Enterprise Linux 8 for x86_64 - AppStream (RPMs) rhel-8-for-x86_64-baseos-rpms Red Hat Enterprise Linux 8 for x86_64 - BaseOS (RPMs)
- 备份任何修改后的配置文件和自定义模块。
删除 RH-SSO 7.4 的软件包。
通常，
dnf 升级会删除旧的软件包。但是，RH-SSO 7.5 软件包使用的格式与 JBoss EAP 7.3 软件包处理的文件冲突。因此，必须删除 RH-SSO 7.4 和 JBoss EAP 7.3 软件包。dnf remove --exclude java-1.8.0-openjdk rh-sso7-keycloak
删除 java-1.8.0-openjdk 并不是必需的，但此步骤在以后的流程中会保存同一组相关软件包的额外下载。
安装新版本的 RH-SSO。
dnf groupinstall rh-sso7
dnf install rh-sso7-keycloak-15.0.2-3.redhat_00002.1.el8sso rh-sso7-keycloak-server-15.0.2-3.redhat_00002.1.el8sso
- 要激活新版本中的所有新功能，如新子系统，您必须将每个备份配置文件手动合并到现有的配置文件中。
- 复制添加到模块目录中的任何自定义模块。
继续 部分，运行服务器升级脚本。
注意Red Hat Single Sign-On RPM 服务器分发使用
RHSSO_HOME=/opt/rh/rh-sso7/root/usr/share/keycloak在调用以下的迁移脚本时使用它。
3.1.3. 运行服务器升级脚本
根据您的之前安装，运行适用于您的情况的适当升级脚本：
3.1.3.1. 运行单机模式升级脚本
流程
- 如果您使用与默认配置文件不同的配置文件，请编辑迁移脚本来指定新的文件名。
- 停止服务器。
运行升级脚本：
bin/jboss-cli.sh --file=bin/migrate-standalone.cli
3.1.3.2. 运行 Standalone-High Availability Mode 升级脚本
对于独立高可用性(HA)模式，所有实例都必须同时升级。
流程
- 如果您使用与默认配置文件不同的配置文件，请编辑迁移脚本来指定新的文件名。
- 停止服务器。
运行升级脚本：
bin/jboss-cli.sh --file=bin/migrate-standalone-ha.cli
3.1.3.3. 运行域模式升级脚本
对于域模式，所有实例都必须同时升级。
流程
- 如果更改了配置集名称，您必须编辑升级脚本，以在脚本开头附近更改变量。
- 编辑域脚本，使其包含 keycloak-server.json 文件的位置。
- 停止服务器。
在域控制器上运行升级脚本
bin/jboss-cli.sh --file=bin/migrate-domain.cli
3.1.3.4. 运行 Domain-clustered Mode 升级脚本
对于域集群模式，所有实例都必须同时升级。
流程
- 如果更改了配置集名称，您必须编辑升级脚本，以在脚本开头附近更改变量。
- 编辑 domain-clustered 脚本，使其包含 keycloak-server.json 文件的位置。
- 停止服务器。
仅在域控制器上运行升级脚本：
bin/jboss-cli.sh --file=bin/migrate-domain-clustered.cli
3.1.4. 数据库迁移
Red Hat Single Sign-On 可以自动迁移数据库模式，也可以选择手动进行。默认情况下，当您第一次启动新安装时，数据库会被自动迁移。
3.1.4.1. 自动关系数据库迁移
要启用数据库模式的自动升级，将 migrationStrategy 属性值设置为默认的 connectionJpa 供应商 更新 ：
<spi name="connectionsJpa">
<provider name="default" enabled="true">
<properties>
...
<property name="migrationStrategy" value="update"/>
</properties>
</provider>
</spi>或者运行此 CLI 命令：
/subsystem=keycloak-server/spi=connectionsJpa/provider=default/:map-put(name=properties,key=migrationStrategy,value=update)
当您使用此设置启动服务器时，如果新版本中的数据库 schema 已更改，则会自动迁移数据库。
在带有数以百万条记录的大型表中创建索引可轻松花费大量时间，并可能会在升级时造成主要服务中断。对于这些情况，我们添加了用于自动索引创建的阈值（记录数）。默认情况下，这个阈值是 300000 记录。当记录数量大于阈值时，索引不会被自动创建，并且在服务器日志中会出现警告信息，包括稍后手动应用的 SQL 命令。
要更改阈值，请设置 indexCreationThreshold 属性，为默认的 connection Liquibase provider 的值：
<spi name="connectionsLiquibase">
<provider name="default" enabled="true">
<properties>
<property name="indexCreationThreshold" value="300000"/>
</properties>
</provider>
</spi>或者运行此 CLI 命令：
/subsystem=keycloak-server/spi=connectionsLiquibase/:add(default-provider=default)
/subsystem=keycloak-server/spi=connectionsLiquibase/provider=default/:add(properties={indexCreationThreshold => "300000"},enabled=true)3.1.4.2. 手动关系数据库迁移
要启用数据库 schema 的手动升级，请将默认 connectionJpa 供应商的 migrationStrategy 属性值设置为 manual ：
<spi name="connectionsJpa">
<provider name="default" enabled="true">
<properties>
...
<property name="migrationStrategy" value="manual"/>
</properties>
</provider>
</spi>或者运行此 CLI 命令：
/subsystem=keycloak-server/spi=connectionsJpa/provider=default/:map-put(name=properties,key=migrationStrategy,value=manual)
当您使用此配置启动服务器时，它会检查是否需要迁移数据库。所需的更改写入到 SQL 文件中，您可以检查并手动针对数据库运行。有关如何将此文件应用到数据库的详情，请参考相关数据库文档。将更改写入到文件后，服务器将退出。
3.1.5. 主题迁移
如果您创建了任何自定义主题，则必须将其迁移到新服务器。根据您的已定制的功能，对内置主题的任何更改都可能需要反映在您的自定义主题中。
您必须将自己的自定义主题从旧服务器 复制到新的 服务器 主题 目录。在您需要查看以下更改之后，考虑更改是否需要应用到您的自定义主题。
总结：
- 如果您已自定义了以下列出的任何已更改模板，则需要比较基础中的模板，以查看是否需要应用更改。
- 如果您已自定义了任何样式，并且正在扩展 Red Hat Single Sign-Ones，您需要查看对风格的更改。如果您扩展了基本主题，您可以跳过这一步。
- 如果您有自定义消息，您可能需要更改密钥或值或添加额外的消息。
每个步骤都会在更改列表的下面详细阐述。
3.1.5.1. 主题更改 RH-SSO 7.3
模板
- 账户：account.ftl
- 帐户：application.ftl
- 帐户：resource-detail.ftl （新的）
- 帐户：resource.ftl （新）
- account: template.ftl
- account: totp.ftl
- email-html: email-test.ftl
- email-html: email-verification-with-code.ftl （新的）
- email-html: email-verification.ftl
- Email-html: event-login_error.ftl
- Email-html: event-removed_totp.ftl
- email-html: event-update_password.ftl
- Email-html: event-update_totp.ftl
- email-html: executeActions.ftl
- email-html: identity-provider-link.ftl
- email-html: password-reset.ftl
- email-text：电子邮件验证-with-code.ftl （新的）
- Email-text: email-verification.ftl
- email-text: executeActions.ftl
- email-text: identity-provider-link.ftl
- email-text: password-reset.ftl
- login：cli_splash.ftl （新的）
- login: code.ftl
- login: error.ftl
- login: info.ftl
- login: login-config-totp-text.ftl （新的）
- login: login-config-totp.ftl
- Login: login-idp-link-confirm.ftl
- login: login-idp-link-email.ftl
- login: login-oauth-grant.ftl
- login: login-page-expired.ftl
- login: login-reset-password.ftl
- login: login-totp.ftl
- login: login-update-password.ftl
- login: login-update-profile.ftl
- login: login-verify-email-code-text.ftl （新的）
- login: login-verify-email.ftl
- login: login-x509-info.ftl
- login: login.ftl
- login: register.ftl
- login: template.ftl
- login：术语.ftl
- welcome: index.ftl （新的）
消息
- account: messages_en.properties
- admin: admin-messages_en.properties
- 电子邮件： messages_en.properties
- login: messages_en.properties
样式
- 登录：login-rhsso.css （新的）
- 欢迎： welcome-rhsso.css
3.1.5.2. Theme changes RH-SSO 7.2
模板
- 账户：account.ftl
- 帐户：application.ftl
- 账户： federatedIdentity.ftl
- 帐户：password.ftl
- 账户： sessions.ftl
- account: template.ftl
- account: totp.ftl
- admin: index.ftl
- 电子邮件： email-test.ftl （新的）
- 电子邮件： email-verification.ftl
- 电子邮件：event-login_error.ftl
- 电子邮件：event-removed_totp.ftl
- 电子邮件：event-update_password.ftl
- 电子邮件：event-update_totp.ftl
- email: executeActions.ftl
- 电子邮件：identity-provider-link.ftl
- 电子邮件：password-reset.ftl
- login: bypass_kerberos.ftl （删除）
- login: error.ftl
- login: info.ftl
- login: login-config-totp.ftl
- login: login-idp-link-email.ftl
- login: login-oauth-grant.ftl
- login: login-page-expired.ftl （新的）
- login: login-reset-password.ftl
- login: login-totp.ftl
- login: login-update-password.ftl
- login: login-update-profile.ftl
- login: login-verify-email.ftl
- login: login-x509-info.ftl （新的）
- login：login.ftl （新）
- login： register.ftl （新）
- login：template.ftl （新）
- login：术语.ftl （新的）
消息
- account: messages_en.properties
- admin: admin-messages_en.properties
- admin: messages_en.properties
- 电子邮件： messages_en.properties
- login: messages_en.properties
样式
- 帐户：accounts.css
- login: login.css
3.1.5.3. 主题改变了 RH-SSO 7.1
模板
- 账户：account.ftl
- 账户： federatedIdentity.ftl
- account: totp.ftl
- login: info.ftl
- login: login-config-totp.ftl
- login: login-reset-password.ftl
- login: login.ftl
消息
- 帐户：编辑AccountHtmlTtile 重命名为 editAccountHtmlTitle
- account: role_uma_authorization 添加
- login: loginTotpStep1 值已更改
- login: invalidPasswordGenericMessage added
- login: invlidRequesterMessage 重命名为 invalidRequesterMessage
- login：添加 clientDisabledMessage
样式
- 帐户：accounts.css
- login: login.css
3.1.5.4. 迁移模板
如果您已自定义了任何模板，您需要仔细检查对模板进行的更改，以确定您是否需要对自定义模板应用这些更改。很可能需要对自定义模板应用相同的更改。如果您还没有自定义任何列出的模板，您可以跳过本节。
最佳实践是使用 diff 工具比较模板，以查看可能需要对自定义模板进行的更改。如果您只进行了较小的更改，比较更新的模板与自定义模板更为简单。但是，如果您进行了很多更改，可以将新模板与自定义旧模板进行比较，因为这会显示您需要做了哪些更改。
以下屏幕截图对比了来自登录主题的 info.ftl 模板和示例自定义主题：
带有自定义登录主题模板的更新版本与自定义登录主题模板的比较
从这一比较比较，易于识别第一个更改(Hello world!!)是自定义，而第二次更改(如果页重定向)是更改为主题的变动。通过将第二个更改复制到自定义模板，您已成功更新自定义模板。
对于替代方法，以下屏幕截图将旧安装中的 info.ftl 模板与新安装的 update info.ftl 模板进行比较：
旧安装中的登录主题模板与登录主题模板的更新版本的比较
从此比较中，易于识别基本模板中更改的内容。然后，您必须手动对修改的模板进行相同的更改。由于这种方法并不像第一种方法那样简单，因此只有第一种方法不能可行时，才使用此方法。
3.1.5.5. 迁移消息
如果您添加了对其他语言的支持，则需要应用上面列出的所有更改。如果您没有为其他语言添加支持，则您可能不需要更改任何内容；您只需要在主题中更改了受影响的消息，则只需要进行更改。
对于添加的值，请查看基本主题中消息的值以确定是否需要自定义该消息。
对于重命名的密钥，请重命名自定义主题中的 键。
对于 changed 值，请检查基本主题中的值，以确定您是否需要对自定义主题进行更改。
3.1.5.6. 迁移风格
如果您要从 keycloak 或 rh-sso 它们继承样式，您可能需要更新自定义样式，以反映对内置方式所做的更改。
最佳实践是使用 diff 工具比较旧服务器安装与新服务器安装之间的样式表的更改。
例如，使用 diff 命令：
$ diff RHSSO_HOME_OLD/themes/keycloak/login/resources/css/login.css \ RHSSO_HOME_NEW/themes/keycloak/login/resources/css/login.css
检查更改，并确定它们是否影响您的自定义样式。
