Jenkins 2.580.1 配置参数详解

目标：系统梳理 Jenkins 2.580.1 的核心配置参数，覆盖 JVM/进程参数、数据目录与服务端口、系统配置（执行器/JNLP/静默期）、系统属性、凭证、全局工具与插件等维度。每个参数给出实测默认值、修改方式与生产调优建议。本文已在 Ubuntu 22.04 真实环境实测通过。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS
• 系统架构：x86_64
• Jenkins 版本：2.580.1（LTS）
• JVM：OpenJDK 21.0.12.1
• 数据目录：/opt/data/jenkins（JENKINS_HOME）
• 服务管理：systemd 单元 jenkins.service，drop-in：/etc/systemd/system/jenkins.service.d/jenkins.conf
• 主配置文件：JENKINS_HOME/config.xml
• 根地址配置：JENKINS_HOME/jenkins.model.JenkinsLocationConfiguration.xml
• 监听端口：HTTP 8080、HTTPS 8443

💡 说明：下表"实测默认值"均来自本机全新初始化的 Jenkins 2.580.1（仅按安装指南做了数据目录/JVM/HTTPS/账号预置）实测采集，默认值与 Jenkins 默认一致，便于读者对照。

二、前置条件

• 已部署 Jenkins 2.580.1（参考《Ubuntu 22.04 安装 Jenkins 2.580.1 指南》）
• 具备数据目录写权限（生成 jenkins 用户或当前账户）
• root 权限用于修改 systemd drop-in（修改进程级/JVM 参数时）

三、参数查看与修改方式

3.1 进程级参数（JVM/监听）：systemd drop-in

以 2.580.1 为例，进程级参数通过 systemd drop-in /etc/systemd/system/jenkins.service.d/jenkins.conf 的 Environment= 注入，由 /usr/bin/jenkins 启动脚本读取后传给 Java。

sudo systemctl cat jenkins | grep -E "JAVA_OPTS|JENKINS_HOME|JENKINS_PORT"

修改后：

sudo systemctl daemon-reload
sudo systemctl restart jenkins

3.2 实例级配置（config.xml）：Web 或直接改文件

实例级参数（执行器数、静默期、JNLP 端口、安全检查开关）集中存于 JENKINS_HOME/config.xml。可在 Web 管理界面（系统管理 → 系统配置）修改，或直接编辑该文件后重启服务。编辑前建议备份：

cp /opt/data/jenkins/config.xml /opt/data/jenkins/config.xml.bak

3.3 根地址：JenkinsLocationConfiguration.xml

cat /opt/data/jenkins/jenkins.model.JenkinsLocationConfiguration.xml

实测内容：

<?xml version='1.1' encoding='UTF-8'?>
<jenkins.model.JenkinsLocationConfiguration>
  <jenkinsUrl>http://localhost:8080/</jenkinsUrl>
</jenkins.model.JenkinsLocationConfiguration>

⚠️ 注意：jenkinsUrl 未配置或错误会导致 CLI 首次握手报 Jenkins URL is not configured，务必设置正确的访问地址（见安装指南"8.3"）。

3.4 动态系统属性：Groovy

可用系统 Groovy 脚本接口动态查看/修改部分参数（系统管理 → 脚本控制台）：

def j = jenkins.model.Jenkins.get()
println("numExecutors=" + j.getNumExecutors())
println("useSecurity=" + j.isUseSecurity())
j.setNumExecutors(4)   // 修改执行器数并保存
j.save()

四、参数总览

五、核心参数分类详解

5.1 JVM / Java 进程参数

验证（ps -ef | grep java）：

/usr/bin/java -Xms256m -Xmx512m -Djava.awt.headless=true -jar /usr/share/java/jenkins.war --webroot=/var/cache/jenkins/war --httpPort=8080 --httpsPort=8443

💡 调优建议：堆大小按编译任务规模设置，小型 CI 服务 -Xmx512m 即可；即使任务多、并发高，也建议将堆上限控制在 256–512MB 区间（最多不超过 1GB），将更多内存留给构建子进程并行使用，并配合 -Xmn 与 jps -v/监控确认实际占用，避免盲目把堆加大到 g 级导致宿主机 OOM。

5.2 数据目录与服务端口参数

⚠️ 注意：修改这些参数需同时保证目标目录属主为 jenkins，否则服务可能因权限不足启动失败。

5.3 实例级系统配置（config.xml）

JENKINS_HOME/config.xml 中的实例级关键参数（实测采集）：

💡 说明：quietPeriod（默认 5）为提交后延迟执行秒数，用于合并改动；扁平滑的集群可适当调低。这些都是实例级参数，直接在 Web「系统配置」页改即可。

5.4 系统属性（Java -D 开关）

除堆外，部分行为由 Java 系统属性控制，写在 JAVA_OPTS 里，例如：

| 系统属性 | -Djenkins.install.runSetupWizard=false | 跳过首次设置向导（自动化部署常用） | | 系统属性 | -Dhudson.model.DirectoryBrowserSupport.CSP | 定制目录浏览 CSP（为 JAVA_OPTS 追加取值即可） | | 插件属性 | 各插件自带前缀（如 hudson.plugins.*） | 由插件文档定义，通过 JAVA_OPTS 注入 -D 开关 |

⚠️ 注意：系统属性与进程级参数一样，需 systemctl restart jenkins 才生效。

5.5 凭证（Credentials）相关

凭证存放于数据目录（/opt/data/jenkins/credentials.xml 及凭证库插件目录），按"全局/系统级"范围隔离，支持用户名密码、SSH 私钥、Secret text、证书等类型。凭证属敏感信息，建议：

• 通过 Web「系统管理 → 凭证」管理，避免明文落配置；
• 使用"凭证绑定（Credentials Binding）"把密钥注入流水线，而不写死在脚本；
• 服务级身份用专用的服务账号/令牌，最小权限原则，定期轮换。

5.6 全局工具（JDK / Maven / Git）

「系统管理 → 全局工具配置」维护各工具链（JDK、Maven、Git 等），可"自动安装"或"指定本机路径"。这些配置落在 JENKINS_HOME/hudson.model.*.xml 等工具配置文件中。例如指定本机 JDK 路径：

ls /opt/data/jenkins/hudson.tools.JDKInstaller.xml 2>/dev/null

💡 说明：流水线中通过 tools { jdk 'DemoJDK' } 引用已配置的工具。同一工具可按不同版本多实例配置，由任务显式选用。

5.7 插件相关

插件安装于 JENKINS_HOME/plugins/（.jpi/.hpi）。使用命令行安装：

cd /opt/data/jenkins
java -jar jenkins-cli.jar -s http://localhost:8080/ -auth admin:q1w2e3r4 install-plugin git --restart
java -jar jenkins-cli.jar -s http://localhost:8080/ -auth admin:q1w2e3r4 list-plugins

💡 说明：本部署为全新安装、默认未装任何插件，list-plugins 输出为空属正常。常用插件（Git、Pipeline、Credentials、Blue Ocean 等）可按需安装。

六、生产配置模板（按内存 / 磁盘 / 场景）

6.1 小内存 CI（2GB 内存 / HDD / 低频构建）

[Service]
Environment="JAVA_OPTS=-Xms256m -Xmx512m -Djava.awt.headless=true"

同时将执行器降为 1（<numExecutors>1</numExecutors>），避免并发堆积导致 OOM。

6.2 中配 CI（8GB 内存 / SSD / 常规多项目）

[Service]
Environment="JAVA_OPTS=-Xms256m -Xmx512m -XX:+UseG1GC -Djava.awt.headless=true"

执行器 4、scmCheckoutRetryCount=2；数据目录放 SSD，日志限长。建议堆上限控制在 512MB 内，将更多内存留给构建进程并行使用。

6.3 高并发流水线（16GB+ 内存 / NVMe SSD / 大规模构建）

[Service]
Environment="JAVA_OPTS=-Xms512m -Xmx512m -XX:+UseG1GC -Djava.awt.headless=true"

执行器按核数设置；numExecutors 与物理核数匹配；凭证用专用服务账号；开启 HTTPS；构建产物与工作区对接到独立存储。堆内存仍建议限制在 512MB 以内（最多不超过 1GB），Jenkins 本体所需堆并不随构建并发线性增长，其余内存由构建子进程与 JVM 外部工具使用，避免 -Xmx4g 式大堆造成 OOM 与内存浪费。

⚠️ 安全与运维：生产务必开 HTTPS；凭证最小权限、定期轮换；对 JENKINS_HOME 定期备份；上线调参遵循"一次一项 + 压测 + 记录回滚"。

七、常见问题

7.1 问题 1：修改 config.xml 后不生效/服务异常

原因： config.xml 语法错误或未重启服务。

解决： 用备份还原后再重启，或先在 Web 界面修改：

cp /opt/data/jenkins/config.xml.bak /opt/data/jenkins/config.xml
sudo systemctl restart jenkins

7.2 问题 2：CLI 报 Jenkins URL is not configured

原因： 根地址未设置。修改 jenkins.model.JenkinsLocationConfiguration.xml 的 jenkinsUrl 或经「系统配置」设置后重启。

7.3 问题 3：改 Java 堆后 ps -ef 看不到新值

原因： systemd drop-in 被主单元覆盖，或未 daemon-reload / restart。

解决： 确认参数写在 drop-in 目录（非主单元），并执行 systemctl daemon-reload && systemctl restart jenkins。

7.4 问题 4：JNLP 代理连不上内置节点

原因： slaveAgentPort=-1（禁用 JNLP）。如需外部代理接入，改为固定端口（如 50000）并放行防火墙。

7.5 问题 5：凭证优先级混乱/被覆盖

原因： 凭证按范围（系统级/全局）隔离，同名凭证在不同范围会相互覆盖。建议为不同环境拆分独立凭证库，并在流水线中显式指定 credentialsId。

八、参考链接

• Jenkins 系统属性参考
• Jenkins 系统配置（config.xml）说明
• Jenkins 凭证管理
• Jenkins 初始化 Groovy 脚本（init.groovy.d）

本文档由 www.quzuo.net 平台开发