如何在Docker容器内为Spring Boot应用运行Testcontainers测试

问题根源 #

构建时测试任务报错DockerClientProviderStrategy.java:256，本质是Testcontainers无法在容器内找到可用的Docker运行环境，常见原因包括：容器内缺少Docker CLI工具、挂载的Docker套接字权限不足、Testcontainers未正确配置指向宿主机Docker。

分步解决方法 #

1. 优化Dockerfile配置 #

使用多阶段构建，确保构建阶段具备完整的Docker依赖，并配置Testcontainers环境变量：

FROM openjdk:17-jdk-alpine AS build

# 安装Docker CLI工具（Testcontainers依赖）
RUN apk add --no-cache docker-cli curl

# 复制项目构建文件与源码
COPY gradle gradle
COPY gradle.properties build.gradle settings.gradle gradlew ./
COPY ./src ./src

# 赋予gradlew执行权限
RUN chmod +x ./gradlew

# 配置Testcontainers连接宿主机Docker
ENV TESTCONTAINERS_HOST_OVERRIDE=host.docker.internal
ENV DOCKER_HOST=unix:///var/run/docker.sock

# 执行构建与测试
RUN ./gradlew clean build --stacktrace

2. 正确执行构建命令 #

构建时需挂载宿主机的Docker套接字，同时处理权限问题：

docker build \
  --mount type=bind,source=/var/run/docker.sock,target=/var/run/docker.sock \
  -t spring-boot-build-image .

如果遇到套接字权限拒绝问题，可临时添加--privileged参数（仅用于调试，生产环境不推荐）：

docker build --privileged \
  --mount type=bind,source=/var/run/docker.sock,target=/var/run/docker.sock \
  -t spring-boot-build-image .

3. 处理用户权限（可选，更安全） #

为避免权限问题，可在Dockerfile中创建与宿主机同UID/GID的用户，并加入docker组：

FROM openjdk:17-jdk-alpine AS build

# 安装依赖
RUN apk add --no-cache docker-cli curl

# 创建匹配宿主机的用户与组
ARG UID=$(id -u)
ARG GID=$(id -g)
RUN addgroup -g $GID appgroup && adduser -u $UID -G appgroup -D appuser
# 将用户加入docker组（宿主机docker组GID通常为999）
RUN addgroup -g 999 docker && adduser appuser docker

# 复制项目文件
COPY gradle gradle
COPY gradle.properties build.gradle settings.gradle gradlew ./
COPY ./src ./src

RUN chmod +x ./gradlew

ENV TESTCONTAINERS_HOST_OVERRIDE=host.docker.internal
ENV DOCKER_HOST=unix:///var/run/docker.sock

# 切换到普通用户执行构建
USER appuser
RUN ./gradlew clean build --stacktrace

构建时传递UID/GID参数：

docker build \
  --build-arg UID=$(id -u) \
  --build-arg GID=$(id -g) \
  --mount type=bind,source=/var/run/docker.sock,target=/var/run/docker.sock \
  -t spring-boot-build-image .

4. 验证Testcontainers测试配置 #

确保Spring Boot测试类中PostgreSQL容器配置正确：

import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.DynamicPropertySource;
import org.springframework.test.context.DynamicPropertyRegistry;
import org.testcontainers.containers.PostgreSQLContainer;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;

@SpringBootTest
@Testcontainers
public class DatabaseTest {

    @Container
    private static final PostgreSQLContainer<?> postgresContainer = new PostgreSQLContainer<>("postgres:15-alpine")
            .withDatabaseName("testdb")
            .withUsername("testuser")
            .withPassword("testpass");

    @DynamicPropertySource
    static void configureProperties(DynamicPropertyRegistry registry) {
        registry.add("spring.datasource.url", postgresContainer::getJdbcUrl);
        registry.add("spring.datasource.username", postgresContainer::getUsername);
        registry.add("spring.datasource.password", postgresContainer::getPassword);
    }

    // 测试方法...
}

常见问题排查 #

• 确认宿主机Docker daemon处于运行状态：执行docker ps验证
• 检查宿主机Docker套接字权限：ls -l /var/run/docker.sock，确保当前用户属于docker组
• 如果使用Docker Desktop，需在设置中启用"Allow the default Docker socket to be used"选项

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