配置分布式缓存

Keycloak 在本地缓存持久化数据，以避免不必要的数据库往返。

以下数据使用本地缓存保存在集群中的每个节点本地

realms、users 和 authorization 的本地缓存默认配置为最多保存 10,000 个条目。本地密钥缓存默认可以保存最多 1,000 个条目，并默认为每小时过期一次。因此，密钥会被强制定期从外部客户端或身份提供商处下载。

为了实现最佳运行时并避免额外的数据库往返，你应该考虑查看每个缓存的配置，以确保最大条目数与你的数据库大小对齐。你可以缓存的条目越多，服务器需要从数据库获取数据的频率就越低。你应该评估内存利用率和性能之间的权衡。

本地缓存提高了性能，但在多节点部署中增加了一个挑战。

当一个 Keycloak 节点更新共享数据库中的数据时，所有其他节点都需要意识到这一点，以便它们从其缓存中使该数据失效。

work 缓存是一个复制缓存，用于发送这些失效消息。此缓存中的条目/消息非常短暂，你不应期望此缓存的大小随时间增长。

每当用户尝试进行身份验证时，都会创建身份验证会话。一旦身份验证过程完成或由于达到其过期时间，它们将自动销毁。

authenticationSessions 分布式缓存用于存储身份验证会话以及在身份验证过程中与之关联的任何其他数据。

通过依赖可分布式缓存，身份验证会话可供集群中的任何节点使用，以便可以将用户重定向到任何节点而不会丢失其身份验证状态。但是，生产就绪型部署应始终考虑会话亲缘性，并倾向于将用户重定向到最初创建其会话的节点。通过这样做，你将避免节点之间不必要的状态转移，并提高 CPU、内存和网络利用率。

一旦用户通过身份验证，就会创建一个用户会话。用户会话跟踪你的活动用户及其状态，以便他们可以无缝地向任何应用程序进行身份验证，而无需再次被要求提供凭据。对于用户使用客户端会话进行身份验证的每个应用程序，服务器可以跟踪用户通过身份验证的应用程序及其在每个应用程序上的状态。

每当用户执行注销、客户端执行令牌撤销或由于达到其过期时间时，用户和客户端会话都会自动销毁。

会话数据默认存储在数据库中，并按需加载到以下缓存中

通过依赖可分布式缓存，缓存的用户和客户端会话可供集群中的任何节点使用，以便可以将用户重定向到任何节点，而无需从数据库加载会话数据。但是，生产就绪型部署应始终考虑会话亲缘性，并倾向于将用户重定向到最初创建其会话的节点。通过这样做，你将避免节点之间不必要的状态转移，并提高 CPU、内存和网络利用率。

这些用于用户会话和客户端会话的内存缓存默认限制为每个节点 10000 个条目，这减少了大型安装中 Keycloak 的总体内存使用量。内部缓存将为每个缓存条目仅运行一个所有者。考虑内存消耗与数据库利用率之间的权衡，并为缓存设置不同的大小，编辑 Keycloak 的缓存配置文件 (conf/cache-ispn.xml) 以为这些缓存设置 <memory max-count="..."/>。

默认情况下，用户会话存储在数据库中，并按需加载到缓存中。可以配置 Keycloak 仅将用户会话存储在缓存中，并最大限度地减少数据库利用率。

由于此设置中的所有会话都存储在内存中，因此存在两个与此相关的副作用

按照以下步骤启用此设置

作为 OpenID Connect 提供商，服务器还能够对用户进行身份验证并颁发离线令牌。与常规用户和客户端会话类似，当服务器在成功身份验证后颁发离线令牌时，服务器还会创建一个离线用户会话和一个离线客户端会话。

以下缓存用于存储离线会话

与常规用户和客户端会话缓存类似，离线用户和客户端会话缓存也默认限制为每个节点 10000 个条目。从内存中逐出的项目将在需要时按需从数据库加载。考虑内存消耗与数据库利用率之间的权衡，并为缓存设置不同的大小，编辑 Keycloak 的缓存配置文件 (conf/cache-ispn.xml) 以为这些缓存设置 <memory max-count="..."/>。

loginFailures 分布式缓存用于跟踪有关失败登录尝试的数据。此缓存是暴力破解保护功能在多节点 Keycloak 部署中正常工作所必需的。

操作令牌用于用户需要异步确认操作的场景，例如在忘记密码流程发送的电子邮件中。actionTokens 分布式缓存用于跟踪有关操作令牌的元数据。

为了减少内存使用量，可以对给定缓存中存储的条目数设置上限。要指定缓存的上限，你必须提供以下命令行参数 --cache-embedded-${CACHE_NAME}-max-count=，其中 ${CACHE_NAME} 替换为你想要应用上限的缓存名称。例如，要对 offlineSessions 缓存应用 1000 的上限，你可以配置 --cache-embedded-offline-sessions-max-count=1000。以下缓存无法定义上限：actionToken、authenticationSessions、loginFailures、work。

分布式缓存将缓存条目复制到集群中节点的一个子集，并将条目分配给固定的所有者节点。

每个分布式缓存，即数据的主要真实来源 (authenticationSessions、loginFailures 和 actionTokens)，默认情况下有两个所有者，这意味着两个节点具有特定缓存条目的副本。非所有者节点查询特定缓存的所有者以获取数据。当两个所有者节点都离线时，所有数据都会丢失。

默认的所有者数量足以在至少三个节点的集群设置中承受 1 个节点（所有者）的故障。你可以自由更改所有者的数量，以更好地满足你的可用性要求。要更改所有者的数量，请打开 conf/cache-ispn.xml 并将分布式缓存的 owners=<value> 值更改为你期望的值。

要指定你自己的缓存配置文件，请输入此命令

配置文件相对于 conf/ 目录。

为了配置 Keycloak 服务器以实现高可用性和多节点集群部署，引入了以下 CLI 选项 cache-remote-host、cache-remote-port、cache-remote-username 和 cache-remote-password，从而简化了 XML 文件中的配置。一旦存在任何声明的 CLI 参数，则表示 XML 文件中不存在与远程存储相关的配置。

下表显示了可用的传输堆栈，除了使用 --cache-stack 运行时选项外，无需任何其他配置

下表显示了可用的传输堆栈，它们使用 --cache-stack 运行时选项和最少配置

当使用 tcp、udp 或 jdbc-ping-udp 堆栈时，每个集群必须使用不同的多播地址和/或端口，以便它们的节点形成不同的集群。默认情况下，Keycloak 使用 239.6.7.8 作为 jgroups.mcast_addr 的多播地址，使用 46655 作为 jgroups.mcast_port 的多播端口。

尽管不建议用于标准设置，但如果在特定设置中至关重要，你可以手动配置包含传输堆栈证书的密钥库。cache-embedded-mtls-key-store-file 设置密钥库的路径，cache-embedded-mtls-key-store-password 设置解密密钥库的密码。信任库包含接受连接的有效证书，可以使用 cache-embedded-mtls-trust-store-file（信任库的路径）和 cache-embedded-mtls-trust-store-password（解密信任库的密码）进行配置。为了限制未经授权的访问，请始终为每个 Keycloak 部署使用自签名证书。