BitBucket Pipelines运行Testcontainers容器启动失败排查

问题根因 #

Bitbucket Pipelines 内置Docker服务有严格的卷挂载限制：仅允许挂载$BITBUCKET_CLONE_DIR（流水线默认工作目录，路径为/opt/atlassian/pipelines/agent/build）及其子目录。
Testcontainers 默认通过挂载宿主机/var/run/docker.sock套接字的方式和Docker守护进程通信，自动生成的挂载规则里包含/var/run/docker.sock:/docker.sock:rw项，该路径不在Bitbucket允许的挂载范围内，会被流水线权限插件直接拦截：

Status 403: {"message":"authorization denied by plugin pipelines: -v only supports $BITBUCKET_CLONE_DIR and its subdirectories"}

配置TESTCONTAINERS_CHECKS_DISABLE=true仅会跳过Testcontainers客户端的前置校验，不会解决挂载被拦截的核心问题，最终触发容器启动失败报错：

Could not start container java.lang.IllegalStateException: Container did not start correctly.

解决步骤 #

核心配置调整（推荐） #

Bitbucket Pipelines 内置的Docker服务默认在tcp://127.0.0.1:2375暴露无TLS的守护进程端口，不需要挂载docker.sock即可完成通信，只需在流水线集成测试步骤中添加对应环境变量，让Testcontainers走TCP协议连接Docker即可：

1. 移除原有的TESTCONTAINERS_CHECKS_DISABLE=true配置
2. 在script段添加两个环境变量：

script:
  - export TESTCONTAINERS_RYUK_DISABLED=true
  - export DOCKER_HOST=tcp://127.0.0.1:2375
  - export TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE=/nonexistent/path
  - mvn -B verify -Dsurefire.skip=true --file pom.xml

变量说明：

• DOCKER_HOST=tcp://127.0.0.1:2375：指定Testcontainers通过TCP端口访问Docker守护进程，不再尝试挂载宿主机docker.sock
• TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE=/nonexistent/path：禁止Testcontainers向启动的业务容器注入docker.sock挂载规则，彻底规避违规的-v参数

持久化配置（可选） #

如果需要本地测试和流水线配置统一，可以在项目测试资源目录下新增testcontainers.properties文件，固定Docker连接规则：

docker.host=tcp://127.0.0.1:2375
ryuk.disabled=true
docker.client.strategy=org.testcontainers.dockerclient.EnvironmentAndSystemPropertyClientProviderStrategy

验证标准 #

重新运行流水线后，查看容器启动日志的HostConfig.Binds字段，不会再出现/var/run/docker.sock相关的挂载项，Postgres容器可正常启动，集成测试步骤可正常执行。

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