1. 项目概述与核心价值最近在帮团队搭建自动化部署流水线又一次用到了 Jenkins。虽然现在各种云原生 CI/CD 工具层出不穷但 Jenkins 凭借其强大的插件生态、高度的可定制性和开源免费的特性依然是很多中小团队和传统项目构建自动化流程的首选。尤其是在 Linux 服务器上部署 Jenkins几乎是每个后端开发和运维工程师的必修课。这个教程的目标就是带你从零开始在一台干净的 Linux 服务器上完整、稳定地安装并初步配置好 Jenkins避开那些新手常踩的坑。无论你是想学习持续集成还是急需为项目搭建一个自动化的构建部署环境这篇基于实战的详细指南都能让你少走弯路。简单来说Jenkins 是一个用 Java 编写的开源自动化服务器它可以帮助你自动化与构建、测试、交付或部署软件相关的各种任务。通过它你可以设置一套流水线Pipeline当代码提交到 Git 仓库后自动触发编译、运行测试、打包镜像、部署到服务器等一系列操作极大提升开发效率和软件质量。本教程将涵盖从环境准备、Jenkins 安装、初始解锁、插件配置到创建一个简单流水线的全过程并分享一些确保服务稳定运行的经验技巧。2. 安装环境准备与规划在开始安装之前充分的准备工作能避免很多后续的麻烦。我们需要一台 Linux 服务器这里以最流行的 CentOS 7/Rocky Linux 8 或 Ubuntu 20.04/22.04 LTS 为例。虽然 Jenkins 提供了多种安装方式如 Docker 容器、WAR 包直接运行但为了获得最佳的可维护性和稳定性我强烈推荐使用官方仓库进行安装。这种方式便于后续的版本升级和管理。2.1 系统基础检查与更新首先登录你的 Linux 服务器。第一步永远是检查系统状态并进行更新这能确保我们在一个已知的、稳定的基础环境上操作。# 对于基于 RedHat 的系统如 CentOS, Rocky Linux sudo yum update -y # 检查系统版本 cat /etc/redhat-release # 对于基于 Debian 的系统如 Ubuntu sudo apt update sudo apt upgrade -y # 检查系统版本 lsb_release -a更新系统后建议重启一下以确保所有更新生效特别是内核更新。sudo reboot。接下来检查并安装一些基础工具如wget,curl,vim它们会在后续步骤中用到。# CentOS/Rocky Linux sudo yum install -y wget curl vim # Ubuntu sudo apt install -y wget curl vim2.2 Java 运行环境安装Jenkins 是一个 Java 应用因此必须安装 Java 运行时环境JRE或开发工具包JDK。Jenkins 官方推荐使用 OpenJDK 11 或 OpenJDK 17。长期支持版本LTS的 Jenkins 对 Java 版本有明确要求安装前最好去官网确认一下。这里我们安装 OpenJDK 11。# CentOS/Rocky Linux 8 sudo yum install -y java-11-openjdk-devel # Ubuntu 20.04/22.04 sudo apt install -y openjdk-11-jdk安装完成后验证 Java 是否安装成功以及版本是否正确java -version你应该能看到类似openjdk version 11.0.xx的输出。确保版本号是 11 或更高如 17。如果系统之前安装过其他版本的 Java可能需要使用alternatives --config java来切换默认版本。注意不建议使用系统默认可能存在的旧版本 Java 8虽然某些旧版 Jenkins 可能支持但新版本插件或功能可能会遇到兼容性问题。统一使用 Jenkins 官方推荐的 LTS Java 版本是最稳妥的选择。2.3 防火墙与 SELinux 配置为了让外部能够访问 Jenkins 的 Web 界面默认端口 8080我们需要在防火墙中开放该端口。同时如果系统启用了 SELinuxCentOS/Rocky Linux 默认启用也需要进行相应配置。配置防火墙# 对于 firewalldCentOS/Rocky Linux 默认 sudo firewall-cmd --permanent --add-port8080/tcp sudo firewall-cmd --reload # 检查端口是否开放 sudo firewall-cmd --list-ports # 对于 ufwUbuntu 常用 sudo ufw allow 8080/tcp sudo ufw reload sudo ufw status配置 SELinux如果系统启用了 SELinux并且你不想直接禁用它生产环境不建议禁用需要调整策略允许 Jenkins 使用 8080 端口。# 检查 SELinux 状态 getenforce # 输出 Enforcing 表示启用 # 允许 httpd 使用 8080 端口Jenkins 默认使用此上下文 sudo semanage port -a -t http_port_t -p tcp 8080 # 如果 semanage 命令未找到需要安装 policycoreutils-python-utils # sudo yum install -y policycoreutils-python-utils如果上述命令执行失败或者你只是在测试环境可以考虑临时将 SELinux 设置为宽容模式以继续安装调试sudo setenforce 0。但这只是临时生效重启后会恢复。永久修改需要编辑/etc/selinux/config文件将SELINUXenforcing改为SELINUXpermissive但这会降低安全性请谨慎评估。3. Jenkins 核心安装流程详解环境准备好后我们就可以开始安装 Jenkins 本体了。使用官方仓库安装能自动处理依赖关系和服务配置是最省心的方式。3.1 添加 Jenkins 官方仓库Jenkins 提供了稳定的 LTS长期支持版本和每周更新的常规版本。对于生产环境强烈建议使用 LTS 版本。我们需要将 Jenkins 的官方仓库添加到系统的包管理器源中。对于 CentOS/Rocky Linux/RHEL 系统# 导入 Jenkins 仓库的 GPG 密钥用于验证软件包 sudo rpm --import https://pkg.jenkins.io/redhat-stable/jenkins.io.key # 添加 Jenkins 稳定版仓库 sudo wget -O /etc/yum.repos.d/jenkins.repo https://pkg.jenkins.io/redhat-stable/jenkins.repo对于 Ubuntu/Debian 系统# 导入 GPG 密钥 curl -fsSL https://pkg.jenkins.io/debian-stable/jenkins.io.key | sudo tee /usr/share/keyrings/jenkins-keyring.asc /dev/null # 添加仓库到 sources.list echo deb [signed-by/usr/share/keyrings/jenkins-keyring.asc] https://pkg.jenkins.io/debian-stable binary/ | sudo tee /etc/apt/sources.list.d/jenkins.list /dev/null # 更新本地包索引 sudo apt update实操心得网络问题可能是这里最大的障碍。如果服务器在国内从pkg.jenkins.io下载密钥或仓库定义文件速度慢或失败可以尝试多试几次或者先下载到本地再上传到服务器。确保命令中的 URL 拼写正确。3.2 安装 Jenkins 软件包添加仓库后安装就非常简单了。# CentOS/Rocky Linux sudo yum install -y jenkins # Ubuntu sudo apt install -y jenkins这个命令会安装 Jenkins 的最新 LTS 版本及其所有依赖。安装过程会自动完成以下几件事创建系统用户和用户组jenkins。将 Jenkins 安装到/usr/lib/jenkinsJAR 文件和/var/lib/jenkins工作目录即JENKINS_HOME。创建 Systemd 服务单元文件以便使用systemctl管理服务。设置默认的日志目录/var/log/jenkins。3.3 启动 Jenkins 服务并设置开机自启安装完成后我们需要启动 Jenkins 服务并让它能在系统重启后自动启动。# 启动 Jenkins 服务 sudo systemctl start jenkins # 设置开机自启 sudo systemctl enable jenkins # 检查服务状态确认是否运行正常 sudo systemctl status jenkins运行status命令后你应该看到绿色的active (running)字样并且没有明显的错误日志。如果状态是failed可以使用sudo journalctl -u jenkins -f来实时查看 Jenkins 服务的日志排查问题。常见问题包括 Java 版本不兼容、端口冲突8080 已被占用或权限问题。4. 初始访问与基础配置服务启动后Jenkins 还不能立即使用我们需要通过 Web 界面完成初始的解锁和配置。4.1 解锁 Jenkins打开浏览器访问http://你的服务器IP地址:8080。你会看到 Jenkins 的解锁页面它要求你输入一个初始管理员密码。这个密码在 Jenkins 首次启动时自动生成并保存在服务器的一个特定文件中。页面上会提示文件路径通常是/var/lib/jenkins/secrets/initialAdminPassword。我们通过命令查看它sudo cat /var/lib/jenkins/secrets/initialAdminPassword将终端输出的那一长串随机字符复制粘贴到网页的输入框中点击“继续”。4.2 自定义插件安装解锁后会进入“自定义 Jenkins”页面。这里有两个选项安装推荐的插件这是给新手的建议选项会安装一套最常用的插件如 Git、Pipeline、邮件通知等。对于大多数用户我建议直接选这个。选择插件来安装你可以手动勾选需要的插件。如果你清楚自己需要什么或者网络环境较差想分批安装可以选这个。点击“安装推荐的插件”。安装过程可能会持续几分钟到十几分钟取决于网络速度和服务器性能。这里是一个极易出错的环节。注意事项由于 Jenkins 插件中心默认服务器在国外国内服务器直接安装可能会非常慢甚至超时失败。如果遇到插件下载失败不要慌可以点击“重试”多次。如果始终无法成功可以考虑以下两种方案更换插件更新中心镜像在安装插件前先修改 Jenkins 的hudson.model.UpdateCenter.xml文件将 URL 替换为国内镜像如清华镜像。但初始安装时可能来不及操作。“跳过插件安装”在插件安装页面其实右上角有一个不显眼的“跳过并继续使用空密码”链接后续版本可能文案不同。你可以先跳过插件安装进入 Jenkins 主界面后在系统管理 插件管理 高级选项卡中将“升级站点”的 URL 改为https://mirrors.tuna.tsinghua.edu.cn/jenkins/updates/update-center.json然后重试。这是更实用的方法。4.3 创建第一个管理员用户插件安装完成后或跳过插件安装后会进入“创建第一个管理员用户”页面。强烈建议在此创建自定义的管理员账户不要使用默认的admin账户并继续使用初始密码这非常不安全。填写用户名、密码、全名和邮箱地址然后点击“保存并完成”。后续登录 Jenkins 就使用这个账户。4.4 配置实例 URL下一步是配置 Jenkins 的根 URL即 Jenkins 对外访问的地址。默认会是http://服务器IP:8080。如果你后续打算配置域名或反向代理如通过 Nginx 用域名访问可以在这里修改。初次安装如果直接通过 IP 和端口访问保持默认即可点击“保存并完成”。至此你会看到“Jenkins 已就绪”的页面点击“开始使用 Jenkins”即可进入主控制台。5. 关键插件安装与全局工具配置进入 Jenkins 后一个空荡荡的界面可能让你无从下手。别急我们还需要安装一些核心插件并配置必要的全局工具才能开始创建任务。5.1 安装必备插件虽然初始安装可能装了一些插件但为了支持现代的开发流程我们通常还需要手动安装几个关键的。进入系统管理 插件管理 可选插件。在搜索框中查找并勾选以下插件根据你的实际需求调整Pipeline 提供了一套可扩展的流水线 DSL是构建复杂 CI/CD 流程的核心。安装Pipeline和Pipeline: Stage View。Git 提供从 Git 仓库GitHub, GitLab, Gitee 等拉取代码的能力。通常初始安装已包含检查一下。Docker Pipeline 如果你使用 Docker 进行构建和部署这个插件提供了流水线中与 Docker 交互的步骤。Blue Ocean 提供了一个现代化的、可视化的流水线编辑和查看界面对新手更友好。Role-based Authorization Strategy 如果需要细粒度的用户权限管理这个插件非常有用。勾选后点击页面底部的“直接安装”或“下载待重启后安装”。安装完成后根据提示重启 Jenkins。提示重启 Jenkins 可以通过 Web 界面完成安装插件后有重启按钮也可以在服务器上执行命令sudo systemctl restart jenkins。重启后需要重新登录。5.2 配置全局工具插件是“能力”工具是“武器”。我们需要告诉 Jenkins 一些常用工具如 JDK, Git, Maven, Gradle, Docker 等在服务器上的安装路径。进入系统管理 全局工具配置。JDK 虽然系统安装了 JDK但 Jenkins 可能无法自动找到。点击“JDK 安装”下的“新增 JDK”。取消勾选“自动安装”因为我们已手动安装。在“别名”中输入一个名字如openjdk-11。在“JAVA_HOME”中填入你的 JDK 安装路径。可以通过which java找到java命令路径然后通过readlink -f $(which java)追踪到真实路径其上级目录的上级通常是JAVA_HOME。更直接的方法是使用echo $JAVA_HOME如果已设置或对于 yum/apt 安装的 openjdk路径通常是/usr/lib/jvm/java-11-openjdk-版本号。你可以用ls /usr/lib/jvm/查看。Git 同样新增 Git取消“自动安装”别名填system-gitPath to Git executable 填which git命令的输出通常是/usr/bin/git。Maven/Gradle 如果你的项目需要可以在这里配置。建议使用“自动安装”功能让 Jenkins 在首次构建时自动下载指定版本非常方便。配置完成后点击页面底部的“保存”。6. 创建你的第一个 Jenkins 流水线任务现在所有准备工作都已就绪让我们创建一个最简单的流水线任务来验证 Jenkins 是否工作正常。我们将创建一个从 Git 仓库拉取代码然后执行一个 Shell 命令的流水线。6.1 新建流水线任务点击 Jenkins 首页的“新建任务”。输入一个任务名称例如My-First-Pipeline。选择“流水线”类型然后点击“确定”。6.2 配置流水线脚本在任务配置页面向下滚动到“流水线”部分。定义 选择“Pipeline script”。在Script文本框中输入以下简单的流水线脚本pipeline { agent any // 在任何可用的代理上运行 stages { stage(Checkout) { steps { echo 开始从 Git 拉取代码... // 这里假设你有一个公开的测试仓库 git https://github.com/jenkins-docs/simple-java-maven-app.git } } stage(Build) { steps { echo 正在构建项目... // 模拟构建命令这里只是列出目录 sh ls -la } } stage(Test) { steps { echo 正在运行测试... // 模拟一个成功的测试 sh echo 所有测试通过 } } } post { always { echo 流水线执行结束。 } } }这个脚本定义了一个包含三个阶段拉取代码、构建、测试的流水线。agent any表示 Jenkins 会分配一个可用的执行节点目前就是主节点本身来运行。git步骤会克隆指定的仓库。6.3 执行与查看结果点击页面底部的“保存”。回到任务主页面点击左侧的“立即构建”。你会看到任务开始排队并执行。点击构建历史中的编号如 #1然后点击“控制台输出”可以实时查看整个构建过程的详细日志。如果一切顺利你会在日志末尾看到SUCCESS的标志并且各个阶段echo的命令都有输出。恭喜你你的第一个 Jenkins 流水线已经成功运行7. 安全加固与日常维护指南Jenkins 安装并运行起来只是第一步要让它稳定、安全地服务于生产环境还需要进行一些加固和维护。7.1 安全配置建议启用安全性 确保系统管理 全局安全配置中“安全域”和“授权策略”已正确配置。我们之前创建的管理员用户就是基于“Jenkins 专有用户数据库”和“登录用户可以做任何事”的简单策略。对于团队建议使用“Role-Based Strategy”插件进行更细粒度的控制。限制脚本命令行 在“全局安全配置”中找到“脚本命令行”建议将其禁用或只对管理员开放。这是一个强大的功能但也非常危险。定期更新 定期检查系统管理 插件管理和系统管理 系统配置中的 Jenkins 版本更新。及时更新可以修复安全漏洞。更新前请务必在测试环境验证并备份JENKINS_HOME默认是/var/lib/jenkins。备份JENKINS_HOME 这个目录包含了 Jenkins 的所有配置、任务定义、构建历史和插件数据。定期备份此目录是灾难恢复的底线。可以使用tar命令打包并结合cron定时任务实现自动备份。7.2 性能与稳定性调优调整 JVM 参数 Jenkins 是 Java 应用其性能受 JVM 堆内存影响。编辑/etc/sysconfig/jenkinsCentOS/RHEL或/etc/default/jenkinsUbuntu文件找到JENKINS_JAVA_OPTIONS或类似参数。默认可能是-Xmx256m。对于有一定负载的 Jenkins建议增加到-Xmx1024m或更高例如JAVA_OPTS-Djava.awt.headlesstrue -Xmx1024m -Xms512m -XX:MaxPermSize256m。具体数值根据服务器物理内存和 Jenkins 负载调整。修改后需要重启 Jenkinssudo systemctl restart jenkins。管理构建历史 旧的构建记录会占用大量磁盘空间。在每个任务的配置页面可以找到“丢弃旧的构建”选项设置保留构建的天数或个数策略。监控日志 Jenkins 的日志位于/var/log/jenkins/jenkins.log。使用tail -f命令可以实时监控运行状态和错误。定期清理过大的日志文件。7.3 常见问题排查实录即使按照教程操作你也可能会遇到一些问题。这里记录几个我踩过的坑和解决方法问题一插件安装极慢或失败现象在插件管理页面下载进度条长时间不动最终超时。排查ping updates.jenkins.io查看网络连通性。查看 Jenkins 日志/var/log/jenkins/jenkins.log看是否有网络超时错误。解决更换升级站点镜像如前文所述。手动下载插件从 Jenkins 插件官网或镜像站下载.hpi文件然后在“插件管理”的“高级”选项卡中通过“上传插件”功能手动安装。使用代理服务器需确保符合公司网络政策。问题二启动 Jenkins 时提示“java.io.IOException: Failed to start a listener: winstone.HttpListener”现象systemctl status jenkins显示失败日志提示端口绑定失败。排查端口 8080 可能被其他进程占用。使用sudo netstat -tlnp | grep :8080查看。解决停止占用端口的进程。或者修改 Jenkins 的监听端口。编辑/etc/sysconfig/jenkins或/etc/default/jenkins找到JENKINS_PORT8080修改为其他端口如8081然后重启 Jenkins。问题三流水线中执行 Shell 命令权限不足现象在流水线sh步骤中执行某些命令如docker时报Permission denied。排查Jenkins 服务默认以jenkins系统用户身份运行。该用户可能不在docker等用户组中。解决将jenkins用户添加到所需组并重启 Jenkins 服务。sudo usermod -aG docker jenkins # 加入 docker 组 sudo systemctl restart jenkins注意这可能会带来安全风险请仅在受控环境中操作。问题四构建时无法克隆私有 Git 仓库现象流水线在git步骤失败提示认证失败。排查Jenkins 需要凭据来访问私有仓库。解决在 Jenkins 中进入系统管理 管理凭据。在“全局凭据”域中添加你的 SSH 私钥推荐或用户名/密码。在流水线任务配置或脚本中通过credentialsId参数指定使用的凭据。git credentialsId: your-ssh-key-id, url: gitgithub.com:your/private-repo.git安装和配置 Jenkins 的过程就像搭积木每一步都为基础添砖加瓦。从最初裸机状态的系统准备到中间可能遇到的网络、权限等“坑”再到最后流水线成功运行的那一刻整个流程走下来你对自动化部署的理解会深刻很多。我个人最大的体会是文档和日志是你最好的朋友。遇到任何问题首先查看 Jenkins 的控制台输出日志和系统日志/var/log/jenkins/jenkins.log里面通常包含了非常明确的错误信息。其次善用 Jenkins 自带的“流水线语法”生成工具在任务配置页面点击“流水线语法”它可以帮助你正确地编写 Groovy DSL 脚本避免语法错误。最后对于生产环境一定要养成备份JENKINS_HOME的习惯这是你能在关键时刻救命的最后一道防线。