升级Maven依赖至8.7.1后Zeebe Testcontainer连接失败

我有一个基于Spring Boot的Camunda Zeebe应用，原依赖配置如下：

<dependency>
  <groupId>io.camunda</groupId>
  <artifactId>spring-boot-starter-camunda-sdk</artifactId>
  <version>8.6.13</version>
</dependency>
<dependency>
  <groupId>io.camunda</groupId>
  <artifactId>zeebe-protocol</artifactId>
  <version>8.6.13</version>
</dependency>
<dependency>
  <groupId>io.camunda</groupId>
  <artifactId>zeebe-process-test-extension-testcontainer</artifactId>
  <version>8.6.13</version>
  <scope>test</scope>
</dependency>

此前通过Testcontainer启动Zeebe容器运行正常，但将所有依赖版本升级至8.7.1后，集成测试出现Connection refused: /0.0.0.0:26500错误。

问题原因 #

Camunda 8.7版本对Testcontainer的集成逻辑做了调整，默认端口暴露、容器启动就绪判断逻辑发生变化，导致应用尝试连接的0.0.0.0:26500并非容器实际映射的宿主机端口，或容器未完全就绪就发起连接。

解决方案 #

• 动态获取容器实际映射端口
  不要硬编码26500端口，通过Testcontainer API获取容器映射到宿主机的实际端口：

  ZeebeContainer zeebeContainer = new ZeebeContainer(DockerImageName.parse("camunda/zeebe:8.7.1"));
  zeebeContainer.start();
  // 获取容器26500端口对应的宿主机端口
  Integer actualGatewayPort = zeebeContainer.getExternalPort(26500);
  // 用实际端口初始化Zeebe客户端
  ZeebeClient zeebeClient = ZeebeClient.newClientBuilder()
          .gatewayAddress(String.format("localhost:%d", actualGatewayPort))
          .build();
  

• 适配新版本自动配置
  8.7版本的spring-boot-starter-camunda-sdk内置了Testcontainer自动配置支持，可通过配置文件指定容器地址：
  在application-test.yml中添加：

  camunda:
    zeebe:
      gateway-address: ${zeebe.container.gateway-address}
  

  无需手动编写容器启动代码，starter会自动管理容器生命周期并注入正确的地址。

• 增加容器就绪等待逻辑
  新版本Zeebe容器启动耗时可能更长，添加等待策略确保容器完全就绪后再发起连接：

  ZeebeContainer zeebeContainer = new ZeebeContainer(DockerImageName.parse("camunda/zeebe:8.7.1"))
          .waitingFor(Wait.forHttp("/actuator/health")
                  .forPort(9600)
                  .forStatusCode(200)
                  .withStartupTimeout(Duration.ofMinutes(2)));
  zeebeContainer.start();
  

• 确保依赖版本完全一致
  检查pom.xml中所有io.camundagroupId的依赖版本均为8.7.1，避免混合版本导致的兼容性冲突。

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