如何从 Keycloak 的 keycloak-themes.jar 中提取原生主题并自定义设置

言简意赅的讲解keycloak-themes.jar解决的痛点

在部署和自定义 Keycloak主题时你可能遇到了没有原生主题代码的难点，后续在Keycloak官方项目中获取原生主题文件还是无法找到主题源码。

下面这篇文章将向你展示，在某些 Keycloak 发行版本或特定部署方式下，如果默认的 /opt/keycloak/themes 文件夹里并没有包含所有原生主题（或根本没有），那么如何从 keycloak-themes-{version}.jar 中获取这些原生主题，并将它们解压到正确的位置。

为什么需要从 JAR 中提取原生主题？

在 Keycloak 17+ （基于 Quarkus 发行）的版本中，有时我们会发现位于 /opt/keycloak/themes 下的默认主题并不完整，甚至为空。这是因为部分主题资源可能已经被打包在 lib 目录下的 jar 文件中，而不会以明文形式直接出现在 /opt/keycloak/themes 里。如果你想对主题进行自定义、调试或学习，那么从这些 jar 中提取原生主题文件就成了必须要做的事情。

原生主题所在的文件位置

默认情况下，Keycloak 的原生主题会打包在 keycloak-themes-{version}.jar 文件里。该文件通常位于：

/opt/keycloak/lib/lib/main/keycloak-themes-{version}.jar

注意：

有些 Keycloak Docker 镜像或操作系统包版本，其目录结构可能略有差异，可能放在 /opt/keycloak/lib/ 下的其他子目录里。

{version} 对应的是 Keycloak 的具体版本号，比如：keycloak-themes-22.0.5.jar。

提取步骤

以下以在本地或在容器内操作为例，讲解如何进行提取。

步骤 1：进入 Keycloak 容器（如果是在容器化环境）

如果你是在 Docker/Kubernetes 容器中运行 Keycloak，需要先进入容器：

bash 复制代码

# Docker
docker exec -it <keycloak-container-name> /bin/bash

# 或者 Podman
podman exec -it <keycloak-container-name> /bin/bash

如果你的 Keycloak 是直接安装在操作系统上，可直接操作宿主机中的 /opt/keycloak/ 目录，无需此步骤。

步骤 2：定位 keycloak-themes-{version}.jar

通过 ls 命令找到对应的 themes jar：

bash 复制代码

cd /opt/keycloak/lib/lib/main
ls -l

在输出的文件列表中，你应当能看到类似 keycloak-themes-22.0.5.jar（版本号只是示例）的文件。

步骤 3：创建/确认 /opt/keycloak/themes 目录

如果你想把解压出来的主题放回到默认 Keycloak 主题文件夹中，确保 /opt/keycloak/themes 目录存在，否则创建它：

bash 复制代码

mkdir -p /opt/keycloak/themes

步骤 4：解压 Jar 文件

使用 unzip 或者 jar xf 命令，将原生主题解压到 /opt/keycloak/themes 目录下。例如：

bash 复制代码

unzip /opt/keycloak/lib/lib/main/keycloak-themes-22.0.5.jar -d /opt/keycloak/themes

或者：

bash 复制代码

cd /opt/keycloak/themes
jar xf /opt/keycloak/lib/lib/main/keycloak-themes-22.0.5.jar

解压完成后，你就可以在 /opt/keycloak/themes/ 看到 base, keycloak, rh-sso 等主题文件夹（具体目录名称依版本而异）。

配置并启用主题

在成功解压主题后，你可以通过以下方式指定你要使用的主题：

修改 standalone[-ha].xml 或 keycloak.conf 等配置文件

在 Quarkus 版 Keycloak 中，常见的配置选项是通过 keycloak.conf 或环境变量来进行。例如：
properties 复制代码
```
# 如果你想使用自定义主题（比如 base），可以在 keycloak.conf 中添加
quarkus.theme.type=keycloak
quarkus.theme.dir=base
```
在 Admin Console 中指定

登录 Keycloak Admin Console，进入 Realm Settings > Themes ，将 Login Theme、Account Theme、Admin Console Theme 等切换为你想要启用的主题名称（比如 base、keycloak 等）。

小结

有时，在升级或安装新的 Keycloak 发行版本后，你可能发现原本在 /opt/keycloak/themes 中的主题文件缺失或不完整，这是因为官方在 Keycloak 17+ Quarkus 版本中将许多资源进行了打包。如果你打算对原生主题进行定制，或者只是在学习如何写 Keycloak 主题，那么可以按照本文介绍的方式，在 /opt/keycloak/lib/lib/main/keycloak-themes-{version}.jar 中手动解压出原生主题文件。

通过上述步骤，你就能拿到最原始、可修改的 Keycloak 主题文件，然后即可开始自由地定制登录页、账户管理界面或管理员控制台的样式与布局。

通过上述内容，你就已经基本理解了这个方法，基础用法我也都有展示。如果你能融会贯通，我相信你会很强

Best

Wenhao (楠博万)