聊到 Jenkins 安装，我见过太多人卡在第一步就放弃了：war 包、包管理器、Docker 三种方式到底怎么选？JDK 用 11 还是 17？解锁密码到底去哪儿看？这些问题我在第一次搭持续集成环境时也全都踩过一遍。
这篇文章是我计划中的 Jenkins 系列第一篇，先把“安装”这个地基打牢。我会从装之前的环境评估讲起，把三种主流安装方式的完整步骤、初始化配置、常见坑位排查一起盘清楚，全部基于我自己的实操记录和踩坑经验。刚接触持续集成的同学可以照着一步步做下来，已经装过的也能对照排查一些遗留问题。
1. 装之前先想清楚：Jenkins 到底是什么，装成什么样才算“装得好”
很多新手容易犯一个错误：拿到安装命令就跑，装完发现用不起来，然后又重装。所以我不急着给命令，先聊清楚三个问题。
1.1 Jenkins 解决了什么问题
Jenkins 是一个开源的自动化服务器，核心能力就是“把你想自动化的任务编排起来”。最常见的场景是持续集成：代码提交到仓库之后，自动触发构建、跑测试、打包，再把产物推到一个统一的位置。
你可以把它理解成一个带调度能力的任务机器人。它本身不写代码、不构建代码，它的工作方式是：你说清楚“什么时候做什么事”，比如“每天晚上十点拉最新代码、跑单元测试、出测试报告”，它就按这个规则去执行。执行的具体动作，由插件和构建任务（Job）来定义。
所以安装 Jenkins 的最终目的，不是把服务跑起来就行，而是让它稳定地成为一个能承载任务编排、插件管理、权限控制、构建记录留存的自动化平台。这决定了你选择安装方式时，不能只图省事。
1.2 三种主流安装方式怎么选
我把常见的安装方式整理成一张选型表，方便你对照自己的场景判断。
| 安装方式 | 适用场景 | 优点 | 需要留意的点 |
|---|---|---|---|
| 官方 war 包 | 本地测试、快速体验、想手动控制一切 | 一条命令启动，升级就是换 war 包 | 服务管理、开机自启要自己配置 |
| 系统包管理器（apt/yum） | 长期运行的服务器、团队共用环境 | 集成 systemd，能开机自启，路径规范，升级方便 | 版本通常会滞后于最新版 |
| Docker | 容器化运维、想隔离环境、快速迁移 | 环境隔离，部署快，回滚方便 | 数据卷管理要小心，日志排查要多一步 |
从我个人的实践来看，并没有“最好”的方式，只有“当前环境最合适”的方式：
- 如果你是刚入门，想最快看到 Jenkins 界面长什么样，war 包最合适，一条 java -jar 就能起来。
- 如果你是在公司服务器上搭一个长期使用的 CI 环境，我推荐系统包管理器或者 Docker。前者胜在原生、稳定、好维护；后者胜在干净、隔离、可复用。
- 如果你所在团队已经有容器化体系，Jenkins 用 Docker 方式跑是顺势而为，后面做备份、迁移、多环境复制都方便。
1.3 建议不要忽略的前置检查项
有一个非常容易被忽略的点：Java 版本。不同版本的 Jenkins 对 JDK 版本有硬性要求。较新版本的 Jenkins 已经不再支持 Java 8，当前建议使用 Java 17（部分旧版本需要 Java 11）。装完 Jenkins 才发现 JDK 版本不匹配，启动会直接报错，报错信息里明确写着“Unsupported Java version”。
检查当前机器的 JDK 版本：
java -version如果提示找不到 java，或者版本过低，先下载安装对应版本的 OpenJDK。这里我建议直接装 JDK 17，因为这是 Jenkins 主流版本推荐的基础运行环境。
另外一个意外但是常见的问题：8080 端口占用。Jenkins 默认监听 8080，如果你本机已经跑了其他开发服务占用这个端口，启动会失败。建议提前确认端口占用情况：
# Linux ss -lntp | grep 8080 # macOS lsof -i :8080提示：端口占用类错误在各类安装方式下都会出现，而且错误日志不算直观，提前检查能省不少时间。
2. 三种安装方式分步实操：从下载到启动一手记录
这一章我按自己实际跑通过的流程来写。你根据自己的选型，跳到自己需要的那一节即可。
2.1 官方 war 包方式：本地快速体验首选
war 方式的核心就两步：下载 war 包，用 Java 启动它。
先去官网下载页获取最新稳定版（lts 版本）的下载链接，然后在服务器上这样操作：
mkdir -p /opt/jenkins && cd /opt/jenkins curl -L -o jenkins.war https://get.jenkins.io/war-stable/latest/jenkins.war下载完成后直接启动：
java -jar jenkins.war --httpPort=8080默认情况下，日志里会打印一段随机管理密码的存储路径，通常在你的用户目录下，形如:
~/.jenkins/secrets/initialAdminPassword启动完成、浏览器访问http://服务器IP:8080，就能看到解锁页面。在这个页面输入的密码，就是上面那个文件里的内容。
war 方式的优点是很轻量，但它不会自动注册成系统服务，服务器重启后 Jenkins 不会自动拉起。如果你要用它做正式环境，需要手动配置一个 systemd 服务。
我习惯的做法是：把 Jenkins 作为独立的系统用户运行，不要用 root 跑。创建用户后，写一个服务配置文件。创建一个服务文件/etc/systemd/system/jenkins.service：
[Unit] Description=Jenkins Service After=network.target [Service] User=jenkins Group=jenkins Environment="JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64" ExecStart=/usr/bin/java -Xms512m -Xmx2048m -jar /opt/jenkins/jenkins.war --httpPort=8080 Restart=on-failure RestartSec=30 [Install] WantedBy=multi-user.target然后刷新服务并设置开机自启：
systemctl daemon-reload systemctl enable jenkins systemctl start jenkins这个配置里我特意加了Restart=on-failure，这样进程因为内存不足等原因挂掉时，systemd 会自动拉起，省掉半夜爬起来重启服务的尴尬。
2.2 系统包管理器方式：服务器长期运维省心路线
如果你用的是 Debian/Ubuntu，或者 CentOS/RHEL 系，系统包管理器方式是最省心的。它会自动创建jenkins用户、注册 systemd 服务、规划好数据目录，路径也相对标准。
以 Debian/Ubuntu 为例，先导入仓库密钥并添加软件源：
curl -fsSL https://pkg.jenkins.io/debian-stable/jenkins.io-2023.key | sudo tee /usr/share/keyrings/jenkins-keyring.asc > /dev/null 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 sudo apt install jenkins安装完成后，状态检查、自启配置都是现成的：
systemctl status jenkins systemctl enable jenkins如果 yum/rpm 系（CentOS、RHEL、Fedora），则需要先下载 Jenkins 仓库配置并执行yum install jenkins，命令结构类似，习惯上就是用systemctl start jenkins来控制。
包管理器安装后，Jenkins 的数据目录默认是/var/lib/jenkins，war 包在/usr/share/java/jenkins.war，配置文件在/etc/default/jenkins（Debian 系）或/etc/sysconfig/jenkins（RHEL 系）。
有一个细节我要重点提醒：包管理器安装的版本会比官方最新版稍微滞后一些，但这通常是件好事，因为仓库里的版本通过了更多环境回归测试，更适合长期稳定的 CI 环境。如果你有一天想升级 Jenkins，直接用包管理器的 update 命令一般就能搞定。
2.3 Docker 方式：干净隔离，迁移灵活
Docker 方式是我现在个人最常用的一种。它最大的好处是环境完全隔离：宿主机里的 JDK、环境变量、目录结构都影响不到 Jenkins，反过来 Jenkins 也污染不了宿主机的全局环境。
直接用官方镜像启动：
docker run -d \ --name jenkins \ -p 8080:8080 \ -p 50000:50000 \ -v jenkins_home:/var/jenkins_home \ -v /etc/localtime:/etc/localtime:ro \ jenkins/jenkins:lts-jdk17解释一下这几个参数：
-p 8080:8080：宿主机 8080 映射到容器 8080，这是 Jenkins Web 访问入口。-p 50000:50000：这是 Jenkins 主节点与构建节点（agent）通信的端口。如果你以后会加构建节点，必须把这个端口透传出来。-v jenkins_home:/var/jenkins_home：给 Jenkins 数据目录挂一个命名卷。所有任务配置、插件、构建记录都写在这里，容器删了数据还在。-v /etc/localtime:/etc/localtime:ro：让容器跟随宿主机时区，避免构建记录的时间比本地时间慢了 8 个小时。
如果你需要持久化到指定的宿主机目录，可以把命名卷替换成绝对路径的 bind mount：
-v /data/jenkins:/var/jenkins_home启动后同样访问http://服务器IP:8080，首次解锁密码需要进入容器读取：
docker exec -it jenkins cat /var/jenkins_home/secrets/initialAdminPasswordDocker 方式还有一个隐性好处：后续你想做版本回退，只需要换回旧镜像重新起一个容器，并把旧数据卷挂回去。比重新装一套环境快得多。不过代价是数据卷管理需要你自己上心，我一般会定期备份整个jenkins_home目录。
3. 第一次启动后的初始化配置：把 Jenkins 调顺手的几个动作
服务能跑起来，只算完成了前半段。第一次打开 Jenkins 界面后，还有几项配置会直接影响你后续的日常使用体验，我按实操顺序讲。
3.1 解锁、选插件、创建管理员账号
第一次访问会引导你走三步：输入管理员密码、安装插件、创建管理员账号。
密码获取这一块，三种安装方式稍有差别：
| 安装方式 | 密码位置 |
|---|---|
| war 包 | 启动时日志输出路径，默认在~/.jenkins/secrets/initialAdminPassword |
| 系统包 | /var/lib/jenkins/secrets/initialAdminPassword |
| Docker | 容器内/var/jenkins_home/secrets/initialAdminPassword |
插件安装这一步，新手容易卡住。界面上有两个选项：“安装推荐的插件”和“选择插件来安装”。我的建议是：如果你不确定需要什么，就选“安装推荐的插件”，它默认包含了 Git、Pipeline、JDK/Maven 勾配管理等基础插件，能覆盖多数常规场景。后续缺什么插件，再在“系统管理-插件管理”里按需装。
插件安装过程在网络状况不佳的时候会变得很慢，甚至卡着不动，这一块放到后面的常见问题里再说。
创建管理员账号这一步，我建议不要偷懒跳过去。虽然 Jenkins 默认也允许你用初始管理员继续用，但长期多人协同时，每个人应该有自己的账号，便于审计操作记录和安全管控。初始管理员密码只用来解锁这一次，解锁后就应该彻底转向正式账号体系。
3.2 JVM 参数与内存策略调整
Jenkins 默认的 JVM 堆内存设置比较保守。如果你打算跑比较多的构建任务，内存不足会导致构建被杀、系统假死。我建议安装完成后就手动调一下 JVM 参数。
常见做法是修改 Jenkins 启动参数中的JAVA_OPTS。不同安装方式调整地方不一样：
- 包管理器方式：Debian 系修改
/etc/default/jenkins，RHEL 系修改/etc/sysconfig/jenkins，找到JAVA_ARGS或JENKINS_JAVA_OPTIONS。 - war 包手动运行：直接改启动命令里的 Java 参数。
- Docker 方式：通过环境变量传入
JAVA_OPTS。
我常用的一组基准参数（按 4G 内存机器估算）：
-Xms512m -Xmx2048m -Duser.timezone=Asia/Shanghai其中-Xms是初始堆内存，-Xmx是最大堆内存。给 Jenkins 分配太多内存不一定好，因为跑构建任务的是执行进程，它们也有自己的资源占用，主机内存要留出余地。一个比较稳妥的经验是：如果机器 8G 内存，Jenkins 堆给到 2G~3G 左右，剩下的留给系统缓存和构建进程。
注意：修改 JVM 参数后，需要重启 Jenkins 服务才会生效。systemd 管理的服务重启命令是
systemctl restart jenkins，Docker 容器则是docker restart jenkins。
3.3 基础配置里我强烈建议立刻改掉的三个默认项
进入“系统管理-系统配置”，有几个选项我建议在第一天就调整掉。
第一个是时区。Jenkins 很多默认时间用的是 UTC，构建历史、定时任务显示的时间会让你在日常沟通中对不上号。安装后就顺手改成本地时区，避免每天看时间还要心算 8 小时。
第二个是“执行者数量”。默认情况下主节点会有 2 个执行器，如果都留给系统本身使用，那主节点基本上只适合管理。别把执行器数量调成 0，除非你打算让所有任务都跑到独立构建节点上，否则主节点至少要留 1 个执行器给系统任务使用。
第三个是“允许用户注册”。默认配置下 Jenkins 是开放注册的，放在公司内网还好，如果是暴露在公网环境，这一步不关就等于是把系统权限拱手让人。请你在系统管理-安全配置里关闭“允许用户注册”，并把安全域设置为“Jenkins 专有用户数据库”，管理员账号建好后就不要再开放自助注册。
3.4 反向代理和访问入口优化
如果你的服务器上还跑了 Nginx 或者其他 Web 服务，通常会希望用域名或者统一的 80/443 端口来访问 Jenkins。这种场景下，Jenkins 本身不需要额外配置，只需要在 Nginx 层做好反向代理，同时把请求头里的 Host 和 X-Forwarded-Proto 正确传给 Jenkins。
一段常见配置长这样：
server { listen 80; server_name ci.example.com; 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_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; } }我把Upgrade和Connection "upgrade"特别标出来了，因为 Jenkins 的 WebSocket 功能（比如实时控制台输出、流水线步骤视图）依赖这些头，漏掉的话界面会出现输出不刷新、控制台空白之类的诡异问题。
4. 安装阶段常见问题与排查实录
这一部分整理的问题是安装阶段我实际碰到过、并且在社群答疑时高频出现的。做成速查表格，方便你按症状找解法。
4.1 安装与启动类问题
| 症状 | 可能原因 | 排查与处理 |
|---|---|---|
| 启动失败，日志提到 Unsupported Java version | JDK 版本与 Jenkins 版本不匹配 | 检查java -version，换 JDK 17（老版本 Jenkins 用 JDK 11） |
| 浏览器访问不了 8080 | 防火墙、安全组规则、端口被占用 | 确认端口监听状态，放行防火墙端口；端口占用就换启动参数或改监听端口 |
| 服务一直处于 activating 状态 | systemd 脚本中 Java 路径或参数配置错误 | 查看journalctl -u jenkins -n 50，修正 ExecStart 配置 |
| 解锁页面打不开 | 容器端口映射没生效或 Jenkins 还在初始化 | 等待几十秒后刷新浏览器；确认容器日志没有异常报错 |
| war 包方式启动后进程退出了 | 内存不足、JVM 参数异常 | 用 `dmesg -T \ |
