105 lines
4.2 KiB
Markdown
105 lines
4.2 KiB
Markdown
# 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 页面。
|