Windows 11 + WSL2环境下docker-java交互式PTY流启动后立即终止（IOException: Connection aborted / Pipe has been terminated）

我之前也踩过一模一样的坑！在Windows 11 Home 24H2搭配WSL2后端的Docker Desktop（用的Ubuntu 2发行版）、JDK 17.0.11环境下，不管是用docker-java 3.3.6、3.4.0还是3.5.0版本，只要依赖docker-java-transport-httpclient5作为传输层，通过execStartCmd创建的交互式PTY流总会刚启动就直接终止，还会抛出IOException: Connection aborted或者Pipe has been terminated的错误。折腾了好一阵，总结了几个有效的解决思路：

一、调整PTY会话的核心配置 #

WSL2的管道转发对PTY参数比较敏感，默认配置下很容易触发连接提前关闭，你可以试试在创建ExecStartCmd时加上这些关键配置：

// 假设你已经通过execCreateCmd创建好交互式命令的execId
String execId = "你的execId";

ExecStartCmd execStartCmd = dockerClient.execStartCmd(execId)
    .withTty(true)
    .withDetach(false)
    .withInputStream(System.in)
    .withOutputStream(System.out)
    .withErrorStream(System.err);

// 关键1：禁用读取超时，防止httpclient5的默认超时逻辑切断连接
execStartCmd.getDockerCmd().withReadTimeout(0);
// 关键2：明确指定PTY窗口尺寸，WSL2下部分场景需要这个参数才能维持会话
execStartCmd.withTtySize(80, 24);

// 执行命令并等待会话完成
execStartCmd.exec(new ExecStartResultCallback() {
    @Override
    public void onComplete() {
        super.onComplete();
        // 会话结束后的自定义清理逻辑
    }
}).awaitCompletion();

二、切换docker-java的传输层实现 #

docker-java-transport-httpclient5在WSL2的管道场景下可能存在连接管理的兼容性问题，换成netty传输层大概率能解决问题：

1. 把依赖从docker-java-transport-httpclient5替换成同版本的docker-java-transport-netty
2. 核心业务代码不需要修改，直接重新构建DockerClient即可——netty传输层对WSL2的socket转发支持要稳定得多

三、直接指定WSL2的Docker Socket路径 #

Windows下docker-java默认用npipe:////./pipe/docker_engine访问Docker Desktop，但WSL2的实际socket路径是/var/run/docker.sock，Docker Desktop的自动映射偶尔会出问题。你可以直接指定WSL2的共享socket路径绕开映射层：

DockerClientConfig config = DefaultDockerClientConfig.createDefaultConfigBuilder()
    // 指向WSL2共享给Windows的Docker Socket路径
    .withDockerHost("unix:///mnt/wsl/docker-desktop/shared-sockets/run/docker.sock")
    .build();
DockerClient dockerClient = DockerClientBuilder.getInstance(config).build();

四、确保IO流不会被提前关闭 #

有时候PTY会话终止是因为Java的输入输出流被提前关闭了，你可以用单独的线程维持输入流的活跃状态：

// 启动PTY会话前，开一个线程维持系统输入流的传输
new Thread(() -> {
    try {
        // 把系统输入流转发给PTY的输入流
        System.in.transferTo(execStartCmd.getInputStream());
    } catch (IOException e) {
        // 仅做日志记录，不要直接终止程序
        System.err.println("输入流转发异常：" + e.getMessage());
    }
}).start();

// 执行PTY命令
execStartCmd.exec(new ExecStartResultCallback()).awaitCompletion();

额外排查点 #

如果上面的方法都不管用，先确认基础环境是否正常：

• 打开WSL2的Ubuntu终端，直接执行docker exec -it 容器ID/名称 你的命令，看交互式会话是否能正常运行。如果这里也有问题，那就是Docker Desktop和WSL2的集成问题，试试重启Docker Desktop或者更新到最新版本。
• 检查Docker Desktop的WSL2集成状态：打开Docker Desktop设置 -> Resources -> WSL Integration，确保你的Ubuntu发行版处于开启状态。

备注：内容来源于stack exchange，提问作者ha33an