如何配置Keycloak扩展开发环境？含调试、日志与热重载需求

云上老周

2026-7-17

Keycloak自定义RequiredActionProvider配置问题解决

问题背景

我通过实现org.keycloak.authentication.RequiredActionsProvider接口扩展Keycloak功能，使用Docker容器启动Keycloak时遇到以下问题：

Keycloak启动时未打印环境变量
容器仅输出ERROR级日志
无法用IntelliJ IDEA社区版调试自定义实现
希望实现代码修改后的组件热重载，替代当前mvn package+重启容器的流程

当前Docker Compose配置和Maven POM配置如下：

Docker Compose配置

version: '3.0'
services:
  keycloak:
    image: quay.io/keycloak/keycloak:${keycloak_version:-latest}
    environment:
      KC_HOSTNAME: auth.lvh.me
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: Password1#
      DEBUG: true
      PRINT_ENV: true
    ports: [ "8080:8080", "8787:8787" ]
    command: [ "start-dev", "--log-level", "DEBUG",  "--debug" ]
    volumes:
      - ./target:/opt/keycloak/providers
    working_dir: /opt/keycloak
    networks:
      default:
        aliases:
          - auth.lvh.me

Maven POM配置

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://maven.apache.org/POM/4.0.0" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.lrkwz.keycloak</groupId>
    <artifactId>keycloak-required-actions</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>jar</packaging>
    <properties>
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <keycloak.version>21.1.0</keycloak.version>
        <maven.compiler.version>3.10.1</maven.compiler.version>
        <maven.compiler.release>11</maven.compiler.release>
        <maven-shade.version>3.2.4</maven-shade.version>
        <maven-surefire.version>3.0.0-M9</maven-surefire.version>
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>com.github.dasniko</groupId>
                <artifactId>keycloak-spi-bom</artifactId>
                <version>${keycloak.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <dependencies>
        <dependency>
            <groupId>org.keycloak</groupId>
            <artifactId>keycloak-core</artifactId>
        </dependency>
        <dependency>
            <groupId>org.keycloak</groupId>
            <artifactId>keycloak-server-spi</artifactId>
        </dependency>
        <dependency>
            <groupId>org.keycloak</groupId>
            <artifactId>keycloak-server-spi-private</artifactId>
        </dependency>
        <dependency>
            <groupId>org.keycloak</groupId>
            <artifactId>keycloak-services</artifactId>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
        </dependency>
    </dependencies>

    <repositories>
        <repository>
            <id>jitpack.io</id>
            <url>https://jitpack.io</url>
        </repository>
    </repositories>

    <build>
        <finalName>${project.groupId}-${project.artifactId}</finalName>
        <pluginManagement>
            <plugins>
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-compiler-plugin</artifactId>
                    <version>${maven.compiler.version}</version>
                </plugin>
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-shade-plugin</artifactId>
                    <version>${maven-shade.version}</version>
                    <configuration>
                        <artifactSet>
                            <excludes>
                                <exclude>org.keycloak*</exclude>
                                <exclude>org.apache.httpcomponents:httpcore</exclude>
                            </excludes>
                        </artifactSet>
                    </configuration>
                    <executions>
                        <execution>
                            <goals>
                                <goal>shade</goal>
                            </goals>
                            <phase>package</phase>
                        </execution>
                    </executions>
                </plugin>
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-surefire-plugin</artifactId>
                    <version>${maven-surefire.version}</version>
                </plugin>
            </plugins>
        </pluginManagement>
    </build>
</project>

解决方案

1. 修复环境变量打印问题

Keycloak的PRINT_ENV环境变量仅在start命令下生效，start-dev模式不支持该变量。如需在开发模式下查看环境变量，修改Docker Compose的command，先执行打印命令再启动Keycloak：

command: [ "/bin/sh", "-c", "printenv && /opt/keycloak/bin/kc.sh start-dev --log-level DEBUG --debug" ]

2. 输出DEBUG级日志

--log-level DEBUG仅设置根日志级别，自定义SPI的日志需单独指定包级别：

修改Docker Compose环境变量：

environment:
  # 保留原有变量
  KC_LOG_LEVEL: DEBUG,com.lrkwz.keycloak:DEBUG

或在启动命令中细化：

command: [ "start-dev", "--log-level", "DEBUG,com.lrkwz.keycloak:DEBUG", "--debug" ]

自定义代码中使用SLF4J日志API：

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class CustomRequiredAction implements RequiredActionsProvider {
    private static final Logger logger = LoggerFactory.getLogger(CustomRequiredAction.class);
    
    @Override
    public void evaluateTriggers(KeycloakSession session, RealmModel realm, UserModel user) {
        logger.debug("自定义RequiredAction调试日志");
        logger.info("自定义RequiredAction信息日志");
    }
    // 其他方法实现
}

3. 配置IntelliJ IDEA社区版调试

步骤1：确认调试端口配置

修改Docker Compose的command，明确调试端口绑定：

command: [ "start-dev", "--log-level", "DEBUG", "--debug", "*:8787" ]

*:8787允许外部IDE连接容器的8787端口，启动容器后需确认日志输出Listening for transport dt_socket at address: 8787。

步骤2：创建远程调试配置

打开IntelliJ，进入Run > Edit Configurations
点击+，选择Remote JVM Debug
配置名称（如Keycloak Remote Debug），设置Host为localhost，Port为8787
选择Debugger mode为Attach to remote JVM，保存配置

步骤3：启动调试

点击IntelliJ调试按钮启动远程调试，在自定义代码中设置断点，触发对应逻辑即可命中断点。

4. 实现组件热重载

Keycloakstart-dev模式支持自动检测providers目录下的jar变化并重新加载，无需重启容器：

步骤1：调整Maven构建配置

用maven-jar-plugin快速构建开发包，保留maven-shade-plugin用于生产打包：

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-jar-plugin</artifactId>
            <version>3.3.0</version>
            <configuration>
                <archive>
                    <manifestEntries>
                        <Automatic-Module-Name>com.lrkwz.keycloak.requiredactions</Automatic-Module-Name>
                    </manifestEntries>
                </archive>
            </configuration>
        </plugin>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-shade-plugin</artifactId>
            <version>${maven-shade.version}</version>
            <configuration>
                <artifactSet>
                    <excludes>
                        <exclude>org.keycloak*</exclude>
                        <exclude>org.apache.httpcomponents:httpcore</exclude>
                    </excludes>
                </artifactSet>
            </configuration>
            <executions>
                <execution>
                    <id>shade-for-production</id>
                    <goals>
                        <goal>shade</goal>
                    </goals>
                    <phase>package</phase>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

步骤2：触发热重载

执行mvn compile或mvn jar:jar，新构建的jar会同步到容器/opt/keycloak/providers目录，Keycloak会自动检测变化并重新加载SPI组件。

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

如何配置Keycloak扩展开发环境？含调试、日志与热重载需求

问题背景 #

Docker Compose配置 #

Maven POM配置 #

解决方案 #

1. 修复环境变量打印问题 #

2. 输出DEBUG级日志 #

3. 配置IntelliJ IDEA社区版调试 #