#自定义主题

Keycloak 主题控制登录页面、账户控制台、管理控制台和电子邮件模板的外观与风格。本指南介绍如何在由 Kubernetes Operator 管理的部署中自定义主题。

#主题类型

#选择主题

要在内置主题之间切换：

1. 在管理控制台中，转到 Realm Settings > Themes 选项卡。
2. 为每种类型（Login、Account、Admin、Email）选择所需的主题。
3. 单击 Save。

内置主题包括 keycloak（默认）和 keycloak.v2（用于新的账户控制台）。

#创建自定义主题

自定义主题是一个目录（或 JAR 归档），其中包含用于覆盖或扩展基础主题的文件。

#主题目录结构

my-custom-theme/
└── login/                      # Theme type (login, account, admin, email)
    ├── theme.properties        # Theme configuration
    ├── resources/
    │   ├── css/
    │   │   └── custom.css      # Custom stylesheets
    │   └── img/
    │       └── logo.png        # Custom logo
    ├── messages/
    │   ├── messages_en.properties  # English text overrides
    │   └── messages_zh.properties  # Chinese text overrides
    └── login.ftl               # Custom FreeMarker login page template (optional)

#theme.properties

# Inherit from the default Keycloak theme
parent=keycloak
import=common/keycloak

# Add custom stylesheet
styles=css/custom.css

# Set custom logo (overrides the Keycloak logo)
# kcLogoLink=https://my-company.example.com

#自定义 CSS 示例

创建 resources/css/custom.css：

/* Override the login page background */
.login-pf body {
    background-color: #1a1a2e;
}

/* Override the login card */
#kc-login {
    background: #ffffff;
    border-radius: 8px;
}

/* Custom logo size */
#kc-logo-wrapper img {
    max-height: 60px;
}

#覆盖文本标签

创建 messages/messages_en.properties：

loginAccountTitle=Sign in to My Company
loginTitle=Welcome
loginTitleHtml=Welcome to <strong>My Company</strong>

#在 Kubernetes 中部署主题

在由 Kubernetes Operator 管理的部署中，必须让自定义主题可供 Keycloak Pod 使用。建议构建自定义容器镜像。基于 ConfigMap 的替代方案仅适用于开发和测试。

#选项 A：自定义 Keycloak 镜像（生产环境推荐）

构建预安装主题的自定义容器镜像：

FROM quay.io/keycloak/keycloak:26.7.4

# Copy custom theme
COPY my-custom-theme /opt/keycloak/themes/my-custom-theme

# Rebuild Keycloak with the theme — include any build-time options here
RUN /opt/keycloak/bin/kc.sh build \
  --health-enabled=true \
  --metrics-enabled=true

构建并推送镜像：

docker build -t my-registry.example.com/keycloak-custom:26.7.4 .
docker push my-registry.example.com/keycloak-custom:26.7.4

更新 Keycloak CR 以使用自定义镜像：

spec:
  image: my-registry.example.com/keycloak-custom:26.7.4

#选项 B：ConfigMap（仅限开发和测试）

在开发期间进行快速迭代时，可以通过 ConfigMap 和 unsupported.podTemplate 字段挂载主题：

1. 将主题目录打包到 ConfigMap 中：

   kubectl create configmap keycloak-custom-theme \
     --from-file=my-custom-theme/ \
     -n <namespace>

2. 通过 Keycloak CR 将 ConfigMap 挂载到 Keycloak Pod 中：

   spec:
     unsupported:
       podTemplate:
         spec:
           containers:
             - volumeMounts:
                 - name: custom-theme
                   mountPath: /opt/keycloak/themes/my-custom-theme
           volumes:
             - name: custom-theme
               configMap:
                 name: keycloak-custom-theme

3. 应用更新后的 CR，并等待 Pod 重启。

4. 在管理控制台中，转到 Realm Settings > Themes，然后选择 my-custom-theme。

#自定义电子邮件模板

电子邮件模板使用 FreeMarker（.ftl）语法，并属于 email 主题类型。

#覆盖电子邮件模板

1. 在自定义主题中，创建 email/html/ 和 email/text/ 目录。
2. 从默认主题复制要自定义的模板。
3. 修改模板内容。

常用电子邮件模板：

#自定义电子邮件消息

在 messages/messages_en.properties 中覆盖电子邮件主题和正文文本：

emailVerificationSubject=Verify your My Company account
passwordResetSubject=My Company - Password Reset

#国际化（i18n）

Keycloak 主题通过消息属性文件支持多种语言。

1. 在 Realm Settings > Localization 选项卡中启用国际化。
2. 添加支持的区域设置。
3. 在自定义主题中，为每个区域设置创建消息文件：
   • messages/messages_en.properties
   • messages/messages_zh_CN.properties
   • messages/messages_ja.properties
4. 在 Realm 设置中设置默认区域设置。