GitLab Runner绑定Docker Socket时Testcontainers连Ryuk报错排查

该故障与自定义镜像缺依赖无关，核心是Socket挂载模式下TESTCONTAINERS_HOST_OVERRIDE配置错误导致的网络链路不通：

• 你通过挂载/var/run/docker.sock让CI作业容器直接调用宿主机Docker daemon，Testcontainers启动的Ryuk、PostgreSQL容器实际运行在宿主机Docker环境中
• 你手动配置了TESTCONTAINERS_HOST_OVERRIDE=host.docker.internal，强制Testcontainers走宿主机映射端口访问Ryuk，但Ryuk启动时默认将暴露端口绑定在宿主机127.0.0.1回环地址，没有绑定到host-gateway对应的网卡地址，CI作业容器发往host.docker.internal的流量根本到不了Ryuk的监听端口，最终触发Ryuk侧等待首个连接超时、Testcontainers侧连接Ryuk失败的报错。

本地IDE、命令行执行测试时没有这个问题，是因为本地Docker环境默认会将容器端口绑定到所有网卡，且本地测试时Testcontainers和Docker daemon在同一网络命名空间，不存在跨容器网络路由问题。

按顺序验证即可快速定位问题：

• 第一步：验证Socket权限，在test任务的script块中加入docker ps命令，确认CI作业容器内可以正常列出宿主机上运行的Docker容器，排除Socket读写权限问题。
• 第二步：验证端口绑定，测试触发Ryuk启动后，在gitlab-runner宿主机执行docker ps查看Ryuk容器的端口映射规则，如果显示为127.0.0.1:随机端口->8080/tcp，即可确认端口仅绑定回环地址，CI容器无法跨网络访问。
• 第三步：验证连通性，在test任务脚本中加入nc -zv host.docker.internal <Ryuk映射的随机端口>，如果返回连接超时/拒绝，即可确认网络链路不通。

优先选方案1，配置最简单、稳定性最高，不需要修改runner或宿主机配置。

方案1：使用Testcontainers原生Socket模式（推荐） #

删除原有错误的TESTCONTAINERS_HOST_OVERRIDE配置，补充Socket路径变量，让Testcontainers自动适配Docker网络：

variables:
  DOCKER_HOST: unix:///var/run/docker.sock
  TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE: /var/run/docker.sock
  # 注释或删除下面这行错误配置
  # TESTCONTAINERS_HOST_OVERRIDE: "host.docker.internal"

该模式下Testcontainers启动依赖容器时，会自动创建共享Docker网络，作业容器不需要绕宿主机端口映射，直接通过Docker内部DNS即可访问Ryuk、PostgreSQL等容器，完全规避端口绑定、防火墙拦截问题。
如果使用的Testcontainers版本低于1.17.0，额外添加一行配置关闭旧版本的主机IP强制探测逻辑即可：

variables:
  TESTCONTAINERS_HOST_OVERRIDE: "docker"

方案2：保留host.docker.internal路由模式 #

如果因为环境限制必须走宿主机端口路由，需要做三处调整：

1. 调整gitlab-runner的Docker配置，在[runners.docker]段添加userns_mode = "host"，保证作业容器和宿主机网络命名空间路由连通。
2. 修改宿主机Docker daemon配置（/etc/docker/daemon.json），添加"ip": "0.0.0.0"配置，让Docker启动容器时默认将暴露端口绑定到所有网卡，重启Docker生效。
3. 放通宿主机防火墙规则，允许Docker网桥网段（默认172.17.0.0/16）访问宿主机临时端口段。

快速验证方案 #

如果需要快速确认问题根因，可以临时关闭Ryuk资源回收器执行测试：

variables:
  TESTCONTAINERS_RYUK_DISABLED: "true"

如果关闭Ryuk后测试可以正常运行，即可100%确认故障为Ryuk网络访问链路问题，和镜像、JDK、Gradle配置无关。

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