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

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

👋 欢迎来到 Stackhero 文档！

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

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

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

打开 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 design system，大多数颜色变量以 --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 base email theme 复制所需模板到 default/email/html/，然后编辑副本。

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

需要重置主题时

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

您的 realm、用户和 client 数据都保存在数据库中，不受影响。