Keycloak Docker 沙箱 Java 原生容器编排：ProcessBuilder 驱动 docker-compose 的完整实践

作者： 必码｜ bima.cc

前言

Keycloak SPI 开发的容器化困境

Keycloak 作为全球领先的开源身份与访问管理（IAM）平台，凭借其完善的 OAuth 2.0、OpenID Connect、SAML 2.0 协议支持以及强大的单点登录（SSO）能力，已经成为企业级应用身份认证的事实标准。在 Keycloak 的生态体系中，SPI（Service Provider Interface）机制是其最核心的扩展能力——从用户存储、事件监听、密码策略到协议映射、加密算法，SPI 覆盖了身份认证的几乎所有维度。

然而，SPI 开发者在实际工作中面临着一个普遍却鲜少被讨论的痛点：开发环境的搭建与容器化部署之间的鸿沟。当开发者完成一个 SPI 扩展的编码和编译后，需要将其部署到 Keycloak 运行环境中进行验证。传统的部署方式要求开发者手动执行一系列 Docker 命令——拉取镜像、创建容器、挂载卷、配置环境变量、启动服务——每一步都可能出现因环境差异导致的问题。更糟糕的是，Keycloak 的版本迭代非常频繁（从 20.x 到 26.x，几乎每个大版本都引入 API 变更），当开发者需要在不同版本之间进行兼容性测试时，这些重复性的 Docker 操作将消耗大量宝贵的时间。

在团队协作场景中，这个问题更加突出。不同开发者的操作系统可能不同（Windows、macOS、Linux），Docker 的安装路径和配置方式各异，docker-compose 的可用性也不统一。缺乏标准化的容器编排方案，不仅降低了团队协作效率，也增加了持续集成的复杂度。

本文定位

本文基于 keycloak-sandbox 项目中的 keycloak-server-docker 模块，深入剖析如何使用 Java 原生的 ProcessBuilder API 驱动 docker-compose 实现完整的 Keycloak Docker 容器编排。这不是一篇简单的 "Docker 入门教程"，而是一次从架构设计到工程实践的深度探索。

我们将从以下几个维度展开讨论：

架构选择：为什么在 Docker Java 客户端库和 ProcessBuilder 之间选择了后者？这个选择背后的技术权衡是什么？
守护进程管理：如何可靠地检测 Docker 守护进程的状态？如何设计优雅的重试策略？
镜像生命周期：如何自动获取 Keycloak 版本号？如何智能地管理镜像的拉取和存在性检测？
编排文件动态生成：如何从 classpath 读取 docker-compose.yml 模板？如何动态注入版本号？
容器生命周期：如何自动清理残留容器？如何管理 providers 和 themes 目录的挂载？
服务就绪检测：如何通过 HTTP 健康检查确认服务可用？如何处理启动失败场景？
跨平台兼容：如何让同一份代码在 Windows、Linux、macOS 三个平台上无缝运行？

读者受众

本文面向以下读者群体：

Keycloak SPI 扩展开发者：希望了解如何将 SPI 开发与 Docker 容器化部署无缝集成的开发者
Java 容器编排工程师：对使用 Java 原生 API 驱动 Docker 容器编排感兴趣的技术人员
DevOps 工程师：希望了解如何通过编程方式管理 Docker 容器生命周期的运维人员
技术架构师：正在评估 Java 应用与 Docker 集成方案的技术决策者

阅读本文需要具备以下前置知识：

Java 基础编程能力（了解 ProcessBuilder、InputStream、NIO 等核心 API）
Docker 和 docker-compose 的基本使用经验
Maven 项目构建的基础知识
Keycloak 的基本概念和 SPI 机制的了解（非必需，但有助于理解上下文）

第一章 Java 驱动 Docker 的架构选择

1.1 Docker Java 客户端库 vs ProcessBuilder

在 Java 应用中驱动 Docker 操作，开发者通常面临两种主流方案的选择：

方案一：Docker Java 客户端库

docker-java（github.com/docker-java/docker-java）是目前最成熟的 Docker Java 客户端库，它通过 Docker Remote API 与 Docker 守护进程通信，提供了类型安全的 Java API 来管理容器、镜像、网络、卷等 Docker 资源。其核心优势包括：

类型安全：所有的 Docker 操作都封装为强类型的 Java 对象和方法调用
异步支持：支持同步和异步两种调用模式
功能完整：覆盖了 Docker CLI 的几乎所有功能
社区活跃：持续维护，与 Docker 版本保持同步

然而，docker-java 也有其不可忽视的局限性：

依赖重量级：引入 docker-java 会带来大量的传递依赖（包括 Jersey、Jackson、Apache HTTP Client 等），对于一个轻量级的工具模块来说，这些依赖显得过于沉重
版本耦合：docker-java 的版本需要与 Docker Engine 的版本保持兼容，当 Docker 版本升级时，可能需要同步升级客户端库
docker-compose 支持有限：docker-java 主要面向单容器操作，对 docker-compose 编排的支持不够完善
学习曲线：API 设计较为复杂，需要理解 Docker Remote API 的底层细节

方案二：ProcessBuilder（Java 原生）

ProcessBuilder 是 Java 标准库中用于创建操作系统进程的类，它允许 Java 程序直接执行系统命令。通过 ProcessBuilder 调用 docker 和 docker-compose 命令行工具，本质上与在终端中手动执行命令等价。其核心优势包括：

零外部依赖：完全基于 JDK 标准库，无需引入任何第三方依赖
行为一致：与手动执行 Docker 命令的行为完全一致，不存在 API 语义差异
docker-compose 原生支持：直接调用 docker-compose 命令，天然支持多容器编排
调试友好：可以直接看到执行的命令，便于排查问题

当然，ProcessBuilder 也有其不足之处：

缺乏类型安全：命令以字符串形式传递，编译期无法检查命令的正确性
输出解析繁琐：需要手动解析命令的输出流和错误流
错误处理原始：只能通过退出码和错误流来判断执行结果

1.2 为什么选择 ProcessBuilder

在 keycloak-server-docker 模块的设计中，我们最终选择了 ProcessBuilder 方案。这个决策并非出于对 docker-java 的偏见，而是基于对项目实际需求的深入分析。

核心决策因素一：依赖最小化

keycloak-server-docker 模块的定位是一个轻量级的容器编排工具，它只需要完成以下核心操作：

检测 Docker 守护进程状态
拉取和管理 Keycloak Docker 镜像
通过 docker-compose 启动和停止 Keycloak 容器
执行 HTTP 健康检查

这些操作完全可以通过 docker 和 docker-compose 命令行工具完成，无需引入重量级的客户端库。保持零外部依赖意味着：

更小的 JAR 包体积（keycloak-server-docker-1.0.0-SNAPSHOT.jar 仅有几十 KB）
更快的构建速度
更少的依赖冲突风险
更简单的维护成本

核心决策因素二：docker-compose 编排需求

keycloak-server-docker 的核心编排方式是 docker-compose，而非单容器管理。docker-compose 提供了声明式的服务定义、依赖管理、网络配置等能力，这些是 docker-java 的单容器 API 难以直接替代的。虽然社区存在 docker-compose 的 Java 绑定库，但它们的成熟度和维护状态远不如 docker-java。

通过 ProcessBuilder 直接调用 docker-compose 命令，我们可以：

完整使用 docker-compose 的所有功能特性
利用 docker-compose.yml 的声明式配置
保持与 Docker 生态的天然兼容性

核心决策因素三：版本号动态获取的便利性

keycloak-server-docker 需要根据当前项目的 Keycloak 版本号动态拉取对应的 Docker 镜像。版本号来自 org.keycloak.common.Version.VERSION，这个类已经在项目的依赖中（通过 keycloak-common 依赖）。使用 ProcessBuilder 方案，我们可以直接将版本号作为环境变量注入到 docker-compose 命令中，实现版本号的动态替换。

核心决策因素四：调试和可观测性

在 SPI 开发场景中，开发者需要清楚地了解 Docker 容器的启动过程、镜像拉取进度、服务就绪状态等信息。ProcessBuilder 方案可以直接将命令的输出流透传到控制台，提供与手动执行命令一致的视觉体验。这对于调试容器启动问题尤为重要。

以下是两种方案的架构对比：

┌─────────────────────────────────────────────────────────────────┐
│                    方案一：Docker Java 客户端库                    │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Java Application                                               │
│       │                                                         │
│       ▼                                                         │
│  docker-java Client                                             │
│       │                                                         │
│       ▼                                                         │
│  Docker Remote API (HTTP/REST)                                  │
│       │                                                         │
│       ▼                                                         │
│  Docker Daemon (dockerd)                                        │
│       │                                                         │
│       ▼                                                         │
│  Docker Container                                               │
│                                                                 │
│  优点：类型安全、功能完整、异步支持                                │
│  缺点：依赖重、版本耦合、compose支持有限                           │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                    方案二：ProcessBuilder（本文选择）               │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Java Application                                               │
│       │                                                         │
│       ▼                                                         │
│  ProcessBuilder                                                 │
│       │                                                         │
│       ▼                                                         │
│  docker / docker-compose CLI                                    │
│       │                                                         │
│       ▼                                                         │
│  Docker Daemon (dockerd)                                        │
│       │                                                         │
│       ▼                                                         │
│  Docker Container                                               │
│                                                                 │
│  优点：零依赖、compose原生支持、调试友好                           │
│  缺点：缺乏类型安全、输出解析繁琐                                  │
└─────────────────────────────────────────────────────────────────┘

1.3 keycloak-server-docker 模块定位

在 keycloak-sandbox 项目的整体架构中，keycloak-server-docker 模块承担着"容器化运行环境管理器"的角色。为了更好地理解它的定位，我们先来看 keycloak-sandbox 的整体模块结构：

keycloak-sandbox（父POM，统一版本管理）
│
├── keycloak-server-docker      ← 本文主角：Docker 容器编排模块
│   ├── KeycloakServerStart     启动类（约637行）
│   └── KeycloakServerStop      停止类（约222行）
│
├── keycloak-server-release     Release 版沙箱模块
│   ├── KeycloakServerStart     启动类
│   └── KeycloakServerStop      停止类
│
├── keycloak-server-extensions  扩展包管理模块
│   └── ExtensionPackagesMain   扩展打包工具
│
├── spi-user-storage-extension  用户存储 SPI 扩展
├── spi-sm-crypto-extension     国密算法 SPI 扩展
└── spi-event-listener-extension 事件监听 SPI 扩展

keycloak-server-docker 模块的核心职责可以概括为以下几点：

职责一：环境预检与准备

在启动 Keycloak 容器之前，模块需要完成一系列环境预检工作：

检测 Docker 守护进程是否运行
清理可能存在的残留容器
检查 Keycloak Docker 镜像是否存在
创建必要的目录结构（providers、themes）

职责二：容器编排与启动

模块通过 docker-compose 编排 Keycloak 容器的启动过程：

从 classpath 读取 docker-compose.yml 模板
动态注入 Keycloak 版本号
执行 docker-compose up 启动容器
配置环境变量和卷挂载

职责三：服务就绪验证

容器启动后，模块需要验证 Keycloak 服务是否真正可用：

通过 HTTP 健康检查确认服务就绪
实现重试策略和超时控制
提供清晰的启动状态反馈

职责四：优雅停止与资源清理

模块支持两种停止方式：

通过 --stop 参数触发 docker-compose down
通过 KeycloakServerStop 独立类执行停止
多级降级策略确保容器被彻底清理

从 Maven 依赖的角度来看，keycloak-server-docker 模块极其精简：

xml

<dependencies>
    <!-- Keycloak common dependency for Version class -->
    <dependency>
        <groupId>org.keycloak</groupId>
        <artifactId>keycloak-common</artifactId>
    </dependency>
</dependencies>

唯一的外部依赖是 keycloak-common，它仅用于获取 Keycloak 的版本号（org.keycloak.common.Version.VERSION）。这个依赖已经在父 POM 的 dependencyManagement 中统一管理，版本号由 keycloak.version 属性控制（当前为 26.6.1）。

模块的构建配置也体现了其"轻量级"的设计理念：

xml

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-jar-plugin</artifactId>
            <configuration>
                <archive>
                    <manifest>
                        <mainClass>cc.bima.keycloak.server.docker.KeycloakServerStart</mainClass>
                    </manifest>
                </archive>
            </configuration>
        </plugin>
    </plugins>
</build>

通过 maven-jar-plugin 配置了主类为 KeycloakServerStart，使得打包后的 JAR 可以直接通过 java -jar 命令运行。

第二章 Docker 守护进程检测与初始化

2.1 Docker 可用性检测

Docker 守护进程（dockerd）是所有 Docker 操作的基础。在执行任何容器编排操作之前，必须首先确认 Docker 守护进程正在运行并且可以正常通信。这是整个启动流程的第一道关卡。

在 keycloak-server-docker 中，Docker 可用性检测的实现非常直观——通过执行 docker info 命令来判断守护进程的状态：

java

/**
 * 检测 Docker 守护进程是否可用
 * 教学简化版本
 */
private static boolean checkDockerDaemon(String dockerCommand) throws Exception {
    System.out.println("Checking Docker daemon status...");

    Process dockerInfoProcess = Runtime.getRuntime().exec(dockerCommand + " info");
    int dockerInfoExitCode = dockerInfoProcess.waitFor();

    if (dockerInfoExitCode == 0) {
        System.out.println("Docker daemon is running");
        return true;
    } else {
        System.out.println("Docker daemon not ready");
        return false;
    }
}

为什么选择 docker info 而不是 docker version 或 docker ps？这个选择基于以下考虑：

docker version 只能确认 Docker 客户端存在，不能确认守护进程是否运行
docker ps 虽然也能检测守护进程状态，但其语义是"列出容器"，用作健康检查不够直观
docker info 的语义是"获取 Docker 系统信息"，其退出码为 0 表示守护进程正常运行且可以通信，是最合适的健康检查命令

docker info 命令在成功时会返回大量的系统信息（包括容器数量、镜像数量、存储驱动、内核版本等），在失败时会返回错误信息。我们只关心退出码，不需要解析输出内容，因此直接忽略输出流。

2.2 重试策略设计

在实际的生产环境中，Docker 守护进程可能不会立即就绪。特别是在以下场景中：

系统启动阶段：操作系统刚启动时，Docker 守护进程可能还在初始化中
Docker Desktop 启动中：在 Windows 和 macOS 上，Docker Desktop 的启动需要较长时间
资源竞争：当系统资源紧张时，Docker 守护进程的响应可能变慢
网络延迟：在某些配置下，Docker 守护进程的通信可能涉及网络层

因此，keycloak-server-docker 实现了一个带重试的守护进程检测策略：

java

/**
 * 带重试的 Docker 守护进程检测
 * 教学简化版本
 */
private static boolean waitForDockerDaemon(String dockerCommand,
                                           int maxAttempts,
                                           long retryIntervalMs) throws Exception {
    System.out.println("Checking Docker daemon status...");

    boolean dockerReady = false;
    int attempt = 0;

    while (attempt < maxAttempts && !dockerReady) {
        System.out.println("Attempting to connect to Docker daemon... ("
            + (attempt + 1) + "/" + maxAttempts + ")");
        try {
            Process dockerInfoProcess = Runtime.getRuntime().exec(
                dockerCommand + " info");
            int dockerInfoExitCode = dockerInfoProcess.waitFor();

            if (dockerInfoExitCode == 0) {
                dockerReady = true;
                System.out.println("Docker daemon is running");
            } else {
                System.out.println("Docker daemon not ready yet, waiting...");
                Thread.sleep(retryIntervalMs);
            }
        } catch (Exception e) {
            System.out.println("Error connecting to Docker daemon: "
                + e.getMessage());
            Thread.sleep(retryIntervalMs);
        }
        attempt++;
    }

    return dockerReady;
}

这个重试策略的设计包含以下几个关键参数：

参数	值	说明
maxAttempts	5	最大重试次数
retryIntervalMs	2000	重试间隔（毫秒）
总等待时间	~10秒	maxAttempts x retryIntervalMs

为什么选择 5 次重试和 2 秒间隔？

这个参数组合是基于实际测试经验得出的平衡点：

5 次重试提供了足够的容错空间。在大多数情况下，Docker 守护进程会在 2-3 次尝试内就绪
2 秒的间隔既不会过于频繁（避免对 Docker 守护进程造成压力），也不会让用户等待过久
总等待时间约 10 秒，在用户体验和可靠性之间取得了良好的平衡

重试流程可以用以下流程图表示：

                    ┌──────────────────────┐
                    │   开始检测            │
                    └──────────┬───────────┘
                               │
                    ┌──────────▼───────────┐
                    │ attempt < maxAttempts │
                    │     && !dockerReady   │
                    └──────────┬───────────┘
                               │
                 ┌─────────────┼─────────────┐
                 │ Yes         │             │ No
                 ▼             │             ▼
    ┌────────────────────┐     │   ┌──────────────────┐
    │ 执行 docker info   │     │   │ 返回检测结果      │
    └────────┬───────────┘     │   └──────────────────┘
             │                 │
      ┌──────┴──────┐         │
      │ exitCode==0 │         │
      └──────┬──────┘         │
       │Yes   │No             │
       ▼      ▼               │
  ┌────────┐ ┌──────────────┐ │
  │就绪    │ │等待2秒       │ │
  │返回    │ │attempt++    │ │
  └────────┘ └──────┬───────┘ │
                    └─────────┘

2.3 Docker Credential Store 问题处理

在实际使用中，开发者可能会遇到一个常见的 Docker 配置问题：Docker Credential Store 错误。

当 Docker Desktop 安装后，它会在 ~/.docker/config.json 中配置一个 credential store（通常是 docker-credential-desktop 或 docker-credential-osxkeychain）。这个 credential store 用于安全地存储 Docker Hub 等镜像仓库的认证信息。然而，在某些环境下（例如 CI/CD 流水线、远程 SSH 会话、或者 Docker Desktop 未完全启动时），credential store 可能不可用，导致 Docker 命令执行失败并报出类似以下的错误：

error storing credentials - err: exit status 1, out: `Cannot autolaunch D-Bus: X11 initialization failed.`

keycloak-server-docker 通过一个巧妙的方式来规避这个问题——临时覆盖 DOCKER_CONFIG 环境变量：

java

ProcessBuilder pb = new ProcessBuilder(command);
Map<String, String> env = pb.environment();
// 临时覆盖Docker配置，避免使用不存在的credential store
env.put("DOCKER_CONFIG", System.getProperty("java.io.tmpdir"));

这个方案的原理是：

Docker CLI 在启动时会读取 DOCKER_CONFIG 环境变量来确定配置目录
如果 DOCKER_CONFIG 指向一个不包含 config.json 的目录，Docker CLI 会使用默认配置（不使用 credential store）
通过将 DOCKER_CONFIG 指向系统临时目录（java.io.tmpdir），我们确保 Docker CLI 不会尝试访问可能不可用的 credential store

这个方案的安全性分析：

临时目录中不存在 Docker 配置文件，因此 Docker CLI 不会使用任何存储的认证信息
对于拉取公开镜像（如 quay.io/keycloak/keycloak），不需要认证信息
环境变量的修改仅影响当前进程及其子进程，不会影响系统的全局 Docker 配置
操作完成后，临时目录中的任何临时文件都会被正常清理

这个处理方式在镜像拉取和 docker-compose 操作中都被一致地使用，确保了整个流程的健壮性。

2.4 跨平台 Docker 路径适配

Docker 在不同操作系统上的安装路径和命令名称存在差异。keycloak-server-docker 通过操作系统检测来适配这些差异：

java

/**
 * 跨平台 Docker 命令路径解析
 * 教学简化版本
 */
private static String[] resolveDockerCommands() {
    String os = System.getProperty("os.name").toLowerCase();

    String dockerCommand;
    String dockerComposeCommand;

    if (os.contains("win")) {
        // Windows 平台
        dockerCommand = "docker.exe";
        dockerComposeCommand = "docker-compose.exe";
    } else {
        // Linux / macOS 平台
        dockerCommand = "/usr/local/bin/docker";
        dockerComposeCommand = "/usr/local/bin/docker-compose";
    }

    return new String[]{dockerCommand, dockerComposeCommand};
}

为什么 Windows 使用相对命令名而 Linux/macOS 使用绝对路径？

这个差异源于不同操作系统上 Docker 的安装和发现机制：

Windows：Docker Desktop 安装后，会将 docker.exe 和 docker-compose.exe 添加到系统的 PATH 环境变量中。使用相对命令名可以让系统通过 PATH 自动发现命令，避免了硬编码安装路径的问题（Docker Desktop 在 Windows 上的安装路径可能因版本和用户配置而异）。
Linux/macOS：Docker 的安装路径相对固定（通常在 /usr/local/bin/ 或 /usr/bin/）。使用绝对路径可以避免 PATH 配置问题，确保命令的可发现性。特别是在自动化脚本和 CI/CD 环境中，PATH 可能不包含 Docker 的安装目录。

路径解析策略的演进思考：

当前的实现是一个简单但有效的方案。在更复杂的场景中，可以考虑以下增强策略：

which/where 命令探测：在 Linux/macOS 上使用 which docker，在 Windows 上使用 where docker 来动态发现 Docker 的安装路径
多路径回退：维护一个候选路径列表，依次尝试直到找到可用的命令
环境变量覆盖：允许通过环境变量（如 DOCKER_PATH、DOCKER_COMPOSE_PATH）自定义命令路径

以下是跨平台路径适配的完整流程：

┌──────────────────────────────────────────────────────────┐
│              操作系统检测                                  │
│  System.getProperty("os.name").toLowerCase()              │
└──────────────────┬───────────────────────────────────────┘
                   │
         ┌─────────┴─────────┐
         │                   │
    os.contains("win")   其他（Linux/macOS）
         │                   │
         ▼                   ▼
┌─────────────────┐  ┌─────────────────────────┐
│ docker.exe      │  │ /usr/local/bin/docker    │
│ docker-compose  │  │ /usr/local/bin/          │
│   .exe          │  │   docker-compose         │
└─────────────────┘  └─────────────────────────┘
         │                   │
         └─────────┬─────────┘
                   │
                   ▼
┌──────────────────────────────────────────────────────────┐
│              命令可用性验证                                │
│  执行 docker info 确认命令可执行                           │
└──────────────────────────────────────────────────────────┘

第三章 Keycloak Docker 镜像管理

3.1 镜像版本自动获取

在传统的 Docker 工作流中，开发者需要手动指定镜像的版本标签。例如，要拉取 Keycloak 26.0.1 的镜像，需要执行：

bash

docker pull quay.io/keycloak/keycloak:26.0.1

这种方式存在一个明显的问题：版本号分散在多个地方，容易不一致。如果项目的 Maven POM 中配置的 Keycloak 版本是 26.0.1，但 docker-compose.yml 中写的是 25.0.0，就会导致版本不匹配，可能引发运行时错误。

keycloak-server-docker 通过 org.keycloak.common.Version.VERSION 实现了版本号的自动获取：

java

import org.keycloak.common.Version;

// 自动获取当前 Keycloak 版本号
String keycloakVersion = Version.VERSION;
// 例如输出：26.6.1
System.out.println("Keycloak version: " + keycloakVersion);

org.keycloak.common.Version 是 Keycloak 核心库中的一个工具类，它在编译时由 Maven 资源过滤自动填充版本号。这个机制的工作原理如下：

在 keycloak-common 的源码中，Version.VERSION 的值来自一个 properties 文件
Maven 在打包时会将项目的版本号注入到这个 properties 文件中
因此，Version.VERSION 的值始终与项目的实际 Keycloak 依赖版本一致

这意味着，当开发者在 keycloak-sandbox 的父 POM 中修改 <keycloak.version> 属性时：

xml

<properties>
    <keycloak.version>26.6.1</keycloak.version>
</properties>

Version.VERSION 会自动返回 26.6.1，无需任何手动修改。这个机制确保了以下一致性保证：

┌─────────────────────────────────────────────────────────────┐
│                    版本号自动传播链路                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  父 POM: keycloak.version = 26.6.1                          │
│       │                                                     │
│       ├──▶ keycloak-common 依赖版本 = 26.6.1                │
│       │       │                                             │
│       │       └──▶ Version.VERSION = "26.6.1"               │
│       │               │                                     │
│       │               ├──▶ Docker 镜像标签 = 26.6.1         │
│       │               └──▶ docker-compose 环境变量 = 26.6.1  │
│       │                                                     │
│       ├──▶ SPI 模块依赖版本 = 26.6.1                        │
│       └──▶ 编译目标版本 = 26.6.1                             │
│                                                             │
│  结果：所有组件使用完全一致的 Keycloak 版本                   │
└─────────────────────────────────────────────────────────────┘

3.2 quay.io/keycloak/keycloak 镜像

Keycloak 的官方 Docker 镜像托管在 Red Hat 的 Quay.io 容器镜像仓库上，而非更常见的 Docker Hub。镜像地址为：

quay.io/keycloak/keycloak:<version>

为什么选择 Quay.io 而非 Docker Hub？

这是 Red Hat 的战略决策。Quay.io 是 Red Hat 旗下的企业级容器镜像仓库，相比 Docker Hub 具有以下优势：

企业级安全扫描：内置容器镜像安全扫描功能
更好的访问控制：支持细粒度的访问权限管理
地理分布：全球 CDN 加速，拉取速度更快
与 OpenShift 生态集成：作为 Red Hat 容器生态的一部分，与 OpenShift 无缝集成

镜像的版本标签策略：

Keycloak Docker 镜像的版本标签与 Keycloak 的发布版本完全对应。常见的标签格式包括：

标签格式	示例	说明
精确版本	`26.6.1`	特定版本，推荐生产使用
最新版	`latest`	最新稳定版，不推荐生产使用
夜间构建	`nightly`	每日构建版，包含最新功能

在 keycloak-server-docker 中，我们始终使用精确版本标签，确保环境的可重复性：

java

String imageName = "quay.io/keycloak/keycloak:" + Version.VERSION;
// 例如：quay.io/keycloak/keycloak:26.6.1

3.3 镜像拉取策略

镜像拉取是容器启动流程中最耗时的环节之一。Keycloak 的 Docker 镜像体积较大（通常在 500MB-1GB 之间），拉取时间取决于网络条件。keycloak-server-docker 实现了一个带重试的镜像拉取策略：

java

/**
 * 带重试的镜像拉取策略
 * 教学简化版本
 */
private static boolean pullImageWithRetry(String dockerCommand,
                                          String version,
                                          int maxAttempts) throws Exception {
    String imageName = "quay.io/keycloak/keycloak:" + version;
    System.out.println("Pulling image: " + imageName);

    int pullAttempt = 0;
    boolean imagePulled = false;

    while (pullAttempt < maxAttempts && !imagePulled) {
        pullAttempt++;
        System.out.println("Image pull attempt: " + pullAttempt
            + "/" + maxAttempts);

        if (pullKeycloakImage(dockerCommand, imageName)) {
            imagePulled = true;
        } else {
            if (pullAttempt < maxAttempts) {
                System.out.println("Retrying image pull...");
                Thread.sleep(3000); // 等待3秒后重试
            }
        }
    }

    if (!imagePulled) {
        System.err.println("Failed to pull Keycloak image after "
            + maxAttempts + " attempts");
        // 注意：不返回false，继续执行启动容器的步骤
        // docker-compose 会尝试自动拉取镜像
    }

    return imagePulled;
}

镜像拉取的容错设计亮点：

最多 3 次重试：网络抖动是镜像拉取失败的常见原因，3 次重试提供了足够的容错空间
3 秒重试间隔：给予网络一定的恢复时间
失败不阻断：即使预拉取失败，也不会阻止后续的 docker-compose 启动流程。docker-compose 在启动时会自动拉取缺失的镜像，这是一个额外的保障层

Credential Store 错误的降级处理：

在镜像拉取过程中，如果检测到 credential store 相关的错误，会自动降级为不使用内容信任的拉取方式：

java

/**
 * 镜像拉取实现（含认证错误降级）
 * 教学简化版本
 */
private static boolean pullKeycloakImage(String dockerCommand,
                                         String imageName) throws Exception {
    ProcessBuilder pb = new ProcessBuilder(
        dockerCommand, "pull", imageName);
    Map<String, String> env = pb.environment();
    env.put("DOCKER_CONFIG", System.getProperty("java.io.tmpdir"));

    Process pullProcess = pb.start();

    // 读取错误输出，检测认证错误
    boolean hasAuthError = false;
    try (BufferedReader errorReader = new BufferedReader(
            new InputStreamReader(pullProcess.getErrorStream()))) {
        String errorLine;
        while ((errorLine = errorReader.readLine()) != null) {
            if (errorLine.contains("docker-credential-desktop")
                || errorLine.contains("credential")) {
                hasAuthError = true;
            }
        }
    }

    int exitCode = pullProcess.waitFor();

    if (exitCode == 0) {
        return true;
    } else if (hasAuthError) {
        // 降级：不使用内容信任重试
        return pullImageWithoutContentTrust(dockerCommand, imageName);
    }
    return false;
}

降级策略使用 --disable-content-trust 参数重试拉取。内容信任（Content Trust）是 Docker 的镜像签名验证机制，在开发环境中通常不需要启用。降级处理的流程如下：

┌────────────────────────────────────┐
│        执行 docker pull             │
└──────────────┬─────────────────────┘
               │
        ┌──────┴──────┐
        │  成功？      │
        └──────┬──────┘
         │Yes   │No
         ▼      ▼
    ┌────────┐ ┌──────────────────────┐
    │返回成功│ │检测错误类型           │
    └────────┘ └──────────┬───────────┘
                          │
                   ┌──────┴──────┐
                   │认证错误？    │
                   └──────┬──────┘
                    │Yes   │No
                    ▼      ▼
         ┌──────────────┐ ┌──────────┐
         │降级：         │ │返回失败  │
         │--disable-    │ └──────────┘
         │content-trust │
         │重试拉取       │
         └──────────────┘

3.4 镜像存在性检测

在拉取镜像之前，keycloak-server-docker 会先检查本地是否已经存在所需的镜像。这个优化可以避免不必要的网络请求，显著加快启动速度：

java

/**
 * 检查 Docker 镜像是否已存在于本地
 * 教学简化版本
 */
private static boolean checkImageExists(String dockerCommand,
                                        String version) throws Exception {
    String imageName = "quay.io/keycloak/keycloak:" + version;
    System.out.println("Checking for image: " + imageName);

    Process checkProcess = Runtime.getRuntime().exec(
        dockerCommand + " images -q " + imageName);

    try (BufferedReader reader = new BufferedReader(
            new InputStreamReader(checkProcess.getInputStream()))) {
        String imageId = reader.readLine();
        if (imageId != null && !imageId.isEmpty()) {
            System.out.println("Keycloak image found: " + imageId);
            return true;
        } else {
            System.out.println("Keycloak image not found");
            return false;
        }
    }
}

docker images -q 的妙用：

docker images -q <image_name> 命令是一个高效的镜像存在性检查方式：

-q 参数表示只输出镜像 ID，不输出表头和其他信息
如果镜像存在，输出镜像的 SHA256 摘要（短格式），例如 a1b2c3d4e5f6
如果镜像不存在，输出为空

相比 docker images <image_name>（输出完整信息）或 docker inspect <image_name>（尝试获取详细配置），docker images -q 是最轻量级的检查方式。

镜像管理的完整流程：

┌──────────────────────────────────────────────────────────┐
│              镜像管理流程                                   │
├──────────────────────────────────────────────────────────┤
│                                                          │
│  1. 获取版本号                                            │
│     Version.VERSION → "26.6.1"                           │
│                    │                                     │
│                    ▼                                     │
│  2. 构造镜像名称                                          │
│     "quay.io/keycloak/keycloak:26.6.1"                   │
│                    │                                     │
│                    ▼                                     │
│  3. 检查本地镜像                                          │
│     docker images -q quay.io/keycloak/keycloak:26.6.1    │
│                    │                                     │
│             ┌──────┴──────┐                              │
│             │ 存在？      │                              │
│             └──────┬──────┘                              │
│              │Yes   │No                                  │
│              ▼      ▼                                    │
│         ┌────────┐ ┌──────────────────────┐             │
│         │跳过拉取│ │执行镜像拉取（含重试）  │             │
│         └────────┘ └──────────┬───────────┘             │
│                               │                          │
│                        ┌──────┴──────┐                   │
│                        │ 拉取成功？   │                   │
│                        └──────┬──────┘                   │
│                         │Yes   │No                       │
│                         ▼      ▼                          │
│                    ┌────────┐ ┌────────────────────┐     │
│                    │继续    │ │继续（compose会      │     │
│                    │启动    │ │自动拉取）           │     │
│                    └────────┘ └────────────────────┘     │
│                                                          │
└──────────────────────────────────────────────────────────┘

第四章 docker-compose 动态生成与启动

4.1 docker-compose.yml 模板设计

docker-compose.yml 是 keycloak-server-docker 的核心编排文件，它定义了 Keycloak 容器的完整运行配置。以下是项目中的实际配置：

yaml

version: '3.8'

# 设置项目名称为keycloak-server
name: keycloak-server

services:
  keycloak:
    image: quay.io/keycloak/keycloak:${keycloak_version}
    environment:
      - KC_RUN_IN_CONTAINER=true
      - KC_BOOTSTRAP_ADMIN_USERNAME=root
      - KC_BOOTSTRAP_ADMIN_PASSWORD=root
      - KC_HTTP_ENABLED=true
      - KC_HOSTNAME=localhost
    ports:
      - "8080:8080"
    volumes:
      - ./keycloak-providers:/opt/keycloak/providers
      - ./keycloak-themes:/opt/keycloak/themes
    command: start-dev

配置逐项解析：

version: '3.8'：指定 docker-compose 文件格式版本。3.8 是当前广泛支持的稳定版本，兼容 Docker Engine 19.03.0+。

name: keycloak-server：设置项目名称。这个名称会被用作 Docker 网络和容器名称的前缀，确保不同项目的容器不会冲突。

image: quay.io/keycloak/keycloak:${keycloak_version}：使用 Quay.io 上的官方 Keycloak 镜像。${keycloak_version} 是一个环境变量占位符，在运行时由 Java 进程通过环境变量注入实际的版本号。

environment 配置项解析：

环境变量	值	说明
`KC_RUN_IN_CONTAINER`	`true`	标识当前运行在容器环境中
`KC_BOOTSTRAP_ADMIN_USERNAME`	`root`	初始管理员用户名
`KC_BOOTSTRAP_ADMIN_PASSWORD`	`root`	初始管理员密码
`KC_HTTP_ENABLED`	`true`	启用 HTTP 访问（开发环境）
`KC_HOSTNAME`	`localhost`	设置主机名为 localhost

ports: "8080:8080"：端口映射，将容器内的 8080 端口映射到主机的 8080 端口。Keycloak 默认在 8080 端口提供 HTTP 服务。

volumes 配置解析：

./keycloak-providers:/opt/keycloak/providers

这行配置将宿主机上的 keycloak-providers 目录挂载到容器内的 /opt/keycloak/providers 目录。Keycloak 在启动时会自动扫描 providers 目录下的 JAR 文件，并将它们注册为 SPI 扩展。这意味着开发者只需将编译好的 SPI JAR 文件复制到宿主机的 keycloak-providers 目录，Keycloak 容器就能自动加载这些扩展。

./keycloak-themes:/opt/keycloak/themes

类似地，keycloak-themes 目录挂载到容器内的 /opt/keycloak/themes，用于存放自定义登录主题。

command: start-dev：使用开发模式启动 Keycloak。开发模式的特点包括：

禁用 HTTPS（适合本地开发）
启用热重载（修改主题后无需重启）
输出详细的日志信息
自动创建初始管理员账户

4.2 版本号动态注入

版本号的动态注入是 keycloak-server-docker 最精巧的设计之一。它通过 Java 进程的环境变量机制，将 Version.VERSION 的值传递给 docker-compose 的变量替换引擎：

java

ProcessBuilder pb = new ProcessBuilder(command);
Map<String, String> env = pb.environment();

// 设置环境变量传递版本号
// docker-compose 会自动将 ${keycloak_version} 替换为环境变量的值
env.put("keycloak_version", Version.VERSION);
pb.directory(dockerComposeDir.toFile());

工作原理详解：

Java 进程通过 ProcessBuilder.environment() 获取当前进程的环境变量
向环境变量中添加 keycloak_version=26.6.1（假设当前版本为 26.6.1）
启动的 docker-compose 子进程继承了这些环境变量
docker-compose 在解析 YAML 文件时，遇到 ${keycloak_version} 会自动替换为环境变量的值
最终，image: quay.io/keycloak/keycloak:${keycloak_version} 被解析为 image: quay.io/keycloak/keycloak:26.6.1

为什么选择环境变量注入而非字符串替换？

在实现版本号动态注入时，有两种可选方案：

方案 A：字符串替换（在 Java 中直接替换 YAML 文件中的占位符）

java

String content = dockerComposeContent
    .replace("${keycloak_version}", Version.VERSION);
Files.writeString(outputFile, content);

方案 B：环境变量注入（利用 docker-compose 的原生变量替换）

java

env.put("keycloak_version", Version.VERSION);

我们选择了方案 B，原因如下：

不修改模板文件：保持 docker-compose.yml 的原始格式不变，便于版本控制和团队协作
docker-compose 原生能力：利用 docker-compose 内置的变量替换机制，无需引入额外的字符串处理逻辑
可扩展性：如果将来需要注入更多变量（如端口、管理员密码等），只需添加环境变量即可
安全性：敏感信息（如密码）通过环境变量传递，不会明文写入文件

4.3 classpath 资源读取与写入

docker-compose.yml 模板文件存放在 keycloak-server-docker 模块的 src/main/resources/ 目录下，在 Maven 打包后会被包含在 JAR 文件的 classpath 中。在运行时，需要从 classpath 读取这个文件并将其写入到工作目录：

java

/**
 * 从 classpath 读取 docker-compose.yml 并写入工作目录
 * 教学简化版本
 */
private static Path prepareDockerComposeFile() throws Exception {
    System.out.println("Using docker-compose file from classpath");

    // 从 classpath 读取模板文件
    ClassLoader classLoader = KeycloakServerStart.class.getClassLoader();
    try (InputStream inputStream = classLoader
            .getResourceAsStream("docker-compose.yml")) {

        if (inputStream == null) {
            System.err.println("Error: docker-compose.yml not found in classpath");
            return null;
        }

        // 读取文件内容
        String dockerComposeContent = new String(
            inputStream.readAllBytes(), StandardCharsets.UTF_8);

        // 确定输出目录（项目的 resources 目录）
        Path dockerComposeDir = Path.of(
            System.getProperty("user.dir"),
            "src", "main", "resources");

        if (!Files.exists(dockerComposeDir)) {
            Files.createDirectories(dockerComposeDir);
        }

        // 写入文件
        Path outputFile = dockerComposeDir.resolve("docker-compose.yml");
        Files.writeString(outputFile, dockerComposeContent);

        System.out.println("Docker compose file written to: " + outputFile);
        return outputFile;
    }
}

为什么需要从 classpath 读取并写入文件，而不是直接引用文件路径？

这个设计决策基于以下考虑：

JAR 内运行：当模块打包为 JAR 后，docker-compose.yml 位于 JAR 文件内部，无法直接通过文件路径访问。docker-compose 命令需要一个实际的文件系统路径，因此必须将文件从 classpath 提取到文件系统。
版本一致性：从 classpath 读取确保了使用的是与当前 JAR 版本一致的 docker-compose.yml 模板。如果直接引用源码目录中的文件，可能会因为源码修改导致模板与编译后的代码不一致。
目录结构约定：将 docker-compose.yml 写入 src/main/resources/ 目录，与卷挂载的相对路径（./keycloak-providers、./keycloak-themes）保持一致。docker-compose 在解析相对路径时，会以 docker-compose.yml 所在目录为基准。

资源读取的目录结构关系：

keycloak-server-docker/
├── src/main/resources/          ← docker-compose.yml 的源位置
│   ├── docker-compose.yml       ← 模板文件（包含 ${keycloak_version}）
│   ├── keycloak-providers/      ← SPI JAR 挂载目录（自动创建）
│   └── keycloak-themes/         ← 主题文件挂载目录（自动创建）
│
├── target/
│   └── classes/
│       ├── docker-compose.yml   ← 编译后的副本
│       └── cc/bima/keycloak/... ← 编译后的 class 文件
│
└── target/
    └── keycloak-server-docker-1.0.0-SNAPSHOT.jar
        └── docker-compose.yml   ← JAR 内的模板（classpath 资源）

4.4 docker-compose up 执行

当所有准备工作完成后，执行 docker-compose up 启动 Keycloak 容器。这是整个启动流程的核心步骤：

java

/**
 * 执行 docker-compose up 启动 Keycloak 容器
 * 教学简化版本
 */
private static int executeDockerComposeUp(String dockerComposeCommand,
                                          Path dockerComposeDir,
                                          String composeFile) throws Exception {
    // 构建命令列表
    List<String> command = new ArrayList<>();
    command.add(dockerComposeCommand);
    command.add("-f");
    command.add(composeFile);
    command.add("up");
    command.add("-d");  // 后台运行

    System.out.println("Executing command: " + String.join(" ", command));

    // 创建进程
    ProcessBuilder pb = new ProcessBuilder(command);
    Map<String, String> env = pb.environment();

    // 注入环境变量
    env.put("DOCKER_CONFIG", System.getProperty("java.io.tmpdir"));
    env.put("keycloak_version", Version.VERSION);

    // 设置工作目录
    pb.directory(dockerComposeDir.toFile());

    // 合并标准输出和错误输出
    pb.redirectErrorStream(true);

    // 启动进程
    Process process = pb.start();

    // 读取并输出命令执行结果
    try (BufferedReader reader = new BufferedReader(
            new InputStreamReader(process.getInputStream()))) {
        String line;
        while ((line = reader.readLine()) != null) {
            System.out.println("Docker output: " + line);
        }
    }

    // 等待命令执行完成
    process.waitFor();

    return process.exitValue();
}

命令参数解析：

参数	说明
`docker-compose`	docker-compose 命令
`-f docker-compose.yml`	指定 compose 文件路径
`up`	创建并启动所有服务
`-d`	后台运行模式（detached mode）

-d（后台模式）的选择：

使用 -d 参数让容器在后台运行，而不是占用当前终端。这个选择非常重要：

Java 进程不会因为 docker-compose 的输出而阻塞
可以在容器启动后继续执行健康检查等后续操作
用户可以在 Java 进程运行期间通过其他终端查看容器日志

redirectErrorStream(true) 的作用：

将子进程的错误输出合并到标准输出。这意味着：

System.out 和 System.err 的输出都会通过 process.getInputStream() 读取
简化了输出处理逻辑（只需要读取一个流）
确保不会因为错误输出缓冲区满而导致进程阻塞

ProcessBuilder 的关键配置项：

┌────────────────────────────────────────────────────────────┐
│              ProcessBuilder 配置全景                        │
├────────────────────────────────────────────────────────────┤
│                                                            │
│  ProcessBuilder                                            │
│  ├── command: [docker-compose, -f, compose.yml, up, -d]   │
│  ├── environment:                                          │
│  │   ├── DOCKER_CONFIG = /tmp                              │
│  │   └── keycloak_version = 26.6.1                         │
│  ├── directory: /path/to/resources                         │
│  └── redirectErrorStream: true                             │
│                                                            │
│  启动后的进程树：                                           │
│                                                            │
│  Java Process                                              │
│    └── docker-compose up -d                                │
│          └── Docker Daemon                                 │
│                └── keycloak container                      │
│                      └── Quarkus (Keycloak runtime)        │
│                                                            │
└────────────────────────────────────────────────────────────┘

4.5 环境变量配置

keycloak-server-docker 通过环境变量向 docker-compose 传递配置信息。这些环境变量分为两类：

第一类：Docker 运行时配置

java

// 临时覆盖 Docker 配置目录，避免 credential store 问题
env.put("DOCKER_CONFIG", System.getProperty("java.io.tmpdir"));

第二类：应用配置（传递给 docker-compose 的变量替换）

java

// Keycloak 版本号，用于替换 docker-compose.yml 中的占位符
env.put("keycloak_version", Version.VERSION);

环境变量传递链路：

Java 进程环境变量
    │
    ├── DOCKER_CONFIG=/tmp
    │       │
    │       ▼
    │   docker-compose 子进程继承
    │       │
    │       ▼
    │   Docker CLI 使用 /tmp 作为配置目录
    │   （不加载 ~/.docker/config.json 中的 credential store）
    │
    └── keycloak_version=26.6.1
            │
            ▼
        docker-compose 子进程继承
            │
            ▼
        docker-compose 解析 YAML 时替换 ${keycloak_version}
            │
            ▼
        image: quay.io/keycloak/keycloak:26.6.1

可扩展的环境变量设计：

当前的实现虽然只传递了两个环境变量，但这个设计具有良好的可扩展性。如果将来需要支持更多的配置项，只需在 docker-compose.yml 中添加对应的占位符，并在 Java 代码中注入环境变量即可。例如：

yaml

# 扩展后的 docker-compose.yml 示例
services:
  keycloak:
    image: quay.io/keycloak/keycloak:${keycloak_version}
    environment:
      - KC_BOOTSTRAP_ADMIN_USERNAME=${admin_username}
      - KC_BOOTSTRAP_ADMIN_PASSWORD=${admin_password}
    ports:
      - "${host_port}:8080"

java

// 扩展后的环境变量注入
env.put("keycloak_version", Version.VERSION);
env.put("admin_username", config.getAdminUsername());
env.put("admin_password", config.getAdminPassword());
env.put("host_port", String.valueOf(config.getHostPort()));

第五章容器生命周期管理

5.1 残留容器自动清理

在开发过程中，由于各种原因（进程被强制终止、IDE 崩溃、系统重启等），可能会留下未正常停止的 Keycloak 容器。这些残留容器不仅占用系统资源，还可能导致端口冲突等问题。

keycloak-server-docker 在每次启动之前都会自动清理残留容器：

java

/**
 * 清理残留的 Keycloak 容器
 * 教学简化版本
 */
private static void cleanupExistingContainers(String dockerCommand)
        throws Exception {
    System.out.println("Cleaning up any existing Keycloak containers...");

    // 查找所有名称包含 "keycloak" 的容器
    Process findProcess = Runtime.getRuntime().exec(
        dockerCommand + " ps -a -q --filter name=keycloak");
    findProcess.waitFor();

    // 逐个删除找到的容器
    try (BufferedReader reader = new BufferedReader(
            new InputStreamReader(findProcess.getInputStream()))) {
        String containerId;
        while ((containerId = reader.readLine()) != null) {
            containerId = containerId.trim();
            if (!containerId.isEmpty()) {
                System.out.println("Removing existing container: "
                    + containerId);
                Process removeProcess = Runtime.getRuntime().exec(
                    dockerCommand + " rm -f " + containerId);
                removeProcess.waitFor();

                if (removeProcess.exitValue() == 0) {
                    System.out.println("Container removed successfully");
                }
            }
        }
    }
}

清理策略的设计要点：

ps -a：不仅查找运行中的容器，还查找已停止的容器（-a 表示 all）
--filter name=keycloak：按名称过滤，只清理与 Keycloak 相关的容器，避免误删其他容器
-q：只输出容器 ID，不输出表头和其他信息
rm -f：强制删除容器（-f 表示 force），即使容器正在运行也会被强制停止并删除

双重清理策略：

keycloak-server-docker 实际上执行了两轮清理：

java

// 第一轮：清理名称包含 "keycloak" 的容器
cleanupContainers(dockerCommand, "keycloak");

// 第二轮：清理名称包含 "classes" 的容器
// （classes 是 docker-compose 默认的项目目录名）
cleanupContainers(dockerCommand, "classes");

第二轮清理针对的是 docker-compose 的默认命名行为。当 docker-compose.yml 位于 target/classes/ 目录时，docker-compose 会使用 classes 作为项目名前缀，创建名为 classes_keycloak_1 之类的容器。通过双重清理，确保所有可能的残留容器都被清除。

清理流程图：

┌──────────────────────────────────────────────────────────┐
│              残留容器清理流程                               │
├──────────────────────────────────────────────────────────┤
│                                                          │
│  ┌────────────────────────────────────────────┐          │
│  │ docker ps -a -q --filter name=keycloak     │          │
│  └──────────────────┬─────────────────────────┘          │
│                     │                                    │
│              ┌──────┴──────┐                             │
│              │ 有结果？     │                             │
│              └──────┬──────┘                             │
│               │Yes   │No                                 │
│               ▼      ▼                                   │
│  ┌────────────────┐ ┌────────────────────────────┐      │
│  │ 逐个执行       │ │ 第一轮清理完成              │      │
│  │ docker rm -f   │ └──────────┬─────────────────┘      │
│  │ <container_id> │            │                        │
│  └────────┬───────┘            ▼                        │
│           │          ┌────────────────────────────────┐  │
│           │          │ docker ps -a -q                │  │
│           │          │   --filter name=classes        │  │
│           │          └──────────┬─────────────────────┘  │
│           │                     │                        │
│           │              ┌──────┴──────┐                 │
│           │              │ 有结果？     │                 │
│           │              └──────┬──────┘                 │
│           │               │Yes   │No                     │
│           │               ▼      ▼                       │
│           │    ┌──────────────┐ ┌──────────────┐        │
│           │    │ 逐个执行     │ │ 清理完成      │        │
│           │    │ docker rm -f │ └──────────────┘        │
│           │    └──────────────┘                         │
│           │                                             │
│           └─────────────────────┐                       │
│                                 ▼                       │
│                    ┌──────────────────────┐             │
│                    │ 继续启动流程          │             │
│                    └──────────────────────┘             │
│                                                          │
└──────────────────────────────────────────────────────────┘

5.2 providers 目录挂载

Keycloak 的 SPI 扩展机制要求将扩展 JAR 文件放置在特定的目录中。在容器化环境中，这个目录通过 Docker 卷挂载实现：

宿主机: ./keycloak-providers  →  容器: /opt/keycloak/providers

keycloak-server-docker 在启动容器之前会自动创建这个目录：

java

// 创建 keycloak-providers 目录
Path providersDir = dockerComposeDir.resolve("keycloak-providers");
if (!Files.exists(providersDir)) {
    Files.createDirectories(providersDir);
    System.out.println("Created keycloak-providers directory at "
        + providersDir);
} else {
    System.out.println("keycloak-providers directory already exists at "
        + providersDir);
}

providers 目录的 SPI 热部署机制：

Keycloak 在开发模式下（start-dev）会定期扫描 providers 目录的变化。当新的 JAR 文件被添加到该目录时，Keycloak 会自动检测并尝试加载这些扩展。这意味着开发者可以：

编译 SPI 扩展模块：mvn clean package
复制生成的 JAR 到 providers 目录
Keycloak 自动检测并加载新的扩展（可能需要重启容器）

目录结构示例：

keycloak-server-docker/src/main/resources/
├── docker-compose.yml
├── keycloak-providers/              ← SPI JAR 挂载点
│   ├── bima-spi-user-storage-extension-1.0.0-SNAPSHOT.jar
│   ├── bima-spi-sm-crypto-extension-1.0.0-SNAPSHOT.jar
│   └── bima-spi-event-listener-extension-1.0.0-SNAPSHOT.jar
└── keycloak-themes/                 ← 主题文件挂载点
    └── my-custom-theme/
        ├── login/
        │   ├── theme.properties
        │   └── resources/
        │       ├── css/
        │       └── img/
        └── account/
            └── theme.properties

5.3 themes 目录挂载

与 providers 目录类似，themes 目录用于存放自定义的 Keycloak 登录主题：

宿主机: ./keycloak-themes  →  容器: /opt/keycloak/themes

java

// 创建 keycloak-themes 目录
Path themesDir = dockerComposeDir.resolve("keycloak-themes");
if (!Files.exists(themesDir)) {
    Files.createDirectories(themesDir);
    System.out.println("Created keycloak-themes directory at "
        + themesDir);
} else {
    System.out.println("keycloak-themes directory already exists at "
        + themesDir);
}

Keycloak 主题体系简介：

Keycloak 的主题系统支持以下几种主题类型：

主题类型	目录名	说明
Login Theme	`login/`	登录页面、注册页面、忘记密码页面等
Account Theme	`account/`	用户账户管理页面
Email Theme	`email/`	邮件模板（验证码、密码重置等）
Admin Console Theme	`admin/`	管理控制台界面
Internationalization	`messages/`	国际化翻译文件

每个主题都需要一个 theme.properties 文件来声明主题的元信息：

properties

# theme.properties 示例
parent=keycloak
import=common/keycloak
styles=css/login.css css/styles.css

在开发模式下，Keycloak 同样支持主题文件的热重载，开发者修改主题文件后刷新浏览器即可看到变化。

5.4 容器停止与资源释放

容器的停止和资源释放是生命周期管理的关键环节。keycloak-server-docker 提供了两种停止方式，并实现了多级降级策略确保容器被彻底清理。

停止方式一：通过 --stop 参数

java

public static void main(String[] args) throws Exception {
    boolean stopMode = false;
    for (String arg : args) {
        if ("--stop".equals(arg)) {
            stopMode = true;
            break;
        }
    }

    if (stopMode) {
        System.out.println("Stopping KeycloakServer");
        stopDockerKeycloak();
        System.out.println("Keycloak service stopped successfully");
    } else {
        // 启动逻辑...
    }
}

停止方式二：通过 KeycloakServerStop 独立类

KeycloakServerStop 是一个独立的 Java 类，拥有自己的 main 方法，可以独立运行。它实现了与 KeycloakServerStart 中 stopDockerKeycloak() 方法相同的停止逻辑，但有以下差异：

临时文件策略：KeycloakServerStop 将 docker-compose.yml 写入系统临时文件（Files.createTempFile），而非项目的 resources 目录。这是因为停止操作不需要维护持久化的 compose 文件。
更完善的降级策略：KeycloakServerStop 实现了更完善的多级降级策略，确保在各种异常情况下都能清理容器。

多级降级停止策略：

┌──────────────────────────────────────────────────────────┐
│              多级降级停止策略                               │
├──────────────────────────────────────────────────────────┤
│                                                          │
│  第一级：docker-compose down                              │
│  ├── 从 classpath 读取 docker-compose.yml                 │
│  ├── 写入临时文件                                         │
│  └── 执行 docker-compose -f <temp> down                  │
│       │                                                  │
│       ├── 成功 ──▶ 检查残留容器 ──▶ 完成                  │
│       │                                                  │
│       └── 失败 ──▶ 降级到第二级                           │
│                                                          │
│  第二级：直接 docker rm -f                                │
│  ├── docker ps -a -q --filter name=keycloak              │
│  └── 逐个执行 docker rm -f <container_id>                │
│       │                                                  │
│       ├── 成功 ──▶ 完成                                  │
│       │                                                  │
│       └── 失败 ──▶ 降级到第三级                           │
│                                                          │
│  第三级：异常捕获后的兜底清理                              │
│  ├── 捕获所有异常                                         │
│  └── 再次尝试 docker rm -f                               │
│       │                                                  │
│       └── 无论成功或失败，流程结束                         │
│           （输出错误信息供用户排查）                        │
│                                                          │
└──────────────────────────────────────────────────────────┘

KeycloakServerStop 的核心实现：

java

/**
 * 多级降级停止策略（教学简化版本）
 */
private static void stopDockerKeycloak() throws Exception {
    // 第一级：尝试 docker-compose down
    try {
        // 从 classpath 读取并写入临时文件
        Path tempFile = Files.createTempFile("docker-compose", ".yml");
        // ... 写入内容 ...

        // 执行 docker-compose down
        ProcessBuilder pb = new ProcessBuilder(
            dockerComposeCommand, "-f",
            tempFile.toString(), "down");
        // ... 配置环境变量 ...
        Process process = pb.start();
        process.waitFor();

        if (process.exitValue() == 0) {
            // 成功：检查并清理残留容器
            removeKeycloakContainers(dockerCommand);
            return;
        }
    } catch (Exception e) {
        // 异常：降级到第二级
    }

    // 第二级：直接删除容器
    try {
        removeKeycloakContainers(dockerCommand);
    } catch (Exception ex) {
        // 第三级：兜底清理
        System.err.println("Fallback removal also failed: "
            + ex.getMessage());
    }
}

为什么需要多级降级策略？

在实际使用中，容器停止可能因为各种原因失败：

docker-compose 文件丢失或损坏：如果之前启动时写入的 docker-compose.yml 被删除或修改，docker-compose down 可能失败
Docker 网络异常：docker-compose 在停止容器时需要清理关联的网络，如果网络配置异常可能导致失败
容器状态异常：容器可能处于 Dead、RemovalInProgress 等异常状态
权限问题：在某些环境下，当前用户可能没有足够的权限执行 docker-compose 操作

多级降级策略确保了即使高级别的操作失败，也能通过更底层的方式完成清理。

第六章服务就绪检测与健康检查

6.1 HTTP 健康检查实现

容器启动并不等于服务就绪。Keycloak 基于 Quarkus 框架，其启动过程包括组件扫描、SPI 加载、数据库初始化、HTTP 服务器启动等多个阶段。从容器进程启动到 HTTP 服务可用，通常需要数秒到数十秒的时间。

keycloak-server-docker 通过 HTTP 健康检查来确认 Keycloak 服务是否真正可用：

java

/**
 * HTTP 健康检查实现
 * 教学简化版本
 */
private static boolean checkServiceHealth(int maxAttempts,
                                          long intervalMs) throws Exception {
    System.out.println("Checking if Keycloak service is running...");

    boolean serviceReady = false;
    int attempt = 0;

    while (attempt < maxAttempts && !serviceReady) {
        try {
            // 使用 curl 命令检查 HTTP 服务
            Process curlProcess = Runtime.getRuntime().exec(
                "curl -I http://localhost:8080/admin");
            int curlExitCode = curlProcess.waitFor();

            if (curlExitCode == 0) {
                serviceReady = true;
                System.out.println("Keycloak service is now ready!");
            } else {
                System.out.println("Service not ready yet, waiting... ("
                    + (attempt + 1) + "/" + maxAttempts + ")");
                Thread.sleep(intervalMs);
            }
        } catch (Exception e) {
            System.out.println("Error checking service status: "
                + e.getMessage());
            System.out.println("Service not ready yet, waiting... ("
                + (attempt + 1) + "/" + maxAttempts + ")");
            Thread.sleep(intervalMs);
        }
        attempt++;
    }

    return serviceReady;
}

为什么选择检查 /admin 路径？

Keycloak 的管理控制台路径为 /admin，选择这个路径作为健康检查端点基于以下考虑：

可用性指示：/admin 页面需要 Keycloak 完全初始化后才能访问，包括所有 SPI 扩展的加载
无需认证：访问 /admin 路径会返回登录页面（HTTP 200），不需要提供认证信息
轻量级：curl -I 只请求 HTTP 头部信息，不下载完整的页面内容

curl -I 的作用：

-I 参数表示只获取 HTTP 响应头（HEAD 请求），不获取响应体。这种方式的优势：

更快的响应速度（不需要传输页面内容）
更少的资源消耗
足以判断服务是否可用（HTTP 200 表示服务正常）

6.2 重试策略与超时控制

服务就绪检测的重试策略与 Docker 守护进程检测类似，但参数有所不同：

参数	值	说明
maxAttempts	10	最大重试次数
intervalMs	2000	重试间隔（毫秒）
初始等待	5000ms	容器启动后的初始等待时间
总等待时间	~25秒	初始等待 + maxAttempts x intervalMs

为什么需要更长的等待时间？

Keycloak 的启动时间比 Docker 守护进程的响应时间长得多：

Quarkus 启动：Quarkus 框架的启动优化虽然显著，但首次启动仍需要数秒
SPI 扫描：Keycloak 需要扫描 providers 目录中的所有 JAR 文件并加载 SPI 扩展
数据库初始化：在开发模式下，Keycloak 使用 H2 内存数据库，需要创建表结构和初始数据
主题编译：Keycloak 需要编译自定义主题中的模板文件

10 次重试加上 2 秒间隔，总等待时间约 25 秒，足以覆盖大多数启动场景。

启动等待的时序图：

时间轴 ─────────────────────────────────────────────────────▶

docker-compose up -d
    │
    ▼
    ├─ 0s:  容器进程启动
    ├─ 1s:  Quarkus 框架初始化
    ├─ 3s:  SPI 扫描和加载
    ├─ 5s:  数据库初始化  ◄── 初始等待 5 秒结束
    │                    ◄── 开始健康检查
    ├─ 5s:  第1次检查 → 失败
    ├─ 7s:  第2次检查 → 失败
    ├─ 9s:  HTTP 服务器启动
    ├─ 9s:  第3次检查 → 失败
    ├─ 11s: 管理控制台初始化
    ├─ 11s: 第4次检查 → 成功 ✓
    │
    ▼
服务就绪！

6.3 服务就绪判定条件

服务就绪的判定基于以下条件：

HTTP 响应状态码为 200：curl -I 命令的退出码为 0，表示成功获取到 HTTP 响应
响应来自 Keycloak 服务：通过检查 localhost:8080 端口，确保响应来自 Keycloak 容器而非其他服务

更完善的健康检查方案（扩展思考）：

当前的实现使用 curl 命令进行健康检查，这在大多数环境下都能正常工作。但在某些特殊环境下（例如没有安装 curl 的系统），可能需要替代方案。以下是几种可选的增强方案：

方案一：使用 Java 原生 HTTP 客户端

java

// 使用 Java 11+ 的 HttpClient
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("http://localhost:8080/admin"))
    .method("HEAD", HttpRequest.BodyPublishers.noBody())
    .timeout(Duration.ofSeconds(5))
    .build();

HttpResponse<String> response = client.send(request,
    HttpResponse.BodyHandlers.ofString());
boolean isReady = response.statusCode() == 200;

方案二：使用 Keycloak 的健康检查端点

Keycloak 从较新版本开始提供了 /health/ready 和 /health/live 端点（基于 SmallRye Health）：

java

// 使用 Keycloak 内置的健康检查端点
Process curlProcess = Runtime.getRuntime().exec(
    "curl -f http://localhost:8080/health/ready");

方案三：使用 TCP 端口检测

java

// 使用 Java Socket 检测端口是否可连接
try (Socket socket = new Socket()) {
    socket.connect(
        new InetSocketAddress("localhost", 8080), 5000);
    // 端口可连接，但服务不一定就绪
}

6.4 启动失败处理

当所有重试都失败后，keycloak-server-docker 会提供清晰的错误信息和排查建议：

java

if (serviceReady) {
    System.out.println("Keycloak service started successfully "
        + "and is ready for use");
    return true;
} else {
    System.err.println("Keycloak service did not start within "
        + "the expected time");
    System.err.println("Please check the container logs for "
        + "more information");
    return false;
}

启动失败的常见原因和排查方法：

失败现象	可能原因	排查方法
容器启动失败	镜像拉取失败	`docker pull quay.io/keycloak/keycloak:<version>`
端口冲突	8080 端口被占用	`lsof -i :8080` 或 `netstat -tlnp`
SPI 加载失败	JAR 文件损坏或依赖缺失	`docker logs <container_id>`
内存不足	JVM 分配内存过大	`docker stats` 查看资源使用
健康检查超时	服务启动过慢	增加重试次数或间隔时间

查看容器日志的命令：

bash

# 查看 docker-compose 项目的日志
docker-compose -f docker-compose.yml logs -f

# 查看特定容器的日志
docker logs -f <container_id>

# 查看最后的 100 行日志
docker logs --tail 100 <container_id>

完整的启动流程状态机：

                    ┌──────────┐
                    │  开始    │
                    └────┬─────┘
                         │
                    ┌────▼─────┐
                    │Docker    │──── 失败 ──▶ 返回 false
                    │守护进程  │
                    │检测      │
                    └────┬─────┘
                         │ 成功
                    ┌────▼─────┐
                    │残留容器  │
                    │清理      │
                    └────┬─────┘
                         │
                    ┌────▼─────┐
                    │镜像      │──── 不存在 ──▶ 拉取镜像
                    │存在性    │                      │
                    │检测      │              ┌───────┴──────┐
                    └────┬─────┘              │ 拉取成功？   │
                         │ 存在               └───────┬──────┘
                         │                     │Yes    │No
                    ┌────▼─────────────────────▼───────▼────┐
                    │docker-compose up -d                    │
                    └────┬──────────────────────────────────┘
                         │
                    ┌────▼─────┐
                    │初始等待  │
                    │5秒       │
                    └────┬─────┘
                         │
                    ┌────▼─────┐
                    │HTTP健康  │──── 成功 ──▶ 返回 true
                    │检查      │
                    │(10次)    │
                    └────┬─────┘
                         │ 全部失败
                    ┌────▼─────┐
                    │输出错误  │
                    │信息      │
                    └────┬─────┘
                         │
                    ┌────▼─────┐
                    │返回false │
                    └──────────┘

第七章跨平台兼容设计

7.1 操作系统检测

跨平台兼容是 keycloak-server-docker 的核心设计目标之一。整个模块需要在 Windows、Linux 和 macOS 三个主流操作系统上无缝运行。

操作系统检测是跨平台适配的第一步：

java

String os = System.getProperty("os.name").toLowerCase();

if (os.contains("win")) {
    // Windows 平台逻辑
} else if (os.contains("mac")) {
    // macOS 平台逻辑
} else if (os.contains("nix") || os.contains("nux") || os.contains("aix")) {
    // Linux/Unix 平台逻辑
}

System.getProperty("os.name") 的返回值示例：

操作系统	`os.name` 返回值	`toLowerCase()` 后
Windows 11	`Windows 11`	`windows 11`
Windows 10	`Windows 10`	`windows 10`
macOS 14 Sonoma	`Mac OS X`	`mac os x`
Ubuntu 22.04	`Linux`	`linux`
CentOS 7	`Linux`	`linux`
Fedora 39	`Linux`	`linux`

在 keycloak-server-docker 的当前实现中，操作系统检测主要用于区分 Windows 和非 Windows 平台，以确定 Docker 命令的路径。

7.2 路径分隔符处理

不同操作系统使用不同的路径分隔符：

Windows：反斜杠 \（但在 Java 中也可以使用正斜杠 /）
Linux/macOS：正斜杠 /

keycloak-server-docker 使用 Java NIO 的 Path API 来处理路径，自动适配不同操作系统的路径分隔符：

java

// 使用 Path API 构建跨平台路径
Path dockerComposeDir = Path.of(
    System.getProperty("user.dir"),
    "src", "main", "resources");

// Path.of() 会自动使用正确的路径分隔符
// Windows: C:\project\src\main\resources
// Linux:   /home/user/project/src/main/resources
// macOS:   /Users/user/project/src/main/resources

Path.of() vs 手动字符串拼接：

java

// 错误方式：手动拼接（跨平台问题）
String path = System.getProperty("user.dir")
    + "/src/main/resources";  // 在 Windows 上可能有问题

// 正确方式：使用 Path API
Path path = Path.of(System.getProperty("user.dir"),
    "src", "main", "resources");

卷挂载路径的跨平台注意事项：

docker-compose.yml 中的卷挂载路径在不同操作系统上的行为不同：

yaml

volumes:
  - ./keycloak-providers:/opt/keycloak/providers

Linux/macOS：./keycloak-providers 相对路径正常工作
Windows：Docker Desktop for Windows 会自动处理路径转换，将 Windows 路径映射到 WSL2 或 Hyper-V 虚拟机中的路径

在 Windows 上，如果遇到卷挂载问题，可能需要检查 Docker Desktop 的文件共享设置。

7.3 命令差异适配

除了 Docker 命令的路径差异外，不同平台上的命令执行还存在以下差异：

差异一：curl 命令的可用性

健康检查使用 curl 命令，但 curl 在不同平台上的可用性不同：

Linux：大多数发行版预装 curl
macOS：系统预装 curl
Windows：Windows 10 1803+ 版本自带 curl（作为 PowerShell 的别名），但行为可能与 Linux 版本略有差异

差异二：docker-compose 命令的版本

旧版：独立的 docker-compose 命令（Python 实现）
新版：docker compose（作为 Docker CLI 的插件，注意没有连字符）

keycloak-server-docker 当前使用 docker-compose（带连字符），兼容旧版和新版 Docker。如果需要支持新版 Docker CLI 插件，可以添加命令探测逻辑：

java

/**
 * 探测可用的 docker-compose 命令
 * 教学简化版本
 */
private static String detectDockerComposeCommand() {
    // 优先尝试新版（Docker CLI 插件）
    if (commandExists("docker", "compose", "version")) {
        return "docker compose";
    }
    // 回退到旧版（独立命令）
    if (commandExists("docker-compose", "version")) {
        return "docker-compose";
    }
    throw new RuntimeException("docker-compose not found");
}

private static boolean commandExists(String... command) {
    try {
        Process p = new ProcessBuilder(command)
            .redirectErrorStream(true)
            .start();
        return p.waitFor() == 0;
    } catch (Exception e) {
        return false;
    }
}

差异三：进程信号处理

在停止容器时，不同平台对进程信号的处理方式不同：

Linux/macOS：支持 SIGTERM、SIGKILL 等信号
Windows：不支持 Unix 信号，使用 TerminateProcess API

由于我们使用 docker rm -f 和 docker-compose down 来停止容器，这些命令在所有平台上都能正常工作，因此不需要直接处理进程信号。

7.4 Windows/Linux/Mac 三平台测试

为了确保跨平台兼容性，keycloak-server-docker 需要在三个平台上进行测试。以下是各平台的测试要点：

Windows 平台测试要点：

Docker Desktop 确认：确保 Docker Desktop for Windows 已安装并运行
WSL2 集成：如果使用 WSL2 后端，确认文件共享设置正确
路径长度限制：Windows 的 MAX_PATH 限制（260 字符）可能影响深层目录操作
curl 可用性：确认 curl 命令可用（PowerShell 环境下可能需要使用 curl.exe）
防火墙设置：确认 Windows 防火墙不会阻止 Docker 的网络操作

Linux 平台测试要点：

Docker Engine 安装：确认 Docker Engine（非 Docker Desktop）已正确安装
用户权限：确认当前用户在 docker 组中（或使用 sudo）
SELinux/AppArmor：某些安全模块可能影响卷挂载
端口可用性：确认 8080 端口未被其他服务占用
文件权限：确认 providers 和 themes 目录有正确的读写权限

macOS 平台测试要点：

Docker Desktop 确认：确保 Docker Desktop for Mac 已安装并运行
内存分配：Docker Desktop for Mac 的默认内存分配可能不足，建议至少 4GB
文件系统性能：macOS 上的 Docker 卷挂载性能可能较慢（尤其是 bind mount）
Apple Silicon 兼容：在 M1/M2/M3 芯片上，Keycloak 镜像需要是 ARM64 架构（官方镜像已支持）

跨平台测试矩阵：

┌──────────────────────────────────────────────────────────────────┐
│                    跨平台测试矩阵                                 │
├──────────────┬──────────────┬──────────────┬─────────────────────┤
│   测试项     │   Windows    │   Linux      │   macOS             │
├──────────────┼──────────────┼──────────────┼─────────────────────┤
│ Docker检测    │ Docker       │ Docker       │ Docker Desktop      │
│              │ Desktop      │ Engine       │                     │
├──────────────┼──────────────┼──────────────┼─────────────────────┤
│ 命令路径      │ docker.exe   │ /usr/local/  │ /usr/local/bin/     │
│              │              │ bin/docker   │ docker              │
├──────────────┼──────────────┼──────────────┼─────────────────────┤
│ compose命令  │ docker-      │ docker-      │ docker-compose      │
│              │ compose.exe  │ compose      │                     │
├──────────────┼──────────────┼──────────────┼─────────────────────┤
│ curl可用性   │ PowerShell   │ 系统预装     │ 系统预装            │
│              │ 别名         │              │                     │
├──────────────┼──────────────┼──────────────┼─────────────────────┤
│ 卷挂载       │ WSL2/        │ 原生         │ VirtioFS            │
│              │ Hyper-V      │              │                     │
├──────────────┼──────────────┼──────────────┼─────────────────────┤
│ 路径分隔符    │ \ 或 /       │ /            │ /                   │
├──────────────┼──────────────┼──────────────┼─────────────────────┤
│ 临时目录      │ C:\Users\    │ /tmp         │ /var/folders/...    │
│              │ ...\AppData  │              │                     │
│              │ \Local\Temp  │              │                     │
└──────────────┴──────────────┴──────────────┴─────────────────────┘

总结与展望

技术总结

本文深入剖析了 keycloak-server-docker 模块的完整技术实现，从架构选择到跨平台兼容，覆盖了 Java 驱动 Docker 容器编排的方方面面。让我们回顾一下核心的技术决策和设计模式：

架构层面：

选择了 ProcessBuilder 而非 Docker Java 客户端库，这个决策基于"依赖最小化"和"docker-compose 原生支持"两个核心原则。虽然牺牲了类型安全性，但换来了零外部依赖、与 Docker CLI 行为完全一致、以及天然的 docker-compose 支持。对于一个定位为轻量级工具的模块来说，这是一个合理的权衡。

可靠性层面：

在多个关键环节实现了重试策略和降级机制：

Docker 守护进程检测：5 次重试，2 秒间隔
镜像拉取：3 次重试，3 秒间隔，含认证错误降级
服务就绪检测：10 次重试，2 秒间隔，含初始等待
容器停止：三级降级策略（compose down -> rm -f -> 兜底清理）

这些策略共同构成了一个健壮的容器编排系统，能够在各种异常条件下优雅地处理错误。

自动化层面：

通过 org.keycloak.common.Version.VERSION 实现了版本号的自动获取和传播，消除了手动维护版本号的风险。classpath 资源读取和写入机制确保了 docker-compose.yml 模板与代码的一致性。providers 和 themes 目录的自动创建简化了开发环境的初始化。

跨平台层面：

通过操作系统检测、路径适配、命令差异处理等机制，确保了同一份代码在 Windows、Linux、macOS 三个平台上的兼容性。

设计模式回顾

keycloak-server-docker 的实现中体现了多种经典的设计模式：

设计模式	应用场景
模板方法模式	docker-compose.yml 作为模板，运行时动态注入版本号
重试模式	Docker 守护进程检测、镜像拉取、健康检查的重试策略
降级模式	镜像拉取的认证错误降级、容器停止的多级降级
策略模式	跨平台命令路径的选择策略
资源管理模式	classpath 资源的读取、临时文件的创建和清理

改进方向与展望

虽然 keycloak-server-docker 已经实现了一个功能完整的容器编排方案，但仍有以下改进空间：

方向一：配置外部化

当前的环境配置（管理员密码、端口号等）硬编码在 docker-compose.yml 中。可以将这些配置外部化到 properties 文件或环境变量中，提供更灵活的配置方式：

properties

# application.properties
keycloak.admin.username=root
keycloak.admin.password=root
keycloak.http.port=8080
keycloak.debug.enabled=false

方向二：日志框架集成

当前使用 System.out.println 输出日志，可以集成 SLF4J 等日志框架，提供更丰富的日志级别控制和格式化输出：

java

private static final Logger logger =
    LoggerFactory.getLogger(KeycloakServerStart.class);

logger.info("Keycloak version: {}", Version.VERSION);
logger.debug("Docker command: {}", dockerCommand);
logger.error("Failed to pull image: {}", imageName);

方向三：容器状态监控

可以增加容器状态的持续监控能力，定期检查容器的运行状态、资源使用情况，并在异常时发出告警：

java

// 容器状态监控（扩展思考）
ScheduledExecutorService scheduler = Executors
    .newSingleThreadScheduledExecutor();
scheduler.scheduleAtFixedRate(() -> {
    String status = getContainerStatus(dockerCommand);
    if (!"running".equals(status)) {
        logger.warn("Container status: {}", status);
    }
}, 0, 30, TimeUnit.SECONDS);

方向四：多容器编排支持

当前只编排单个 Keycloak 容器。在实际开发中，可能需要同时启动数据库（PostgreSQL）、缓存（Redis）等依赖服务。可以通过扩展 docker-compose.yml 来支持多容器编排：

yaml

services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: keycloak
    ports:
      - "5432:5432"

  keycloak:
    image: quay.io/keycloak/keycloak:${keycloak_version}
    depends_on:
      - postgres
    environment:
      - KC_DB=postgres
      - KC_DB_URL=jdbc:postgresql://postgres:5432/keycloak
      - KC_DB_USERNAME=keycloak
      - KC_DB_PASSWORD=keycloak
    ports:
      - "8080:8080"
    volumes:
      - ./keycloak-providers:/opt/keycloak/providers

方向五：与 IDE 深度集成

可以开发 IDE 插件（IntelliJ IDEA、Eclipse、VS Code），提供图形化的容器管理界面，包括一键启动/停止、日志查看、SPI 部署等功能，进一步提升开发体验。

最终架构全景图

┌─────────────────────────────────────────────────────────────────────┐
│              keycloak-server-docker 完整架构全景图                    │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │                    用户入口层                                │   │
│  │                                                              │   │
│  │  java -jar keycloak-server-docker.jar        启动模式       │   │
│  │  java -jar keycloak-server-docker.jar --stop  停止模式       │   │
│  │  KeycloakServerStop.main()                   独立停止        │   │
│  └──────────────────────────┬──────────────────────────────────┘   │
│                              │                                      │
│  ┌──────────────────────────▼──────────────────────────────────┐   │
│  │                    编排控制层                                │   │
│  │                                                              │   │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │   │
│  │  │ 环境预检      │  │ 容器编排      │  │ 健康检查      │      │   │
│  │  │              │  │              │  │              │      │   │
│  │  │ Docker检测   │  │ compose up   │  │ HTTP检查     │      │   │
│  │  │ 残留清理     │  │ 环境变量注入  │  │ 重试策略     │      │   │
│  │  │ 镜像管理     │  │ 版本号替换   │  │ 超时控制     │      │   │
│  │  │ 目录创建     │  │ 卷挂载配置   │  │ 状态反馈     │      │   │
│  │  └──────────────┘  └──────────────┘  └──────────────┘      │   │
│  └──────────────────────────┬──────────────────────────────────┘   │
│                              │                                      │
│  ┌──────────────────────────▼──────────────────────────────────┐   │
│  │                    进程执行层                                │   │
│  │                                                              │   │
│  │  ProcessBuilder / Runtime.exec()                             │   │
│  │  ├── docker info          守护进程检测                        │   │
│  │  ├── docker ps -a -q      容器查询                            │   │
│  │  ├── docker rm -f         容器删除                            │   │
│  │  ├── docker images -q     镜像查询                            │   │
│  │  ├── docker pull          镜像拉取                            │   │
│  │  ├── docker-compose up -d 容器启动                            │   │
│  │  ├── docker-compose down  容器停止                            │   │
│  │  └── curl -I              健康检查                            │   │
│  └──────────────────────────┬──────────────────────────────────┘   │
│                              │                                      │
│  ┌──────────────────────────▼──────────────────────────────────┐   │
│  │                    跨平台适配层                              │   │
│  │                                                              │   │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐                  │   │
│  │  │ Windows  │  │  Linux   │  │  macOS   │                  │   │
│  │  │          │  │          │  │          │                  │   │
│  │  │docker.exe│  │/usr/local│  │/usr/local│                  │   │
│  │  │compose   │  │/bin/     │  │/bin/     │                  │   │
│  │  │.exe      │  │docker    │  │docker    │                  │   │
│  │  │          │  │          │  │          │                  │   │
│  │  │Path API  │  │Path API  │  │Path API  │                  │   │
│  │  │适配      │  │原生支持  │  │原生支持  │                  │   │
│  │  └──────────┘  └──────────┘  └──────────┘                  │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │                    基础设施层                                │   │
│  │                                                              │   │
│  │  Docker Engine / Docker Desktop                              │   │
│  │  ├── Docker Daemon (dockerd)                                 │   │
│  │  ├── Container Runtime (containerd/runc)                     │   │
│  │  └── Network / Volume / Image Management                    │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

结语

keycloak-server-docker 模块展示了如何用最简单的技术手段（Java 标准库 + Docker CLI）构建一个健壮的容器编排方案。它没有引入任何第三方依赖，没有使用复杂的框架，却完整地覆盖了容器生命周期管理的所有关键环节。

这种"简单但不简陋"的设计哲学，对于工具类项目的开发具有重要的参考价值。在技术选型时，我们不应该盲目追求"最先进"或"最流行"的方案，而应该基于实际需求，选择最合适的方案。有时候，最简单的方案反而是最好的方案。

希望本文能够为正在探索 Java 与 Docker 集成的开发者提供有价值的参考。如果您对 keycloak-sandbox 项目感兴趣，欢迎访问项目仓库了解更多信息。

版权声明： 本文为必码（bima.cc）原创技术文章，仅供学习交流。
本文内容基于实际项目源码解析整理，代码示例均为教学简化版本，仅供学习参考。
如需获取完整项目代码或技术支持，请访问 bima.cc。

Keycloak Docker 沙箱 Java 原生容器编排：ProcessBuilder 驱动 docker-compose 的完整实践 ​

前言 ​

Keycloak SPI 开发的容器化困境 ​

本文定位 ​

读者受众 ​

第一章 Java 驱动 Docker 的架构选择 ​

1.1 Docker Java 客户端库 vs ProcessBuilder ​

1.2 为什么选择 ProcessBuilder ​

1.3 keycloak-server-docker 模块定位 ​

第二章 Docker 守护进程检测与初始化 ​

2.1 Docker 可用性检测 ​

2.2 重试策略设计 ​

2.3 Docker Credential Store 问题处理 ​

2.4 跨平台 Docker 路径适配 ​

第三章 Keycloak Docker 镜像管理 ​

3.1 镜像版本自动获取 ​

3.2 quay.io/keycloak/keycloak 镜像 ​

3.3 镜像拉取策略 ​

3.4 镜像存在性检测 ​

第四章 docker-compose 动态生成与启动 ​

4.1 docker-compose.yml 模板设计 ​

4.2 版本号动态注入 ​

4.3 classpath 资源读取与写入 ​

4.4 docker-compose up 执行 ​

4.5 环境变量配置 ​

第五章 容器生命周期管理 ​

5.1 残留容器自动清理 ​

5.2 providers 目录挂载 ​

5.3 themes 目录挂载 ​

5.4 容器停止与资源释放 ​

第六章 服务就绪检测与健康检查 ​

6.1 HTTP 健康检查实现 ​

6.2 重试策略与超时控制 ​

6.3 服务就绪判定条件 ​

6.4 启动失败处理 ​

第七章 跨平台兼容设计 ​

7.1 操作系统检测 ​

7.2 路径分隔符处理 ​

7.3 命令差异适配 ​

7.4 Windows/Linux/Mac 三平台测试 ​

总结与展望 ​

技术总结 ​

设计模式回顾 ​

改进方向与展望 ​

最终架构全景图 ​

结语 ​

Keycloak Docker 沙箱 Java 原生容器编排：ProcessBuilder 驱动 docker-compose 的完整实践

前言

Keycloak SPI 开发的容器化困境

本文定位

读者受众

第一章 Java 驱动 Docker 的架构选择

1.1 Docker Java 客户端库 vs ProcessBuilder

1.2 为什么选择 ProcessBuilder

1.3 keycloak-server-docker 模块定位

第二章 Docker 守护进程检测与初始化

2.1 Docker 可用性检测

2.2 重试策略设计

2.3 Docker Credential Store 问题处理

2.4 跨平台 Docker 路径适配

第三章 Keycloak Docker 镜像管理

3.1 镜像版本自动获取

3.2 quay.io/keycloak/keycloak 镜像

3.3 镜像拉取策略

3.4 镜像存在性检测

第四章 docker-compose 动态生成与启动

4.1 docker-compose.yml 模板设计

4.2 版本号动态注入

4.3 classpath 资源读取与写入

4.4 docker-compose up 执行

4.5 环境变量配置

第五章容器生命周期管理

5.1 残留容器自动清理

5.2 providers 目录挂载

5.3 themes 目录挂载

5.4 容器停止与资源释放

第六章服务就绪检测与健康检查

6.1 HTTP 健康检查实现

6.2 重试策略与超时控制

6.3 服务就绪判定条件

6.4 启动失败处理

第七章跨平台兼容设计

7.1 操作系统检测

7.2 路径分隔符处理

7.3 命令差异适配

7.4 Windows/Linux/Mac 三平台测试

总结与展望

技术总结

设计模式回顾

改进方向与展望

最终架构全景图

结语