10.2. 配置缓存
Red Hat build of Keycloak 提供了一个缓存配置文件，该文件位于 conf/cache-ispn.xml。
缓存配置是常规 Infinispan 配置文件。
下表提供了红帽构建的 Keycloak 使用的特定缓存概述。您可以在 conf/cache-ispn.xml 中配置这些缓存：
| 缓存名称 | 缓存类型 | 描述 |
|---|---|---|
| realms | Local | 缓存持久的域数据 |
| users | Local | 缓存持久的用户数据 |
| 授权 | Local | 缓存持久的授权数据 |
| keys | Local | 缓存外部公钥 |
| work | 复制 | 在节点间传播无效消息 |
| authenticationSessions | 分布式 | 缓存身份验证会话，在身份验证过程中创建/销毁/过期 |
| 会话 | 分布式 | 缓存持久的用户会话数据 |
| clientSessions | 分布式 | 缓存持久的客户端会话数据 |
| offlineSessions | 分布式 | 缓存保留离线用户会话数据 |
| offlineClientSessions | 分布式 | 缓存保留离线客户端会话数据 |
| loginFailures | 分布式 | 跟踪失败的登录、欺诈检测 |
| actionTokens | 分布式 | 缓存操作令牌 |
10.2.1. 缓存类型和默认值
本地缓存
红帽 Keycloak 的构建会在本地缓存持久数据，以避免对数据库进行不必要的往返。
使用本地缓存将以下数据保存在集群中的每个节点中：
- 域和 相关数据，如客户端、角色和组。
- 用户和 相关数据，如授权角色和组成员身份。
- 授权和 相关数据，如资源、权限和策略。
- keys
域、用户和授权的本地缓存配置为默认容纳最多 10,000 个条目。本地密钥缓存每默认值最多可容纳 1,000 个条目，默认为每小时过期。因此，密钥会被强制从外部客户端或身份提供程序定期下载。
为了实现最佳运行时并避免对数据库的额外往返，您应该考虑查看每个缓存的配置，以确保最大条目数与数据库的大小一致。您可以缓存更多条目，通常服务器需要从数据库获取数据。您应该评估内存利用率和性能之间的利弊。
本地缓存无效
本地缓存提高了性能，但在多节点设置中添加了一个挑战。
当一个红帽构建的 Keycloak 节点更新共享数据库中数据时，所有其他节点都需要了解它，因此它们会导致数据从其缓存中无效。
工作 缓存是一种复制缓存，用于发送这些失效消息。这个缓存中的条目/消息非常短，您不应该预期这个缓存的大小会随时间增长。
身份验证会话
每当用户尝试进行身份验证时，都会创建身份验证会话。身份验证过程完成后或达到其过期时间后会自动销毁。
authenticationSessions 分布式缓存用于存储身份验证会话，以及在身份验证过程中与其关联的任何其他数据。
通过依赖可分布式缓存，身份验证会话可供集群中的任何节点使用，以便用户可以重定向到任何节点，而不会丢失其身份验证状态。但是，生产环境就绪的部署应始终考虑会话关联，而是将用户重定向到初始创建会话的节点。通过这样做，您要避免节点间不必要的状态传输，并改进 CPU、内存和网络利用率。
用户会话
经过身份验证后，将创建一个用户会话。用户会话跟踪您的活跃用户及其状态，以便他们可以无缝地向任何应用程序进行身份验证，而无需再次要求其凭证。对于每个应用程序，用户使用客户端会话进行身份验证，以便服务器可以根据应用程序跟踪用户通过 进行身份验证的应用程序及其状态。
当用户执行注销时，用户和客户端会话都会自动销毁，客户端会执行令牌撤销，或者因为达到它们的过期时间而被销毁。
会话数据默认存储在数据库中，并按需载入到以下缓存：
-
会话 -
clientSessions
通过依赖可分布式缓存，缓存的用户和客户端会话可供集群中的任何节点使用，以便用户可以重定向到任何节点，而无需从数据库加载会话数据。但是，生产环境就绪的部署应始终考虑会话关联，而是将用户重定向到初始创建会话的节点。通过这样做，您要避免节点间不必要的状态传输，并改进 CPU、内存和网络利用率。
对于用户会话和客户端会话的内存缓存，默认为每个节点，10000 个条目会减少红帽构建的 Keycloak 的总内存用量。内部缓存将只为每个缓存条目使用一个所有者运行。考虑在内存消耗和数据库利用率之间权衡，并为缓存设置不同的大小，编辑 Keycloak 的缓存配置文件(conf/cache-ispn.xml)来为这些缓存设置 < ;memory max-count="..."/& gt;。
volatile 用户会话
默认情况下，用户会话存储在数据库中，并按需加载到缓存中。可以将红帽构建的 Keycloak 配置为仅将用户会话存储在缓存中，并最小化数据库利用率。
由于此设置中的所有会话都存储在内存中，因此与此相关的两个副作用：
- 当所有红帽构建的 Keycloak 节点重启时，丢失会话。
- 增加了内存消耗。
按照以下步骤启用此设置：
由于缓存是用户和客户端会话的唯一来源，因此请将缓存配置为不限制条目数量，并将每个条目复制到至少两个节点。要做到这一点，编辑带有以下更新的缓存配置文件的红帽构建的 Keycloak 的缓存配置文件(
conf/cache-ispn.xml)：-
删除 &
lt;memory max-count="..."/> -
将
distributed-cache标签的owners属性更改为 2 或更多
为
会话缓存生成的配置示例如下所示：<distributed-cache name="sessions" owners="2"> <expiration lifespan="-1"/> </distributed-cache>-
删除 &
使用以下命令禁用
persistent-user-sessions功能：bin/kc.sh start --features-disabled=persistent-user-sessions ...
启用 多站点功能时，无法禁用 。
persistent- user-sessions
离线用户会话
作为 OpenID Connect Provider，服务器还可以对用户进行身份验证并发出离线令牌。与普通用户和客户端会话类似，当服务器在成功身份验证时由服务器发出离线令牌时，服务器还会创建离线用户会话和离线客户端会话。
以下缓存用于存储离线会话：
- offlineSessions
- offlineClientSessions
与普通用户和客户端会话缓存类似，默认情况下，离线用户和客户端会话缓存会限制为每个节点有 10000 个条目。根据需要，从内存驱除的项目将从数据库根据需要加载。考虑在内存消耗和数据库利用率之间权衡，并为缓存设置不同的大小，编辑 Keycloak 的缓存配置文件(conf/cache-ispn.xml)来为这些缓存设置 < ;memory max-count="..."/& gt;。
密码过期强制检测
loginFailures 分布式缓存用于跟踪失败登录尝试的数据。对于在多节点红帽构建的 Keycloak 设置中工作，Brute Force Protection 功能需要这个缓存。
操作令牌
当用户需要异步确认操作（例如，忘记密码流发送的电子邮件中）时，可以使用操作令牌。actionTokens 分布式缓存用于跟踪有关操作令牌的元数据。
10.2.2. 配置缓存最大大小
为了减少内存用量，可以将上限放在存储在给定缓存中的条目数。要在缓存上指定 的上限，您必须提供以下命令行参数 --cache-embedded-${CACHE_NAME}-max-count=，用 ${CACHE_NAME} 替换要应用上限的缓存名称。例如，要将上限 1000 应用到 offlineSessions 缓存，您需要 configure --cache-embedded-offline-sessions-max-count=1000。在以下缓存上不能定义上限： actionToken,authenticationSessions,loginFailures,work。
10.2.3. 为可用性配置缓存
分布式缓存在集群的节点上复制缓存条目，并将条目分配给固定所有者节点。
每个分布式缓存，这是数据的主要来源(authenticationSessions,loginFailures 和 actionTokens)默认有两个所有者，这意味着两个节点具有特定缓存条目的副本。非所有者节点查询特定缓存的所有者来获取数据。当两个所有者节点都离线时，所有数据都会丢失。
默认所有者数量足以在至少三个节点的群集设置中保留 1 个节点（所有者）故障。您可以自由地相应地更改所有者数量，以更好地满足您的可用性要求。要更改所有者数，打开 conf/cache-ispn.xml，并将分布式缓存的 owners=<value > 的值改为您所需的值。
10.2.4. 指定您自己的缓存配置文件
要指定您自己的缓存配置文件，请输入以下命令：
bin/kc.[sh|bat] start --cache-config-file=my-cache-file.xml
配置文件相对于 conf/ 目录。
10.2.5. 远程服务器的 CLI 选项
为了配置红帽构建的 Keycloak 服务器配置，以实现高可用性和多节点集群设置，包括以下 CLI 选项 cache-remote-host、cache-remote-port、cache-remote-username 和 cache-remote-password 简化 XML 文件中的配置。一旦出现任何声明的 CLI 参数，则 XML 文件中没有与远程存储相关的配置。
10.2.5.1. 连接到不安全的 Infinispan 服务器
不建议在生产环境中禁用安全性！
在开发或测试环境中，启动不安全的 Infinispan 服务器更容易。对于这些用例，CLI 选项 cache-remote-tls-enabled 会禁用红帽构建的 Keycloak 和 Data Grid 之间的加密(TLS)。如果 Data Grid 服务器被配置为只接受加密的连接，则 Red Hat build of Keycloak 无法启动。
CLI 选项 cache-remote-username 和 cache-remote-password 是可选的，如果未设置，红帽构建的 Keycloak 将连接到 Data Grid 服务器，而无需提供任何凭证。如果 Data Grid 服务器启用了身份验证，红帽构建的 Keycloak 将无法启动。
