部署自定义Keycloak身份提供者插件后HTML资源无法显示求助

核心原因 #

Keycloak 17+基于Quarkus重构后，主题资源加载机制与旧版WildFly架构不同，插件中打包的HTML资源无法自动被识别，必须通过额外的主题构建步骤完成资源整合。

具体解决方案 #

1. 确认插件资源路径正确性 #

检查你的bio-identity-provider-keycloak.jar内部结构，确保HTML文件的最终路径为：
META-INF/resources/theme-resources/partials/
若打包时路径错误，需调整项目中资源文件的存放位置后重新打包。

2. 执行主题构建命令 #

在Docker容器内，完成插件部署和kc.sh build后，必须执行主题构建命令提取插件中的主题资源：

kc.sh theme build

该命令会扫描/opt/keycloak/providers目录下的所有插件Jar，将其中的主题资源提取并合并到Keycloak的主题目录中。

3. 调整Docker启动流程 #

修改Docker启动脚本，按以下顺序执行操作：

• 将插件Jar复制到/opt/keycloak/providers目录
• 执行kc.sh build --db [你的数据库类型，如postgres/mysql]
• 执行kc.sh theme build
• 启动Keycloak服务：kc.sh start --optimized

4. 验证官方插件修复效果 #

对官方Apple、Discord插件，执行上述kc.sh theme build命令后重启容器，对应的HTML资源即可正常显示。

5. 应急方案：手动提取资源 #

若命令行构建不生效，可手动从插件Jar中提取HTML文件到对应主题目录：

# 进入容器终端
docker exec -it [容器ID] bash
# 从Jar中提取partials文件
unzip /opt/keycloak/providers/bio-identity-provider-keycloak.jar "META-INF/resources/theme-resources/partials/*" -d /tmp
# 复制到默认主题的partials目录
cp /tmp/META-INF/resources/theme-resources/partials/*.html /opt/keycloak/themes/base/admin/partials/

提示：若使用自定义主题，替换base/admin为你的主题路径。

关键说明 #

Keycloak 19.0.2的Quarkus版本中，插件主题资源不会自动加载，theme build是完成资源整合的必要步骤，这是与旧版架构的核心差异点。

内容的提问来源于stack exchange，提问作者Shamil Sungatullin