IntelliJ IDEA 连接远程 Docker 报错：client version 1.24 is too old

前言

最近需要实现这样一个开发流程：

在本地 IntelliJ IDEA 中开发 Java 项目；
使用 Maven 在本地打包；
通过 SSH 连接远端 Linux 服务器；
在远端 Docker 中构建镜像并运行容器；
最终实现 IDEA 一键打包和部署。

我的本地环境最开始使用的是：

IntelliJ IDEA 2025.1.1.1 Ultimate Edition

远端 Docker 通过 SSH 配置成功后，IDEA 设置页面也显示：

Connection successful

但在 Services 窗口双击远程 Docker 时，却出现了 Docker API 版本不兼容的错误。

本文记录完整排查和解决过程。

一、环境信息

本地开发环境

操作系统：Windows 64 位
IDE：IntelliJ IDEA 2025.1.x Ultimate Edition
项目类型：Java Maven 多模块项目
Docker 插件：IDEA Bundled Docker Plugin

远端服务器

操作系统：Linux
连接方式：SSH
Docker：较新版本的 Docker Engine
Docker Compose：Docker Compose V2

项目结构类似：

project-root
├── project-admin
│   ├── src
│   ├── target
│   ├── Dockerfile
│   └── pom.xml
├── project-common
├── project-modules
└── pom.xml

其中 project-admin 是 Spring Boot 启动模块。

二、在 IDEA 中配置远程 Docker

首先确认使用的是 IntelliJ IDEA Ultimate Edition：

Help → About

然后检查 Docker 插件：

File
→ Settings
→ Plugins
→ Installed
→ Docker

如果右侧显示的是：

Disable

说明 Docker 插件当前已经启用。

接着进入：

File
→ Settings
→ Build, Execution, Deployment
→ Docker

点击左上角的 +，选择：

SSH

然后配置服务器信息：

Host：远端服务器地址
Port：22
Username：部署用户
Authentication：密码或者 SSH 私钥

配置完成后，IDEA 显示：

Connection successful

此时看起来 SSH 和 Docker 都已经连接成功。

三、实际出现的问题

打开 IDEA 的 Services 窗口：

View → Tool Windows → Services

也可以使用快捷键：

Alt + 8

找到刚刚配置的远程 Docker：

Remote-Docker

双击后，Docker 服务没有正常展开，而是显示以下错误：

Status 400:
client version 1.24 is too old.
Minimum supported API version is 1.40,
please upgrade your client to a newer version

完整含义是：

当前 Docker 客户端使用的是 API 1.24
远端 Docker Engine 最低只支持 API 1.40

因此，远端 Docker 拒绝了 IDEA Docker 插件发送的请求。

四、为什么设置页面显示连接成功

这里比较容易让人误判。

IDEA Docker 设置页面显示：

Connection successful

至少说明以下链路基本正常：

服务器 IP 和 SSH 端口正确；
SSH 用户名和认证信息正确；
IDEA 能够访问远端服务器；
当前用户能够连接远端 Docker daemon。

但连接成功不代表后续所有 Docker API 请求都兼容。

当 IDEA 在 Services 窗口中进一步获取以下资源时：

Containers
Images
Networks
Volumes

旧版 Docker 插件发送了较老的 API 请求，而远端 Docker Engine 已经不再接受该版本，于是返回 HTTP 400。

因此，这个问题不是：

SSH 密码错误；
服务器端口错误；
Docker 没有启动；
SSH 用户没有 Docker 权限；
防火墙阻止连接。

真正的问题是：

IntelliJ IDEA 2025.1.x 内置的 Docker 插件与远端较新的 Docker Engine 存在 API 版本兼容问题。

五、错误的解决方向

遇到这个问题时，不建议首先进行以下操作。

1. 不建议开放 Docker 2375 端口

不要为了绕过 SSH，直接开放：

tcp://0.0.0.0:2375

未配置 TLS 的 Docker TCP 端口具有很高的安全风险。

通过 SSH 连接远端 Docker 本身没有问题，错误发生在 Docker API 版本兼容层面。

2. 不建议修改 Docker 最低 API 版本

不要急着修改远端服务器的：

/etc/docker/daemon.json

强制让新版本 Docker 兼容非常老的 API，只能作为临时方案，而且可能带来安全和兼容风险。

3. 不建议直接降级服务器 Docker

服务器 Docker 可能还承载其他容器。直接降级 Docker Engine 可能影响：

当前正在运行的容器；
Docker Compose；
网络和存储驱动；
其他部署系统；
服务器安全更新。

4. 不需要反复修改 SSH 用户

如果设置页面已经显示：

Connection successful

并且服务器中可以执行：

docker ps

那么通常不是 SSH 用户权限问题。

六、正确解决方案：升级 IntelliJ IDEA

最终采用的解决方案是：

IntelliJ IDEA 2025.1.x
升级到
IntelliJ IDEA 2026.2.1

在旧版 IDEA 中进入：

Help → Check for Updates

更新窗口提示存在新版后，点击：

Download

由于这是跨大版本升级，点击 Download 后可能不会直接在 IDEA 中下载补丁，而是跳转到 JetBrains 下载网页。

这是正常现象。

七、Windows 应该下载哪个安装包

下载页面通常提供以下选项：

.exe (Windows)
.zip (Windows)
.exe (Windows ARM64)

普通 Intel 或 AMD 处理器的 Windows 电脑应该选择：

.exe (Windows)

不要选择：

.zip (Windows)
.exe (Windows ARM64)

其中：

.exe (Windows)：适用于普通 Intel/AMD 64 位 Windows；
.zip (Windows)：免安装压缩包，需要自行管理目录和快捷方式；
.exe (Windows ARM64)：只适用于 ARM 架构的 Windows 设备。

可以在旧版 IDEA 的 Help → About 中查看运行环境。如果显示：

amd64

就应该下载普通的：

.exe (Windows)

八、新版 IDEA 安装选项推荐

下载完成后，先关闭正在运行的 IDEA，然后双击 .exe 安装包。

安装目录

建议让新版本使用独立目录，例如：

C:\Program Files\JetBrains\IntelliJ IDEA 2026.2.1

不要安装到旧版 IDEA 的目录中。

这样做的好处是：

新旧版本可以暂时共存；
新版出现问题时可以回退；
确认新版稳定后再卸载旧版。

文件关联

Java 项目建议至少勾选：

.java

其他文件类型可以根据需要选择：

.kt
.kts
.groovy

如果安装器询问是否删除旧版本，建议暂时不要删除。先确认新版能够正常打开项目并连接远端 Docker。

九、首次启动导入旧版设置

新版 IDEA 第一次启动时，如果出现设置导入页面，选择：

Import settings from previous version

然后选择旧版 IntelliJ IDEA。

通常可以迁移：

主题；
字体；
快捷键；
Maven 设置；
Git 设置；
SSH 配置；
Docker 配置；
已安装插件；
代码格式化配置。

如果 Remote Docker 配置没有自动迁移，可以重新进入：

File
→ Settings
→ Build, Execution, Deployment
→ Docker

重新创建 SSH Docker 连接。

十、验证问题是否解决

新版 IDEA 启动后，首先检查版本：

Help → About

确认已经升级到新版本。

然后打开：

View → Tool Windows → Services

找到：

Remote-Docker

双击连接。

正常情况下，远程 Docker 会展开为：

Remote-Docker
├── Containers
├── Images
├── Networks
└── Volumes

不再出现：

client version 1.24 is too old

说明 IDEA Docker 插件与远端 Docker Engine 已经可以正常通信。

十一、配置 Maven 多模块项目打包

远程 Docker 连接成功后，就可以继续配置项目部署。

假设 Spring Boot 启动模块是：

project-admin

在项目根目录执行：

mvn clean package -pl project-admin -am -DskipTests

参数说明：

-pl project-admin

表示只构建指定模块。

-am

表示同时构建该模块依赖的其他模块。

-DskipTests

表示跳过测试执行，加快部署打包速度。

打包完成后确认生成：

project-admin/target/project-admin.jar

十二、Dockerfile 示例

在启动模块中创建 Dockerfile：

FROM eclipse-temurin:17-jre

WORKDIR /app

COPY target/project-admin.jar app.jar

ENV SERVER_PORT=8080

EXPOSE 8080

ENTRYPOINT ["java", "-jar", "/app/app.jar"]

注意 Dockerfile 中的 JAR 文件名必须与 Maven 实际生成的文件名一致。

如果 Dockerfile 中写的是：

COPY target/project-admin.jar app.jar

那么必须确认本地存在：

project-admin/target/project-admin.jar

否则构建镜像时会出现：

COPY failed

或者：

file not found in build context

十三、创建 IDEA Dockerfile 运行配置

进入：

Run → Edit Configurations

点击：

+ → Docker → Dockerfile

填写：

Name：Deploy-Backend-Remote
Server：Remote-Docker
Dockerfile：project-admin/Dockerfile
Image tag：project-admin:test
Build context：project-admin
Container name：project-admin-test

如果应用运行在 8080 端口，需要配置端口映射：

Host port：8080
Container port：8080

注意：

EXPOSE 8080

只是声明容器使用该端口，并不会自动将服务器端口映射到容器。

十四、配置打包后自动部署

在 Dockerfile 运行配置的 Before launch 中添加 Maven 任务：

Run Maven Goal

配置：

Working directory：项目根目录
Command line：clean package -pl project-admin -am -DskipTests

最终执行顺序变为：

1. IDEA 在本地执行 Maven 打包
2. 生成 Spring Boot JAR
3. IDEA 将 Docker build context 发送到远端服务器
4. 远端 Docker 构建镜像
5. IDEA 启动远端容器

以后只需要在 IDEA 中运行：

Deploy-Backend-Remote

就可以完成本地打包和远程 Docker 部署。

十五、总结

本次问题的表面现象是：

IDEA 已经显示 Connection successful
但 Services 无法展开远端 Docker

具体错误是：

client version 1.24 is too old
Minimum supported API version is 1.40

根本原因是：

旧版 IntelliJ IDEA Docker 插件使用的 Docker API 版本过低，与远端较新的 Docker Engine 不兼容。

最终解决方案是：

升级 IntelliJ IDEA
→ 导入旧版设置
→ 重新连接 Remote Docker
→ 验证 Containers 和 Images 可以正常加载

遇到类似问题时，建议按照下面的顺序排查：

1. 查看完整错误信息
2. 确认是否为 Docker API 版本不兼容
3. 优先升级 IDEA 和 Docker 插件
4. 不要轻易开放 Docker 2375 端口
5. 不要直接降低服务器 Docker 的安全配置
6. 不要在未评估影响的情况下直接降级 Docker Engine

对于开发和测试环境，使用 IntelliJ IDEA 通过 SSH 连接远端 Docker，可以实现非常方便的一键打包部署。

对于正式生产环境，后续可以进一步升级为：

Git 提交
→ CI/CD 执行 Maven 打包
→ 构建带版本号的 Docker 镜像
→ 推送镜像仓库
→ 服务器拉取镜像并部署

这样可以获得更好的版本管理、操作审计和快速回滚能力。

IntelliJ IDEA 连接远程 Docker 报错：client version 1.24 is too old