Docker升级后API版本不兼容导致脚本报错，需先定位客户端/服务端/插件三方版本错位，再通过环境变量降级、锁定CLI版本、补全平台参数等方式兼容，必要时调整cgroup驱动、移除废弃参数、更新镜像认证逻辑，并在脚本中动态适配API特性。
旧项目脚本（比如 Shell 自动化部署、CI/CD 流水线、Spring Boot 的 Docker 插件调用）突然报错“client version 1.24 is too old”或“API version 1.40 required”，基本都是 Docker 升级后客户端或服务端 API 版本跃升导致的。适配关键不是改代码逻辑，而是理清版本边界、保留行为一致性、做最小必要调整。
先确认实际断点在哪
很多问题表面是“脚本失败”，实则是客户端、服务端、插件三方版本错位。分三步定位：
- 运行
docker version，看 Client 和 Server 的 API version 是否匹配（如 Client API 1.43，Server API 1.40 → 兼容；Client 1.24，Server 1.40 → 不兼容） - 检查脚本里是否硬编码了 API 版本（例如
DOCKER_API_VERSION=1.24环境变量，或 Maven 插件配置中指定了<apiVersion>1.24</apiVersion>） - 如果是 Java 项目调用 Docker Remote API（如 docker-java 库），查 pom.xml 中依赖版本：
docker-java3.2.x 支持 API 1.24～1.40，但 3.7.0+ 才完整支持 1.43+
保持脚本行为不变的降级兼容方案
不改业务逻辑的前提下，让旧脚本能继续跑：
OpenClaw Docker Setup
下载
在 Linux 上通过 Docker 运行 OpenClaw，并使用 Tailscale 实现远程访问。⚠️ 涉及 sudo、Docker、Tailscale和凭证挂载——请先查阅安全章节...
-
强制客户端使用旧版 API：在执行脚本前设置环境变量
DOCKER_API_VERSION=1.40（即使客户端是 24.x，也会降级协商）。注意：仅限服务端支持该版本，否则会报错 -
锁定 Docker CLI 版本：避免系统自动升级破坏稳定性。Ubuntu/Debian 下可固定安装：
sudo apt install docker-ce=5:20.10.24-1~ubuntu.22.04~jammy docker-ce-cli=5:20.10.24-1~ubuntu.22.04~jammy -
绕过新版校验字段：Docker 24+ 默认启用
containerd运行时，并拒绝不含--platform的镜像拉取。旧脚本若没指定平台，加一句--platform linux/amd64即可（x86_64 机器默认就是这个）
适配必须修改的 Breaking Change
有些变更无法规避，需针对性调整：
-
cgroup 驱动变更：Docker 24+ 默认用
systemd，而旧脚本假设cgroupfs。若容器启动失败或 kubelet 报错，需在/etc/docker/daemon.json显式写：{"exec-opts": ["native.cgroupdriver=cgroupfs"]}，然后sudo systemctl restart docker -
废弃参数失效：如
docker run --icc=false或--disable-legacy-registry在 24.x 会直接报错退出。删掉这些参数，或改用等效新方式（如网络策略用--network none替代--icc） -
镜像拉取认证逻辑收紧：旧脚本若还用 v1 registry 或未配置
auths，升级后docker login可能成功但pull失败。统一改用 v2 registry，或补全~/.docker/config.json中的凭据格式
自动化脚本里的稳健写法
避免未来再踩坑，建议重构关键脚本段落：
- 用
docker version --format '{{.Server.APIVersion}}'动态获取服务端 API 版本，再决定是否传--platform或--cgroup-parent - Maven 构建中，把
docker-maven-plugin升级到1.4.13+，并去掉<apiVersion>硬编码，让它自动协商 - Shell 脚本开头加检测：
if [[ $(docker version --format '{{.Server.APIVersion}}' | cut -d. -f1) -lt 1 ]]; then echo "Docker too old"; exit 1; fi
