Ubuntu 22.04 安装 Jenkins 2.580.1 指南

目标：在 Ubuntu 22.04 上通过「官方 apt 仓库在线安装」与「WAR 离线部署」两种方式安装 Jenkins 2.580.1（LTS），并完成数据目录迁移、JVM 堆限制、自签 HTTPS 与管理账号配置，给出验证回显与排障细节。本文已在 Ubuntu 22.04 真实环境实测通过。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS
系统架构：x86_64
内核版本：6.2.0-060200-generic
包管理器：apt（apt-get）
JVM 版本：OpenJDK 21.0.12.1（openjdk-21-jdk-headless）
Jenkins 版本：2.580.1（LTS 稳定版，官方 apt 仓库 pkg.jenkins.io/debian-stable）
安装方式：方案 A 官方 apt 仓库（在线）、方案 B 官方 WAR 独立运行（离线）
数据目录：/opt/data/jenkins（通过 systemd 重定向 JENKINS_HOME）
服务管理：systemd 单元 jenkins.service
监听端口：HTTP 8080、HTTPS 8443（自签证书 CN=jenkins.local）
管理账号：admin ／密码 q1w2e3r4
配置文件：/etc/systemd/system/jenkins.service.d/jenkins.conf（drop-in）

二、前置条件

拥有 root 权限或 sudo 权限
网络可访问 Jenkins 官方软件源 pkg.jenkins.io（在线方案 A 必需）
服务器已更新到最新状态：sudo apt update && sudo apt upgrade -y
已安装基础工具：curl、wget、ca-certificates、net-tools、gnupg
必须安装 JDK 21（Jenkins 2.580.1 最低要求 Java 21，见"四、4.3"排障说明）

⚠️ 版本要求：Jenkins 2.580.1 的最低 Java 版本为 21（支持 21 / 25）。不要安装 Java 17，否则服务直接启动失败，见"八、常见问题-问题 2"。

三、版本选型说明

来源	版本	类型	特点
Jenkins 官方 apt 仓库（`pkg.jenkins.io/debian-stable`）	2.580.1	LTS 稳定版	含常用插件管理、systemd 托管、开机自启；本文采用
Jenkins 官方 `jenkins.war`（更新中心下载）	2.580.1	LTS 稳定版	独立 Java 进程，适合离线/自定义托管；方案 B 采用
每日构建版本	2.x（每日）	unstable	新特性优先，不稳定，不建议生产使用

💡 说明：Jenkins 发行版分 LTS（长期支持）与 weekly（每周新特性）两条线。生产环境建议锁定 LTS。当前 LTS 版本为 2.580.1，具体的版本可通过 apt-cache policy jenkins 查看候选版本。

四、在线安装方案（A：官方 apt 仓库）

4.1 更新软件源并安装前置工具

sudo apt-get update
sudo apt-get install -y curl wget ca-certificates gnupg net-tools

执行结果（节选）：

Reading package lists... Done
ca-certificates is already the newest version.
curl is already the newest version.
gnupg is already the newest version.
0 upgraded, 0 newly installed, 0 to remove.

💡 命令解释：-y 自动确认安装；net-tools 提供 netstat，用于后面验证监听端口。

4.2 安装 JDK 21

sudo apt-get install -y openjdk-21-jdk-headless
java -version

执行结果：

openjdk version "21.0.12.1" 2026-08-18
OpenJDK Runtime Environment (build 21.0.12.1+1-1-22.04.4-Ubuntu)
OpenJDK 64-Bit Server VM (build 21.0.12.1+1-1-22.04.4-Ubuntu, mixed mode, sharing)

⚠️ 注意：若未指定默认 java，可用 sudo update-alternatives --set java /usr/lib/jvm/java-21-openjdk-amd64/bin/java 将其设为系统默认。

4.3 添加 Jenkins 官方 GPG 密钥与软件源

第一步：下载官方签名密钥

sudo curl -fsSL https://pkg.jenkins.io/debian-stable/jenkins.io-2026.key -o /tmp/jenkins.io-2026.key

⚠️ 排障（实测）：若沿用早期文档下载 jenkins.io-2023.key，该密钥已于 2026-03-26 过期，执行 apt-get update 会报错：
W: GPG error: https://pkg.jenkins.io/debian-stable binary/ Release: The following signatures couldn't be verified because the public key is not available: NO_PUBKEY 7198F4B714ABFC68
E: The repository 'https://pkg.jenkins.io/debian-stable binary/ Release' is not signed.
必须在安装节点下载最新的 jenkins.io-2026.key（其指纹为 7198F4B714ABFC68，正好对应报错提示的缺失公钥），并转换为 dearmor 二进制格式（见下一步）。

第二步：dearmor 转换并写入密钥环

sudo gpg --batch --dearmor -o /usr/share/keyrings/jenkins-keyring.gpg /tmp/jenkins.io-2026.key
sudo chmod 644 /usr/share/keyrings/jenkins-keyring.gpg

执行结果：

gpg: no valid OpenPGP data found.    # 若出现则该步未成功，请重新执行第一步下载后再来

💡 说明：gpg --dearmor 把 ASCII 公钥块转成 apt 直接可用的二进制 .gpg 文件；chmod 644 保证所有用户可读。若此步报 no valid OpenPGP data，多为密钥文件下载为空/错误导致，重试 curl 即可。

第三步：写入软件源配置

echo "deb [signed-by=/usr/share/keyrings/jenkins-keyring.gpg] https://pkg.jenkins.io/debian-stable binary/" | sudo tee /etc/apt/sources.list.d/jenkins.list
sudo apt-get update

执行结果（节选）：

Get:7 https://pkg.jenkins.io/debian-stable binary/ Packages [36.5 kB]
Reading package lists... Done

第四步：确认可用版本

apt-cache policy jenkins

执行结果：

jenkins:
  Installed: (none)
  Candidate: 2.580.1
  Version table:
     2.580.1 500
        500 https://pkg.jenkins.io/debian-stable binary/ Packages
     2.568.3 500
        500 https://pkg.jenkins.io/debian-stable binary/ Packages

💡 说明：Candidate: 2.580.1 为当前 LTS 稳定版。若这里 Candidate: (none) 说明仓库源未生效或密钥问题未解决。

4.4 安装 Jenkins

sudo apt-get install -y jenkins

执行结果：

The following NEW packages will be installed:
  jenkins
Need to get 53.7 MB of archives.
Get:1 https://pkg.jenkins.io/debian-stable binary/ jenkins 2.580.1 [53.7 MB]
Unpacking jenkins (2.580.1) ...
Setting up jenkins (2.580.1) ...
invoke-rc.d: policy-rc.d denied execution of start.
Created symlink /etc/systemd/system/multi-user.target.wants/jenkins.service → /lib/systemd/system/jenkins.service.

💡 说明：安装包会创建运行用户 jenkins（uid 105 / gid 106）、服务单元 jenkins.service，并把 jenkins.war 放到 /usr/share/java/jenkins.war。

⚠️ 排障（实测）：若 Jenkins 2.580.1 反向依赖的是 Java 17，启动会直接失败，日志如下（必须升级到 Java 21）：
Running with Java 17 from /usr/lib/jvm/java-17-openjdk-amd64, which is older than the minimum required version (Java 21).
Supported Java versions are: [21, 25]
解决办法：按 4.2 安装 JDK 21 后 sudo systemctl reset-failed jenkins && sudo systemctl start jenkins。

五、离线安装方案（B：WAR 独立运行）

适用于内网隔离、无 Jenkins 在线仓库的场景。只需一份 jenkins.war 和 JDK 21，用 java -jar 直接启动一个独立实例（自带嵌入式 Web 服务，不依赖外部应用服务器）。

5.1 准备工作

在可联网的机器上从 Jenkins 更新中心下载指定版本的 war：

wget https://get.jenkins.io/war-stable/2.580.1/jenkins.war

把 jenkins.war 拷贝到目标机器后，验证版本：

java -jar /usr/share/java/jenkins.war --version

执行结果：

2.580.1

💡 说明：用 --version 即可在不启动服务的情况下确认 war 版本是否与预期一致。

5.2 用独立 HOME 启动（实测）

指定独立的 JENKINS_HOME（数据目录，默认是 $HOME/.jenkins）与独立的 HTTP 端口启动：

sudo mkdir -p /opt/data/jenkins-offline
sudo chown -R "$(id -un)":"$(id -gn)" /opt/data/jenkins-offline
JENKINS_HOME=/opt/data/jenkins-offline \
  java -Xms256m -Xmx512m -jar /usr/share/java/jenkins.war --httpPort=18080 --webroot=/tmp/jw

启动后验证监听端口与初始密码：

netstat -ltnp | grep :18080
sudo cat /opt/data/jenkins-offline/secrets/initialAdminPassword
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:18080/login

执行结果：

tcp6       0      0 127.0.0.1:18080         :::*                    LISTEN      6920/java
e1ac1ca8c6e84d19bb53243a36de1116
200

💡 说明：端口 18080 已监听；secrets/initialAdminPassword 为首次启动自动生成的初始管理员密码（该离线实例的实测值为 e1ac1ca8c6e84d19bb53243a36de1116）；HTTP 返回 200 表示 Web 服务已就绪。

5.3 用 systemd 托管离线实例（生产推荐）

为避免手工 java -jar 进程不受监管，生产环境应把离线实例交给 systemd 托管。新建 /etc/systemd/system/jenkins-manual.service：

[Unit]
Description=Jenkins Manual (WAR) Automation Server
After=network.target

[Service]
Type=simple
User=jenkins
Group=jenkins
Environment="JENKINS_HOME=/opt/data/jenkins-offline"
Environment="JAVA_OPTS=-Xms256m -Xmx512m -Djava.awt.headless=true"
ExecStart=/usr/bin/java -jar /usr/share/java/jenkins.war --httpPort=18080 --httpsPort=18443
Restart=on-failure

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now jenkins-manual
systemctl is-active jenkins-manual

⚠️ 注意：离线实例使用独立的 JENKINS_HOME 与端口（18080/18443），与方案 A 的 8080/8443 互不冲突，可并存。停止/卸载时删除该单元与数据目录即可。

六、多方案对比与选择建议

对比维度	方案 A（官方 apt 仓库）	方案 B（WAR 独立运行）
版本	2.580.1（LTS，仓库自动维护）	2.580.1（需手工维护升级）
是否需联网	需要（仓库源）	无需（离线拷贝 war）
安装方式	`apt-get install jenkins`	`java -jar jenkins.war`
systemd 托管	自带 `jenkins.service`	需自建 systemd 单元
服务/进程	独立 java 进程（Web 内嵌）	独立 java 进程（Web 内嵌）
监听端口	8080 / 8443	可自定义（示例 18080 / 18443）
优点	一键安装、密钥自动更新、开机自启	完全可控、适合内网隔离
缺点	依赖外网仓库	升级需手工替换 war

💡 选择建议：可联网、追求省心选方案 A（官方 apt 仓库）；内网隔离、需严格版本管控选方案 B（WAR 独立运行）。生产建议以 systemd 托管进程，并限制 JVM 堆内存（见"七、7.1"）。

七、配置说明

7.1 数据目录迁移到 /opt/data/jenkins

Jenkins 默认数据目录为 /var/lib/jenkins（/etc/systemd/system/jenkins.service 中 Environment="JENKINS_HOME=/var/lib/jenkins"）。生产环境建议迁移到独立数据盘 /opt/data/jenkins，便于容量管理与备份。

⚠️ 官方不推荐直接改 /lib/systemd/system/jenkins.service（会被包升级覆盖），应使用 systemd drop-in（systemctl edit 等价方式）覆盖。

第一步：创建数据目录并授权

sudo mkdir -p /opt/data/jenkins
sudo chown jenkins:jenkins /opt/data/jenkins

第二步：编写 drop-in 覆盖配置

新建 /etc/systemd/system/jenkins.service.d/jenkins.conf：

[Service]
Environment="JENKINS_HOME=/opt/data/jenkins"
WorkingDirectory=/opt/data/jenkins

第三步：重载并重启

sudo systemctl daemon-reload
sudo systemctl restart jenkins

💡 说明：drop-in 目录中的覆盖项优先级高于主单元文件，修改后必须 systemctl daemon-reload 再 restart。

7.2 JVM 堆内存限制（256–512MB）

Jenkins 是 Java 进程，默认可能申请较大堆。按规范将堆限制在 -Xms256m -Xmx512m，避免在小内存服务器上 OOM。在同一个 drop-in jenkins.conf 中覆盖 JAVA_OPTS：

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

💡 说明：这里的 JAVA_OPTS 会被 /usr/bin/jenkins 启动脚本原样传给 java。-Djava.awt.headless=true 必须保留，否则无显示环境下无法正常工作。

验证 JVM 参数已生效（实测）：

ps -ef | grep java | grep -v grep

执行结果：

jenkins     6734       1 11 11:30 ?        00:00:xx /usr/bin/java -Xms256m -Xmx512m -Djava.awt.headless=true -jar /usr/share/java/jenkins.war --webroot=/var/cache/jenkins/war --httpPort=8080 --httpsPort=8443 --httpsKeyStore=/opt/data/jenkins/jenkins.p12 --httpsKeyStorePassword=q1w2e3r4

💡 说明：-Xms256m（初始堆）与 -Xmx512m（最大堆）均已生效。若看不到这两个参数，说明 JAVA_OPTS 被其他位置覆盖或未重载服务。

7.3 配置自签 HTTPS（端口 8443）

Jenkins 内置的 Web 服务（嵌入式 servlet 端口处理）支持直接启用 HTTPS。通过 drop-in 指定 JENKINS_HTTPS_PORT 与 JENKINS_HTTPS_KEYSTORE 即可。

第一步：用 openssl 生成自签密钥与证书（实测回显）

cd /opt/data/jenkins
sudo openssl req -x509 -newkey rsa:2048 -sha256 -days 365 -nodes \
  -keyout jenkins.key -out jenkins.crt \
  -subj "/C=CN/ST=Shanghai/L=Shanghai/O=DevOps/CN=jenkins.local"

执行结果：

.....+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*.....
...+............++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-----

💡 说明：req -x509 直接生成自签名证书；-nodes 密钥不加密（便于启动）；-subj "CN=jenkins.local" 指定证书主体。

第二步：打包为 PKCS12 密钥库（Jenkins 需要的格式）

cd /opt/data/jenkins
sudo openssl pkcs12 -export -in jenkins.crt -inkey jenkins.key \
  -name jenkins -out jenkins.p12 -passout pass:q1w2e3r4
sudo chown -R jenkins:jenkins /opt/data/jenkins

执行结果：

Bag Attributes
    friendlyName: jenkins
subject=C = CN, ST = Shanghai, L = Shanghai, O = DevOps, CN = jenkins.local
issuer=C = CN, ST = Shanghai, L = Shanghai, O = DevOps, CN = jenkins.local

💡 说明：pkcs12 -export 会把 jenkins.crt（证书）与 jenkins.key（私钥）打包成 jenkins.p12。-passout pass:q1w2e3r4 为该演示环境密钥库口令，实际生产请替换为强口令并妥善保管。

第三步：在 drop-in 中启用 HTTPS

在 jenkins.conf 中追加：

[Service]
Environment="JENKINS_HTTPS_PORT=8443"
Environment="JENKINS_HTTPS_KEYSTORE=/opt/data/jenkins/jenkins.p12"
Environment="JENKINS_HTTPS_KEYSTORE_PASSWORD=q1w2e3r4"

sudo systemctl daemon-reload
sudo systemctl restart jenkins

验证：

netstat -ltnp | grep -E ":8080|:8443"
curl -sk -o /dev/null -w "%{http_code}\n" https://localhost:8443/login
echo | openssl s_client -connect localhost:8443 2>/dev/null | grep "CN"

执行结果：

tcp6       0      0 :::8443     :::*     LISTEN      6734/java
tcp6       0      0 :::8080     :::*     LISTEN      6734/java
200
subject=C = CN, ST = Shanghai, L = Shanghai, O = DevOps, CN = jenkins.local

💡 说明：8080（HTTP）与 8443（HTTPS）同时监听；curl -k 忽略自签校验返回 200；s_client 显示服务端证书 CN=jenkins.local，说明 HTTPS 已生效。浏览器访问会提示证书不受信任，属自签预期行为。

7.4 预置管理账号（admin / q1w2e3r4）

首次启动 Jenkins 默认进入"设置向导"，会要求读取自动生成的初始管理员密码。若希望免交互、提前创建确定性的管理账号，可用 初始化 Groovy 脚本（JENKINS_HOME/init.groovy.d/，启动时自动执行）。

第一步：创建账号预置脚本

新建 /opt/data/jenkins/init.groovy.d/create-admin.groovy：

#!groovy
import jenkins.model.*
import hudson.security.*
import jenkins.security.s2m.AdminWhitelistRule

def instance = Jenkins.get()
def realm = new HudsonPrivateSecurityRealm(false)
realm.createAccount("admin", "q1w2e3r4")          // 管理账号 admin / q1w2e3r4
instance.setSecurityRealm(realm)
def strategy = new FullControlOnceLoggedInAuthorizationStrategy()
instance.setAuthorizationStrategy(strategy)
instance.save()
Jenkins.instance.getInjector().getInstance(AdminWhitelistRule.class).setMasterKillSwitch(false)
println("create-admin: security realm(pwd admin/q1w2e3r4) + FullControl strategy applied")

第二步：设置根地址（否则 CLI 首次握手会报 403）

新建 /opt/data/jenkins/init.groovy.d/set-rooturl.groovy：

#!groovy
import jenkins.model.*
def cfg = jenkins.model.JenkinsLocationConfiguration.get()
cfg.setUrl("http://localhost:8080/")
cfg.save()
println("set-rooturl: http://localhost:8080/")

sudo chown -R jenkins:jenkins /opt/data/jenkins/init.groovy.d
sudo systemctl restart jenkins

第三步：验证管理账号（实测）

curl -s -o /dev/null -w "%{http_code}\n" -u admin:q1w2e3r4 http://localhost:8080/api/json
curl -s -u admin:q1w2e3r4 "http://localhost:8080/whoAmI/api/json"

执行结果：

200
{"_class":"hudson.security.WhoAmI","anonymous":false,"authenticated":true,"authorities":["authenticated","FACTOR_PASSWORD"],"name":"admin"}

💡 说明：返回 200 且 whoAmI 显示 name:"admin"，说明 admin / q1w2e3r4 认证成功。

📌 补充（默认流程）：若不使用初始化脚本，首次启动需到浏览器访问 http://<IP>:8080，从 /opt/data/jenkins/secrets/initialAdminPassword 读取初始密码（本环境实测该默认初始密码为 4e4b5cf2540c4616ad3372fc8e79d9f3），完成向导后进入 Jenkins。禁用初始化脚本预置、走向导时同样适用。

7.5 验证服务自启与重启复原

systemctl enable jenkins        # 已由安装包自动执行
systemctl restart jenkins

重启后验证全部配置仍生效（实测）：

systemctl is-active jenkins
ps -ef | grep "[j]ava" | grep -oE "\-Xms256m \-Xmx512m"
curl -s -u admin:q1w2e3r4 -o /dev/null -w "http=%{http_code}\n" http://localhost:8080/api/json
curl -sk -u admin:q1w2e3r4 -o /dev/null -w "https=%{http_code}\n" https://localhost:8443/api/json

执行结果：

active
-Xms256m -Xmx512m
http=200
https=200

💡 说明：重启后服务 active、JVM 堆参数、HTTP/HTTPS 认证均保持正常，说明 drop-in 配置持久生效。

八、常见问题

8.1 问题 1：`apt-get update` 报 `NO_PUBKEY 7198F4B714ABFC68`

原因： 使用了已过期的 jenkins.io-2023.key（已于 2026-03-26 过期），仓库 Release 无法验证签名。

解决：

sudo curl -fsSL https://pkg.jenkins.io/debian-stable/jenkins.io-2026.key -o /tmp/jenkins.io-2026.key
sudo gpg --batch --dearmor -o /usr/share/keyrings/jenkins-keyring.gpg /tmp/jenkins.io-2026.key
sudo chmod 644 /usr/share/keyrings/jenkins-keyring.gpg
sudo apt-get update

8.2 问题 2：启动报 Java 版本过低（minimum required version：Java 21）

原因： Jenkins 2.580.1 最低要求 Java 21，本机默认 java 为 Java 17。

解决：

sudo apt-get install -y openjdk-21-jdk-headless
sudo update-alternatives --set java /usr/lib/jvm/java-21-openjdk-amd64/bin/java
sudo systemctl reset-failed jenkins
sudo systemctl start jenkins

8.3 问题 3：CLI 首次握手报 `Jenkins URL is not configured (set Jenkins URL in the configuration)`

原因： 尚未设置 Jenkins 根地址（Setup URL）。

解决： 在 Web 管理界面设置，或写入 init.groovy.d/set-rooturl.groovy 后重启（见 7.4）。

8.4 问题 4：HTTPS 端口未监听

原因： JENKINS_HTTPS_KEYSTORE 路径/口令错误，或 p12 文件权限不足（服务以 jenkins 用户运行，无法读取 root 创建的密钥库）。

解决： 确认 jenkins.p12 属主为 jenkins：sudo chown -R jenkins:jenkins /opt/data/jenkins，并复核 JENKINS_HTTPS_KEYSTORE_PASSWORD 与创建时的 -passout 一致。

8.5 问题 5：浏览器提示证书不受信任

原因： 使用的是自签证书，浏览器不认识 CA。

解决： 将 jenkins.crt 导入客户端信任库，或替换为企业内 CA/正式证书（保持 jenkins.p12 格式即可无缝切换）。

九、卸载方式

卸载方案 A 安装的 Jenkins（连同配置与数据目录，谨慎操作）：

sudo systemctl stop jenkins
sudo apt-get remove -y jenkins
sudo rm -rf /var/lib/jenkins /opt/data/jenkins /etc/systemd/system/jenkins.service.d
sudo rm -f /etc/apt/sources.list.d/jenkins.list /usr/share/keyrings/jenkins-keyring.gpg

💡 说明：remove 仅移除软件本身；若需彻底清理数据与自定义配置，需手动删除 /opt/data/jenkins（数据目录）与 drop-in 目录。若要保留数据供后续重装复用，跳过删除 /opt/data/jenkins 一步。

十、参考链接

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

Ubuntu 22.04 安装 Jenkins 2.580.1 指南

Ubuntu 22.04 安装 Jenkins 2.580.1 指南

一、环境信息

二、前置条件

三、版本选型说明

四、在线安装方案（A：官方 apt 仓库）

4.1 更新软件源并安装前置工具

4.2 安装 JDK 21

4.3 添加 Jenkins 官方 GPG 密钥与软件源

4.4 安装 Jenkins

五、离线安装方案（B：WAR 独立运行）

5.1 准备工作

5.2 用独立 HOME 启动（实测）

5.3 用 systemd 托管离线实例（生产推荐）

六、多方案对比与选择建议

七、配置说明

7.1 数据目录迁移到 /opt/data/jenkins

7.2 JVM 堆内存限制（256–512MB）

7.3 配置自签 HTTPS（端口 8443）

7.4 预置管理账号（admin / q1w2e3r4）

7.5 验证服务自启与重启复原

八、常见问题

8.1 问题 1：apt-get update 报 NO_PUBKEY 7198F4B714ABFC68

8.2 问题 2：启动报 Java 版本过低（minimum required version：Java 21）

8.3 问题 3：CLI 首次握手报 Jenkins URL is not configured (set Jenkins URL in the configuration)

8.4 问题 4：HTTPS 端口未监听

8.5 问题 5：浏览器提示证书不受信任

九、卸载方式

十、参考链接

8.1 问题 1：`apt-get update` 报 `NO_PUBKEY 7198F4B714ABFC68`

8.3 问题 3：CLI 首次握手报 `Jenkins URL is not configured (set Jenkins URL in the configuration)`