IDEA 远程 Docker 一键部署Java后端（SSH 模式）

环境：本地 Windows 11 + IDEA 2026.x，远程 Linux 服务器（1Panel 管理），后端 Spring Boot（JDK 21）
目标：在 IDEA 里点一下 Run，自动完成「Maven 打包 → 远程构建 Docker 镜像 → 启动容器」，本地不装 Docker Desktop。

---

一、原理：IDEA 是怎么"远程部署"的？

1.1 两种远程 Docker 连接模式对比

IDEA 连接远程 Docker 有两种方式：

对比项	TCP 2375 模式	SSH 模式（本文）
远程 daemon 配置	需改 daemon.json 监听 tcp://0.0.0.0:2375	零配置，默认的 unix socket 即可
本地依赖	无（IDEA 内置 Java HTTP 客户端直连）	需要本地 docker.exe CLI
安全性	❌ 无认证无加密，裸奔公网 = 送矿机	✅ 走 SSH 加密通道
公网暴露	2375 端口直接暴露（高危）	只暴露 22 端口

2375 模式之所以"什么都不用装"，是因为 Docker daemon 本身就是一个 HTTP REST API，IDEA 拿内置客户端直接发 HTTP 请求就行。但这个 API 没有任何认证和加密，扫描器全网扫 2375 端口挖矿，公网环境绝对不能用。

SSH 模式下，远程 daemon 只监听本地的 unix socket，不对外暴露任何端口；本地的 docker.exe 通过 SSH 协议当"翻译官"，把命令隧道转发过去。

1.2 SSH 模式的工作流程

IDEA
 │  1. 调本地 docker.exe
 ▼
本地 docker.exe ──SSH隧道(22端口)──> 服务器 docker daemon
                                        │
        2. 上传构建上下文(JAR+Dockerfile) ─┘
                                        │
        3. 服务器本地执行 docker build ◄─┘ （基础镜像由服务器拉取，不占本地带宽）
                                        │
        4. docker run 启动容器      ◄─────┘

注意两个关键点：

• 镜像在服务器上构建，不是本地构建好再传镜像。本地只上传"构建上下文"（JAR 包 + Dockerfile），一般几十~几百 MB。
• 基础镜像由服务器拉取（如 JDK 镜像），不吃本地网络。

1.3 为什么本地必须装 docker.exe？

IDEA 的 SSH 模式本质是让本地 CLI 执行 docker -H ssh://user@server ...。-H ssh:// 协议由本地 docker CLI 实现：它把 Docker API 请求包装后通过 ssh 命令转发到远程 daemon 的 unix socket。没有本地 CLI，这条链路就断了——这也是第一个报错的根源。

---

二、准备工作

2.1 服务器侧（几乎零配置）

# 1. 确认 docker 已安装且 daemon 运行中
docker info

# 2. 把 SSH 用户加入 docker 组（免 sudo 操作 docker）
sudo usermod -aG docker your-user

# 3. 确认能免密/密码 SSH 登录即可，无需改 daemon.json

如果服务器装了 1Panel，docker 已经就绪，只需要处理第 2 步（1Panel 默认 root 用户本身就在 docker 组）。

2.2 本地安装 Docker CLI（不装 Docker Desktop）

Docker Desktop 要跑一个完整的 Linux 虚拟机，常驻 1~2GB 内存，我只是想要一个客户端，不值。官方提供了纯静态 CLI 包：

下载地址：https://download.docker.com/win/static/stable/x86_64/
(我是下载的最新的版本)

# 1. 下载 zip（本文用 29.7.2），解压得到 docker 目录（内含 docker.exe）
# 2. 放到一个固定目录，如 D:\software\dev\docker-cli\
# 3. 把该目录加入 PATH 环境变量
# 4. 新开终端验证：
docker --version
# Docker version 29.7.2, build a7dcaa6

这个 CLI 是纯客户端，没有任何后台进程、不占内存，完美。
添加环境变量操作步骤图例：

2.3 安装 buildx 插件（⚠️ 本文最大的坑）

装好 CLI 满心欢喜去 IDEA 点部署，结果报错：

ERROR: BuildKit is enabled but the buildx component is missing or broken
Failed to deploy 'xxx Dockerfile: xxx/Dockerfile-dev': Image build failed with exit code 1

原因：新版 docker 的 build 命令默认走 BuildKit，而 BuildKit 的实现 buildx 是一个外部插件——docker 本体里根本没有这个命令。Docker Desktop 用户感知不到，是因为 Desktop 帮你预装了；静态包只包含 docker.exe 一个文件，啥插件都没有。

去 GitHub 下载：https://github.com/docker/buildx/releases

选择 buildx-vX.X.X.windows-amd64.exe，然后：

# 1. 创建插件目录（Windows 固定位置）
#windows位置为：”C:\Users\用户名\.docker\cli-plugins“ 如果没有.docker目录，需要自行创建，且需要打开文件夹里面的
mkdir "%USERPROFILE%\.docker\cli-plugins"

# 2. 把下载的文件改名并移过去（文件名必须是 docker-buildx.exe）
move buildx-v0.x.x.windows-amd64.exe %USERPROFILE%\.docker\cli-plugins\docker-buildx.exe

# 3. 验证
docker buildx version
# github.com/docker/buildx v0.x.x ...

操作系统里面以 “.” 开头的文件都是隐藏文件夹，需要勾选"隐藏的项目"才能看到隐藏的文件夹!

放到此目录下即可：

踩坑细节：我一开始把 docker-buildx.exe 和 docker.exe 放同一个目录（都在 PATH 里），以为会自动发现，结果：

docker: unknown command: docker buildx

实测这个版本的静态包不做 PATH 插件查找，插件必须放在标准目录：

系统	插件目录
Windows	%USERPROFILE%\.docker\cli-plugins\
Linux	/usr/local/lib/docker/cli-plugins/ 或 /usr/lib/docker/cli-plugins/

---

三、IDEA 配置

一图看配置步骤：

3.1 添加 SSH 远程 Docker 连接

1. File → Settings → Build, Execution, Deployment → Docker
2. 点 +，选 SSH
3. 填服务器信息：
   • Host：你的服务器 IP
   • Port：22
   • Username / 认证方式（密码或私钥）
4. 点 Test Connection，出现 Connection successful 即可

配置成功后，IDEA 底部 Services 面板（View → Tool Windows → Services）会出现远程 Docker，能直接浏览服务器上的镜像和容器——以后查看容器日志、进终端都不用开 SSH 工具了。

3.2 创建 Dockerfile 运行配置

Run → Edit Configurations → + → Docker → Dockerfile：

配置项	值	说明
Server	刚创建的 SSH 连接	远程在哪构建
Dockerfile	xxxxx/Dockerfile-dev	相对项目根路径
Image tag	xxx-dev:latest	镜像名
Container name	xxx-dev	容器名
Bind ports	5505:8080	服务器5505 → 容器8080
Before launch	Run Maven Goal: clean package -DskipTests	关键：构建前先打 JAR

Before launch 是这套方案的灵魂：把 Maven 打包挂在部署前面，实现真正的"一键"——点 Run 自动 编译 → 打包 → 传 JAR → 远程 build → 远程 run。

---

四、Dockerfile（dev 版）

# 开发环境镜像（连 dev 库，无需注入环境变量）
FROM bellsoft/liberica-openjdk-rocky:21.0.10-cds

RUN mkdir -p /xxx/server/logs /xxx/server/upload /xxx/server/temp
WORKDIR /xxx/server

ENV SERVER_PORT=8080 \
    SNAIL_PORT=28080 \
    SPRING_PROFILES_ACTIVE=dev \
    TZ=Asia/Shanghai

EXPOSE ${SERVER_PORT}

# JAR 由 IDEA 构建前先打好
COPY ./target/xxx.jar /xxx/server/xxx.jar

ENTRYPOINT ["sh", "-c", "cd /xxx/server && exec java \
    -Dserver.port=${SERVER_PORT} \
    -Dspring.profiles.active=${SPRING_PROFILES_ACTIVE} \
    -Duser.timezone=${TZ} \
    -XX:+HeapDumpOnOutOfMemoryError \
    -XX:HeapDumpPath=/xxx/server/logs/ \
    -XX:+UseZGC \
    -jar /xxx/server/xxx.jar"]

要点：

• dev 环境的数据库/Redis 地址直接写在 application-dev.yml 默认值里，容器零环境变量注入；生产环境则全部改成 ${DB_HOST} 这类占位符，通过 -e 或 compose 注入。
• ENTRYPOINT 用 shell 形式（sh -c）而不是 exec 形式，这样 ${SERVER_PORT} 这类环境变量替换才会生效。
• exec java 让 java 成为 PID 1，正确接收 stop 信号。

---

五、验证

# 本地直接测公网入口（Windows 有系统代理时要加 --noproxy）
curl --noproxy '*' http://your-server-ip:5505/actuator/health
# {"status":"UP"}

跑通后，日常迭代流程变成：改代码 → 点一下 Run → 喝口水 → 服务器上已经是新版本。

六、常见问题速查

报错	原因	解法
Cannot run program "docker.exe" CreateProcess error=2	本地没有 docker CLI	装 2.2 的静态包 + PATH
BuildKit is enabled but the buildx component is missing or broken	缺 buildx 插件	装 2.3 的 buildx
docker: unknown command: docker buildx	插件放错位置（和 docker.exe 同目录无效）	移到 %USERPROFILE%\.docker\cli-plugins\ 且必须改名 docker-buildx.exe
Connection successful 但 build 超时	服务器拉基础镜像慢	提前在服务器手动 docker pull 一次基础镜像
curl 返回 502	Windows 系统代理劫持 localhost/请求	加 --noproxy '*'
端口不通	云安全组没放行	云控制台安全组 + 服务器防火墙都要放行

---

总结

整个方案的核心认知就一句话：IDEA 的 SSH 远程 Docker = 本地 docker CLI（含 buildx 插件）+ SSH 通道 + 远程 daemon。

三个坑的根因其实都指向同一个知识点——docker 的 CLI 与插件是分离的：

1. 本地必须装 CLI（IDEA 只是指挥它干活）
2. CLI 静态包不含 buildx（build 命令是插件提供的）
3. 插件必须放标准目录（%USERPROFILE%\.docker\cli-plugins\），且文件名固定

相比 Docker Desktop：零后台进程、零内存占用；相比手动 docker save | scp | docker load：真正的 IDEA 一键部署。配合 1Panel 管理服务器容器，开发体验非常顺滑。

---

创作日期：2026-08-26