Keycloak: 您的主题已可直接编辑

本文档属于自定义外观指南的一部分。您可以在此处查看完整指南：在 Stackhero 上轻松为您的 Keycloak 登录页面、账户控制台和邮件进行品牌定制：设置您的配色、Logo、文本，甚至可通过内置在线编辑器创建完整的自定义主题。。

👋 欢迎查阅 Stackhero 文档！

Stackhero 提供 Keycloak 云服务，让您仅需 2 分钟即可轻松部署一套可用于生产环境的身份认证服务：

• 无限量用户、realm 和 client
• 支持 OpenID Connect、OAuth 2.0、SAML 2.0、社交登录、LDAP 及 Active Directory 联邦
• 自定义域名，内置 HTTPS，保障安全访问（例如，https://login.your-company.com）
• 自定义主题：通过内置在线编辑器，轻松定制登录页面、账户控制台和邮件的品牌风格
• 专属 邮件服务器，支持 SPF、DKIM 和 DMARC，自动处理账户确认和密码重置
• 内置 PostgreSQL 数据库，管理控制台可通过独立端口访问并支持关闭
• 一键升级，系统自动保持最新，无需手动干预

专注于开发，而非配置：您可以在 5 分钟内体验 Stackhero 的 Keycloak 云解决方案。

打开 themes/，您会看到一个 default/ 目录。这就是当前正在使用的主题，已被您的 Keycloak 实例启用。无需选择，直接编辑其文件即可，修改会立即生效。

无需提前了解 Keycloak 主题机制。每个文件中都已列出常用的可配置项，并以注释形式展示当前 Keycloak 默认值。 若要修改，只需去掉注释符号，调整数值并保存。

如果某行仍为注释，Keycloak 会采用其默认值。这样可以确保您的服务始终与 Keycloak 标准行为保持一致，即使升级后也是如此。

更新您的 Logo

打开 default/login/resources/img/。其中包含当前登录页面使用的两张图片。请用相同文件名 keycloak-logo-text.svg 上传您的 Logo，然后用 Ctrl+F5（macOS 下为 Cmd+Shift+R）刷新登录页面。

这就是全部操作。无需编辑其他文件或重启服务，保存后即可生效。若要更换背景图片，只需更新同一目录下的 keycloak-bg-darken.svg。

如果您想使用不同的文件名，可以在 default/login/resources/css/stackhero.css 的“Your logo”部分修改引用。

设置您的配色方案

在 stackhero.css 文件中，您会看到已写好的变量及其当前值：

:root {
  /* ---------- Colors ---------- */
  /* The buttons */
  /* --pf-v5-global--primary-color--100: #06c; */
  /* The buttons, while hovered */
  /* --pf-v5-global--primary-color--200: #004080; */
  /* The links */
  /* --pf-v5-global--link--Color: #06c; */
  /* The colored line on top of the login box */
  /* --keycloak-card-top-color: #06c; */

要应用更改，只需去掉注释符号，设置您的颜色，保存并刷新页面即可。

操作提示： 您的浏览器会缓存主题的 CSS、图片和脚本，时长为一小时。调试时请始终用 Ctrl+F5 强制刷新，以便看到最新效果。您的访客将在一小时内看到更新。

您拥有完全控制权：该文件为标准 CSS，且最后加载，因此可以覆盖任何样式。可使用浏览器 DevTools（F12）检查元素。Keycloak 26 采用 PatternFly 设计系统，大多数颜色变量以 --pf-v5-global--* 命名，可在 :root 中重定义。

设置公司名称

无需编辑主题文件。在管理控制台中，进入 Realm settings > General，设置 Display name。该名称会显示在登录页面和邮件中。

多语言文本修改

无需修改 CSS 或 HTML 即可更改文本。在 default/login/messages/messages_en.properties 中，您会看到所有登录表单文本及其默认内容。要修改某行，去掉 #，输入您的文本并保存：

loginAccountTitle=Sign in to Acme
doLogIn=Sign in
doForgotPassword=I forgot my password

如需支持法语、德语等其他语言，可添加如 messages_fr.properties、messages_de.properties 等文件，然后在管理控制台的 Realm settings > Localization 启用对应语言。

提示：Localization 选项卡下还有 Realm overrides 区域，可直接在控制台内修改文本，无需编辑文件或重启。请根据您的工作流程选择合适方式。

邮件品牌定制

Keycloak 会发送邮件用于地址确认、密码重置和用户邀请。在 default/email/messages/messages_en.properties 中，您可以自定义标准主题和正文内容：

emailVerificationSubject=Confirm your Acme account
passwordResetSubject=Reset your Acme password

编辑邮件正文时请注意：

• 保留 {0}、{1}、{2} 占位符（Keycloak 会自动填充链接、显示名和延迟时间）。
• 单引号需用两个连续写法转义（如 don''t）。

如需自定义邮件 HTML，可从 Keycloak 基础邮件主题 复制所需模板到 default/email/html/，然后编辑副本。

Stackhero 已为您配置好邮件发送，包括 SPF、DKIM 和 DMARC。请在 Realm settings > Email 中，使用服务页面提供的主机和端口进行设置。

需要重置主题时

如遇问题，您可以删除整个 default 目录并重启服务。Stackhero 会自动生成全新默认主题，恢复 Keycloak 标准外观。

您的 realm、用户和客户端信息都存储在数据库中，不会受到影响。