如何在Docker化Keycloak中为SPI添加外部依赖？

核心思路 #

你的问题本质是SPI依赖的jackson-datatype-jsr310与Keycloak自带的同库版本/包冲突，导致“依赖已存在”异常。针对Docker版Keycloak（当前主流为Quarkus架构版本），提供以下可行方案：

方案1：使用Provided Scope复用Keycloak自带依赖 #

Keycloak默认已包含jackson-datatype-jsr310，只需在SPI的Maven/Gradle配置中标记该依赖为provided，打包时不将其纳入SPI JAR，运行时直接使用Keycloak自带版本：

Maven配置示例

<dependency>
    <groupId>com.fasterxml.jackson.datatype</groupId>
    <artifactId>jackson-datatype-jsr310</artifactId>
    <!-- 版本建议与Keycloak自带版本一致，可从Keycloak官方文档或其pom.xml查询 -->
    <version>2.15.2</version>
    <scope>provided</scope>
</dependency>

Gradle配置示例

dependencies {
    implementation 'com.fasterxml.jackson.datatype:jackson-datatype-jsr310:2.15.2'
    provided 'com.fasterxml.jackson.datatype:jackson-datatype-jsr310:2.15.2'
}

打包SPI后，将JAR放入Docker容器的/opt/keycloak/providers目录（可通过自定义Docker镜像或挂载卷实现），启动Keycloak即可自动加载。

方案2：Shadow Jar重定位依赖包（解决版本冲突） #

如果必须使用与Keycloak自带版本不同的jackson-datatype-jsr310，可通过Maven Shade插件将依赖包重命名，避免包名冲突：

Maven Shade插件配置

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-shade-plugin</artifactId>
    <version>3.4.1</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>shade</goal>
            </goals>
            <configuration>
                <!-- 重定位jackson-jsr310的包路径 -->
                <relocations>
                    <relocation>
                        <pattern>com.fasterxml.jackson.datatype.jsr310</pattern>
                        <shadedPattern>your.custom.namespace.jsr310</shadedPattern>
                    </relocation>
                </relocations>
                <!-- 排除Keycloak已有的Jackson核心依赖，避免重复打包 -->
                <filters>
                    <filter>
                        <artifact>*:*</artifact>
                        <excludes>
                            <exclude>com.fasterxml.jackson.core:*</exclude>
                            <exclude>com.fasterxml.jackson.databind:*</exclude>
                        </excludes>
                    </filter>
                </filters>
            </configuration>
        </execution>
    </executions>
</plugin>

打包后得到的Shadow Jar会包含重命名后的依赖，与Keycloak自带库完全隔离，不会触发冲突。

方案3：自定义Docker镜像添加依赖 #

若需将外部依赖单独放入容器而非打包进SPI，可编写自定义Docker镜像：

Dockerfile示例

# 基于官方Keycloak镜像（替换为你使用的版本）
FROM quay.io/keycloak/keycloak:24.0.1

# 复制你的SPI插件JAR
COPY your-registration-spi.jar /opt/keycloak/providers/

# 复制外部依赖JAR（若未使用方案1/2，需手动下载对应版本的JAR）
COPY jackson-datatype-jsr310-2.15.2.jar /opt/keycloak/providers/

# 执行Keycloak构建命令，扫描并处理providers目录下的依赖
RUN /opt/keycloak/bin/kc.sh build

构建镜像并运行：

docker build -t custom-keycloak .
docker run -p 8080:8080 custom-keycloak start-dev

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