Keycloak 的 realm 和 client 都可以设置登录主题。client 的配置优先于 realm。因此，即使 Realm settings > Themes > Login theme 已选择 tjwater，业务客户端如果仍指定 keycloak，从业务系统跳转后看到的还是默认登录页。

以授权地址中包含 client_id=tjwater 的业务系统为例：

确认左上角当前 realm 是 tjwater。
在左侧菜单进入 Clients。
打开 Client ID 为 tjwater 的客户端。
在 Settings 页面找到 Login settings > Login theme。
将该字段设置为以下任一选项：
- Choose...：不在 client 层指定主题，继承 realm 的 tjwater 主题，推荐使用此方式。
- tjwater：在 client 层明确指定 tjwater 主题。
不要保留 keycloak，否则它会覆盖 realm 的主题。
点击 Save，关闭旧登录页，再从业务前端重新发起一次登录。

Choose... 不是未配置完成，而是表示当前 client 继承 realm 配置。管理控制台登录、账户中心和业务系统可能使用不同的 client。某一个入口已经显示 tjwater 主题，并不能证明业务 client 也已正确配置。

验证时以业务系统实际生成的 OpenID Connect 授权地址为准，并检查其中的 client_id。浏览器加载的主题资源路径应包含 /resources/<版本>/login/tjwater/；如果路径仍包含 /resources/<版本>/login/keycloak/，说明该 client 仍在使用默认主题。

如果 Login theme 下拉框中没有 tjwater，先检查容器内的主题文件：

docker compose \
  --env-file .env \
  -f infra/docker/docker-compose.yml \
  exec -T keycloak \
  test -f /opt/keycloak/themes/tjwater/login/theme.properties

命令成功但控制台仍未显示主题时，重新创建 Keycloak 容器后再检查：

docker compose \
  --env-file .env \
  -f infra/docker/docker-compose.yml \
  up -d --force-recreate keycloak

主题名称已经正确，但页面仍显示旧样式时，也执行上述命令，并在容器启动后使用 Ctrl+F5 强制刷新登录页，避免继续使用浏览器缓存的 CSS。

启用

先启动 infra/docker/docker-compose.yml 中的 Keycloak，再从仓库根目录执行：

bash infra/docker/keycloak/configure-theme.sh apply

脚本默认配置 tjwater realm、简体中文默认语言、中英文切换和 TJWater 智慧水务平台 品牌名，并清除 tjwater client 对登录主题的覆盖，使其继承 realm 主题。其他环境可临时覆盖：

TJWATER_KEYCLOAK_REALM=example \
TJWATER_KEYCLOAK_CLIENT_ID=example-web \
TJWATER_KEYCLOAK_DISPLAY_NAME="示例智慧水务平台" \
bash infra/docker/keycloak/configure-theme.sh apply

管理员凭据继续使用 Compose 已注入的 KC_BOOTSTRAP_ADMIN_USERNAME / KC_BOOTSTRAP_ADMIN_PASSWORD，并兼容现有的 KEYCLOAK_ADMIN / KEYCLOAK_ADMIN_PASSWORD。

验证与回滚

bash infra/docker/keycloak/configure-theme.sh verify
bash infra/docker/keycloak/configure-theme.sh rollback

使用 latest 镜像时，每次重新拉取 Keycloak 后都应重新执行 verify，并在 1280px、375px 和 320px 视口检查登录、错误提示、忘记密码和 OTP 页面。