Docker Buildx 远程TLS连接构建失败问题分析

问题背景

在使用Docker Buildx进行远程构建时，当通过环境变量DOCKER_HOST、DOCKER_CERT_PATH和DOCKER_TLS_VERIFY配置TLS加密的TCP连接时，会出现构建失败的问题，错误信息为"Client sent an HTTP request to an HTTPS server"。而使用Docker上下文(Context)配置相同参数时则能正常工作。

问题重现

1. 准备一个简单的compose.yaml文件
2. 启动一个DinD(Docker in Docker)容器作为远程Docker服务器
3. 创建指向DinD容器的Docker上下文
4. 验证通过上下文构建能正常工作
5. 验证通过环境变量配置时构建失败

技术分析

这个问题主要出现在以下场景：

• 使用环境变量而非Docker上下文配置远程连接
• 启用了Compose的Bake功能(COMPOSE_BAKE=true)
• 直接调用Buildx插件而非通过Docker CLI

根本原因在于Docker CLI插件机制在处理环境变量配置的TLS连接时存在缺陷。当插件直接运行时，未能正确继承主CLI的TLS配置逻辑，导致无法建立正确的HTTPS连接，而是错误地使用了HTTP协议。

影响范围

该问题影响：

• Docker版本28.0.4
• Docker Compose v2.34.0
• 使用环境变量配置TLS远程连接的场景
• 启用了Bake功能的Compose构建

解决方案

目前推荐的解决方案是：

1. 优先使用Docker上下文而非环境变量配置远程连接
2. 临时禁用COMPOSE_BAKE功能
3. 等待官方修复此问题

技术细节

深入分析发现，Docker CLI插件在独立运行时，未能正确处理以下环境变量：

• DOCKER_HOST
• DOCKER_CERT_PATH
• DOCKER_TLS_VERIFY

这导致插件无法正确初始化TLS连接配置，从而回退到不安全的HTTP连接，与远程HTTPS服务器不兼容。而Docker上下文机制由于走的是不同的配置路径，能够正确传递TLS参数。

总结

这个问题揭示了Docker插件机制在环境变量处理上的一个边界情况。对于生产环境中的远程构建场景，建议采用更稳定的Docker上下文配置方式。开发团队已经确认此问题并开始着手修复，预计在后续版本中解决。