Testcontainers-dotnet 中 Keycloak 容器健康检查端口变更问题解析

问题背景

在使用 Testcontainers-dotnet 3.9.0 版本时，开发者发现当使用 Keycloak 25.0.1 版本镜像时，容器无法正常启动。经过排查，这是由于 Keycloak 25.0.0 及以上版本的健康检查端点端口发生了变化，从原先的 8080 端口变更为 9000 端口。

技术细节分析

Keycloak 是一个开源的身份和访问管理解决方案，Testcontainers-dotnet 提供了对 Keycloak 容器的原生支持。在 Keycloak 21 版本及以下，健康检查端点 /health/ready 默认监听在 8080 端口，这与主应用服务端口相同。

从 Keycloak 25.0.0 版本开始，管理接口（包括健康检查端点）被分离到独立的端口 9000 上。这一变更符合现代应用架构中管理接口与业务接口分离的最佳实践，可以提高安全性并减少主业务端口的负载。

解决方案

针对这一变更，开发者可以采用以下几种解决方案：

1. 显式指定健康检查端口：通过自定义等待策略，明确指定健康检查使用 9000 端口。

var keycloak = new KeycloakBuilder()
    .WithImage("quay.io/keycloak/keycloak:25.0.1")
    .WithPortBinding(9000, true)
    .WithWaitStrategy(Wait.ForUnixContainer()
        .UntilHttpRequestIsSucceeded(request => 
            request.ForPath("/health/ready").ForPort(9000)))
    .Build();

2. 配置管理端口：利用 Keycloak 提供的环境变量将管理端口重新映射到 8080。

.WithEnvironment("KC_HTTP_MANAGEMENT_PORT", "8080")

需要注意的是，虽然第二种方法可以让容器启动，但健康检查端点可能仍然无法在 8080 端口响应，因此第一种方案更为可靠。

版本兼容性建议

对于需要同时支持多个 Keycloak 版本的项目，建议实现版本检测逻辑，根据不同的镜像版本自动选择正确的健康检查端口。可以在容器启动时检查镜像标签，然后动态设置相应的等待策略。

最佳实践

1. 明确指定使用的 Keycloak 版本，避免使用 latest 标签
2. 在升级 Keycloak 版本时，特别注意管理接口和健康检查端口的变更
3. 考虑在测试中验证健康检查端口的可用性，而不仅仅是容器启动状态

总结

Testcontainers-dotnet 作为一个强大的测试容器库，为 Keycloak 集成提供了良好支持。理解 Keycloak 25.0.0 版本引入的管理端口变更，能够帮助开发者更有效地配置和使用测试容器。通过适当的配置，可以确保测试环境的稳定性和可靠性。