Bitbucket Pipeline部署Docker Stack遇API版本不匹配报错求助

我之前帮团队排查过好几次类似的问题，虽然你本地和管理节点的Docker客户端API版本都是1.37，但问题大概率出在Bitbucket Pipeline运行环境里的Docker客户端，和你实际连接的Docker daemon之间的版本不匹配——或者你在Pipeline里连接的daemon根本不是你预期的管理节点，而是Pipeline容器自带的低版本daemon。

下面是一步步的排查和解决方法：

1. 先确认Pipeline中的Docker环境细节 #

首先在你的Pipeline脚本里加一行docker version，先搞清楚当前环境里的客户端版本，以及它连接的daemon的API版本：

script:
  # 先打印版本信息，排查问题
  - docker version
  # 再执行部署命令
  - docker stack deploy -c docker-compose.yml --with-registry-auth myapp

运行Pipeline后看输出：

• 如果显示连接的daemon API版本低于1.25，那说明你没正确连接到管理节点，而是用了Pipeline容器内部的默认daemon（版本通常很低）。
• 如果客户端版本低于17.06（对应API 1.25），那就是Pipeline的基础镜像太旧，需要升级。

2. 升级Pipeline的Docker基础镜像 #

Bitbucket Pipeline默认的Docker镜像可能版本偏旧，直接用官方的高版本镜像替换即可，比如docker:20.10（这个版本的客户端API是1.41，完全兼容你的管理节点1.37的API）：

# 指定高版本的Docker镜像作为Pipeline环境
image: docker:20.10

script:
  - docker version
  - docker stack deploy -c docker-compose.yml --with-registry-auth myapp

注意：如果需要使用docker-compose，还要安装对应的工具，比如在脚本里加：

script:
  - apk add --no-cache docker-compose
  - docker-compose version
  - docker stack deploy -c docker-compose.yml --with-registry-auth myapp

3. 确保Pipeline正确连接到管理节点的Docker daemon #

很多时候问题是Pipeline没正确配置远程daemon连接，导致用了本地容器的daemon。你需要在Pipeline里配置远程连接的环境变量：

image: docker:20.10

variables:
  # 指定管理节点的远程API地址（如果用TLS的话是2376端口，否则是2375）
  DOCKER_HOST: "tcp://your-manager-node-ip:2376"
  # 开启TLS验证（如果你的daemon配置了TLS的话）
  DOCKER_TLS_VERIFY: "1"
  # 指定证书路径（需要把证书存在Bitbucket的Secure Files里，或者作为变量传入）
  DOCKER_CERT_PATH: "/root/.docker"

script:
  # 先把证书复制到指定路径（假设你把证书存在了Bitbucket的Secure Files中）
  - mkdir -p /root/.docker
  - cp ./ca.pem ./cert.pem ./key.pem /root/.docker/
  - docker version
  - docker stack deploy -c docker-compose.yml --with-registry-auth myapp

另外要确认你的管理节点已经开启了远程API访问，并且允许Pipeline所在的IP连接。

4. 临时 workaround：强制指定API版本 #

如果暂时没法升级Pipeline的镜像，可以尝试强制客户端使用兼容的API版本，设置环境变量DOCKER_API_VERSION：

script:
  - export DOCKER_API_VERSION=1.25
  - docker stack deploy -c docker-compose.yml --with-registry-auth myapp

不过这个方法只是临时解决，长期来看还是要保持客户端和daemon的版本尽量一致，避免后续出现其他兼容性问题。

5. 检查Docker Compose文件的语法版本 #

最后确认你的docker-compose.yml的version字段和daemon支持的版本匹配，比如18.03的Docker daemon支持3.7及以下的Compose版本，如果用了更高的版本（比如3.8）也可能触发类似的错误。

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