把Jenkins跑在CentOS 7上这件事听起来就三步装Java、跑war包、打开网页。但真做起来十个人里会有八个卡在初始化插件那一步剩下两个多半栽在Java版本或者服务起不来的问题上。我最近又在一批存量CentOS 7机器上重新部署了一遍把整个流程、踩过的坑和部署完之后的调优项都捋了一遍。这篇文章不是给你念官方文档而是把我实际执行的步骤、每一步为什么要这么做、以及出问题时的排查思路完整写出来。如果你正打算在一台CentOS 7上从零搭Jenkins照着走就行。1. 部署前先解决两个环境问题Java版本和系统基础项1.1 新版Jenkins对Java版本的要求别拿默认JDK直接干CentOS 7自带的yum源里默认的Java是OpenJDK 1.8而新版Jenkins LTS已经要求Java 11甚至Java 17。如果你图省事直接yum install java-1.8.0-openjdk然后去跑最新版Jenkins war包大概率会看到类似“Unsupported Java version”的提示或者服务起来之后一堆插件加载异常。这里我按实际使用场景给出两个稳妥组合组合Java版本Jenkins版本适用场景组合AOpenJDK 17最新稳定LTS当前推荐新部署、生产环境、想长期维护组合BOpenJDK 11较老的LTS版本如2.361.x存量机器有Java版本约束、只想快速跑通我建议直接用组合A。OpenJDK 17在CentOS 7上完全能跑性能比8和11都好。CentOS 7的yum源里没有OpenJDK 17所以需要手动下载JDK压缩包解压安装。这个操作并不复杂# 创建Java安装目录 sudo mkdir -p /opt/java # 从你信任的开源镜像站下载OpenJDK 17的Linux x64压缩包 # 文件名格式一般是 OpenJDK17U-jdk_x64_linux_hotspot_17.0.12_7.tar.gz sudo tar -zxvf OpenJDK17U-jdk_x64_linux_hotspot_17.0.12_7.tar.gz -C /opt/java/ # 解压后目录名带版本号做一个软链方便后续配置 sudo ln -s /opt/java/jdk-17.0.127 /opt/java/jdk-17 # 写入环境变量 sudo tee /etc/profile.d/jenkins-java.sh /dev/null EOF export JAVA_HOME/opt/java/jdk-17 export PATH$PATH:$JAVA_HOME/bin EOF # 让环境变量立即生效 source /etc/profile.d/jenkins-java.sh # 验证 java -version这里有一个容易忽略的细节解压出来的目录名通常带加号比如jdk-17.0.127而符号在systemd服务文件里如果直接写路径会出问题。所以我做了软链/opt/java/jdk-17后续所有配置都引用这个干净路径这是实战中少走弯路的关键一步。1.2 防火墙、SELinux和时钟不处理后面全是玄学Java版本搞定之后紧接着就要看系统基础状态。很多人在部署完Jenkins之后发现页面打不开、写文件失败、构建日志时间差8小时这些其实都不是Jenkins的问题而是系统环境没弄干净。防火墙方面如果你在内网测试环境最简单的做法是关闭firewalld并禁用开机自启sudo systemctl stop firewalld sudo systemctl disable firewalld如果你的服务器需要保留防火墙那就只放行Jenkins端口sudo firewall-cmd --permanent --add-port8080/tcp sudo firewall-cmd --reloadSELinux是另一个坑。用war包方式部署在自定义目录/opt/jenkins时SELinux的默认策略可能会阻止Jenkins写文件。对绝大多数中小团队来说内网服务器直接放宽容许状态是更务实的选择sudo setenforce 0 sudo sed -i s/^SELINUXenforcing/SELINUXpermissive/ /etc/selinux/config不建议直接改成disabled因为改SELinux配置文件为disabled之后下次重启SELinux策略会被重新初始化反而可能带来其他意外。设成permissive已经足够让Jenkins正常工作。时钟同步很容易被忽略但Jenkins构建日志、定时任务全部依赖系统时间。顺手装上chrony并启动sudo yum install -y chrony sudo systemctl enable --now chronyd sudo chronyc makestep这三件事做完后面部署的过程会顺畅很多大部分“莫名其妙的报错”都是从这里先排除掉的。2. 安装方式我为什么推荐war包加systemd管理2.1 官方rpm仓库安装与war包部署怎么选CentOS 7上的Jenkins安装一般有两种主流方式官方rpm仓库安装、war包手动部署。很多教程默认让你用rpm仓库命令确实短但实际用起来有几个隐患。官方rpm仓库的地址维护在Jenkins官网GPG key地址会不定期更新如果你照搬几个月前的教程经常遇到key下载失败或者repo文件过期。rpm方式对目录结构也做了固定封装/var/lib/jenkins、/etc/sysconfig/jenkins这些路径全定死了对新手友好但可定制性差一些。war包部署的逻辑更简单Jenkins本质上是一个Java Web应用官方提供一个可独立运行的war包里面内置了Web服务器直接用java -jar就能跑起来。这种方式的好处有三个版本完全自己控制想用哪个LTS版本自己下载不受yum仓库更新节奏影响目录结构自定义升级就替换war包回滚也方便用systemd管理后开机自启、崩溃重启、日志采集都和系统原生服务保持一致我个人的建议是如果只是临时体验rpm方式也行但如果要长期维护、还要写进自动化部署脚本里war包加systemd的方式更靠谱。2.2 war包部署完整步骤和systemd服务文件先创建Jenkins运行所需的目录和专用用户sudo mkdir -p /opt/jenkins sudo mkdir -p /var/lib/jenkins sudo mkdir -p /var/log/jenkins sudo useradd -r -s /sbin/nologin jenkins sudo chown -R jenkins:jenkins /opt/jenkins sudo chown -R jenkins:jenkins /var/lib/jenkins sudo chown -R jenkins:jenkins /var/log/jenkins这里专门创建一个名叫jenkins的系统用户目的是让Jenkins进程以普通用户权限运行避免一旦Jenkins被攻破就直接拿到root权限。然后下载war包并放到/opt/jenkins目录下cd /opt/jenkins sudo wget https://get.jenkins.io/war-stable/latest/jenkins.war这个官方下载地址在部分网络环境下可能比较慢如果慢到无法接受就找一个国内开源镜像站在镜像站的jenkins目录下找war-stable子目录即可。镜像站和官方保持同步用起来没有区别。接着创建systemd服务文件sudo tee /etc/systemd/system/jenkins.service /dev/null EOF [Unit] DescriptionJenkins Automation Server Afternetwork-online.target Wantsnetwork-online.target [Service] Typesimple Userjenkins Groupjenkins WorkingDirectory/var/lib/jenkins EnvironmentJAVA_HOME/opt/java/jdk-17 EnvironmentJENKINS_HOME/var/lib/jenkins EnvironmentJENKINS_WAR/opt/jenkins/jenkins.war ExecStart/opt/java/jdk-17/bin/java -Xms1024m -Xmx2048m -Duser.timezoneAsia/Shanghai -jar /opt/jenkins/jenkins.war --httpPort8080 Restarton-failure RestartSec30s [Install] WantedBymulti-user.target EOF这个服务文件里有几个细节值得解释。WorkingDirectory设置了工作目录Jenkins在初始化时会往当前目录写入一些临时文件如果这个目录没有写权限启动会失败。EnvironmentJENKINS_HOME/var/lib/jenkins明确了Jenkins的数据目录这个目录之后保存所有任务配置、插件、构建记录是全部家当。内存参数-Xms1024m -Xmx2048m是我在2核4G机器上的常用配置。如果机器内存只有2G建议改成-Xms512m -Xmx1024m别贪大。时区参数-Duser.timezoneAsia/Shanghai写在JVM参数里避免构建日志和任务时间全部显示成UTC时间。2.3 验证服务状态和日志服务文件写好之后执行sudo systemctl daemon-reload sudo systemctl enable --now jenkins查看状态sudo systemctl status jenkins -l正常情况下能看到进程是active (running)并且监听在8080端口。再用curl验证一下curl -I http://localhost:8080如果返回HTTP/1.1 302说明服务已经正常响应它只是在等待你访问初始化页面。如果服务启动失败第一时间看日志journalctl -u jenkins -f日志里会明确告诉你失败原因最常见的是/var/lib/jenkins目录属主不对或者Java路径不对。排查思路就是先看属主再看Java路径最后看端口占用。3. 首次初始化最容易被卡住的插件安装环节3.1 首次解锁密码在哪看服务正常启动后浏览器访问http://服务器IP:8080第一次进入会看到“解锁Jenkins”页面。解锁密码在服务端保存查看方式sudo cat /var/lib/jenkins/secrets/initialAdminPassword把这一串密码复制粘贴到网页输入框就能进入下一步。3.2 插件初始化转圈问题把更新源换成镜像站进入初始化向导后系统会推荐安装一组默认插件点击“安装建议的插件”。很多人的噩梦从这里开始页面卡在“安装中”几个小时都不动弹进度条纹丝不动。这个问题的根因是Jenkins初始化时要从它官方更新中心下载插件元数据和插件本身而官方更新服务器在你所处的网络环境下访问极不稳定经常连接超时页面就卡住了。解决办法不是傻等而是提前把更新中心地址换成国内镜像站。这里有一个关键认知镜像站只是镜像了Jenkins的update-center.json元数据文件但该文件内部记录的每个插件的下载URL仍然指向官方地址。如果只改更新中心URL你会发现元数据能读取了但安装插件时依旧超时。所以正确姿势是把update-center.json下载到本地把内部所有插件下载地址批量替换成镜像站地址再让Jenkins读取这个本地文件。我在实践中的完整步骤如下。先下载镜像站的update-center.json保存到/var/lib/jenkins下cd /var/lib/jenkins sudo -u jenkins curl -fsSL --compressed -o update-center.json https://你的镜像站域名/jenkins/updates/update-center.json--compressed参数很重要因为该接口返回的是gzip压缩内容如果不加这个参数下载到本地的是一个压缩过的文件后面sed替换会直接失败。然后替换文件内的插件下载地址前缀sudo -u jenkins sed -i s#https://updates.jenkins.io/download#https://你的镜像站域名/jenkins#g /var/lib/jenkins/update-center.json接着修改Jenkins的更新中心配置文件sudo -u jenkins cat /var/lib/jenkins/hudson.model.UpdateCenter.xml EOF ?xml version1.0 encodingUTF-8? sites site iddefault/id urlfile:///var/lib/jenkins/update-center.json/url /site /sites EOFhudson.model.UpdateCenter.xml这个文件是Jenkins读取更新中心配置的地方默认指向官方URL。改成file://协议指向本地文件后插件元数据和下载地址全部走本地速度会明显改善。改完重启服务sudo systemctl restart jenkins再回到浏览器刷新页面重新进入向导此时安装插件的速度通常是本地网络中拉取镜像站的速度几十个插件基本几分钟内装完。3.3 跳过安装之后如何再补插件如果你的初始化页面已经卡死先关掉页面重启Jenkins服务然后重新访问初始化页面时不选“安装建议的插件”直接选择“选择要安装的插件列表”但不要勾选任何插件直接提交。这样就能绕过下载环节进入创建管理员页面。创建完管理员之后进入“系统管理Manage Jenkins”下的“插件管理Plugins”在“高级”标签页里同样可以修改更新站点配置。把Update Site改成file:///var/lib/jenkins/update-center.json保存后回到“可选插件”页面就能正常搜索和安装插件了。生产环境中以下几个插件建议必装插件名作用说明localization-zh-cnJenkins中文语言包界面汉化团队协作时降低使用门槛gitGit源码管理Jenkins能拉取Git仓库代码的基础插件pipeline-stage-view流水线阶段视图可视化查看流水线各阶段执行情况docker-workflowDocker构建支持使用Docker容器作为构建节点时必需role-based-authorization-strategy基于角色的权限管理多人共用时区分不同权限4. 部署完立刻要做的四件事内存、时区、反代和权限4.1 调整JVM内存和时区避免构建到一半OOMJenkins安装完成并不代表结束默认配置跑几个任务之后就会暴露问题。首先就是内存设置。Jenkins的war包自带的默认JVM参数比较保守一旦同时构建多个Job经常出现OutOfMemoryError表现为某次构建卡死或是服务无响应。我在systemd服务文件里已经写入了-Xms1024m -Xmx2048m如果你安装时用的不是上面的服务文件就需要打开服务文件检查确认。另外日志里经常出现java.lang.OutOfMemoryError: Metaspace说明JVM元空间也需要调大可以在JVM参数里追加-XX:MaxMetaspaceSize512m。时区问题也要反复确认。即使系统时区是Asia/ShanghaiJenkins默认的JVM时区也可能是UTC结果就是构建历史显示时间和实际时间差8个小时。最佳做法是在启动参数里写死时区也就是服务文件里的-Duser.timezoneAsia/Shanghai。在JVM参数里写死比在系统设置里改要可靠得多。4.2 用Nginx做反向代理顺便解决URL和CSRF问题如果Jenkins所在的机器有对外域名或者你想通过标准80端口访问就很有必要用Nginx做一层反向代理。CentOS 7上安装Nginxsudo yum install -y nginx然后写一个Jenkins专用的server配置server { listen 80; server_name jenkins.你的域名.com; client_max_body_size 100m; location / { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_read_timeout 300s; } }写完配置后启动服务sudo systemctl enable --now nginx sudo nginx -t sudo systemctl reload nginx反代配置完成后还有一个容易被忽略的步骤登录Jenkins进入“系统管理 系统配置”把“Jenkins URL”从http://localhost:8080/改成http://jenkins.你的域名.com/。这个URL如果不改Jenkins在发送构建通知、Webhook回调时会使用错误的地址导致Git仓库推送后触发构建失败。4.3 端口和权限默认配置不能直接上线war包部署的Jenkins默认监听0.0.0.0:8080也就是说如果这台服务器有公网IP任何人都能直接访问你的Jenkins页面。默认管理员密码是初始化时你自己设置的但如果密码太弱风险极大。我对所有生产环境的建议是不要让Jenkins直接暴露在公网。最稳妥的做法是让Jenkins只监听内网或本机sudo sed -i s/--httpPort8080/--httpPort8080 --httpListenAddress127.0.0.1/ /etc/systemd/system/jenkins.service sudo systemctl daemon-reload sudo systemctl restart jenkins然后通过Nginx反向代理对外提供服务。这样外网只能访问Nginx的80端口而Nginx需要配置访问控制。如果连Nginx都不想暴露就在云安全组里只放行特定IP访问80端口。权限管理上如果只是单人或小团队使用默认的“登录用户可以做任何事”可以接受。但人多之后就需要安装role-based-authorization-strategy插件按角色分配“系统管理员”“普通开发者”“只读用户”等权限避免有人误删Job或者修改全局配置。5. 运行期间踩过的坑四类故障排查实录5.1 缺字体库导致的构建报错Jenkins在构建过程中如果涉及生成HTML报告、图片验证、PDF输出等功能可能会抛出一个异常java.lang.UnsatisfiedLinkError: /usr/lib64/libfontconfig.so.1: cannot open shared object file: No such file or directory这个报错的直观意思是找不到字体库文件。CentOS 7最小化安装经常不带字体相关依赖而Jenkins构建过程中某些Java绘图操作需要调用系统的字体库。解决办法很简单sudo yum install -y fontconfig dejavu-sans-fonts装完之后重启Jenkins这个报错就不会再出现。这个问题在Docker容器内跑Jenkins时同样常见基础镜像选择时要注意选带字体库的镜像。5.2 端口冲突和Home目录属主问题有一次我部署完Jenkins后执行systemctl start jenkins提示失败systemctl status jenkins -l显示Error: Failed to start Jenkins查看journalctl -u jenkins -f发现日志末尾有java.net.BindException: Address already in use。用ss -lntp查了一下果然8080端口被另一个进程占用。这种问题的处理最简单要么杀掉占用进程要么换掉Jenkins端口。换端口只需要修改service文件里的--httpPort8080为--httpPort9090然后重启服务。更隐蔽的一个坑是目录属主问题。Jenkins服务以jenkins用户运行但如果你在root下执行过java -jar jenkins.war它会在当前用户目录下生成.jenkins文件夹。之后再用systemd方式启动由于JENKINS_HOME权限不对或者目录指向不一致会出现无法写入配置文件的报错。我的排查习惯是启动失败后先执行ls -ld /var/lib/jenkins stat -c %U:%G /var/lib/jenkins如果属主不是jenkins:jenkins直接用chown -R jenkins:jenkins /var/lib/jenkins修正。这类问题在教程中往往一笔带过实际排障时却占了半壁江山。5.3 构建节点找不到java命令Jenkins在上游机器上跑得好好的但到一个新配置的构建节点上执行Pipeline或者自由风格任务时报错/usr/bin/env: ‘java’: No such file or directory这个问题不是Jenkins配置问题而是构建节点的PATH环境变量里没有Java。Jenkins执行构建时通过ssh等方式连上节点调用env命令初始化环境如果你的Java是安装在/opt/java/jdk-17并且只在/etc/profile.d/jenkins-java.sh里写了环境变量但Jenkins的登录shell不一定加载这个文件。保险做法是到“系统管理 全局工具配置”里在JDK安装部分手动指定Java路径取消“自动安装”选项明确填上/opt/java/jdk-17。这样Jenkins在调用Maven或Java编译时会自己拼好完整路径不再依赖节点shell的PATH环境变量。5.4 CentOS 7 EOL之后yum源失效CentOS 7生命周期结束后不少默认yum源里的软件包已经迁移或下架。如果你在新机器上执行yum install时提示404或者找不到路径需要把系统yum源切换到存档源或者迁移到继续维护的社区源。我处理这类问题时会把/etc/yum.repos.d/下的repo文件里的mirror.centos.org换成存档源地址。这个操作要在部署Jenkins之前做否则可能连fontconfig都装不上。另外还要明白一点CentOS 7本身已停止维护如果这台机器要长期对外提供服务后续系统安全更新会缺失这属于运维层面的长期风险建议尽早规划迁移到更新的操作系统版本。6. 这几次部署下来我额外会写进运维清单的事部署环境不同遇到的问题会略有差异但有几件事我每次都会固定写进自己的运维清单里。第一是备份/var/lib/jenkins这个目录是整个Jenkins的全部家当Job配置、构建记录、插件配置全在里面。我用一个简单的cron任务每天打包备份到另一台机器上恢复的时候直接把备份解压回去再重启服务整个过程不超过五分钟。第二是升级节奏。Jenkins LTS版本大概每三个月发布一次但不要一有新版本就立刻升级。我会先在测试机上替换war包确认插件兼容性没有问题之后再升级生产环境。升级之前务必先备份/var/lib/jenkins因为插件升级失败时至少能退回去。第三是安全基线检查。每隔一段时间检查一下Jenkins已安装插件的安全公告尤其是暴露在公网上的实例。插件长期不更新是Jenkins安全事件的最大来源比Jenkins主版本更新更紧急。具体的做法是定期去插件管理页面看更新提示有安全修复版本就及时升级升级完立刻跑一遍核心构建任务做回归验证。如果你也准备在CentOS 7上部署Jenkins希望这篇记录能帮你少走点弯路。环境问题提前处理好插件下载源提前换好部署完把内存、时区、反代和安全权限收拾利索这台Jenkins跑个一两年基本不用再折腾。