🔧 内网 Jenkins HTTPS 部署与节点配置

在内网环境部署 Jenkins 时，为满足安全要求需要启用 HTTPS 并使用自签证书。本文将详细介绍如何解决自签证书导致的节点添加失败、中文乱码等常见问题，提供完整的配置流程和验证方法。

准备工作

  • Jenkins 服务已部署并配置反向代理
  • 已生成自签 SSL 证书文件（.crt 格式）
  • Windows 节点已安装 JDK 环境
  • 已获取 Jenkins 节点密钥和 agent.jar 文件

问题背景

内网部署 Jenkins 时通常会遇到以下技术挑战：

  1. 证书信任问题：Windows 系统信任自签证书，但 JVM 拥有独立的 trustStore 证书库，不会自动识别系统信任的证书
  2. 节点连接失败：Jenkins 节点使用 JVM 连接 HTTPS 服务时，因无法验证自签证书导致连接失败
  3. 中文乱码：Windows 节点 PowerShell 控制台默认编码与 Jenkins 输出编码不匹配

第一步：导入自签证书到 JVM 证书库

🪟 Windows 环境操作

使用 keytool 工具将自签证书导入 JVM 证书库：

1
keytool.exe -importcert -v -noprompt -alias "prod_jenkins" -file "c:\temp\_.test.cn.crt" -storepass changeit -storetype PKCS12 -keystore "c:\users\test\.keystore"

参数说明：

  • -v：详细输出，便于排查错误
  • -noprompt：非交互式模式，自动确认信任证书
  • -alias：证书别名，便于后续管理
  • -file：自签证书文件路径
  • -storepass：JVM 默认证书库密码（通用密码为 changeit）
  • -storetype：证书库类型（JDK 11+ 使用 PKCS12，JDK 8 使用 JKS）
  • -keystore：证书库文件路径（可选，默认为用户家目录下的 .keystore）

证书库路径选择

  1. 用户级证书库（推荐）：c:\users\<username>\.keystore

    • 仅影响当前用户运行的 Java 程序
    • 无需管理员权限

  2. 全局证书库：%JAVA_HOME%\jre\lib\security\cacerts

    • 影响所有 Java 程序
    • 需要管理员权限执行

第二步：配置 Jenkins 节点启动参数

启动 Jenkins agent 时，通过 JVM 参数指定证书库路径，确保节点信任自签证书：

PowerShell 命令：

1
2
3
4
5
6
7
8
9
java "-Djavax.net.ssl.trustStore=c:\users\test\.keystore" `
"-Djavax.net.ssl.trustStorePassword=changeit" `
"-Djavax.net.ssl.trustStoreType=PKCS12" `
-jar agent.jar `
-url https://jenkins.test.cn `
-workDir "D:\jenkins_agent" `
-secret "xxxxxx" `
-name "Windows-构建节点01" `
-webSocket

根据实际环境修改以下参数：

  • c:\users\test\.keystore：证书库文件路径
  • https://jenkins.test.cn：Jenkins 服务地址
  • D:\jenkins_agent：节点工作目录
  • xxxxxx：节点密钥（从 Jenkins 管理页面获取）
  • Windows-构建节点01：自定义节点名称

关键参数：

  • -Djavax.net.ssl.trustStore：指向导入证书的库文件
  • -Djavax.net.ssl.trustStorePassword：证书库密码（与导入时一致）
  • -Djavax.net.ssl.trustStoreType：证书库类型（必须匹配导入时的类型）
  • -url：Jenkins 服务 HTTPS 地址
  • -secret：节点密钥（从 Jenkins 管理页面获取）
  • -workDir：节点工作目录

第三步：解决中文乱码问题

配置 JVM 编码环境变量

通过设置 JAVA_TOOL_OPTIONS 环境变量，强制 JVM 使用 UTF-8 编码：

🪟 Windows 配置步骤：

  1. 右键「此电脑」→「属性」→「高级系统设置」→「环境变量」
  2. 在「系统变量」中点击「新建」
  3. 输入以下配置：
    • 变量名：JAVA_TOOL_OPTIONS
    • 变量值：-Dfile.encoding=UTF-8
  4. 点击「确定」保存
  5. 重启 Jenkins 节点代理和 PowerShell 控制台

补充验证方法

如果配置环境变量后仍出现乱码，可以尝试以下方法：

方法一：调整 PowerShell 控制台编码

1
chcp 65001

方法二：启动时直接指定编码参数

1
java -Dfile.encoding=UTF-8 -Djavax.net.ssl.trustStore=c:\users\test\.keystore -jar agent.jar ...

注意事项

  1. 证书库类型兼容性

    • JDK 8 及以下版本默认使用 JKS 类型
    • JDK 11+ 版本默认使用 PKCS12 类型
    • 导入和启动参数的 trustStoreType 必须保持一致

  2. 权限要求

    • 导入全局证书库需要管理员权限
    • Jenkins 节点启动用户需要对证书库文件具有读取权限

  3. 反向代理配置

    • 确保反向代理正确配置 HTTPS 转发
    • 需要透传 HTTPS 相关头信息（如 X-Forwarded-Proto: https）
    • 验证 Jenkins 节点访问的 URL 能正确映射到服务端口

验证步骤

完成配置后，通过以下步骤验证部署是否成功：

  1. 启动 Jenkins 节点，观察控制台输出是否有 SSL 相关错误
  2. 在 Jenkins 管理页面检查节点状态是否为「在线」
  3. 执行测试任务，验证中文日志输出是否正常显示
  4. 检查节点工作目录是否正常创建和写入文件

常见问题

问题：节点启动后提示 unable to find valid certification path

解决方案：检查证书是否正确导入，确认 -Djavax.net.ssl.trustStore 路径与导入时的 -keystore 路径一致

问题：环境变量配置后仍然乱码

解决方案：确认已重启 PowerShell 控制台和 Jenkins 节点服务，环境变量修改需要重启才能生效

问题：JDK 版本不同导致证书库类型不匹配

解决方案：根据 JDK 版本调整 -storetype 参数，JDK 8 使用 JKS，JDK 11+ 使用 PKCS12