环境配置

本章将指导你在不同操作系统上安装和配置 Jenkins。

系统要求

Java 版本要求

Jenkins 对 Java 版本有严格要求，不同版本的 Jenkins 支持不同的 Java 版本：

支持的 Java 版本	LTS 版本	Weekly 版本
Java 21 或 Java 25	-	2.545 (2026年1月)
Java 17、Java 21 或 Java 25	2.541.1 (2026年1月)	2.534 (2025年10月)
Java 17 或 Java 21	2.479.1 (2024年10月)	2.463 (2024年6月)
Java 11、Java 17 或 Java 21	2.426.1 (2023年11月)	2.419 (2023年8月)
Java 11 或 Java 17	2.361.1 (2022年9月)	2.357 (2022年6月)
Java 8、Java 11 或 Java 17	2.346.1 (2022年6月)	2.340 (2022年3月)

重要提示：

如果安装了不支持的 Java 版本，Jenkins 控制器将无法启动
Java 17 支持将于 2026 年 3 月 31 日后结束，建议尽快迁移到 Java 21
这些要求适用于 Jenkins 系统的所有组件，包括控制器、Agent、CLI 客户端等

Jenkins 项目推荐使用 Eclipse Temurin 作为 Java 运行时，这是 Jenkins 官方用于构建和测试的 JDK 发行版。选择 Temurin 的原因包括：

支持多种 Java SE 版本和广泛的平台（不同操作系统和架构）
由 Eclipse 基金会提供定期维护和长期支持
完全开源免费

其他经过测试的 JDK/JRE 也支持使用，如 Amazon Corretto。Jenkins 维护者主要测试基于 HotSpot 的 Java 虚拟机（如 OpenJDK、Eclipse Temurin、Amazon Corretto），但不测试基于 Eclipse OpenJ9 的虚拟机。

最低配置

内存：至少 256MB RAM
磁盘空间：至少 1GB 可用空间（Docker 容器运行建议至少 10GB）
Java：Java 17 或 Java 21（根据 Jenkins 版本选择）

详细硬件建议

对于不同规模的团队，硬件配置建议如下：

规模	内存	磁盘	说明
个人/学习	1-2GB	10GB	单用户，少量任务
小团队	4GB+	50GB+	5-10人，中等构建负载
中型团队	8GB+	100GB+	10-50人，多项目并行
大型团队	16GB+	500GB+	50人以上，高并发构建

Java 环境安装

Jenkins 需要 Java 运行时环境。从 Jenkins 2.462 开始，Jenkins 要求 Java 21 或更高版本。推荐使用 OpenJDK（Eclipse Temurin 是常用的 OpenJDK 发行版）。

Ubuntu/Debian

# 更新包索引
sudo apt update

# 安装 OpenJDK 21 和 fontconfig（Jenkins UI 需要）
sudo apt install -y fontconfig openjdk-21-jre

# 验证安装
java -version

安装成功后，输出应该类似于：

openjdk 21.0.8 2025-07-15
OpenJDK Runtime Environment (build 21.0.8+9-Debian-1)
OpenJDK 64-Bit Server VM (build 21.0.8+9-Debian-1, mixed mode, sharing)

CentOS/RHEL/Rocky Linux/AlmaLinux

# 安装 OpenJDK 21 和 fontconfig
sudo yum install -y fontconfig java-21-openjdk

# 验证安装
java -version

Fedora

# 安装 OpenJDK 21 和 fontconfig
sudo dnf install -y fontconfig java-21-openjdk

# 验证安装
java -version

macOS

# 使用 Homebrew 安装 OpenJDK 21
brew install openjdk@21

# 创建符号链接
sudo ln -sfn /usr/local/opt/openjdk@21/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk-21.jdk

# 验证安装
java -version

Windows

下载 Eclipse Temurin（OpenJDK 发行版）：Adoptium 下载页面
选择 JDK 21 (LTS) 版本，下载 Windows x64 安装程序
运行安装程序，建议安装到默认路径

设置环境变量：

# 设置 JAVA_HOME（管理员权限运行）
[Environment]::SetEnvironmentVariable("JAVA_HOME", "C:\Program Files\Eclipse Adoptium\jdk-21", "Machine")

# 添加到 Path
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";%JAVA_HOME%\bin", "Machine")

重新打开命令提示符，验证安装：
```
java -version
```

Docker 环境

如果使用 Docker 运行 Jenkins，无需单独安装 Java，Jenkins 官方镜像已包含所需的 Java 运行时。

Jenkins 安装

方式一：使用包管理器安装（推荐）

Ubuntu/Debian

Jenkins 提供两种发布版本：LTS（长期支持） 和 每周发布。LTS 版本每 12 周发布一次，更加稳定，适合生产环境；每周发布版本包含最新的功能和修复。

安装 LTS 版本（推荐）：

# 添加 Jenkins 仓库密钥
sudo wget -O /etc/apt/keyrings/jenkins-keyring.asc \
  https://pkg.jenkins.io/debian-stable/jenkins.io-2026.key

# 添加 Jenkins 仓库
echo "deb [signed-by=/etc/apt/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

# 安装 Jenkins
sudo apt install -y jenkins

# 启动 Jenkins 服务
sudo systemctl start jenkins

# 设置开机自启
sudo systemctl enable jenkins

安装每周发布版本：

# 使用 debian 仓库而非 debian-stable
sudo wget -O /etc/apt/keyrings/jenkins-keyring.asc \
  https://pkg.jenkins.io/debian/jenkins.io-2026.key

echo "deb [signed-by=/etc/apt/keyrings/jenkins-keyring.asc]" \
  https://pkg.jenkins.io/debian binary/ | sudo tee \
  /etc/apt/sources.list.d/jenkins.list > /dev/null

sudo apt update
sudo apt install -y jenkins

CentOS/RHEL/Rocky Linux/AlmaLinux

安装 LTS 版本：

# 添加 Jenkins 仓库
sudo wget -O /etc/yum.repos.d/jenkins.repo \
    https://pkg.jenkins.io/rpm-stable/jenkins.repo

# 更新系统
sudo yum upgrade

# 安装依赖
sudo yum install -y fontconfig java-21-openjdk

# 安装 Jenkins
sudo yum install -y jenkins

# 重新加载 systemd 配置
sudo systemctl daemon-reload

# 启动 Jenkins 服务
sudo systemctl start jenkins

# 设置开机自启
sudo systemctl enable jenkins

安装每周发布版本：

# 使用 rpm 仓库而非 rpm-stable
sudo wget -O /etc/yum.repos.d/jenkins.repo \
    https://pkg.jenkins.io/rpm/jenkins.repo

sudo yum upgrade
sudo yum install -y fontconfig java-21-openjdk
sudo yum install -y jenkins

Fedora

# 安装 LTS 版本
sudo wget -O /etc/yum.repos.d/jenkins.repo \
    https://pkg.jenkins.io/rpm-stable/jenkins.repo

sudo dnf upgrade
sudo dnf install -y fontconfig java-21-openjdk
sudo dnf install -y jenkins
sudo systemctl daemon-reload

方式二：使用 Docker 安装

# 拉取 Jenkins 镜像
docker pull jenkins/jenkins:lts

# 创建 Jenkins 数据卷
docker volume create jenkins_home

# 运行 Jenkins 容器
docker run -d \
  --name jenkins \
  -p 8080:8080 \
  -p 50000:50000 \
  -v jenkins_home:/var/jenkins_home \
  jenkins/jenkins:lts

# 查看初始密码
docker exec jenkins cat /var/jenkins_home/secrets/initialAdminPassword

方式三：使用 WAR 文件安装

# 下载 Jenkins WAR 文件
wget https://get.jenkins.io/war-stable/latest/jenkins.war

# 运行 Jenkins
java -jar jenkins.war --httpPort=8080

初始配置

1. 解锁 Jenkins

首次访问 Jenkins 时，需要输入初始管理员密码：

# 查看初始密码
sudo cat /var/lib/jenkins/secrets/initialAdminPassword

在浏览器中访问 http://localhost:8080，粘贴密码并继续。

2. 安装插件

Jenkins 提供两种插件安装选项：

安装建议的插件：适合新手，安装常用插件集合
选择插件来安装：自定义安装需要的插件

推荐初学者选择"安装建议的插件"。

3. 创建管理员用户

填写管理员用户信息：

用户名
密码
全名
电子邮件地址

4. 配置 Jenkins URL

设置 Jenkins 访问地址，可以使用默认配置或自定义域名。

防火墙配置

Ubuntu/Debian (UFW)

# 允许 Jenkins 端口
sudo ufw allow 8080/tcp

# 如果需要 Agent 连接
sudo ufw allow 50000/tcp

# 重新加载防火墙
sudo ufw reload

CentOS/RHEL (Firewalld)

# 允许 Jenkins 端口
sudo firewall-cmd --permanent --add-port=8080/tcp
sudo firewall-cmd --permanent --add-port=50000/tcp

# 重新加载防火墙
sudo firewall-cmd --reload

Jenkins 配置目录

了解 Jenkins 的重要配置文件位置：

操作系统	配置路径
Ubuntu/Debian	`/var/lib/jenkins/`
CentOS/RHEL	`/var/lib/jenkins/`
macOS	`~/.jenkins/`
Windows	`%ProgramFiles%\Jenkins\`
Docker	`/var/jenkins_home/`

重要文件说明

JENKINS_HOME/
├── config.xml              # 主配置文件
├── secrets/                # 敏感信息目录
│   └── initialAdminPassword # 初始管理员密码
├── plugins/                # 插件目录
├── jobs/                   # 任务配置目录
├── users/                  # 用户配置目录
├── nodes/                  # 节点配置目录
└── workspace/              # 工作空间目录

常用管理命令

服务管理

# 启动 Jenkins
sudo systemctl start jenkins

# 停止 Jenkins
sudo systemctl stop jenkins

# 重启 Jenkins
sudo systemctl restart jenkins

# 查看状态
sudo systemctl status jenkins

# 查看日志
sudo journalctl -u jenkins -f

Docker 管理

# 查看容器日志
docker logs -f jenkins

# 进入容器
docker exec -it jenkins bash

# 停止容器
docker stop jenkins

# 启动容器
docker start jenkins

# 删除容器
docker rm -f jenkins

升级 Jenkins

包管理器升级

# Ubuntu/Debian
sudo apt update
sudo apt upgrade jenkins

# CentOS/RHEL
sudo yum update jenkins

Docker 升级

# 拉取最新镜像
docker pull jenkins/jenkins:lts

# 停止并删除旧容器
docker stop jenkins
docker rm jenkins

# 运行新容器（数据卷会自动保留）
docker run -d \
  --name jenkins \
  -p 8080:8080 \
  -p 50000:50000 \
  -v jenkins_home:/var/jenkins_home \
  jenkins/jenkins:lts

备份与恢复

备份 Jenkins

# 停止 Jenkins
sudo systemctl stop jenkins

# 创建备份
sudo tar -czvf jenkins_backup_$(date +%Y%m%d).tar.gz /var/lib/jenkins/

# 启动 Jenkins
sudo systemctl start jenkins

恢复 Jenkins

# 停止 Jenkins
sudo systemctl stop jenkins

# 恢复备份
sudo tar -xzvf jenkins_backup_20240101.tar.gz -C /

# 确保权限正确
sudo chown -R jenkins:jenkins /var/lib/jenkins

# 启动 Jenkins
sudo systemctl start jenkins

常见问题

1. 端口冲突

如果 8080 端口被占用，可以修改端口：

# 编辑配置文件
sudo nano /etc/default/jenkins  # Ubuntu/Debian
sudo nano /etc/sysconfig/jenkins # CentOS/RHEL

# 修改 HTTP_PORT
HTTP_PORT=8081

# 重启 Jenkins
sudo systemctl restart jenkins

2. 内存不足

如果遇到内存问题，可以调整 JVM 参数：

# 编辑配置文件
sudo nano /etc/default/jenkins

# 修改 JAVA_OPTS
JAVA_OPTS="-Djava.awt.headless=true -Xmx2048m -Xms512m"

# 重启 Jenkins
sudo systemctl restart jenkins

3. 权限问题

确保 Jenkins 用户有正确的权限：

# 添加 Jenkins 用户到 docker 组（如果使用 Docker）
sudo usermod -aG docker jenkins

# 添加 Jenkins 用户到 sudo 组（如果需要）
sudo usermod -aG sudo jenkins

下一步

完成环境配置后，你可以：

系统要求​

Java 版本要求​

最低配置​

推荐配置（小团队）​

详细硬件建议​

Java 环境安装​

Ubuntu/Debian​

CentOS/RHEL/Rocky Linux/AlmaLinux​

Fedora​

macOS​

Windows​

Docker 环境​

Jenkins 安装​

方式一：使用包管理器安装（推荐）​

Ubuntu/Debian​

CentOS/RHEL/Rocky Linux/AlmaLinux​

Fedora​

方式二：使用 Docker 安装​

方式三：使用 WAR 文件安装​

初始配置​

1. 解锁 Jenkins​

2. 安装插件​

3. 创建管理员用户​

4. 配置 Jenkins URL​

防火墙配置​

Ubuntu/Debian (UFW)​

CentOS/RHEL (Firewalld)​

Jenkins 配置目录​

重要文件说明​

常用管理命令​

服务管理​

Docker 管理​

升级 Jenkins​

包管理器升级​

Docker 升级​

备份与恢复​

备份 Jenkins​

恢复 Jenkins​

常见问题​

1. 端口冲突​

2. 内存不足​

3. 权限问题​

下一步​

系统要求

Java 版本要求

最低配置

推荐配置（小团队）

详细硬件建议

Java 环境安装

Ubuntu/Debian

CentOS/RHEL/Rocky Linux/AlmaLinux

Fedora

macOS

Windows

Docker 环境

Jenkins 安装

方式一：使用包管理器安装（推荐）

Ubuntu/Debian

CentOS/RHEL/Rocky Linux/AlmaLinux

Fedora

方式二：使用 Docker 安装

方式三：使用 WAR 文件安装

初始配置

1. 解锁 Jenkins

2. 安装插件

3. 创建管理员用户

4. 配置 Jenkins URL

防火墙配置

Ubuntu/Debian (UFW)

CentOS/RHEL (Firewalld)

Jenkins 配置目录

重要文件说明

常用管理命令

服务管理

Docker 管理

升级 Jenkins

包管理器升级

Docker 升级

备份与恢复

备份 Jenkins

恢复 Jenkins

常见问题

1. 端口冲突

2. 内存不足

3. 权限问题

下一步