Docker环境下Keycloak Prometheus Exporter配置问题求助

开发者阿泽

2026-5-11

我来帮你排查下当前配置的问题，再给你讲讲Docker环境下正确配置Keycloak metrics SPI的方法，还有其他适合的exporter选项。

问题排查：你的现有步骤哪里可能出错

容器文件系统临时特性：你手动把jar包复制到Docker容器内的providers目录，但容器重启后这个目录的修改会丢失——因为容器的文件系统是临时的，除非用卷挂载或者自定义镜像持久化配置。
缺少Provider安装步骤：Keycloak不会自动识别providers目录里的jar包，必须执行安装命令让它扫描并加载SPI。旧版Wildfly架构的Keycloak需要用jboss-cli.sh执行模块添加命令，新版Quarkus架构的Keycloak需要执行kc.sh build来完成provider的安装。你跳过了这一步，导致SPI根本没被加载。
路径错误：如果你的Keycloak是17及以上版本，官方已经移除了/auth前缀，正确的metrics路径应该是http://localhost/realms/master/metrics，而不是带/auth的旧路径。
监听器配置验证：你添加了metrics-listener作为事件监听器，但要确认是否点击了保存按钮，并且Keycloak是否重启过（加载SPI需要重启生效）。

Docker环境下正确配置aerogear metrics SPI的方法

推荐用自定义Docker镜像的方式，这样配置会持久化，容器重启也不会丢失。步骤如下：

确认版本兼容性：先检查你使用的Keycloak版本和aerogear的metrics SPI是否兼容，比如Quarkus架构的Keycloak（17+）需要对应版本的SPI，避免因为版本不匹配导致加载失败。
获取SPI jar包：要么直接从项目的release页面下载对应版本的jar，要么自己构建：
```
git clone <仓库地址>
cd keycloak-metrics-spi
./gradlew jar
```
构建完成后，jar包在/build/libs目录下。

编写Dockerfile：

# 替换成你正在使用的Keycloak镜像版本
FROM quay.io/keycloak/keycloak:24.0.1
# 复制SPI jar包到Keycloak的providers目录
COPY keycloak-metrics-spi.jar /opt/keycloak/providers/
# 执行build命令，让Keycloak安装这个provider
RUN /opt/keycloak/bin/kc.sh build

构建自定义镜像：

docker build -t custom-keycloak-with-metrics .

启动容器：

docker run -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  custom-keycloak-with-metrics start-dev

配置事件监听器：进入Keycloak GUI，依次进入管理 -> 事件 -> 配置，添加metrics-listener作为事件监听器并保存。
验证metrics：访问http://localhost/realms/master/metrics（如果是旧版Keycloak，用http://localhost/auth/realms/master/metrics），应该能看到Prometheus格式的metrics数据了。

如果只是临时测试，也可以用卷挂载的方式，不需要构建镜像：

# 把jar包放到宿主机的./providers目录下
docker run -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  -v ./providers:/opt/keycloak/providers \
  quay.io/keycloak/keycloak:24.0.1 start-dev --build

--build参数会让Keycloak启动前自动扫描providers并完成安装。

适合Docker环境的替代Exporter

如果aerogear的SPI和你的Keycloak版本不兼容，或者你不想修改Keycloak容器，可以试试基于API的独立Exporter：
这类Exporter不需要部署到Keycloak内部，而是作为单独的Docker容器运行，通过调用Keycloak的管理API来获取metrics，配置更灵活。你只需要启动Exporter容器，配置Keycloak的地址、管理员账号密码，然后让Prometheus抓取Exporter的metrics端口即可。这种方式不需要修改Keycloak的任何配置，对现有环境侵入性极低。

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