Docker Buildx远程构建器inactive含义及激活方法

问题场景 #

执行以下docker buildx create命令创建远程构建器：

# 说明："$ " 表示输入行，"> " 表示输出行

$ docker buildx create \
  --name amd64_builder \
  --node amd64_builder \
  --platform linux/amd64 \
  "ssh://<MY_USER>@<IP>"

> WARNING: new settings may not be used until builder is restarted
> amd64_builder

命令执行成功（退出码0），但输出警告：

WARNING: new settings may not be used until builder is restarted

执行docker buildx ls查看构建器状态，发现远程构建器处于inactive：

$ docker buildx ls

> NAME/NODE       DRIVER/ENDPOINT          STATUS   BUILDKIT             PLATFORMS
> amd64_builder * remote
>   amd64_builder ssh://<MY_USER>@<IP>     inactive                      linux/amd64*
> default         docker
>   default       default                  running  v0.12.2+6560bb937e8c linux/arm64, linux/amd64, linux/amd64/v2, linux/riscv64, linux/ppc64le, linux/s390x, linux/mips64le, linux/mips64
> desktop-linux   docker
>   desktop-linux desktop-linux            running  v0.12.2+6560bb937e8c linux/arm64, linux/amd64, linux/amd64/v2, linux/riscv64, linux/ppc64le, linux/s390x, linux/mips64le, linux/mips64

已确认可通过ssh <MY_USER>@<IP>正常连接目标主机（配置了有效的~/.ssh/config）。

一、inactive状态的含义 #

inactive表示该远程构建节点尚未启动BuildKit服务，无法接收构建任务。Buildx创建远程构建器时，仅在本地完成了构建节点的信息注册，并不会自动在远程主机上启动对应的BuildKit实例，因此状态显示为未激活。

二、激活远程构建器的步骤 #

方式1：手动重启构建器 #

执行命令重启指定构建器，触发Buildx在远程主机上启动BuildKit服务：

docker buildx stop amd64_builder
docker buildx start amd64_builder

完成后再次执行docker buildx ls，状态会切换为running。

方式2：通过构建任务自动激活 #

首次使用该构建器执行docker buildx build命令时，Buildx会自动尝试在远程主机上启动BuildKit服务，任务执行后构建器状态会自动变为running，示例命令：

docker buildx build --builder amd64_builder --platform linux/amd64 -t your-image:tag .

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