运行Docker Agent时Jenkins流水线因缺失ca.pem失败，该如何解决？

问题背景 #

环境配置：

• Jenkins版本：2.426.3
• 操作系统：Linux - 5.15.133.1-microsoft-standard-WSL2
• Java版本：17.0.9 - Eclipse Adoptium (OpenJDK 64-Bit Server VM)

通过以下Docker Compose启动Jenkins服务：

version: "3"

services:
  jenkins-blueocean:
    image: myjenkins-blueocean:1
    container_name: jenkins-blueocean
    restart: on-failure
    networks:
      - jenkins
    environment:
      - DOCKER_HOST=tcp://docker:2376
      - DOCKER_CERT_PATH=/certs/client
      - DOCKER_TLS_VERIFY=1
    volumes:
      - jenkins-data:/var/jenkins_home
      - jenkins-docker-certs:/certs/client:ro
    ports:
      - "8080:8080"
      - "50000:50000"

networks:
  jenkins:

volumes:
  jenkins-data:
  jenkins-docker-certs:

执行Docker Agent流水线时失败，流水线代码：

pipeline {
    agent {
        docker {
            image 'node:20-alpine'
            args '-p 3000:3000'
        }
    }
    stages {
        stage('Build') {
            steps {
                echo 'Building...'
            }
        }
    }
}

错误信息：

Failed to initialize: unable to resolve docker endpoint: open /certs/client/ca.pem: no such file or directory

ca.pem文件的获取位置 #

ca.pem是Docker TLS认证所需的根证书，获取途径分两种情况：

1. 从Docker Desktop（WSL2环境）获取 #

如果你的WSL2使用Windows上的Docker Desktop（默认开启TLS认证），证书存放在：

• Windows路径：%USERPROFILE%\.docker
• WSL2映射路径：/mnt/c/Users/<你的Windows用户名>/.docker
  该目录下会有ca.pem、cert.pem、key.pem三个文件。

2. 手动生成Docker TLS证书 #

如果没有现成证书，可通过OpenSSL手动生成：

# 创建证书目录
mkdir -p certs/client certs/server

# 生成CA证书
openssl genrsa -out certs/ca-key.pem 4096
openssl req -new -x509 -days 365 -key certs/ca-key.pem -sha256 -out certs/ca.pem -subj "/CN=docker-ca"

# 生成服务器证书
openssl genrsa -out certs/server/server-key.pem 4096
openssl req -subj "/CN=docker" -sha256 -new -key certs/server/server-key.pem -out certs/server/server.csr
echo "subjectAltName = DNS:docker,DNS:localhost,IP:127.0.0.1" >> certs/server/extfile.cnf
echo "extendedKeyUsage = serverAuth" >> certs/server/extfile.cnf
openssl x509 -req -days 365 -sha256 -in certs/server/server.csr -CA certs/ca.pem -CAkey certs/ca-key.pem -CAcreateserial -out certs/server/server-cert.pem -extfile certs/server/extfile.cnf

# 生成客户端证书
openssl genrsa -out certs/client/key.pem 4096
openssl req -subj "/CN=client" -new -key certs/client/key.pem -out certs/client/client.csr
echo "extendedKeyUsage = clientAuth" >> certs/client/extfile.cnf
openssl x509 -req -days 365 -sha256 -in certs/client/client.csr -CA certs/ca.pem -CAkey certs/ca-key.pem -CAcreateserial -out certs/client/cert.pem -extfile certs/client/extfile.cnf

# 设置权限
chmod 0400 certs/ca-key.pem certs/server/server-key.pem certs/client/key.pem
chmod 0444 certs/ca.pem certs/server/server-cert.pem certs/client/cert.pem

生成后，certs/client目录下就是所需的ca.pem、cert.pem、key.pem。

配置Jenkins使用该文件 #

方法1：填充jenkins-docker-certs卷 #

1. 找到jenkins-docker-certs卷的实际存储路径：

docker volume inspect jenkins-docker-certs

输出中的Mountpoint字段即为路径，例如/var/lib/docker/volumes/jenkins-docker-certs/_data。

2. 将获取到的三个证书文件复制到该路径：

cp /path/to/your/ca.pem /path/to/jenkins-docker-certs/_data/
cp /path/to/your/cert.pem /path/to/jenkins-docker-certs/_data/
cp /path/to/your/key.pem /path/to/jenkins-docker-certs/_data/

3. 重启Jenkins容器：

docker restart jenkins-blueocean

方法2：修改Docker Compose配置（临时测试用） #

测试环境可临时禁用TLS认证，修改environment部分：

environment:
  - DOCKER_HOST=tcp://docker:2375  # 改用非TLS端口2375
  # 注释掉以下两行
  # - DOCKER_CERT_PATH=/certs/client
  # - DOCKER_TLS_VERIFY=1

注意：生产环境禁用TLS会带来安全风险，不推荐。

方法3：在Jenkins流水线中指定证书路径 #

若证书已挂载到Jenkins容器内的其他路径，可在Docker Agent配置中直接指定：

pipeline {
    agent {
        docker {
            image 'node:20-alpine'
            args '-p 3000:3000'
            certPath '/path/to/certs/in/jenkins'  # 替换为容器内实际证书路径
        }
    }
    stages {
        stage('Build') {
            steps {
                echo 'Building...'
            }
        }
    }
}

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