解决 GitLab CI/CD 中 kwargs_from_env() 的 ssl_version 参数错误

问题描述

在 GitLab CI/CD 的 docker_test 阶段使用以下配置时：

docker_test:
  image: docker:stable
  services:
    - docker:stable-dind
  stage: docker-test

管道运行会报错：
TypeError: kwargs_from_env() got an unexpected keyword argument 'ssl_version'

该错误由 Docker Python 客户端 (docker-py) 升级至 v7.0.0 导致💡。新版本移除了 ssl_version 参数支持，但旧版 Docker Compose v1 仍在尝试传递该参数，引发兼容性问题。

---

解决方案

✅ 推荐方案：迁移到 Docker Compose v2（长期最佳实践）

Docker Compose v2 已完全替代旧版 Python 实现的 v1，改用 Go 语言编写并内置于 Docker 引擎中：

1. 替换 CLI 命令

   # 旧命令 (v1)
   docker-compose up
   
   # 新命令 (v2)
   docker compose up

2. 修改 GitLab CI/CD 配置

   docker_test:
     image: docker:20.10.24  # 明确指定包含 v2 的版本
     services:
       - docker:20.10.24-dind  # 使用匹配的 dind 服务
     stage: docker-test

   📌 关键点：

   • 避免使用 docker:stable 标签（可能指向旧版本）
   • 明确指定兼容版本（如 20.10.24）

⚠️ 临时方案：降级 docker-py（不推荐长期使用）

通过降低 docker-py 版本兼容旧版 Compose v1：

pip install docker==6.1.3  # 指定兼容版本

此方案仅作为临时过渡，后续仍需升级到 v2。

---

错误方案（避免操作）

切勿通过修改代码内部文件（如 utils.py）强行兼容：

sudo nano /usr/local/lib/python/dist-packages/docker/utils/utils.py

此方法存在重大隐患：

1. 破坏版本一致性
2. 绕过安全升级（如 SSL/TLS 改进）
3. 导致后续更难迁移

---

原因总结

组件	状态	导致问题
Docker Compose v1	已废弃 (Python 实现)	依赖废弃的 ssl_version
docker-py v7+	移除 ssl_version 参数	造成参数不匹配
Docker Compose v2	官方当前版本 (Go 实现)	无兼容问题

解决总结

1. 首选方案
   升级到 Docker Compose v2 + 指定兼容镜像版本（迁移文档）

2. 临时方案
   降级 docker-py 至 6.1.3

3. 禁止方案
   手动修改库源代码

---

💡 迁移提示：
切换到 Compose v2 不仅解决此错误，还能获得更好的性能和新特性（如 GPU 支持）。GitLab CI/CD 配置中使用明确版本号可避免类似破坏性更新问题。