Docker CI/CD中“无法连接守护进程”或TLS握手失败，主因是客户端与守护进程TLS配置不匹配：若daemon.json启用TLS双向认证，客户端须提供ca.crt、client.crt、client.key并设置DOCKER_HOST、DOCKER_TLS_VERIFY、DOCKER_CERT_PATH；否则应关闭TLS或改用socket+docker组权限方案。
CI/CD流水线中出现“无法连接到Docker守护进程”或TLS握手失败（如dial unix /var/run/docker.sock: connect: connection refused、tls: failed to verify certificate），往往不是Docker服务本身宕了，而是客户端与守护进程通信时因TLS配置不匹配被拦截。尤其在私有化部署、远程构建节点或安全加固环境中，这个问题高频发生。
确认Docker守护进程是否启用TLS认证
默认情况下，Docker守护进程监听unix:///var/run/docker.sock，不启用TLS。但若CI节点启用了TLS（例如通过daemon.json配置了tls、tlscert、tlskey和tlscacert），而客户端未同步配置，就会拒绝连接。
- 登录CI执行节点，检查
/etc/docker/daemon.json是否存在TLS相关字段："tls": true,"tlscert": "/etc/docker/certs/server.crt","tlskey": "/etc/docker/certs/server.key","tlscacert": "/etc/docker/certs/ca.crt" - 若存在，说明守护进程强制要求TLS双向认证，此时CLI必须提供对应客户端证书，不能直连
docker.sock - 验证方式：临时用
curl --cert client.crt --key client.key --cacert ca.crt https://localhost:2376/_ping测试
CI环境中的客户端TLS配置补全
流水线任务运行在普通用户上下文，Docker CLI默认不加载任何TLS凭据。需显式注入证书并指定远程API地址。
Docker Image Puller
下载
使用 Python 脚本下载 Docker 镜像并打包为 tar 文件。用户说“下载镜像”“拉取镜像”“pull xxx”“帮我下载 nginx 镜像”等时触发。支持 SOCKS5 代理直连（推荐）和国内镜像站加速两种模式。
- 将
ca.crt、client.crt、client.key作为CI secrets安全挂载到工作目录（如./docker-certs/） - 在job脚本中设置环境变量：
export DOCKER_HOST=tcp://localhost:2376export DOCKER_TLS_VERIFY=1export DOCKER_CERT_PATH=$(pwd)/docker-certs - 确保
DOCKER_CERT_PATH下文件权限为600（特别是client.key），否则Docker CLI会拒绝加载
避免TLS配置冲突的两种务实路径
并非所有CI场景都需要TLS——关键看构建节点是否暴露在不可信网络。多数内部Kubernetes或专用Runner可降级为Unix socket通信，更简单可靠。
-
路径一：关闭守护进程TLS（推荐用于内网可信CI节点）
注释或删除daemon.json中的TLS配置项，执行sudo systemctl restart docker，之后CI直接使用docker ps即可 -
路径二：统一使用socket+权限控制（兼顾安全与简洁）
保持守护进程监听unix:///var/run/docker.sock，但将CI执行用户加入docker组：sudo usermod -aG docker $CI_USER；再确保/var/run/docker.sock权限为srw-rw----，属组docker
排查证书信任链断裂的典型表现
即使TLS开启，若CA证书未被系统信任，也可能报错x509: certificate signed by unknown authority，这在Alpine基镜像或精简OS中尤为常见。
- 在CI job容器内执行：
cat /etc/os-release确认基础镜像类型 - 若为Alpine，需在构建阶段安装根证书：
apk add --no-cache ca-certificates && update-ca-certificates - 若为Ubuntu/Debian，检查
/etc/ssl/certs/ca-certificates.crt是否包含你的私有CA；缺失则追加并更新：cat ca.crt >> /etc/ssl/certs/ca-certificates.crt && update-ca-certificates
