GitLab流水线中Testcontainers Redis集群报JedisConnectionException问题

核心问题根源 #

1. Redis集群端口映射不完整：Redis集群需要两个关键端口——6379（客户端连接用）和16379（集群节点间总线通信用）。之前用fixedExposePort时强制完成了双端口映射，节点间能正常通信；去掉后仅映射单个端口，导致集群内部连通性断裂，本地和流水线都出现连接问题。
2. 集群节点地址宣告错误：Redis集群启动后默认向客户端返回容器内部的IP和端口，而GitLab流水线（或本地无固定端口场景）的外部环境无法访问该内部地址，Jedis客户端拿到无效地址自然无法建立连接。
3. Testcontainers网络与Runner配置不匹配：GitLab Runner的Docker网络模式（如bridge）和本地环境可能存在差异，若端口映射规则配置不当，外部无法正常访问容器内的Redis服务。

解决步骤 #

1. 完整映射Redis集群所需端口 #

必须同时映射6379和16379端口，兼顾客户端连接和集群内部通信需求。以Java代码为例：

RedisClusterContainer redisCluster = new RedisClusterContainer(DockerImageName.parse("redis:7-alpine"))
    // 暴露两个必要端口
    .withExposedPorts(6379, 16379)
    .withCreateContainerCmdModifier(cmd -> cmd.withHostConfig(
        new HostConfig().withPortBindings(
            // 绑定客户端端口到主机
            new PortBinding(Ports.Binding.bindPort(6379), new ExposedPort(6379)),
            // 绑定集群总线端口到主机
            new PortBinding(Ports.Binding.bindPort(16379), new ExposedPort(16379))
        )
    ));

若不想用固定端口，也可使用动态映射，但需确保后续能正确获取映射后的端口号。

2. 让Redis集群宣告外部可访问的地址 #

启动Redis集群时，强制节点对外报告Testcontainers提供的主机和映射后的端口，确保Jedis客户端拿到有效访问地址：

redisCluster.withCommandModifier(cmd -> cmd.withArgs(
    "--cluster-announce-ip", redisCluster.getHost(),
    "--cluster-announce-port", redisCluster.getMappedPort(6379).toString(),
    "--cluster-announce-bus-port", redisCluster.getMappedPort(16379).toString()
));

3. 动态构建JedisCluster连接参数 #

禁止硬编码localhost或固定端口，从容器对象动态获取连接信息：

Set<HostAndPort> jedisClusterNodes = new HashSet<>();
// 用容器暴露的主机和映射后的端口构建节点
jedisClusterNodes.add(new HostAndPort(redisCluster.getHost(), redisCluster.getMappedPort(6379)));
JedisCluster jedisCluster = new JedisCluster(jedisClusterNodes);

4. 检查GitLab Runner配置 #

• 确认Runner的Docker executor网络模式：若使用bridge模式，需保证端口映射规则生效；若使用host模式，注意避免端口冲突。
• 确保Runner拥有足够权限创建、管理容器，Testcontainers所需的Docker权限不能被限制。

额外排查技巧 #

• 在GitLab流水线中添加调试步骤，执行docker exec <container-id> redis-cli cluster info，查看集群状态是否正常、节点间是否连通。
• 对比本地和流水线的Testcontainers版本，版本差异可能引发兼容性问题，尽量保持环境版本一致。

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