1. 项目概述：为什么在 Ubuntu 20.04 上装 Jenkins 不是“点下一步”那么简单

Jenkins 是持续集成与持续交付（CI/CD）领域里绕不开的基石型工具，尤其在中小型技术团队和 DevOps 实践初期，它几乎是默认起点。但当你真正动手在 Ubuntu 20.04 上安装 Jenkins 时，很快就会发现——官方文档写的“三步搞定”，实际操作中可能卡在第 0.5 步：Java 版本不兼容、apt 源超时、防火墙拦截、端口被占用、systemd 服务启动失败、甚至安装完打不开网页……这些不是玄学，而是 Ubuntu 20.04 这个 LTS 版本与 Jenkins 生态之间真实存在的“代际摩擦”。我过去三年在 17 个不同客户环境里部署 Jenkins，其中 12 个用的是 Ubuntu 20.04，踩过的坑足够填满一个小型知识库。这不是因为 Jenkins 太难，而是因为 Ubuntu 20.04 的默认配置（OpenJDK 11、systemd 245、firewalld 默认关闭但 ufw 常开、/etc/apt/sources.list 镜像源稳定性差异）与 Jenkins 2.3xx+ 主线版本对运行时环境的隐性要求存在错位。比如，Jenkins 官方明确要求 Java 11 或 17，但 Ubuntu 20.04 自带的 openjdk-11-jdk 在某些云主机上会因缺少 headless 模块导致 UI 渲染异常；再比如，很多人复制粘贴curl -fsSL https://pkg.jenkins.io/debian-stable/jenkins.io.key | sudo apt-key add -就报错，根本原因是 apt-key 已被 Debian/Ubuntu 社区弃用，而这条命令在 2022 年后的新镜像中直接失效。所以，“installer”这个词在这里绝不是指图形化向导，而是指一套包含环境校验、源配置、依赖锁定、服务加固、权限隔离、反向代理前置的完整工程化动作。它适合两类人：一是刚接触 CI/CD 的开发者，需要一份能从零跑通、不跳坑的实操指南；二是运维或 SRE 同事，需要理解每个步骤背后的系统级影响，以便后续做高可用、审计合规或安全加固。这篇文章不讲抽象概念，只讲我在生产环境反复验证过的每一条命令、每一个参数、每一次失败原因和修复逻辑。

2. 整体设计思路与方案选型解析：为什么不用 Docker？为什么坚持 deb 包？为什么必须手动配 Java？

2.1 为什么放弃 Docker 方案作为默认推荐？

网络热词里高频出现 “docker 安装高版本的 jenkins”、“docker 部署 jenkins”，看起来很现代、很轻量。但在我经手的 12 个 Ubuntu 20.04 环境中，有 9 个最终放弃了纯 Docker 部署，转为原生 deb 包 + systemd 管理。原因很实在：

• 存储卷权限地狱：Jenkins 主目录/var/lib/jenkins默认由jenkins用户拥有，Docker 容器内 UID 1000 与宿主机jenkins用户（UID 114）不一致，导致挂载卷后插件安装失败、job 配置无法写入、甚至 Jenkins 启动时直接 panic 报 “Permission denied on /var/lib/jenkins/plugins”。你得手动chown -R 114:114 /path/to/jenkins_home，而这个 UID 在不同 Ubuntu 20.04 实例中并不固定（取决于创建顺序），查 UID 要getent passwd jenkins，新手根本不会想到这一步。

• 日志与调试割裂：docker logs jenkins只能看到启动日志，而 Jenkins 内部的jenkins.log、access_log、update-center.json下载失败详情全在容器内文件系统里。一旦出问题，你得docker exec -it jenkins bash进去查，再tail -f /var/log/jenkins/jenkins.log，比直接journalctl -u jenkins -f多两层跳转，排查效率下降 40% 以上。

• 系统级集成缺失：Ubuntu 20.04 的systemd是服务管理核心。Jenkins 作为长期运行的守护进程，需要与logrotate（日志轮转）、fail2ban（防暴力爆破）、auditd（操作审计）深度集成。Docker 容器天然隔离了这些系统服务，你得额外写docker-compose.yml配置 volume 映射、log driver、healthcheck，复杂度指数上升。而原生 deb 包安装后，/etc/logrotate.d/jenkins和/etc/fail2ban/jail.d/jenkins.local是开箱即用的。

提示：Docker 方案并非错误，它适合快速 PoC 或多版本并行测试。但如果你的目标是“上线即稳定、运维可审计、故障可回滚”的生产环境，原生 deb 包 + Ubuntu 标准 systemd 流程是更稳妥的选择。本文所有步骤均基于此前提。

2.2 为什么必须手动安装并指定 Java，而不是依赖系统默认？

Ubuntu 20.04 默认安装openjdk-11-jdk，路径为/usr/lib/jvm/java-11-openjdk-amd64。但 Jenkins 2.346+（当前主流 LTS）对 Java 的要求已悄然升级：

• JVM 参数兼容性：Jenkins 主进程启动脚本/usr/bin/jenkins中硬编码了-XX:+UseG1GC -XX:MaxGCPauseMillis=100等 G1 垃圾回收参数。Ubuntu 20.04 自带的 OpenJDK 11.0.11 存在一个已知 bug：当MaxGCPauseMillis设置过低时，JVM 会拒绝启动并报Unrecognized VM option 'MaxGCPauseMillis=100'。这个问题在 Oracle JDK 11u28+ 或 OpenJDK 11.0.16+ 中已修复，但 Ubuntu 20.04 的 apt 源里最高只到 11.0.11。

• Headless 模块缺失风险：Jenkins Web UI 依赖 AWT/Swing 渲染部分图表（如构建历史趋势图）。Ubuntu 20.04 的openjdk-11-jdk-headless包不含java.desktop模块，而openjdk-11-jdk又默认不安装 GUI 相关依赖。结果就是 Jenkins 启动成功，但访问http://localhost:8080时页面空白，后台日志疯狂刷java.awt.HeadlessException。你得手动sudo apt install openjdk-11-jdk并确认java -version输出含OpenJDK Runtime Environment (build 11.0.16+8-Ubuntu-120.04)。

因此，我的标准操作是：彻底卸载系统默认 Java，从 Adoptium（现 Eclipse Temurin）下载预编译的 JDK 11.0.22+8-LTS。这个版本经过 Jenkins 官方 CI 流水线验证，且.deb包自带alternatives配置，能无缝接管系统 Java。

2.3 为什么选择官方 Jenkins Debian 源，而非 snap 或第三方 PPA？

网络热词中出现 “ubuntu 20.04 安装mysql8.025”、“advanced installer 教程”，说明用户对“一键安装”有强烈期待。但 Jenkins 的 snap 包（sudo snap install jenkins) 在 Ubuntu 20.04 上存在两个致命缺陷：

• 经典 confinement 权限限制：snap 默认运行在严格沙箱中，无法直接读写/var/lib/jenkins（它被重定向到/var/snap/jenkins/common/），导致所有插件安装、job 配置、凭证存储全部失效。要解除限制，得sudo snap connect jenkins:home、sudo snap connect jenkins:network-manager等一长串命令，且每次 Jenkins 更新都可能重置这些连接。

• 更新策略不可控：snap 的--channel=stable实际指向的是 Jenkins 的 weekly build，而非 LTS 版本。你今天装的是 2.361.1，明天snap refresh就可能变成 2.370.0，而后者可能引入破坏性变更（如 Pipeline API 调整），导致现有 job 全部失败。

至于第三方 PPA（如ppa:webupd8team/java），早在 2019 年就已废弃，且其签名密钥早已过期。尝试apt update会报NO_PUBKEY错误，修复需手动导入旧密钥，安全风险极高。

所以，唯一可靠路径是：使用 Jenkins 官方维护的https://pkg.jenkins.io/debian-stable/源，并通过apt的apt-transport-https和ca-certificates机制确保传输安全与证书校验。这个源的包由 Jenkins 基金会直接构建，版本发布节奏与 LTS 严格同步，且.deb包内嵌完整的postinst脚本，自动处理用户创建、目录初始化、systemd 单元注册等所有脏活。

3. 核心细节解析与实操要点：从环境校验到服务启动的每一步深意

3.1 环境预检：5 条命令定生死

在敲下任何apt install之前，必须执行这组检查。它们耗时不到 10 秒，却能避免 80% 的后续失败。

1. 确认系统架构与内核版本

   uname -m && cat /etc/os-release | grep -E "(VERSION_ID|PRETTY_NAME)"

   输出应为x86_64和VERSION_ID="20.04"。若为aarch64（ARM64），则 Jenkins 官方源不提供 ARM 构建包，必须改用 Docker 或手动编译 WAR。这是硬性前提，无例外。

2. 检查 swap 分区是否启用

   swapon --show=NAME,TYPE,SIZE,USED,PRIORITY

   Jenkins 是内存密集型应用，官方建议最小 4GB RAM。若物理内存 < 4GB 且 swap 关闭，Jenkins 启动时会因 OOM Killer 终止进程。Ubuntu 20.04 默认禁用 swap，需手动创建：

   sudo fallocate -l 4G /swapfile && sudo chmod 600 /swapfile && sudo mkswap /swapfile && sudo swapon /swapfile echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

3. 验证 DNS 解析与基础连通性

   ping -c 3 mirrors.tuna.tsinghua.edu.cn && curl -I https://pkg.jenkins.io

   网络热词中出现jenkins failed to resolve host name mirrors.tuna.tsinghua.edu.cn，说明 DNS 配置是常见故障点。若ping失败，先检查/etc/resolv.conf是否含有效 nameserver（如114.114.114.114或8.8.8.8）；若curl -I返回Connection refused，则可能是公司防火墙拦截了https://pkg.jenkins.io（端口 443），此时需联系网络管理员放行，或临时改用 HTTP 源（不推荐，安全性降级）。

4. 确认 8080 端口未被占用

   sudo ss -tuln | grep ':8080'

   若输出非空，说明已有进程监听 8080。常见冲突进程：nginx（反向代理）、tomcat（Java 应用）、k3s（Kubernetes 控制平面）。解决方案：要么sudo kill -9 <PID>强制终止，要么修改 Jenkins 端口（见 3.4 节）。

5. 检查 /var/lib/jenkins 目录权限

   ls -ld /var/lib/jenkins && ls -l /var/lib/jenkins | head -5

   正常应为drwxr-xr-x 3 jenkins jenkins 4096 ...。若目录不存在，apt install会自动创建；若存在但属主不是jenkins用户，则 Jenkins 启动时无法写入config.xml，报java.io.IOException: Failed to write to /var/lib/jenkins/config.xml。此时需sudo chown -R jenkins:jenkins /var/lib/jenkins。

注意：以上 5 条命令必须全部通过，才能进入下一步。我曾因忽略第 2 条（swap 检查），在一台 2GB RAM 的阿里云 ECS 上反复重装 Jenkins 7 次，直到dmesg | grep -i "killed process"显示 OOM Killer 日志才恍然大悟。

3.2 Java 环境的精准安装与验证

放弃系统默认 Java 后，我们采用 Eclipse Temurin（原 Adoptium）的二进制包，因其与 Jenkins 兼容性最佳，且提供.deb安装包，能完美融入 Ubuntu 的alternatives机制。

步骤 1：下载并安装 Temurin JDK 11.0.22+8-LTS

# 创建临时目录并下载 mkdir -p ~/temurin && cd ~/temurin wget https://github.com/adoptium/temurin11-binaries/releases/download/jdk-11.0.22%2B8/OpenJDK11U-jdk_x64_linux_hotspot_11.0.22_8.deb # 安装（自动注册 alternatives） sudo apt install ./OpenJDK11U-jdk_x64_linux_hotspot_11.0.22_8.deb # 清理系统默认 Java（防止冲突） sudo apt remove openjdk-11-jdk-headless openjdk-11-jre-headless

步骤 2：验证 Java 版本与模块完整性

# 检查版本与构建号 java -version # 正确输出应为： # openjdk version "11.0.22" 2024-01-16 # OpenJDK Runtime Environment Temurin-11.0.22+8 (build 11.0.22+8) # 检查 java.desktop 模块是否存在（关键！） java --list-modules | grep desktop # 必须输出：java.desktop@11.0.22 # 检查 JVM 参数兼容性 java -XX:+UseG1GC -XX:MaxGCPauseMillis=100 -version # 若无报错，说明 G1 GC 参数被正确识别

步骤 3：设置系统默认 Java

# 列出所有已注册的 Java 版本 sudo update-alternatives --config java # 选择 Temurin 对应的编号（通常为 2 或 3） # 验证 JAVA_HOME（Jenkins 启动脚本依赖此变量） echo "export JAVA_HOME=$(dirname $(dirname $(readlink -f $(which java))))" | sudo tee -a /etc/environment source /etc/environment echo $JAVA_HOME # 应输出 /usr/lib/jvm/temurin-11-jdk-amd64

实操心得：Temurin 的.deb包会自动创建/usr/lib/jvm/temurin-11-jdk-amd64符号链接，比手动解压 tar.gz 更可靠。/etc/environment是系统级环境变量配置文件，比~/.bashrc更适合 Jenkins 这类由 systemd 启动的服务，因为 systemd 不读取用户 shell 配置。

3.3 Jenkins 官方源的可信配置与安装

这是整个流程中最易出错的环节。网络热词中 “the installation cannot continue as the installer file may be damaged” 和 “installer integrity check has failed” 多源于此步。

步骤 1：安装 HTTPS 传输支持与证书库

sudo apt update && sudo apt install -y apt-transport-https ca-certificates curl gnupg lsb-release

apt-transport-https是apt通过 HTTPS 协议拉取包的必要组件；ca-certificates确保能验证pkg.jenkins.io的 SSL 证书有效性。若跳过此步，apt update会报Could not fetch https://pkg.jenkins.io/...。

步骤 2：添加 Jenkins GPG 密钥（新方式，替代已废弃的 apt-key）

# 创建密钥存放目录 sudo mkdir -p /usr/share/keyrings # 下载并保存密钥（使用 curl -fsSL 确保静默且校验 SSL） curl -fsSL https://pkg.jenkins.io/debian-stable/jenkins.io-2023.key | sudo gpg --dearmor -o /usr/share/keyrings/jenkins.io-2023-archive-keyring.gpg

这里的关键是：不再使用apt-key add（已被 Debian 官方标记为 deprecated），而是采用gpg --dearmor将 ASCII-armored 密钥转换为二进制.gpg文件，并存入/usr/share/keyrings/。这是 Ubuntu 20.04+ 的标准做法，apt会自动信任该目录下的密钥。

步骤 3：添加 Jenkins 源到 sources.list.d

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/jenkins.io-2023-archive-keyring.gpg] https://pkg.jenkins.io/debian-stable binary/" | sudo tee /etc/apt/sources.list.d/jenkins.list > /dev/null

注意signed-by=参数，它显式指定了密钥路径，apt会严格校验从此源下载的每个.deb包的 GPG 签名。若密钥路径错误或文件损坏，apt install jenkins会直接报The following signatures couldn't be verified并中止。

步骤 4：更新源并安装 Jenkins

sudo apt update sudo apt install -y jenkins

apt update成功标志是看到Hit:6 https://pkg.jenkins.io/debian-stable binary/ Release行，且无GPG error。若失败，请回头检查步骤 2 的密钥下载是否完整（ls -l /usr/share/keyrings/jenkins.io-2023-archive-keyring.gpg应 > 1KB）。

提示：apt install jenkins会自动执行以下动作：

• 创建jenkins系统用户（UID 114，GID 120）
• 创建/var/lib/jenkins目录并设权drwxr-xr-x jenkins:jenkins
• 注册/lib/systemd/system/jenkins.service单元文件
• 启动jenkins服务（状态为active (running)）
  这些是 deb 包的postinst脚本完成的，无需手动干预。

3.4 Jenkins 主配置文件的精细化调整

安装完成后，Jenkins 默认监听0.0.0.0:8080，但这在生产环境极不安全。我们必须修改其主配置文件/etc/default/jenkins，这是控制 Jenkins JVM 行为的唯一权威入口。

关键参数解析与设置：

实操修改命令：

# 备份原配置 sudo cp /etc/default/jenkins /etc/default/jenkins.bak # 使用 sed 批量替换（安全、可逆） sudo sed -i 's/^HTTP_PORT=.*/HTTP_PORT=8080/' /etc/default/jenkins sudo sed -i 's/^JENKINS_ARGS=.*/JENKINS_ARGS="--httpPort=$HTTP_PORT --prefix=/jenkins --sessionTimeout=7200"/' /etc/default/jenkins sudo sed -i 's/^JAVA_ARGS=.*/JAVA_ARGS="-Djava.awt.headless=true -Xmx2g -Xms1g -XX:+UseG1GC -XX:MaxGCPauseMillis=200"/' /etc/default/jenkins # 验证修改结果 sudo grep -E "^(HTTP_PORT|JENKINS_ARGS|JAVA_ARGS)" /etc/default/jenkins

重启服务并验证：

sudo systemctl daemon-reload sudo systemctl restart jenkins sudo systemctl status jenkins # 应显示 active (running) sudo journalctl -u jenkins -n 50 --no-pager | grep -i "started\|listening" # 正确日志应含：Jenkins is fully up and running，Listening on http://0.0.0.0:8080/jenkins

注意：systemctl daemon-reload是必须的，它让 systemd 重新读取修改后的 service 文件。若跳过，systemctl restart仍会使用旧参数启动。

4. 实操过程与核心环节实现：从首次登录到基础流水线跑通

4.1 首次登录与管理员密码获取

Jenkins 启动后，首次访问http://<your-server-ip>:8080/jenkins会进入解锁界面，要求输入管理员密码。这个密码不是明文存储，而是 Jenkins 初始化时自动生成的哈希值，位于/var/lib/jenkins/secrets/initialAdminPassword。

获取密码的三种方式（按推荐度排序）：

1. 直接读取文件（最常用）

   sudo cat /var/lib/jenkins/secrets/initialAdminPassword # 输出类似：5a3f8b2e1c7d9a4f6b8c0e2d1a9f8b7c

2. 通过 journalctl 实时抓取（若文件被误删）

   sudo journalctl -u jenkins -n 100 --no-pager | grep "Please use the following password" # 输出：Please use the following password to proceed to installation: 5a3f8b2e1c7d9a4f6b8c0e2d1a9f8b7c

3. 重置密码（终极方案，仅当上述均失败）

   # 停止 Jenkins sudo systemctl stop jenkins # 删除 config.xml 中的 admin 用户定义（备份先行！） sudo cp /var/lib/jenkins/config.xml /var/lib/jenkins/config.xml.bak sudo sed -i '/<useSecurity>true<\/useSecurity>/,/<\/securityRealm>/d' /var/lib/jenkins/config.xml # 启动 Jenkins，此时无需密码即可登录 sudo systemctl start jenkins

提示：复制密码时务必小心，末尾可能有不可见空格。建议用xclip工具：sudo cat /var/lib/jenkins/secrets/initialAdminPassword | xclip -selection clipboard，然后直接 Ctrl+V 粘贴。

4.2 插件安装策略：LTS 版本的“最小可行集”

Jenkins 安装向导会推荐安装一堆插件（Git、Pipeline、Blue Ocean 等），但盲目全选会导致首次启动时间长达 15 分钟以上，且部分插件（如 Blue Ocean）与 Ubuntu 20.04 的 GTK 版本存在兼容性问题，页面渲染异常。

我的生产环境标准是：只装 4 个核心插件，其余按需安装。

安装命令（跳过向导，命令行静默安装）：

# 获取 Jenkins CLI JAR（用于命令行操作） sudo wget -O /tmp/jenkins-cli.jar http://localhost:8080/jnlpJars/jenkins-cli.jar # 使用初始密码登录并安装插件（需先创建管理员用户） # 此处假设你已用初始密码登录并创建了 admin 用户 java -jar /tmp/jenkins-cli.jar -s http://localhost:8080/jenkins/ -auth admin:your_password install-plugin git workflow-aggregator credentials matrix-project # 重启 Jenkins 使插件生效 sudo systemctl restart jenkins

实操心得：workflow-aggregator是 Pipeline 插件的聚合包，它自动安装workflow-job、workflow-cps、pipeline-stage-view等 12 个子插件，比单个安装更可靠。matrix-project插件在 Ubuntu 20.04 上需额外依赖libgtk-3-0，若安装失败，执行sudo apt install libgtk-3-0即可。

4.3 创建第一个 Pipeline 项目：从 GitHub 仓库自动构建

以一个简单的 Python Flask 项目为例，演示如何让 Jenkins 自动拉取代码、安装依赖、运行测试。

前提：你的 GitHub 仓库已存在，且包含Jenkinsfile

// Jenkinsfile 示例 pipeline { agent any environment { PYTHONUNBUFFERED = "1" } stages { stage('Checkout') { steps { checkout scm } } stage('Install Dependencies') { steps { sh 'python3 -m pip install --upgrade pip' sh 'python3 -m pip install -r requirements.txt' } } stage('Run Tests') { steps { sh 'python3 -m pytest tests/' } } } }

Jenkins Web 界面操作步骤：

1. 登录 Jenkins → 点击左上角New Item
2. 输入项目名（如my-flask-app）→ 选择Pipeline→ 点击OK
3. 在配置页，向下滚动到Pipeline部分
4. Definition选择Pipeline script from SCM
5. SCM选择Git
6. Repository URL填写你的 GitHub 仓库地址（如https://github.com/yourname/my-flask-app.git）
7. Credentials点击Add→ 选择Jenkins→Kind选Username with password→Username填 GitHub 用户名，Password填 Personal Access Token（非密码！需在 GitHub Settings → Developer settings → Personal access tokens 中生成，勾选repo权限）
8. Script Path保持默认Jenkinsfile
9. 点击Save

触发首次构建：

• 回到项目主页 → 点击左侧Build Now
• 右侧Build History中会出现#1→ 点击它 → 点击Console Output查看实时日志

预期成功日志片段：

[Pipeline] // stage [Pipeline] stage [Pipeline] { (Run Tests) [Pipeline] sh + python3 -m pytest tests/ ============================= test session starts ============================== platform linux -- Python 3.8.10, pytest-6.2.5, py-1.10.0, pluggy-0.13.1 rootdir: /var/lib/jenkins/workspace/my-flask-app collected 3 items tests/test_app.py ... [100%] ============================== 3 passed in 0.02s =============================== [Pipeline] } [Pipeline] // stage [Pipeline] End of Pipeline Finished: SUCCESS

注意：若构建失败，90% 的原因是 Credentials 配置错误（GitHub Token 权限不足或过期）或Jenkinsfile路径错误。此时不要修改 Jenkins 配置，先 SSH 登录服务器，手动执行cd /var/lib/jenkins/workspace/my-flask-app && git pull，看是否能正常拉取代码。

5. 常见问题与排查技巧实录：那些让你抓狂的“小问题”真相

5.1 问题速查表：症状、原因、解决命令三列对照

5.2 独家避坑技巧：来自 12 个生产环境的血泪总结

• 技巧 1：永远不要用 root 用户运行 Jenkins
  网络热词中出现 “jenkins 如何果通过跳板机登录指定服务器”，暗示用户试图用 root 执行 SSH。这是严重安全违规。Jenkins 进程必须以jenkins用户运行。若需提权操作（如sudo systemctl restart nginx），应在目标服务器上配置jenkins用户的NOPASSWD权限：sudo visudo→ 添加jenkins ALL=(ALL) NOPASSWD: /bin/systemctl restart nginx。

• 技巧 2：/var/lib/jenkins目录必须独立挂载
  我在一家电商客户处遇到过惨痛教训：Jenkins 安装在系统盘/，某次构建产生大量临时文件，/分区被占满（100%），导致整个 Ubuntu 20.04 系统无法登录。解决方案：在安装前，用lvcreate创建独立逻辑卷，挂载到/var/lib/jenkins，并设置df -h监控告警。

• 技巧 3：时间同步是 Jenkins 定时任务的隐形杀手
  Ubuntu 20.04 默认启用systemd-timesyncd，但某些云主机（如 AWS EC2）的 NTP 服务不稳定。Jenkins 的Build periodically触发器依赖系统时间。若时间漂移 > 3 分钟，定时任务会完全失效。强制同步：sudo timedatectl set-ntp true && sudo systemctl restart systemd-timesyncd，并用timedatectl status确认System clock synchronized: yes。

• 技巧 4：ufw防火墙必须放行 8080 端口
  Ubuntu 20.04 默认不启用ufw，但很多用户会手动开启。若 `sudo ufw status