Red Hat Summit 红帽全球峰会支持控制台（Console）开发人员开始试用联系人

第 3 章 升级 Red Hat Single Sign-On 服务器

Red Hat Single Sign-On 服务器的升级或迁移流程取决于软件以前的版本。

  • 如果您要升级到一个新的次版本，例如从 7.5.x 升级到 7.6，请按照 Minor Upgrades 中的步骤操作。
  • 如果您要从 Keycloak 18.0.0 迁移，请按照 Minor Upgrades 中的步骤操作。
  • 如果您要升级到新的微版本，例如从 7.5.2 升级到 7.5.3，请按照 Micro Upgrades 中的步骤操作。

3.1. 执行次要升级

3.1.1. 准备升级

在升级前，请注意您需要执行升级步骤的顺序。特别是，在升级适配器前，请务必升级 Red Hat Single Sign-On 服务器。

警告

在 Red Hat Single Sign-On 的次要升级中，所有用户会话都会丢失。升级后，所有用户都需要再次登录。

流程

  1. 备份旧安装（配置、主题等）。
  2. 使用关系数据库文档中的说明备份数据库。

  3. 升级红帽单点登录服务器。

    升级后，该数据库将不再与旧服务器兼容。

  4. 如果您需要恢复升级，首先恢复旧的安装，然后从备份副本中恢复数据库。
  5. 升级适配器。

3.1.2. 升级 Red Hat Single Sign-On 服务器

按照以下步骤确保服务器升级成功：

  • 先在非生产环境中测试升级，以防止生产环境中的出现任何安装问题，
  • 在升级适配器前，先升级 Red Hat Single Sign-On 服务器。另外，在升级适配器前，还确保升级的服务器可以在生产环境中正常工作。
警告

因为特定于您的安装，这个升级步骤可能需要修改。有关可能影响升级的手动更改的详情，请参阅 特定于发布的更改。

根据您用于安装的方法，从 ZIP 文件或 RPM 升级服务器。

3.1.2.1. 从 ZIP 文件升级服务器

先决条件

  • 处理任何开放事务并删除 data/tx-object-store/ 事务目录。

流程

  1. 下载新服务器存档。
  2. 将下载的存档移动到所需位置。
  3. 提取存档。这一步会安装最新 Red Hat Single Sign-On 版本的一个干净实例。

  4. 对于单机安装，请将上一安装中的 RHSSO_HOME/standalone/ 目录复制到新安装中的 目录。

    对于域安装，请将之前安装的 RHSSO_HOME/domain/ 目录复制到新安装中的 目录。

    对于域安装，请创建空目录 RHSSO_HOME/domain/deployments。

    注意：bin 目录中的文件不应由之前版本中的文件覆盖。更改应手动进行。

  5. 复制添加到模块目录中的任何自定义模块。
  6. 继续操作，运行服务器升级脚本。

3.1.2.2. 从 RPM 升级服务器

先决条件

  • 处理任何开放事务并删除 /var/opt/rh-sso7/lib/keycloak/standalone/data/tx-object-store/ transaction 目录。

流程

  1. 订阅正确的包含 Red Hat Single Sign-On 的软件仓库。

    Red Hat Enterprise Linux 7：

    Copy to Clipboard Toggle word wrap 
    subscription-manager repos --enable=rh-sso-7.6-for-rhel-7-x86_64-rpms

    Red Hat Enterprise Linux 8：

    Copy to Clipboard Toggle word wrap 
    subscription-manager repos --enable=rh-sso-7.6-for-rhel-8-x86_64-rpms

  2. 为 Red Hat Single Sign-On 禁用旧的产品存储库：

    Copy to Clipboard Toggle word wrap 
    subscription-manager repos --disable=rh-sso-7.5-for-rhel-8-x86_64-rpms

  3. 检查软件仓库列表：

    Copy to Clipboard Toggle word wrap 
    dnf repolist
     Copy to Clipboard Toggle word wrap 
    Updating Subscription Management repositories.
repo id repo name
rh-sso-7.6-for-rhel-8-x86_64-rpms Single Sign-On 7.6 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)
  4. 备份所有修改后的配置文件和自定义模块。

  5. 使用 dnf upgrade 升级到新的 Red Hat Single Sign-On 版本。

    RPM 升级过程不会替换任何修改后的配置文件。相反，此过程会为新红帽单点登录版本的默认配置创建 .rpmnew 文件。

  6. 要激活新版本中的任何新功能，如新子系统，手动将每个 .rpmnew 文件合并到您现有的配置文件中。
  7. 复制添加到模块目录中的任何自定义模块。

  8. 继续操作，运行服务器升级脚本。

    注意

    Red Hat Single Sign-On RPM 服务器发行版本使用

    RHSSO_HOME=/opt/rh/rh-sso7/root/usr/share/keycloak

    在调用以下迁移脚本时使用它。

3.1.3. 运行服务器升级脚本

根据您的安装，运行适用于您的情况的适当升级脚本：

3.1.3.1. 运行独立模式升级脚本

流程

  1. 如果您使用不同于默认值的配置文件，请编辑迁移脚本以指定新文件名。
  2. 停止服务器。

  3. 运行升级脚本：

    Copy to Clipboard Toggle word wrap 
    bin/jboss-cli.sh --file=bin/migrate-standalone.cli

3.1.3.2. 运行 standalone-High Availability Mode 升级脚本

对于独立高可用性(HA)模式，所有实例必须同时升级。

流程

  1. 如果您使用不同于默认值的配置文件，请编辑迁移脚本以指定新文件名。
  2. 停止服务器。

  3. 运行升级脚本：

    Copy to Clipboard Toggle word wrap 
    bin/jboss-cli.sh --file=bin/migrate-standalone-ha.cli

3.1.3.3. 运行 Domain Mode 升级脚本

对于域模式，所有实例必须同时升级。

流程

  1. 如果您更改了配置集名称，您必须编辑升级脚本，以在脚本开始时更改变量。
  2. 编辑域脚本，使其包含 keycloak-server.json 文件的位置。
  3. 停止服务器。

  4. 在域控制器上运行升级脚本

    Copy to Clipboard Toggle word wrap 
    bin/jboss-cli.sh --file=bin/migrate-domain.cli

3.1.3.4. 运行 Domain-clustered 模式升级脚本

对于 domain-clustered 模式，所有实例必须同时升级。

流程

  1. 如果您更改了配置集名称，您必须编辑升级脚本，以在脚本开始时更改变量。
  2. 编辑 domain-clustered 脚本，使其包含 keycloak-server.json 文件的位置。
  3. 停止服务器。

  4. 仅在域控制器上运行升级脚本：

    Copy to Clipboard Toggle word wrap 
    bin/jboss-cli.sh --file=bin/migrate-domain-clustered.cli

3.1.4. 数据库迁移

Red Hat Single Sign-On 可以自动迁移数据库架构，也可以选择手动操作。默认情况下，当您首次启动新安装时，数据库会自动迁移。

3.1.4.1. 自动关系数据库迁移

要启用对数据库 schema 的自动升级，请将 migrationStrategy 属性值设置为 更新默认 connectionJpa 供应商：

Copy to Clipboard Toggle word wrap 
 <spi name="connectionsJpa">
    <provider name="default" enabled="true">
        <properties>
            ...
            <property name="migrationStrategy" value="update"/>
        </properties>
    </provider>
</spi>

或运行此 CLI 命令：

Copy to Clipboard Toggle word wrap 
/subsystem=keycloak-server/spi=connectionsJpa/provider=default/:map-put(name=properties,key=migrationStrategy,value=update)

使用此设置启动服务器时，如果新版本中更改了数据库，则会自动迁移数据库。

在具有数百万记录的大量表中创建索引，可轻松花费大量时间，并可能对升级造成主要服务中断。对于这些情况，我们添加了用于自动创建索引的阈值（记录数）。默认情况下，这个阈值是 300000 记录。当记录数量高于阈值时，索引不会自动创建，且服务器日志中会有一个警告消息，包括稍后可以手动应用的 SQL 命令。

要更改阈值，请设置 indexCreationThreshold 属性，默认 connection Liquibase 供应商的值：

Copy to Clipboard Toggle word wrap 
<spi name="connectionsLiquibase">
    <provider name="default" enabled="true">
        <properties>
            <property name="indexCreationThreshold" value="300000"/>
        </properties>
    </provider>
</spi>

或运行此 CLI 命令：

Copy to Clipboard Toggle word wrap 
/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 ：

Copy to Clipboard Toggle word wrap 
 <spi name="connectionsJpa">
    <provider name="default" enabled="true">
        <properties>
            ...
            <property name="migrationStrategy" value="manual"/>
        </properties>
    </provider>
</spi>

或运行此 CLI 命令：

Copy to Clipboard Toggle word wrap 
/subsystem=keycloak-server/spi=connectionsJpa/provider=default/:map-put(name=properties,key=migrationStrategy,value=manual)

使用此配置启动服务器时，它会检查是否需要迁移数据库。所需更改写入到 SQL 文件中，您可以检查并手动针对数据库运行。有关如何将此文件应用到数据库的详情，请查看您使用的关系数据库的文档。在更改写入到该文件后，服务器会退出。

3.1.5. Theme migration

如果您创建了任何自定义它们，则必须将其迁移到新服务器。对内置主题的任何更改可能需要根据您自定义哪些方面在自定义中反映在自定义中。

您必须将自定义它们从旧服务器复制到新服务器，将其复制到新服务器目录中。 之后，您需要查看以下更改并考虑更改是否需要应用于您的自定义主题。

概述：

  • 如果您自定义了以下所有更改的模板，则需要将模板与基础主题进行比较，以查看您是否需要应用了更改。
  • 如果您已自定义了任何一种方式，并且要扩展红帽单点登录，那么您需要审查对风格的更改。如果要扩展基础，您可以跳过这一步。
  • 如果您有自定义消息，您可能需要更改密钥或值或添加其他消息。

每个步骤都会详细介绍更改列表的下方。

3.1.5.1. 主题更改 RH-SSO 7.3

模板

  • account: account.ftl
  • 帐户：application.ftl
  • 账户： resource-detail.ftl（新的）
  • account: resources.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：电子邮件验证-带有码.ftl（新的）
  • email-text：电子邮件验证.ftl
  • email-text： executeActions.ftl
  • Email-text: identity-provider-link.ftl
  • email-text：password-reset.ftl
  • 登录：cli_splash.ftl（新的）
  • login: code.ftl
  • login: error.ftl
  • login: info.ftl
  • 登录：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
  • 登录名： terms.ftl
  • 欢迎：index.ftl（新的）

消息

  • account: message_en.properties
  • admin: admin-messages_en.properties
  • 电子邮件： message_en.properties
  • login: message_en.properties

样式

  • 登录：login-rhsso.cs（新的）
  • 欢迎： welcome-rhsso.css

3.1.5.2. 主题会改变 RH-SSO 7.2

模板

  • account: account.ftl
  • 帐户：application.ftl
  • 帐户： federatedIdentity.ftl
  • 帐户：password.ftl
  • account： sessions.ftl
  • account: template.ftl
  • account: totp.ftl
  • admin: index.ftl
  • 电子邮件： email-test.ftl（新的）
  • 电子邮件：电子邮件验证.ftl
  • 电子邮件： event-login_error.ftl
  • 电子邮件： event-removed_totp.ftl
  • 电子邮件： event-update_password.ftl
  • 电子邮件： event-update_totp.ftl
  • 电子邮件： executeActions.ftl
  • 电子邮件： identity-provider-link.ftl
  • 电子邮件：password-reset.ftl
  • 登录名： 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-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（新的）
  • 登录名： register.ftl（新的）
  • login: template.ftl（新的）
  • 登录名： terms.ftl（新的）

消息

  • account: message_en.properties
  • admin: admin-messages_en.properties
  • admin: message_en.properties
  • 电子邮件： message_en.properties
  • login: message_en.properties

样式

  • account: account.css
  • login: login.css

3.1.5.3. 主题更改 RH-SSO 7.1

模板

  • account: account.ftl
  • 帐户： federatedIdentity.ftl
  • account: totp.ftl
  • login: info.ftl
  • login: login-config-totp.ftl
  • login: login-reset-password.ftl
  • login: login.ftl

消息

  • 帐户：编辑AccountHtmlTtile 重命名以编辑AccountHtmlTitle
  • account: role_uma_authorization added
  • login: loginTotpStep1 值已更改
  • login: invalidPasswordGenericMessage added
  • login: invlidRequesterMessage renamed to invalidRequesterMessage
  • login: clientDisabledMessage added

样式

  • account: account.css
  • login: login.css

3.1.5.4. 迁移模板

如果您已自定义了任何模板，您需要仔细检查对模板所做的更改，以确定是否需要将这些更改应用到您的自定义模板。很可能需要对自定义模板应用相同的更改。如果您还没有自定义任何列出的模板，您可以跳过本节。

最佳实践是使用 diff 工具比较模板，以了解您可能需要对自定义模板进行的更改。如果您只进行了小更改，将更新的模板与自定义模板进行比较。但是，如果您进行了很多更改，将新模板与自定义旧模板进行比较，因为这将向您展示您需要做了哪些更改。

以下屏幕截图比较了 Login theme 和 example custom theme 中的 info.ftl 模板：

登录主题模板的更新版本与示例自定义登录主题模板进行比较

theme migration meld info 1

从这个比较上，很容易确认第一个更改(Hello world!!)是一个自定义，而第二次更改（如果页面RedirectUri）是对主题的基本更改。通过将第二个更改复制到自定义模板，您可以成功更新自定义模板。

对于其他方法，以下屏幕截图将旧安装中的 info.ftl 模板与新安装中的更新的 info.ftl 模板进行比较：

旧安装中的登录主题模板与登录主题模板的更新版本进行比较

theme migration meld info 2

从此比较便于识别基本模板中的变化。然后，您必须手动对修改的模板进行相同的更改。由于此方法不像第一种方法那样简单，因此仅当第一个方法不可行时，才使用此方法。

3.1.5.5. 迁移消息

如果您添加了对其它语言的支持，则需要应用上述所有更改。如果您尚未添加对其他语言的支持，您可能不需要更改任何内容；如果您在主题中更改了受影响的消息，您只需要进行更改。

对于添加的值，请查看主题中消息的值，以确定您是否需要自定义该消息。

对于重命名的密钥，请重命名自定义主题中的密钥。

对于 changed 的值，检查基础主题中的值，以确定是否需要更改您的自定义主题。

3.1.5.6. 迁移风格

如果您要从键或 rh-sso 继承样式，您可能需要更新您的自定义风格，以反映内置它们对样式所做的更改。

最佳实践是使用 diff 工具比较旧服务器安装与新服务器安装之间样式表的更改。

例如，使用 diff 命令：

Copy to Clipboard Toggle word wrap 
$ diff RHSSO_HOME_OLD/themes/keycloak/login/resources/css/login.css \
RHSSO_HOME_NEW/themes/keycloak/login/resources/css/login.css

检查更改，并确定它们是否影响您的自定义风格。

返回顶部
Red Hat logoGithubredditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务，以及可以信赖的内容，帮助红帽用户创新并实现他们的目标。 了解我们当前的更新.

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情，请参阅红帽博客.

關於紅帽

我们提供强化的解决方案，使企业能够更轻松地跨平台和环境（从核心数据中心到网络边缘）工作。

Theme

© 2025 Red Hat, Inc.