Jenkins使用自签名证书时Docker入站从节点连接失败如何解决？

两类报错的直接原因 #

• 加-cert @<path to file>返回empty input：核心原因是参数格式错误，-cert和后续的@文件路径之间不能加空格，加空格会导致程序把@<path>识别为独立参数，无法读取证书文件；少数情况是容器内证书文件权限配置错误，运行agent的jenkins用户（UID 1000）没有文件读权限，或挂载路径错误导致文件实际不存在。
• 传入证书内容报识别到未知选项-----END CERTIFICATE-----：是因为PEM格式证书自带换行符，直接拼接到启动命令时，程序会把换行后的每一行内容（包括证书尾标记）识别为独立启动参数，无法和-cert参数绑定。

可行解决方案 #

方案1：将自签名证书导入镜像Java信任库（生产环境首选，最稳定） #

jenkins-inbound-agent是Java编写的程序，默认会读取JRE内置的信任证书库，直接把自签名证书打进镜像信任链，不需要额外加启动参数，不会出现参数解析问题。
自定义Dockerfile构建自定义agent镜像即可：

FROM jenkins/inbound-agent:latest
USER root
# 把本地的自签名证书拷贝到镜像内
COPY your-jenkins-selfsigned.crt /tmp/jenkins-ca.crt
# 导入证书到Java信任库，默认信任库密码是changeit
RUN keytool -importcert -noprompt -trustcacerts -alias jenkins-selfsigned-ca \
  -file /tmp/jenkins-ca.crt \
  -keystore $JAVA_HOME/lib/security/cacerts \
  -storepass changeit
# 切回默认的jenkins用户运行，避免权限问题
USER jenkins

后续启动从节点时使用这个自定义镜像即可，不需要额外配置证书相关参数。

方案2：修正-cert参数格式，解决参数解析错误 #

如果不想自定义镜像，可以修正启动参数的写法：

1. 启动容器时，把本地自签名证书挂载到容器内的固定路径，比如/var/jenkins_ca.crt，保证证书文件权限对jenkins用户可读。
2. 启动参数里的-cert写法不要加空格，正确格式为-cert@/var/jenkins_ca.crt，即可正常读取证书文件，不会报empty input错误。
   如果要通过环境变量传递证书内容，不要直接把带换行的PEM内容拼到命令行，先把证书内容转成无换行的单行字符串，或者用bash进程替换传参，示例启动命令片段：

# 先把证书内容存到环境变量，注意用引号包裹保留换行
export JENKINS_CA=$(cat your-jenkins-selfsigned.crt)
# 启动时用进程替换传递内容，避免换行导致参数解析错误
jenkins-agent -url $JENKINS_URL -secret $AGENT_SECRET -name $AGENT_NAME -cert <(echo "$JENKINS_CA")

方案3：挂载证书到系统CA目录，更新系统信任链 #

启动容器时把自签名证书挂载到容器内/usr/local/share/ca-certificates/目录下，自定义启动入口先执行系统证书更新，再启动agent：

# 启动命令示例
docker run -v /local/path/your-jenkins-ca.crt:/usr/local/share/ca-certificates/jenkins-ca.crt \
  jenkins/inbound-agent \
  bash -c "update-ca-certificates && exec jenkins-agent -url $JENKINS_URL -secret $AGENT_SECRET -name $AGENT_NAME"

注意这个方案需要容器以root用户执行update-ca-certificates，执行完可以切回jenkins用户启动进程，生产环境注意权限收敛。

方案4：临时跳过证书校验（仅排障用，禁止生产环境使用） #

如果只是临时测试连通性，可以加启动参数直接跳过SSL证书校验：

jenkins-agent -url $JENKINS_URL -secret $AGENT_SECRET -name $AGENT_NAME -noCertificateCheck

该方案会完全跳过SSL证书校验，存在中间人攻击风险，绝对不能在生产环境使用。

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