Keycloak.X 发行版介绍

2020 年 12 月 16 日，Keycloak 团队发布

世界变化很快，IT 一直是其重要的引擎。随着公司开始将其基础设施迁移到云端，安全性成为此旅程成功的关键因素。

我们很自豪地宣布，Keycloak 现在运行在 Quarkus 之上，Quarkus 是一个 Kubernetes 和云原生堆栈，它使用了最好的 Java 库和标准，为我们的用户提供了一个云友好的发行版，该发行版非常注重可用性、可伸缩性，并针对在混合云中运行进行了优化。

这个新发行版格式也称为 Keycloak.X，它提供了

为什么选择 Quarkus？

Keycloak 本质上是一个 Java 应用程序，目前运行在 Wildfly (JEE) 应用程序服务器之上。到目前为止，我们一直以这种方式发布 Keycloak 服务器以供通用。

虽然 Wildfly 可能是经过最佳优化、易于使用且性能最佳的 JEE 应用程序服务器，但我们现在对以更云原生方式运行的需求推动我们向前发展，Quarkus 作为一个 Java 和容器优先的堆栈，为 Keycloak 提供了更自然的方式，使其具备所有功能，从而使 Quarkus 非常适合在混合云中运行，并专注于 Kubernetes 和 Openshift 等平台。

有关 Quarkus 的更多信息，请访问其网站 https://quarkus.io/。

关注可用性

在 Quarkus 上，Keycloak 是一个常规的 Java 应用程序，与 Wildfly 发行版相比，堆栈要简单得多。

使用新的发行版，用户在配置和启动服务器以及执行其他常见操作时，应该会获得更好的体验。

引入丰富的命令行界面使安装和使用 Keycloak 变得更加容易。

更小

该发行版更简单，只有几个目录，并且发行版的总大小几乎是当前基于 WildFly 的发行版的一半。

通过利用 Quarkus，Keycloak 显着缩短了服务器启动时间、内存占用（低 RSS），并通过 Vert.x 提高了运行时性能。

当部署在混合云中时，所有这些方面都很重要，在混合云中应优化资源使用，以提供最佳的运行时环境并降低成本。

容器优先和云原生发行版

与 Keycloak Operator 结合使用，将 Keycloak 部署到混合云应该会更容易。

启动一个简单的容器也是如此。

开发者体验

Quarkus 为开发人员提供了一个丰富的生态系统，其中令人印象深刻地集成了各种库。

灵活性可能是 Keycloak 的主要特性之一，借助 Quarkus，我们希望为开发人员提供更好的体验。

安装

从 https://keycloak.com.cn/downloads 下载并解压 Keycloak.X 发行版 zip 或 tar.gz 文件。

目录结构

bin 目录是所有二进制文件所在的位置，基本上是新的 Keycloak CLI 和一些其他实用程序。

conf 目录，顾名思义，是配置文件所在的位置。您可能会使用此目录中的 keycloak.properties 文件来配置服务器，也可能不使用。稍后当我们详细讨论配置时，您将了解更多信息。

providers 目录是您应该部署包含自定义提供程序或主题 jar 的 JAR 文件的位置。

命令行界面

我们的主要要求之一是改善用户体验，无论是在首次使用服务器时，还是在服务器在生产环境中长期运行时。

人们通常在服务器上执行的常见操作更容易执行，并且通过提供良好的默认值并仅需最少的选项即可运行服务器，配置应该更简单。

Keycloak CLI 是您现在应该使用的工具，用于启动和更改服务器的配置。与任何其他 CLI 一样，它具有自描述性，并附带有关其用法的良好文档。

通过运行

kc.sh --help

您现在可以查看可以执行的不同操作，例如启动服务器或导出 realm，以及浏览可以为每个支持的命令设置的不同配置选项。

我们一直在寻求改进 CLI。如果您认为有任何建议可能会有所帮助，请随时与我们联系。

启动服务器

如前所述，默认配置对服务器的启动方式施加了一些条件。

成功启动服务器的主要条件之一是配置 HTTPS。

但是，出于开发目的，Keycloak 可以以开发模式启动。

目前，此模式基本上是一个配置配置文件，允许您在不使用 HTTPS 的情况下使用本地缓存运行服务器。

kc.sh start-dev

执行上述命令后，服务器应可在 http://localhost:8080/ 上访问。

将来，此模式还将放宽某些 realm 的配置策略，否则这些策略在生产环境中运行时将不允许使用。例如，将通配符用作客户端的有效重定向 URI。

配置服务器

考虑到 IAM 解决方案的重要性以及错误配置对部署整体安全性的影响，Keycloak 现在以尽可能最少的配置进行分发，并以默认安全策略为指导。

我们的想法是提供运行服务器的最基本配置选项，同时对在生产环境中运行之前应如何设置配置施加一些关键约束。

这是我们正在改进的主要领域之一，并且不断尝试改进，应通过一小组配置选项或良好的默认值来避免样板配置。

现在可以使用属性文件、环境变量或通过 Keycloak CLI 作为参数来设置不同的配置选项。

您可以通过运行 help 命令轻松检查可用的配置选项。

有关配置的更多详细信息，请查看 配置设计 文档。

配置类别

配置选项分为两类

  • 那些可以在启动服务器时在运行时设置的选项

  • 那些只能在通过 config 命令配置服务器时设置的选项

例如，如果您想将 HTTP 端口更改为 8180，您可以使用

kc.sh --http-port=8180

但是，要更改数据库，您需要先运行 config 命令，然后再启动服务器

kc.sh config --db=postgres --db-username=******* --db-password=*******
Kc.sh # then start the server

基本上，您在配置服务器时可以设置的任何配置选项也可以在启动服务器时设置，但反之则不然，数据库配置就是这样的一个例子。

查看 help 选项以检查可以为每个可用命令设置哪些属性。

HTTPS

在实际应用中，您将配置有效的密钥对和证书，但您可以使用以下命令生成自签名证书，以了解如何设置 HTTPS。

只需确保在发行版的根目录中执行以下命令

keytool -genkeypair -storepass password -storetype PKCS12 -keyalg RSA -keysize 2048 -dname "CN=server" -alias server -ext "SAN:c=DNS:localhost,IP:127.0.0.1" -keystore conf/server.keystore

上面的命令应在 conf 目录中创建一个 server.keystore 文件。默认情况下，如果未设置密钥和证书，Keycloak 将从此密钥库加载密钥和证书。

之后，您可以按如下方式运行服务器

kc.sh

数据库

数据库配置要简单得多。您只需几个简单的命令行参数即可更改数据库

kc.sh config --db=postgres && kc.sh --db-username=**** --db-password=****

对于每个数据库，我们为 JDBC URL、驱动程序、数据库名称和方言提供了良好的默认值。因此，如果您对默认值感到满意，则无需提供这些选项。

在上面的示例中，服务器连接到在 localhost 上运行的 PostgreSQL 服务，其中数据库名称为 keycloak。

当然，在生产环境中运行时，您通常需要自定义 JDBC URL 和其他参数，因此您可以按如下方式启动服务器

kc.sh --db-url=jdbc:postgresql://<host>/<database> \
      --db-username=****** \
      --db-password=******

或者仍然依赖默认的 JDBC URL，并按如下方式设置主机和数据库

kc.sh -Dkc.db.url.host=<host> \
      -Dkc.db.url.database=<database>
      --db-username=******
      --db-password=******

集群

目前，我们仍然使用 Infinispan 和 JGroups 进行集群和 HA 部署。

但是，配置现在使用 Infinispan 的原生配置，而不是像 Wildfly Infinispan 子系统那样使用抽象。这应该在配置、支持以及文档方面提供更大的灵活性。

配置也得到了简化，您应该为服务器部署的不同平台获得良好的默认值。

默认情况下，集群已启用，您可以准备好使用默认配置构建 Keycloak 集群。

默认配置位于 conf 目录中，文件名是 cluster-default.xml。

在同一目录中，您还有一个 cluster-local.xml 文件，该文件将所有缓存配置为本地缓存，不进行集群。要使用此配置，请运行以下命令

kc.sh --cluster=local

您可以通过在 conf 目录中创建一个带有 cluster- 前缀的文件来定义自己的缓存配置，就像我们随发行版一起提供的 cluster-local.xml 和 cluster-default 文件一样。

我们还为 Kubernetes 和 EC2 等特定平台提供了一些良好的默认值。例如，要在 Kubernetes 中运行集群，您可以运行以下命令

kc.sh -Djgroups.dns.query=<jgroups-ping-service>.<namespace>.<cluster-domain-suffix> --cluster-stack=kubernetes

这些平台的默认配置基于 Infinispan 提供的默认值。

在上面的示例中，Kubernetes 的默认配置将基于 UDP 进行节点通信，并基于 DNS_PING 进行节点发现。您可以用来自定义默认配置的任何参数都可以从 Infinispan 文档中获得。

自定义提供程序和主题

自定义提供程序和主题的 JAR 文件应放置在 providers 目录中。

但是，为了从安装自定义提供程序时的优化中获益，您应该首先运行 config 命令，然后再启动服务器

kc.sh config
kc.sh # then start the server

基本上，SPI 实现是在配置服务器时解析的，因此可以节省启动时间和启动期间的内存。一旦您运行 config 命令来安装您的自定义提供程序，它们将被静态链接到服务器中。

在容器中运行

要使用 Docker 运行 Keycloak，您可以使用以下命令

docker run --name keycloak -p 8080:8080  \
    -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me \
    quay.io/keycloak/keycloak-x \
    start-dev

正如预期的那样，容器将以开发模式运行。

您可以通过传递任何命令行参数，以与使用 Keycloak.X 发行版相同的方式运行服务器。

要使用您想要持久化到服务器镜像中的任何其他配置来配置容器，您可以使用 --auto-config 选项，如下所示

docker run --name keycloak -p 8080:8080 \
    -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me \
    quay.io/keycloak/keycloak-x \
    --auto-config \
    --db=postgres -Dkc.db.url.host=$DB_HOST --db-username=keycloak --db-password=change_me --http-enabled=true

上面的命令应该足以运行使用 PostgreSQL 数据库并在给定的 DB_HOST 上侦听的服务器。容器创建后，后续重启将不再经历配置阶段，而只是使用先前定义的配置启动服务器。

但是，建议始终基于此镜像创建您自己的镜像。通过这样做，您可以执行更多自定义操作，例如部署自定义提供程序或主题，以及通过消除配置步骤来缩短启动时间。

有关更多详细信息和示例，请参阅 https://github.com/keycloak/keycloak-containers/tree/master/server-x。

基准测试

以下是一些数字，用于简单比较在 Quarkus 和 Wildfly 上运行的 Keycloak。

这两个发行版都使用 OpenJDK 11、PostgreSQL 数据库运行，数字是每个发行版连续运行 10 次的平均值。

测试场景包括首次运行服务器以及数据库已初始化时运行服务器。

发行版

启动时间（秒）

内存占用（RSS/MB）

首次

第二次+

首次

第二次+

Wildfly

12.1

8.1

646

512

Quarkus

7.6

3.1

428

320

这些数字应该是不言自明的，人们应该期望这些数字在每个 Keycloak.X 版本中都会得到改善。

但是，这不仅仅是减少 MB，而是如何优化内存使用率。通过使用 64MB 堆运行两个服务器，您应该会注意到，当在 Wildfly 上运行时，您会进行大量的垃圾回收，最终可能导致服务器启动失败。而使用 Keycloak.X 使用相同的堆大小，您就可以拥有一个正在运行的服务器。当然，根据您的用例，使用此堆大小是不现实的，但这很好地说明了您从现在开始应该期待什么。

关于性能，在此首个版本中，我们的主要重点是启动时间和内存消耗。运行时性能正在进行中 (WIP)，并且由于 Keycloak.X 运行在 Vert.X 之上，因此结果令人鼓舞。

总的来说，我们仍处于旅程的开始阶段。一旦 Keycloak 在 Quarkus 上拥有原生发行版，我们可以期待更快的启动时间、更小的内存消耗以及总体上以更少的资源获得更好的性能。

路线图

这仅仅是我们为 Keycloak 用户提供更云友好体验的旅程的开始。

Keycloak.X 是一个预览发行版，在我们的社区的帮助下，我们正在不断改进它，直到它成为我们的主要发行版。我们感谢您在此旅程中的任何反馈。

正在进行许多重要的工作来补充 Keycloak.X 发行版，例如

  • 零 downtime 升级

  • 原生镜像支持

  • 改善开发者体验

  • 更多文档

我们希望请求您的支持和反馈，以不断改善您使用 Keycloak 的体验。

感谢社区

这是社区共同努力的结果，因此我们要强调并感谢我们收到的所有贡献。

特别感谢

以及所有为 配置设计文档 提供帮助的人。

参考