迁移到 Quarkus 发行版

Keycloak 的 WildFly 发行版使用复杂的 XML 文件进行配置，因此需要使用 CLI 工具 (jboss-cli) 来操作这些文件。这些文件也给升级带来了复杂性，升级时需要使用容易出错的脚本来升级以前版本的配置。

新的 Quarkus 发行版使用简单的配置文件，并提供相应的 CLI 参数和环境变量作为选项，从而大大简化了 Keycloak 的配置。然而，这也导致无法自动迁移以前发行版的配置。

要迁移到新的 Quarkus 发行版，第一步是了解您对传统发行版应用的配置更改，并按照新的 服务器指南 将必要的更改应用到新的发行版。

需要注意的是，新的发行版在配置方面更加有主见。它的目标是提供更好的默认设置，减少您需要自己配置的内容。但是，我们可能并不总是能达到平衡，并且可能存在未涵盖的用例。

如果您无法在新的发行版中配置您需要调整的内容，请在 GitHub Discussions 中发起讨论。

在新版本发布之前，可以通过直接通过 conf/quarkus.properties 文件应用 Quarkus 级别的配置来配置新的发行版。我们建议您谨慎使用此方法，因为您将应用未经 Keycloak 团队测试和支持的配置。

与 WildFly 不同，Quarkus 不是应用服务器。虽然应用服务器可以动态部署应用程序，并在运行时更改加载到内存中的内容，但在 Quarkus 上这是不可能的。

另一方面，Quarkus 为容器带来了不变性、更快的启动速度和更高的可预测性。

虽然在 WildFly 发行版中，您可以热部署自定义提供程序，将数据库供应商更改为运行时配置，但这已不再受支持。

相反，Quarkus 发行版提供了一个单独的构建步骤来优化运行时。这里需要注意的重要一点是，构建步骤实际上并没有构建 Keycloak 源代码，而只是通过增强过程优化运行时，这个过程相当快，并且能够充分优化加载到运行时的内容。

我们建议您将此构建步骤作为安装 Keycloak 的一部分，通过 CI，或通过创建扩展基本 Keycloak 镜像的自定义容器镜像来完成。

然而，也有一种自动构建模式，使 Keycloak 在这方面或多或少与 WildFly 发行版表现相同。这会带来启动时间上的损失，但仍然能够比 WildFly 发行版更好地优化运行时。

Keycloak Wildfly 发行版包含名为 add-user-keycloak.sh 的脚本，用于向 Keycloak 添加初始用户。这些脚本不再包含在 Quarkus 发行版中。

要添加初始管理员用户，请为用户的用户名和密码设置环境变量 KC_BOOTSTRAP_ADMIN_USERNAME 和 KC_BOOTSTRAP_ADMIN_PASSWORD。Keycloak 在首次启动时使用它们来创建具有管理权限的初始用户。一旦存在第一个具有管理权限的用户，请使用命令行工具 kcadm.sh (Linux) 或 kcadm.bat (Windows) 创建其他用户。

默认情况下，新的 Quarkus 发行版从上下文路径中删除了 /auth。要重新引入 /auth，请使用 http-relative-path 构建选项。例如

当指定相对路径时，仍然可以从根路径重定向到相对路径。具体来说，当用户访问 localhost:8080/ 时，页面将重定向到 localhost:8080/auth。

与 WildFly 发行版类似，自定义提供程序通过复制到部署目录来部署到 Keycloak。在新的发行版中，您应该将您的提供程序复制到 providers 目录，而不是不再存在的 standalone/deployments 目录。其他依赖项也复制到 providers 目录。

在新的发行版中，自定义提供程序不再有单独的类路径，因此您可能需要更加注意您包含的其他依赖项。此外，EAR 打包格式和 jboss-deployment-structure.xml 文件不再受支持。

虽然 WildFly 发行版自动发现自定义提供程序，甚至支持在 Keycloak 运行时热部署自定义提供程序，但这已不再受支持，并且当您更改 providers 目录中的提供程序或依赖项时，您必须在之后执行构建，或者使用自动构建功能重启服务器。

根据您的提供程序使用的 API，您可能还需要对提供程序进行一些更改。如果您只使用了 Keycloak SPI 中的类，您应该不需要这样做，但是如果您使用了 WildFly 中的其他 API，您可能需要进行一些更改。此外，不再支持 JavaEE API，例如 session/stateless beans。

要在 Kubernetes 和 OpenShift 上使用 Quarkus 发行版，您需要使用新的 Operator，旧的 Operator 不支持新的发行版。

没有“直接”迁移路径，要使用新的 Operator 安装 Keycloak，您需要创建一个新的自定义资源 (CR)，以获得基于 Quarkus 发行版的新 Keycloak 部署。

新旧 Operator 可以共存，即使在同一命名空间中，因为它们在 CRD 中使用不同的 API Group 和 Version。

对于旧的 Operator，apiVersion 是

对于新的 Operator，apiVersion 是

当使用 kubectl 命令，并且集群中安装了 2 个 CRD 时，请确保使用完全限定的名称，包括 API Group，例如

新的 Operator 不直接支持 Client、User 和 Realm CRD。相反，它提供一个 CRD 来执行 Realm 导入。使用这个新的 CR，您可以通过包装 Realm 导入用户、客户端等。

在 Quarkus 中，当使用 Hostname V1 功能时，X-Forwarded-Port 标头优先于 X-Forwarded-Host 中包含的任何端口。这与 WildFly 发行版不同，在 WildFly 发行版中，X-Forwarded-Host 中包含的端口优先于 X-Forwarded-Port。