Testcontainers：把数据库与消息队列变成可验证的测试对象

Testcontainers 临时测试基础设施生命周期高清原图

一组订单集成测试在开发机上连续通过，进入 CI 后却出现三种互相矛盾的结果：有时连接 localhost:5432 被拒绝，有时 PostgreSQL 已经监听端口但初始化表尚未完成，有时作业失败后留下几十个容器，下一轮又因为磁盘耗尽而失败。团队把超时从 30 秒改到 5 分钟，偶发失败少了一点，流水线却更慢，也没有人能回答失败发生在镜像拉取、Docker API、容器启动、服务就绪还是应用断言阶段。

Testcontainers 的价值不是把 docker run 换成测试代码，而是把外部依赖建模为测试生命周期内的对象：测试进程声明镜像、环境变量、网络、端口和就绪条件；客户端通过 Docker API 创建资源；运行时返回实际主机和随机端口；测试只在业务能力可用后取得连接参数；结束时再按所有权清理资源。只要其中一个边界仍写死在开发机假设里，容器化也不会让测试稳定。

先证明测试进程真的能控制容器运行时

Testcontainers for Java 2.x 需要 Java 17 或更高版本，并把各模块的制品名统一为 testcontainers-*，容器类也迁到了 org.testcontainers.<module> 包。Node.js 是独立实现，入口由 testcontainers 核心包和数据库、消息队列等 @testcontainers/* 模块包组成；Java 的 Maven 坐标、包名和 JUnit 扩展不能套用到 Node。Java 与 Node.js 开源库采用 MIT License；Testcontainers Desktop 是闭源可选应用并提供个人免费计划，Testcontainers Cloud 的配额、计费和企业能力则按账号方案治理，不能从客户端库许可证推导这些产品的使用权。两种实现都需要兼容 Docker API 的运行时；Docker Desktop、Linux Docker Engine 是常见基线，替代运行时是否支持 Ryuk、网络、文件挂载和特权容器要逐项验证，不能只以 docker ps 成功作为兼容证明。

先在将要运行测试的同一个 shell 或 CI step 中执行：

docker version
docker info
docker run --rm alpine:3.22 echo RUNTIME_OK

三条命令分别证明客户端能连接 API、daemon 能返回能力信息、daemon 能拉取并启动一个容器。预期最后输出 RUNTIME_OK。若 docker version 只有 Client 段，先修复 daemon 连接；若 docker info 成功而拉取失败，排查 registry、代理、CA、认证和平台架构；若命令行成功而测试仍报 Could not find a valid Docker environment，比较测试进程实际继承的 DOCKER_HOST、DOCKER_TLS_VERIFY、DOCKER_CERT_PATH 和用户权限。

Java 运行时发现规则会按自己的 client provider strategy 读取 Docker 连接环境变量并尝试受支持的本机入口；Java 还可以从用户目录和 classpath 的 testcontainers.properties 读取配置。Node 运行时与配置说明则列出 Docker、Podman、Colima、Rancher Desktop 等入口，并以环境变量作为公开配置面，不读取 Java 的 ~/.testcontainers.properties。诊断时必须使用当前语言实现的日志和配置规则，不能因为 Java 在同一台机器上发现成功，就推断 Node 也会选择同一个 endpoint。

无论哪种实现，都要分清三个地址：

DOCKER_HOST 告诉客户端去哪里调用 Docker API。TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE 告诉 Ryuk 等辅助容器从容器内部挂载哪个 daemon socket。TESTCONTAINERS_HOST_OVERRIDE 告诉测试进程应通过哪个主机地址访问映射端口。

它们偶尔指向同一台机器，却不是同一个语义。把远程 daemon 的 tcp://builder:2376 原样当成 PostgreSQL 主机，或仅凭 DOCKER_HOST 猜测 Ryuk 应挂载的 socket，都会产生“业务容器能创建、辅助容器或映射端口却不可用”的分裂状态。

用 Maven 建立一条可重复的 Java 基线

建立只含测试代码的实验目录：

testcontainers-java-lab/
├─ pom.xml
└─ src/test/java/lab/
   ├─ PostgresLifecycleTest.java
   └─ BrokenReadinessTest.java

pom.xml 用 BOM 对齐 Testcontainers 核心、JUnit 扩展和 PostgreSQL 模块，驱动仍由项目显式管理。下面是一条可复制的版本基线；只有在目标机器得到 Maven、容器和清理输出后，才能记为该环境已验证。升级时先在隔离分支重跑正反实验，再更新依赖锁定和 CI 镜像。

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>example</groupId>
  <artifactId>testcontainers-java-lab</artifactId>
  <version>1.0-SNAPSHOT</version>

  <properties>
    <maven.compiler.release>17</maven.compiler.release>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <testcontainers.version>2.0.5</testcontainers.version>
    <junit.version>5.13.4</junit.version>
  </properties>

  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>org.testcontainers</groupId>
        <artifactId>testcontainers-bom</artifactId>
        <version>${testcontainers.version}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>

  <dependencies>
    <dependency>
      <groupId>org.junit.jupiter</groupId>
      <artifactId>junit-jupiter</artifactId>
      <version>${junit.version}</version>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>org.testcontainers</groupId>
      <artifactId>testcontainers-junit-jupiter</artifactId>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>org.testcontainers</groupId>
      <artifactId>testcontainers-postgresql</artifactId>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>org.postgresql</groupId>
      <artifactId>postgresql</artifactId>
      <version>42.7.8</version>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>org.slf4j</groupId>
      <artifactId>slf4j-simple</artifactId>
      <version>2.0.17</version>
      <scope>test</scope>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.14.1</version>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>3.5.5</version>
        <configuration>
          <useModulePath>false</useModulePath>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

安装入口就是 Maven 的测试依赖解析，不需要全局安装 Testcontainers CLI：

mvn -q -DskipTests dependency:go-offline
mvn -q test

第一条命令应下载依赖而不启动容器，第二条才会调用 Docker。若依赖解析阶段失败，问题属于 Maven 仓库、代理或企业 CA；若测试编译通过后才找不到 Docker，问题属于运行时发现。把两个阶段分开，能避免用 Docker 排障手段处理 Maven 证书错误。

正向实验让数据库状态与测试生命周期绑定

PostgresLifecycleTest.java 使用静态 @Container，因此同一测试类中的方法共享一个 PostgreSQL 进程；每个测试方法仍在自己的事务和数据清理规则下运行。若去掉 static，JUnit 扩展会按测试方法重建容器，隔离更强但启动成本更高。JUnit 5 集成说明还明确指出该扩展的并行执行没有得到支持，不能在未验证时把同一容器字段交给并发方法竞争。

package lab;

import static org.junit.jupiter.api.Assertions.assertEquals;

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.Statement;
import org.junit.jupiter.api.Test;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;
import org.testcontainers.postgresql.PostgreSQLContainer;
import org.testcontainers.utility.DockerImageName;

@Testcontainers
class PostgresLifecycleTest {
  private static final DockerImageName POSTGRES =
      DockerImageName.parse("postgres:16.9-alpine3.22");

  @Container
  static final PostgreSQLContainer POSTGRESQL =
      new PostgreSQLContainer(POSTGRES)
          .withDatabaseName("orders_test")
          .withUsername("test_user")
          .withPassword("synthetic-test-only");

  @Test
  void writesAndReadsInsideAnOwnedDatabase() throws Exception {
    try (Connection connection = DriverManager.getConnection(
            POSTGRESQL.getJdbcUrl(), POSTGRESQL.getUsername(), POSTGRESQL.getPassword());
        Statement statement = connection.createStatement()) {
      statement.execute("CREATE TABLE orders(id bigint primary key, status text not null)");
      statement.execute("INSERT INTO orders(id, status) VALUES (101, 'CREATED')");

      try (ResultSet result = statement.executeQuery(
          "SELECT status FROM orders WHERE id = 101")) {
        result.next();
        assertEquals("CREATED", result.getString(1));
      }
    }
  }
}

运行单篇实验前先约定判定标准：只有实际保存命令退出码、测试输出和容器清理证据，才能把结果记录为通过。执行后应观察到下面的结果：

mvn -q -Dtest=PostgresLifecycleTest test
docker ps --filter "label=org.testcontainers=true"

预期 Maven 返回成功，测试期间日志能看到镜像、容器 ID 与 JDBC 连接，测试结束后第二条命令不应列出业务容器。测试凭据只在一次性数据库内使用，不得替换成共享环境账号。若表已存在，说明测试数据或容器生命周期被意外共享；若连接仍指向 localhost:5432，说明应用没有使用 getJdbcUrl() 返回的动态连接串。

专用模块不只是语法糖。PostgreSQLContainer 知道默认端口、数据库名、用户名、密码和 JDBC URL，并继承通用容器的创建、等待、日志与清理能力。它仍然运行真实 PostgreSQL，而不是以内存实现近似数据库语义；代价是镜像拉取、进程启动和存储占用都进入测试预算。

反向实验用错误等待条件暴露“进程运行”和“服务可用”的差异

容器进入 running 只证明主进程没有退出，端口监听只证明 TCP 可以建立连接。数据库恢复、迁移、权限初始化或集群选主仍可能没有完成。Java 等待策略把 startup check 与 wait strategy 分开：前者判断容器是否达到预期进程状态，后者判断测试需要的能力是否已经可用。

BrokenReadinessTest.java 故意等待一个永远不会出现的日志：

package lab;

import static org.junit.jupiter.api.Assertions.assertThrows;

import java.time.Duration;
import org.junit.jupiter.api.Test;
import org.testcontainers.containers.ContainerLaunchException;
import org.testcontainers.containers.GenericContainer;
import org.testcontainers.containers.wait.strategy.Wait;
import org.testcontainers.utility.DockerImageName;

class BrokenReadinessTest {
  @Test
  void failsWhenDeclaredCapabilityNeverBecomesReady() {
    ContainerLaunchException error = assertThrows(ContainerLaunchException.class, () -> {
      try (GenericContainer<?> container = new GenericContainer<>(
          DockerImageName.parse("alpine:3.22"))
          .withCommand("sh", "-c", "echo BOOTED; sleep 30")
          .withStartupAttempts(1)
          .waitingFor(Wait.forLogMessage(".*APPLICATION_READY.*\\n", 1)
              .withStartupTimeout(Duration.ofSeconds(3)))) {
        container.start();
      }
    });

    System.out.println("EXPECTED_READINESS_FAILURE type="
        + error.getClass().getSimpleName());
  }
}

mvn -q -Dtest=BrokenReadinessTest test

测试本身应通过，并输出 EXPECTED_READINESS_FAILURE type=ContainerLaunchException，因为它断言启动必须失败。withStartupAttempts(1) 让反例只执行一次启动尝试；若删除它，通用容器的重试会重复创建和等待，整体耗时可能远高于单次 wait strategy 的 3 秒。若一次尝试仍等待 30 秒后才结束，检查超时是否绑定在实际 wait strategy 上；若容器被当成成功，说明自定义等待没有真正附着到容器。

生产代码的等待条件应尽量验证业务能力：数据库执行 SELECT 1 并确认目标 schema 已迁移，HTTP 服务访问无需真实凭据的 readiness 端点，消息队列确认管理 API 或协议握手可用。日志等待适合输出稳定且由镜像契约保证的信号；只匹配 Started、Listening 之类宽泛文本容易被重启日志或旁路进程误命中。延长超时只能覆盖可解释的冷启动预算，不能修复错误条件。

随机端口与专用网络解决的是两条不同链路

Testcontainers 默认把容器端口映射到宿主机随机空闲端口，这是并行测试避免 5432 already in use 的基础。网络说明要求容器启动后再读取 getHost() 和 getMappedPort()；远程 daemon、Docker Desktop 与本地 Linux 的 host 可能不同，不能写死 localhost。

测试进程访问数据库时走宿主机映射：

String host = container.getHost();
int port = container.getMappedPort(5432);

两个容器互相访问时，应加入同一个临时网络并使用网络别名和容器端口，不经过宿主机随机端口：

try (var network = org.testcontainers.containers.Network.newNetwork();
     var postgres = new PostgreSQLContainer(
         DockerImageName.parse("postgres:16.9-alpine3.22"))
         .withNetwork(network)
         .withNetworkAliases("orders-db");
     var worker = new GenericContainer<>(DockerImageName.parse("alpine:3.22"))
         .withNetwork(network)
         .withCommand("sh", "-c", "sleep 60")) {
  postgres.start();
  worker.start();
  var result = worker.execInContainer(
      "sh", "-c", "nc -z orders-db 5432 && echo NETWORK_OK");
  if (result.getExitCode() != 0) throw new IllegalStateException(result.getStderr());
}

预期容器内输出 NETWORK_OK。这里的 orders-db:5432 仅在临时网络内有效，测试进程不能拿它构造 JDBC URL。反过来，把 getMappedPort(5432) 交给另一个容器，也会把内部调用绕到宿主机，增加 NAT、host 发现和防火墙变量。

固定宿主机端口只适合必须与外部人工工具协作的受控诊断，不应成为测试默认值。并行 runner 上固定端口既会冲突，也会诱导应用继续依赖开发机常驻服务。若容器需要回连测试进程中的本地 HTTP server，应先启动 server，再按 Testcontainers 的 host access 机制暴露端口，并让容器访问 host.testcontainers.internal；这与 localhost 指向容器自身的语义不能混用。

数据库和消息队列要验证对象语义，而不是只验证端口

数据库测试至少要证明目标方言、迁移和事务边界。真实 PostgreSQL 能暴露 H2 等近似实现无法复现的索引、锁、JSON、大小写和 DDL 行为，但每个测试都重建完整数据库会提高耗时。常见分层是：纯逻辑单测不用容器；仓储与迁移测试使用真实数据库容器；少量系统测试再组合数据库、MQ 与应用容器。不要把所有测试都升级成容器测试，也不要因容器较慢退回共享测试库。

消息队列的最小证据应是“发布后由独立消费者收到同一条消息”，而不是管理端口可连接。Java 项目可增加 testcontainers-rabbitmq 模块并使用 org.testcontainers.rabbitmq.RabbitMQContainer；连接参数来自 getAmqpUrl()，测试结束前关闭 channel 和 connection，再让容器生命周期结束。需要验证死信、确认、重投或顺序时，应把交换机、队列、routing key 和消费确认模式显式写入测试，不要依赖镜像中的默认对象。

@Container
static final org.testcontainers.rabbitmq.RabbitMQContainer RABBIT =
    new org.testcontainers.rabbitmq.RabbitMQContainer(
        DockerImageName.parse("rabbitmq:4.1-alpine"));

数据库与 MQ 放在同一测试类时，可以并行启动相互独立的容器以降低冷启动时间；存在启动依赖时则先启动底座，再启动依赖其网络别名的应用。并行启动不是无限制提速：runner 的 CPU、内存、磁盘吞吐和 registry 并发都有限，镜像解压同时争抢磁盘时，更多容器反而会让 P95 启动时间恶化。

Node.js 使用同一对象模型，不复制 Java 的生命周期习惯

Node.js 项目安装核心能力、PostgreSQL 模块、驱动和测试运行器，并提交 lockfile：

npm install --save-dev testcontainers @testcontainers/postgresql pg vitest
npm test

依赖版本最终由 package-lock.json 固定；CI 使用 npm ci，不要每轮重新解析浮动范围。下面的 Vitest 用例把容器句柄保存在 suite 作用域，beforeAll 启动，afterAll 先关闭数据库客户端再停止容器：

import { afterAll, beforeAll, expect, test } from "vitest";
import { PostgreSqlContainer } from "@testcontainers/postgresql";
import pg from "pg";

let postgres;
let client;

beforeAll(async () => {
  postgres = await new PostgreSqlContainer("postgres:16.9-alpine3.22")
    .withDatabase("orders_test")
    .withUsername("test_user")
    .withPassword("synthetic-test-only")
    .start();

  client = new pg.Client({ connectionString: postgres.getConnectionUri() });
  await client.connect();
  await client.query(
    "CREATE TABLE orders(id bigint primary key, status text not null)"
  );
}, 120_000);

afterAll(async () => {
  await client?.end();
  await postgres?.stop();
});

test("persists an order in a disposable PostgreSQL", async () => {
  await client.query(
    "INSERT INTO orders(id, status) VALUES ($1, $2)",
    [101, "CREATED"]
  );
  const result = await client.query(
    "SELECT status FROM orders WHERE id = $1",
    [101]
  );
  expect(result.rows).toEqual([{ status: "CREATED" }]);
});

Node 还支持 await using 形式的异步资源释放，但项目的 Node、TypeScript 编译目标和测试运行器必须真的支持显式资源管理后再采用。无论使用哪种语法，正确顺序都是先关闭业务客户端、停止后台消费者和连接池，再停止容器；反过来会制造与业务断言无关的连接重置日志。

Node 等待策略默认优先使用镜像 healthcheck，否则等待映射端口；可以显式改为日志、HTTP、命令或组合条件。Java 与 Node 的类名和默认策略并不完全一致，团队应共享“服务何时可用”的测试契约，而不是跨语言复制 API 调用。

Ryuk 是兜底回收器，不是可以随手关闭的噪声容器

正常路径由 JUnit 扩展、try-with-resources、Node stop() 等生命周期代码停止容器。测试进程崩溃、被强杀或漏掉释放时，Ryuk 会按会话登记和标签回收容器、网络等资源。它需要访问与客户端相同的 Docker daemon；因此 socket 挂载错误时，业务容器可能创建成功，Ryuk 却无法登记或删除资源。

Java 自定义配置与 Node 配置都提供 Ryuk image、socket、privileged、disable 等入口。TESTCONTAINERS_RYUK_DISABLED=true 只能用于平台已经提供等价强制清理且安全策略确实不允许 Ryuk 的环境。关闭后必须同时具备：

每个 job 使用独立 runner、独立 daemon 或独立命名空间，并在 job 结束时销毁。正常与取消路径都执行带标签过滤的清理，不使用无边界的 docker system prune。守护任务能按 owner、job ID 和最大存活时间回收孤儿资源。

连续多轮测试后，存活容器、网络、volume 和磁盘占用回到稳定基线。

观察残留时先看标签和所有者：

docker ps -a --filter "label=org.testcontainers=true"
docker network ls --filter "label=org.testcontainers=true"
docker system df

清理命令必须限定到已确认的测试资源。共享 daemon 上直接 docker system prune -af --volumes 可能删除其他构建缓存、停止容器和 volume，不属于可接受的测试收尾。

复用只能优化本机反馈，不能改变隔离契约

Java reusable containers仍标为实验能力，要求用户在自己的环境显式 opt-in，而且不适合 CI；资源清理和网络等能力也不保证全部按普通生命周期工作。Java 复用容器必须由代码手工 start()，不能交给 JUnit 集成或 try-with-resources，也不能在本轮结束时直接或间接调用 stop()，否则容器已经被销毁，下一轮无从复用。Node 的边界不同：容器代码必须调用 .withReuse()，但当前实现未设置 TESTCONTAINERS_REUSE_ENABLE 时全局能力默认开启；可以显式设为 false 禁止复用。复用的收益是本机多轮测试避免重复拉起重量级依赖，代价是状态、schema、队列、时钟和缓存可能跨轮次存活。

团队启用本机复用前，先证明以下不变量：每轮测试使用唯一数据库/schema/tenant 或在开始时做幂等重置；失败中断后下一轮仍能恢复已知状态；镜像或配置变化会生成新的容器身份；开发者能找到并主动删除复用资源。CI 保持复用关闭，让每个 job 从已知镜像和空状态开始。

Java 入口需要用户级配置，而不是把开关强制写进 classpath：

# ~/.testcontainers.properties
testcontainers.reuse.enable=true

测试代码再显式 .withReuse(true) 并手工调用 start()；这条路径应与前文由 @Container、try-with-resources 管理的确定性清理基线分开。Java 中如果团队只打开全局开关却没有逐容器 opt-in，或代码 opt-in 而用户没有打开能力，都不应假定发生复用；Node 则用 .withReuse() 标记容器，并建议 CI 显式设置 TESTCONTAINERS_REUSE_ENABLE=false，避免默认值随实现升级改变流水线隔离。性能判定看多轮趋势：第二轮启动耗时应下降，测试结果和结束后的业务对象数必须保持一致；复用容器不会随测试结束自动停止，开发者还必须有按标签识别、手工停止并删除它的收尾入口，不能只截取一次“很快”的日志。

镜像标签解决可读性，digest 才冻结实际字节

postgres:16-alpine 会随上游重建而移动，开发机缓存与 CI 新拉取可能运行不同字节。发布级测试应在镜像准入流程中解析并批准 digest，再把不可变引用交给 Testcontainers：

docker pull postgres:16.9-alpine3.22
docker image inspect postgres:16.9-alpine3.22 `
  --format '{{index .RepoDigests 0}}'

得到的 postgres@sha256:... 经过漏洞、许可证和平台架构审查后，进入依赖清单或集中测试基础设施库。代码可保留可读常量名，但运行引用使用批准 digest：

DockerImageName approvedPostgres = DockerImageName.parse(
    "registry.example.invalid/mirror/postgres@sha256:REPLACE_WITH_APPROVED_DIGEST")
    .asCompatibleSubstituteFor("postgres");

占位 digest 不能直接执行；仓库门禁应拒绝 REPLACE_WITH_APPROVED_DIGEST。asCompatibleSubstituteFor 只告诉专用模块该私有镜像与官方镜像的接口兼容，不会验证镜像内容、扩展、初始化脚本或安全性。

企业网络可用 TESTCONTAINERS_HUB_IMAGE_NAME_PREFIX 或 Java 的 Image Name Substitutor 把 Docker Hub 引用映射到镜像代理。镜像替换规则不会处理所有显式 registry 名称，Ryuk、tiny image、sshd 等辅助镜像也必须提前同步。最稳妥的预热清单来自一次完整测试的实际拉取日志，而不是只同步业务数据库镜像。

registry 凭据由 Docker credential helper、短期 CI secret 或工作负载身份提供，不进入测试代码、镜像名、构建日志和归档报告。代理需要分别配置 daemon 拉镜像链路与 Maven/npm 下载链路；只设置测试进程的 HTTPS_PROXY 不一定会传给 Docker daemon。企业 CA 也可能需要分别进入主机、daemon、JVM truststore 和 Node 信任链，排障时按失败请求的发起者定位。

CI 先选择运行时所有权，再谈 YAML 写法

CI 中常见四种形态：

形态	优点	关键代价与判断
宿主机 runner 直连本机 Docker	路径短、映射端口自然	runner 获得 daemon 控制权，必须隔离租户并清理残留
测试 job 容器挂载宿主 socket	启动快、复用宿主缓存	socket 近似宿主机高权限控制面，不能交给不可信 PR 代码
Docker-in-Docker service	daemon 与宿主资源边界较清楚	常需特权、缓存和网络更复杂，host override 必须验证
远程专用 daemon 或托管运行时	可集中容量、镜像和审计	网络时延、租户隔离、TLS/SSH、资源配额与映射端口路由进入架构

挂载 /var/run/docker.sock 并不等于“只允许启动测试容器”。Docker API 可以挂载宿主路径、创建特权容器和控制其他资源，Docker Engine 安全说明要求只让可信主体控制 daemon。来自 fork 或外部贡献者的未审代码不应在拥有 socket 与 registry 凭据的 runner 上执行。

rootless Docker 把 daemon 和容器放入用户命名空间，降低 rootful daemon 的一部分宿主风险，但不是 Testcontainers 的透明开关。Docker rootless 模式的 socket 常位于 unix:///run/user/<uid>/docker.sock；测试进程、Ryuk 挂载、UID 映射、特权要求和网络能力都要验证。先只确认客户端 endpoint，不要从固定 UID 推导配置：

export DOCKER_HOST="unix:///run/user/$(id -u)/docker.sock"
docker info

TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE 是提供给 Ryuk 等辅助容器的 socket 路径，不是 DOCKER_HOST 的机械副本。只有在确认该实现会把 daemon 主机上的实际 socket 挂入辅助容器、且容器内能访问同一 daemon 后才设置它。官方对 rootless Podman 的 Java 与 Node 配置都要求禁用 Ryuk；这意味着 rootless/替代运行时必须逐实现验证，不能把 Docker rootless、Podman rootless 和远程 daemon 当成一种拓扑。Ryuk 无法工作时，优先使用一次性 runner 和平台级回收；不要为了让测试通过而给整个 job 无边界特权。

远程 daemon 只使用 SSH 或双向 TLS。Docker socket 保护指南支持 DOCKER_HOST=ssh://user@host 和 TLS 证书。无认证 tcp://host:2375 等价于把高权限控制面暴露给网络，不能作为“内网临时方案”。远程模式还要验证：测试进程能访问 daemon 所在主机发布的随机端口；上传 bind mount 路径按 daemon 主机解释；本机文件不能凭空出现在远端；每个 job 的资源标签、配额和超时清理可审计。

CI 应把运行时探针放在测试之前，并在失败时保存有限证据：Docker client/server 版本、运行时名称、镜像 digest、容器 inspect、等待失败前后的健康状态和经过脱敏的日志。不要归档 docker inspect 的完整环境数组，也不要打开会打印 registry token、数据库密码或云凭据的调试级日志。

常见失败要沿对象链定位第一条证据

找不到 Docker 环境

先在同一进程身份下运行 docker version，再打印变量是否存在而不是打印证书内容。IDE、Maven daemon、Gradle daemon、Node worker 与交互 shell 可能继承不同环境；重启测试进程比反复修改全局配置更重要。Windows 与 Docker Desktop 场景还要确认使用的是 Linux containers 模式以及当前用户可访问 Desktop 暴露的 API。

Ryuk 无法连接或一直等待确认

业务容器能创建而 Ryuk 失败，通常指向 socket override、特权策略、辅助镜像拉取或防火墙。比较 Ryuk 容器内看到的 socket 与客户端连接的 daemon 是否相同；检查 Ryuk 镜像是否被镜像代理同步；确认平台是否阻断必要能力。不能以永久关闭 Ryuk作为第一修复动作。

容器已运行但测试连接被拒绝

依次读取 container.getHost()、映射端口、容器 inspect 的 port bindings 和测试进程实际连接串。若测试本身也在容器里，localhost 指向测试容器，不是 sibling 容器或 daemon 主机。若服务端口已监听但协议握手失败，再查 wait strategy 是否过早、数据库是否正在恢复、TLS/认证配置是否匹配。

镜像拉取超时或 429

先用 daemon 身份执行 docker pull，区分 DNS、代理、CA、认证、rate limit 和不存在的 tag。记录停在 manifest、layer download 还是 extract；下载停滞与磁盘解压缓慢的处理不同。CI 使用镜像代理、预热和 digest 后仍要保留上游更新流程，不能让缓存变成永不升级的未知副本。

测试结束仍有容器、网络或 volume

检查是否绕过扩展手工 start() 却没有 stop()，是否进程被强杀，Ryuk 是否禁用，以及资源是否真的带本轮 Testcontainers 标签。连续运行多轮并观察存活数量与 docker system df 趋势；只清理一次现场不能证明生命周期已经修复。

并行测试互相污染

查固定端口、固定数据库名、共享 queue/topic、静态单例、reuse、宿主目录 bind mount 和全局时钟。容器独立即不等于数据独立：多个测试方法共享静态 PostgreSQL 时仍会看到同一 schema。使用每测试事务回滚、唯一 schema/tenant、随机队列名或每类独立容器，并给清理失败设置硬断言。

测试数据、凭据和日志也有安全边界

一次性容器不允许复制生产数据。测试数据由工厂或合成器生成，保留业务约束但不保留真实姓名、手机号、订单、token 和密钥；需要统计分布时使用经过批准的去标识化数据集，并记录来源、版本、保留期和 owner。数据库 dump 即使最终进入临时 volume，也可能先经过工作区、对象存储、CI cache 和日志上传，这些副本不会随容器停止而消失。

容器内的 synthetic-test-only 凭据只适用于隔离实验。registry、远程 daemon、Testcontainers Cloud 或企业代理凭据来自受保护 secret，按 job 最小授权并在结束后撤销。不要把密码放进镜像引用、命令行 URL 或异常消息；失败日志只保留字段名、目标环境标识和错误类别。

测试日志也可能包含 SQL 参数、消息 payload、HTTP header 和容器环境。默认只在失败时采集相关容器的末尾日志，并经过字段级脱敏；完整日志使用受限制品存储和短保留期。开发者为了排障复制日志到 issue、聊天工具或 AI 上下文前，仍要做敏感扫描。

容量与成本用队列、镜像和生命周期一起预算

Testcontainers 把共享环境的排队风险换成 runner 本地的资源消耗。容量模型至少包含并行测试进程数、每进程容器数、镜像解压峰值、数据库内存、临时 volume、网络连接和最长生命周期。一个 8 核 runner 同时启动几十个 PostgreSQL 与 RabbitMQ，常见结果不是线性提速，而是磁盘、page cache 和 CPU 争抢导致所有 wait strategy 接近超时。

团队应记录这些趋势：

镜像命中与拉取耗时，区分下载和解压。容器从 create、start 到 ready 的分位耗时。每个 suite 的容器峰值、CPU、内存和磁盘增量。

测试结束后残留资源数与磁盘回归基线所需时间。因 Docker 不可用、拉取失败、等待超时和业务断言导致的失败占比。

阈值来自 runner 容量、历史基线和流水线 SLO，不使用脱离负载的万能秒数。优化顺序通常是减少不必要的容器测试、按 suite 安全共享、并行启动独立依赖、预热批准镜像、扩大 runner，再考虑本机复用。用无限超时或关闭清理换取“稳定”只会把成本推迟到下一轮。

团队把容器测试当成受治理的临时基础设施

成熟的落地方式是维护一层很薄的测试基础设施库：集中批准 Testcontainers 版本、镜像 digest、模块工厂、等待策略、标签、日志脱敏和运行时诊断；业务项目仍声明自己的 schema、queue、fixture 和断言。基础库不能隐藏动态连接参数，也不能把所有服务塞进一个常驻“大集成环境”。

升级时同时验证客户端库、Docker Engine/Desktop、辅助镜像、业务镜像和 CI runner。先在一组代表性项目中跑正向数据库/MQ用例、错误等待反例、进程强杀后的回收、并行隔离和镜像代理冷缓存，再逐步推广。回退不仅是降级 Maven/npm 版本，还要保留上一组镜像 digest、配置和 runner 基线；新版本创建的残留资源要在回退前清理。

职责也要可追踪：业务团队拥有测试语义和数据工厂，平台团队拥有 runner、daemon、镜像代理和配额，安全团队定义 socket、凭据和外部 PR 边界，测试基础设施 owner 维护公共工厂、升级与残留治理。没人拥有的共享 daemon 最终一定会变成不可解释的状态仓库。

一次变更进入主干前，证据应串成同一条链：运行时探针能创建并删除容器；镜像引用可追溯到批准 digest；等待策略证明业务能力而非只看端口；应用使用动态 host 与端口；测试数据与凭据都是隔离合成值；正常、失败和取消路径都能回收；CI 不向不可信代码开放 Docker 控制面；连续多轮后资源和耗时回到稳定基线。做到这些，Testcontainers 才不只是“在测试里启动 Docker”，而是团队可重复、可诊断、可治理的测试支撑能力。