# Keycloak 登录主题

`themes/tjwater` 是 TJWater 智慧水务平台的 Keycloak 登录主题。主题继承
`keycloak.v2`，只覆盖样式、消息和本地 SVG 资源，不修改认证模板或认证流程。

## 在管理控制台切换登录主题

确认 `themes/tjwater` 已挂载到容器的
`/opt/keycloak/themes/tjwater`，然后按以下步骤切换：

1. 打开 Keycloak 管理控制台：
   `http://<Keycloak 地址>:<端口>/admin/`。
2. 使用管理员账号登录。
3. 在左上角选择需要应用主题的 realm，例如 `tjwater`。不要停留在
   `master`，除非确实要修改 `master` realm。
4. 在左侧菜单进入 `Realm settings`，打开 `Themes` 标签页。
5. 在 `Login theme` 下拉框中选择 `tjwater`。
6. 点击 `Save` 保存。
7. 继续检查业务客户端是否单独指定了登录主题，再从业务前端重新进入登录页。

切回 Keycloak 默认登录页时，将 `Login theme` 改为 `keycloak` 并保存。

### 检查业务客户端的主题配置

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

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

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

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

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

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

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

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

```bash
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
bash infra/docker/keycloak/configure-theme.sh apply
```

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

```bash
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
bash infra/docker/keycloak/configure-theme.sh verify
bash infra/docker/keycloak/configure-theme.sh rollback
```

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