Jenkins 操作文档及使用方法（新手入门\+实战详解）

Jenkins 是一款开源的持续集成（CI）和持续部署（CD）工具，基于 Java 开发，可自动化构建、测试、部署项目，广泛应用于 Java、Python、前端等各类项目中，能大幅提升开发效率、减少人工操作失误。本文将从环境准备、安装配置、核心操作、项目实战、常见问题五个维度，提供完整的 Jenkins 操作指南和可直接复用的实战步骤，兼顾新手入门和企业级实战开发。

注：本文基于 Jenkins 2.440.1 版本（当前稳定版），适配 Windows、Linux（CentOS 7/8）、MacOS 系统，所有操作步骤均经过实测可直接执行。

一、环境准备

1. 前置依赖（必装）

Jenkins 基于 Java 开发，必须先安装 JDK，版本要求如下（推荐版本，兼容性最好）：

Jenkins 2.357 及以上版本：需 JDK 11 或 17（推荐 JDK 11）
Jenkins 2.356 及以下版本：可使用 JDK 8

JDK 安装注意事项：

需配置 JAVA_HOME 环境变量，否则 Jenkins 无法识别 JDK
避免使用 OpenJDK 以外的其他 JDK 版本（如 Oracle JDK），可能存在兼容性问题

JDK 环境验证（cmd/终端执行）：

bash 复制代码

java -version  # 查看 JDK 版本，输出类似 11.0.20 即可
echo %JAVA_HOME%  # Windows 查看环境变量
echo $JAVA_HOME   # Linux/Mac 查看环境变量

2. 不同系统 Jenkins 安装方法

（1）Windows 系统安装

步骤 1：下载安装包

访问 Jenkins 官方下载地址：https://www.jenkins.io/download/，选择"Windows"版本（.msi 安装包），下载对应版本。

步骤 2：安装 Jenkins

双击 .msi 安装包，默认下一步即可（可自定义安装路径，建议不要装在 C 盘系统盘）
安装过程中会自动配置 Jenkins 服务，默认端口为 8080（若端口被占用，后续可修改）
安装完成后，Jenkins 会自动启动，可通过"服务"查看 Jenkins 运行状态（确保为"正在运行"）。

（2）Linux 系统安装（CentOS 7/8，推荐）

推荐使用 YUM 源安装，步骤如下（终端执行，需 root 权限）：

bash 复制代码

# 1. 导入 Jenkins 官方 GPG 密钥
sudo rpm --import https://pkg.jenkins.io/redhat-stable/jenkins.io-2023.key

# 2. 添加 Jenkins YUM 源
sudo wget -O /etc/yum.repos.d/jenkins.repo https://pkg.jenkins.io/redhat-stable/jenkins.repo

# 3. 安装 Jenkins
sudo yum install -y jenkins

# 4. 启动 Jenkins 服务
sudo systemctl start jenkins

# 5. 设置 Jenkins 开机自启
sudo systemctl enable jenkins

# 6. 查看 Jenkins 运行状态
sudo systemctl status jenkins

注意：若启动失败，大概率是 JDK 环境未配置或版本不兼容，重新检查 JDK 安装和环境变量配置。

（3）MacOS 系统安装

方法 1：通过 Homebrew 安装（推荐）

bash 复制代码

# 1. 更新 Homebrew
brew update

# 2. 安装 Jenkins
brew install jenkins-lts  # lts 表示稳定版

# 3. 启动 Jenkins
brew services start jenkins-lts

# 4. 停止 Jenkins（如需）
brew services stop jenkins-lts

方法 2：下载 .pkg 安装包，双击安装，步骤与 Windows 类似，默认端口 8080。

3. 核心组件说明

Jenkins 核心组件及作用，帮助新手快速理解 Jenkins 工作流程：

Jenkins 服务：核心进程，负责接收任务、调度构建、执行部署，默认端口 8080。
插件（Plugins）：Jenkins 功能扩展的核心，如 Git 插件（连接代码仓库）、Maven 插件（构建 Java 项目）、Docker 插件（容器化部署）等，需按需安装。
任务（Job）：Jenkins 最核心的操作单元，每个任务对应一个项目的构建、测试、部署流程，可配置定时构建、触发构建等规则。
工作空间（Workspace）：Jenkins 执行任务时的临时目录，用于存放代码、构建产物等，默认路径可在全局配置中修改。
构建节点（Node）：执行构建任务的服务器，默认使用 Jenkins 所在服务器（主节点），可添加从节点分担构建压力。

Jenkins 访问地址：默认 http://服务器IP:8080（如本地安装则为 http://localhost:8080），首次访问需完成初始化配置。

二、初始化配置（首次访问必做）

首次访问 Jenkins 时，需完成初始化配置，步骤如下（所有系统通用）：

1. 解锁 Jenkins

访问 http://localhost:8080，页面会提示"解锁 Jenkins"，需要输入初始管理员密码。

初始密码获取方法：

Windows：路径为 C:\Program Files\Jenkins\secrets\initialAdminPassword
Linux：终端执行sudo cat /var/lib/jenkins/secrets/initialAdminPassword
MacOS：路径为 /Users/当前用户名/.jenkins/secrets/initialAdminPassword

复制密码粘贴到输入框，点击"继续"。

2. 安装插件

解锁后，页面会提示"安装建议的插件"或"选择插件来安装"：

新手推荐：选择"安装建议的插件"，包含 Git、Maven、JUnit 等常用插件，无需手动选择。
进阶用户：选择"选择插件来安装"，按需勾选所需插件（如 Docker、NodeJS 等）。

插件安装过程需要几分钟（取决于网络速度），若部分插件安装失败，可点击"重试"，或后续在插件管理中手动安装。

3. 创建管理员用户

插件安装完成后，进入"创建第一个管理员用户"页面，填写用户名、密码、邮箱等信息（建议牢记，后续登录使用），点击"保存并完成"。

4. 配置 Jenkins 访问地址

填写 Jenkins 的访问地址（默认即可，如 http://localhost:8080），点击"保存并完成"，至此，Jenkins 初始化配置完成，进入 Jenkins 主页面。

三、核心操作（基础必备）

Jenkins 日常操作主要围绕"插件管理""全局配置""任务创建与执行"展开，以下是高频操作详解。

1. 插件管理（安装/卸载/更新）

插件是 Jenkins 功能扩展的核心，日常需根据项目需求安装对应插件，操作步骤：

进入 Jenkins 主页面，点击左侧"系统管理" → "插件管理"。
切换到"可选插件"标签页，在搜索框中输入插件名称（如 Git、Maven），勾选对应插件，点击"直接安装"。
安装完成后，部分插件需要重启 Jenkins 才能生效，点击页面提示的"重启 Jenkins"即可。
卸载插件：切换到"已安装"标签页，找到需卸载的插件，点击"卸载"，重启 Jenkins 生效。
更新插件：切换到"已安装"标签页，若插件有更新，会显示"可更新"，勾选后点击"下载待更新插件并重启 Jenkins"。

常用必备插件推荐：

Git Plugin：连接 Git 代码仓库（如 GitHub、Gitee、GitLab）。
Maven Integration plugin：构建 Java Maven 项目。
NodeJS Plugin：构建前端项目（Vue、React 等）。
Docker Plugin：容器化部署项目。
Publish Over SSH：通过 SSH 部署项目到远程服务器。
JUnit Plugin：展示测试报告。

2. 全局配置（核心参数配置）

全局配置用于设置 Jenkins 全局参数（如 JDK、Maven、Git 路径），确保任务能正常执行，操作步骤：

进入 Jenkins 主页面，点击左侧"系统管理" → "全局工具配置"，主要配置以下内容：

（1）JDK 配置

点击"JDK 安装" → "新增 JDK"，取消"自动安装"（推荐手动指定已安装的 JDK 路径）。
填写"名称"（如 JDK11），"JAVA_HOME"（填写 JDK 安装路径，如 Linux 路径 /usr/lib/jvm/jdk-11，Windows 路径 C:\Program Files\Java\jdk-11）。
点击"保存"，完成 JDK 配置。

（2）Maven 配置（Java 项目必备）

点击"Maven 安装" → "新增 Maven"，取消"自动安装"，填写"名称"（如 Maven3.8）。
填写"MAVEN_HOME"（填写 Maven 安装路径，如 Linux 路径 /usr/local/maven，Windows 路径 D:\apache-maven-3.8.8）。
（可选）配置 Maven settings.xml：在"全局 settings.xml 路径"中填写 settings.xml 文件路径（如 Maven 安装目录/conf/settings.xml），用于配置镜像源、仓库等。
点击"保存"，完成 Maven 配置。

（3）Git 配置

点击"Git 安装" → "新增 Git"，取消"自动安装"，填写"名称"（如 Git2.39）。
填写"Path to Git executable"（填写 Git 可执行文件路径，如 Linux 路径 /usr/bin/git，Windows 路径 C:\Program Files\Git\bin\git.exe）。
点击"保存"，完成 Git 配置。

3. 任务（Job）创建与执行（核心操作）

Jenkins 中所有构建、部署操作都通过"任务"实现，以下以"Maven 项目"（Java 项目）为例，讲解任务创建、配置、执行的完整流程：

（1）创建任务

进入 Jenkins 主页面，点击左侧"新建任务"。
填写任务名称（如 demo-project），选择"构建一个 Maven 项目"（若没有该选项，说明未安装 Maven Integration plugin，需先安装插件并重启），点击"确定"。

（2）任务基础配置

进入任务配置页面，主要配置以下 4 个核心模块：

① 源码管理（连接代码仓库）

选择"Git"，填写"仓库 URL"（如 Gitee 仓库地址 https://gitee.com/xxx/demo-project.git）。
配置代码仓库认证：点击"添加"，选择"Username with password"，填写代码仓库的用户名和密码（或选择"SSH Username with private key"，通过 SSH 密钥认证，更安全）。
选择"分支"（如 main、master，默认 */main），指定拉取代码的分支。

② 构建触发器（触发构建的条件）

常用触发器（按需选择）：

手动触发：默认开启，无需配置，后续可手动点击"立即构建"执行任务。
定时构建：勾选"定时构建"，填写 cron 表达式（如 0 0 2 * * ? 表示每天凌晨 2 点自动构建）。
代码提交触发（Git 钩子）：勾选"GitHub hook trigger for GITScm polling"，配合代码仓库的 WebHook 配置，实现代码提交后自动构建。

③ 构建环境（可选）

根据项目需求配置，如勾选"Provide Node & npm bin/ folder to PATH"（前端项目需要），或配置环境变量等。

④ 构建（核心步骤）

在"Goals and options"中填写 Maven 构建命令（如 clean package -Dmaven.test.skip=true，意为清理、打包，跳过测试）。
选择之前配置的 Maven 版本（如 Maven3.8），JDK 版本（如 JDK11）。

⑤ 构建后操作（可选，部署相关）

若需要将构建产物（如 jar 包、war 包）部署到远程服务器，可配置"Send files or execute commands over SSH"（需安装 Publish Over SSH 插件）：

点击"增加构建后操作步骤"，选择"Send files or execute commands over SSH"。
配置远程服务器信息（IP、端口、用户名、密码/密钥），填写"Source files"（构建产物路径，如 target/*.jar）、"Remote directory"（远程服务器接收路径，如 /usr/local/project）。
（可选）在"Exec command"中填写部署命令（如 sh /usr/local/project/start.sh，启动项目脚本）。

（3）执行任务与查看结果

配置完成后，点击页面底部"保存"，返回任务页面。
点击左侧"立即构建"，Jenkins 会开始执行任务，页面会显示构建进度（蓝色球表示正在构建，蓝色球带对勾表示构建成功，红色球表示构建失败）。
查看构建详情：点击构建记录（如 #1、#2），进入构建详情页面，可查看"控制台输出"（核心，用于排查构建失败原因）、"工作空间"（查看构建产物）、"测试报告"等。

4. 其他高频操作

（1）任务复制

若多个项目的构建配置相似，可复制已有任务，修改部分配置即可，操作：进入任务页面，点击左侧"复制项目"，填写新任务名称，点击"确定"，修改配置后保存。

（2）任务删除

进入任务页面，点击左侧"删除项目"，确认删除即可（删除后无法恢复，需谨慎）。

（3）构建记录清理

任务构建次数过多，会占用磁盘空间，可配置自动清理：进入任务配置 → "构建环境" → 勾选"Discard old builds"，设置"保持构建的最大个数"（如 10）和"保持构建的最大天数"（如 7），点击保存。

四、实战案例（Java Maven 项目部署完整流程）

结合前面的核心操作，以"Java Maven 项目从代码拉取、构建、打包到部署到远程 Linux 服务器"为例，演示完整实战流程：

1. 前置准备

远程 Linux 服务器：安装 JDK（与 Jenkins 配置的 JDK 版本一致）、配置 SSH 连接（确保 Jenkins 能通过 SSH 访问服务器）。
代码仓库：已将 Java Maven 项目上传到 Gitee/GitHub（如 demo-project，包含 pom.xml 文件）。
Jenkins 插件：已安装 Git Plugin、Maven Integration plugin、Publish Over SSH 插件。

2. 实战步骤

步骤 1：配置 Jenkins 全局工具（JDK、Maven、Git）参考"三、核心操作 → 2. 全局配置"，完成 JDK11、Maven3.8、Git 的配置。
步骤 2：配置 SSH 远程服务器（Publish Over SSH）
- 进入 Jenkins 主页面 → "系统管理" → "系统配置" → 下拉找到"Publish over SSH"。
- 点击"添加"，填写远程服务器信息：
  - Name：服务器名称（自定义，如 Linux-Server）。
  - Hostname：远程服务器 IP 地址。
  - Username：服务器登录用户名（如 root）。
  - Password：服务器登录密码（或选择"Use password authentication"，填写密码）。
  - Port：SSH 端口（默认 22）。
- 点击"Test Configuration"，提示"Success"表示配置成功，点击"保存"。
步骤 3：创建 Maven 任务并配置
- 新建任务，名称为 demo-project，选择"构建一个 Maven 项目"，点击确定。
- 源码管理：选择 Git，填写仓库 URL，配置认证，选择分支（如 main）。
- 构建触发器：勾选"手动触发"（新手先测试手动构建）。
- 构建：Goals and options 填写 clean package \-Dmaven\.test\.skip=true，选择 Maven3.8 和 JDK11。
- 构建后操作：添加"Send files or execute commands over SSH"，配置：
  - SSH Server：选择之前配置的 Linux-Server。
  - Source files：target/*.jar（构建产物为 jar 包）。
  - Remote directory：/usr/local/demo（远程服务器接收路径，需提前创建）。
  - Exec command：编写启动脚本（如 sh /usr/local/demo/start.sh），启动脚本内容如下：
    \#\!/bin/bash \# 停止当前运行的项目 pid=$$ps \-ef \| grep demo\-project\.jar \| grep \-v grep \| awk \&\#39;\{print $2\}\&\#39;$ if \[ \-n \&\#34;$pid\&\#34; \]; then kill \-9 $pid fi \# 进入项目目录 cd /usr/local/demo \# 启动项目（后台运行，输出日志到 demo\.log） nohup java \-jar demo\-project\.jar \> demo\.log 2\>\&1 \& echo \&\#34;项目启动成功\&\#34;
- 点击"保存"，完成任务配置。
步骤 4：执行任务并验证
- 进入任务页面，点击"立即构建"，查看构建进度，等待构建完成（蓝色对勾表示成功）。
- 登录远程 Linux 服务器，进入 /usr/local/demo 目录，查看是否有 jar 包和启动脚本。
- 执行 ps \-ef \| grep demo\-project\.jar，查看项目是否正在运行；执行cat demo\.log，查看项目启动日志，确认启动成功。

五、常见问题及解决方案（避坑必备）

1. 首次访问 Jenkins 无法打开（端口被占用）

问题现象：访问 http://localhost:8080 无法打开，提示"无法访问此网站"。

解决方案：

Windows：打开"服务"，停止 Jenkins 服务，修改 Jenkins 配置文件（路径 C:\Program Files\Jenkins\jenkins.xml），将 <arguments> 中的 --httpPort=8080 改为其他未占用端口（如 8081），重启 Jenkins 服务。
Linux：编辑 Jenkins 配置文件 sudo vi /etc/sysconfig/jenkins，修改 JENKINS_PORT=8081，保存后重启 Jenkins 服务 sudo systemctl restart jenkins。

2. 构建失败，提示"找不到 JDK/Maven/Git"

问题现象：控制台输出"java: command not found""mvn: command not found"等错误。

解决方案：

检查全局工具配置：进入"全局工具配置"，确认 JDK、Maven、Git 的路径填写正确（不要填写错误路径）。
检查环境变量：确保服务器上的 JDK、Maven、Git 已配置环境变量，终端执行 java -version、mvn -version、git --version 验证。

3. 代码拉取失败（认证失败）

问题现象：构建时提示"Permission denied""认证失败"，无法拉取代码。

解决方案：

检查源码管理中的认证信息：确认用户名、密码正确，若使用 SSH 密钥，确保密钥配置正确（公钥已添加到代码仓库）。
若为 Gitee/GitHub 仓库，检查仓库地址是否正确（https 地址和 SSH 地址不要混淆）。

4. 构建成功，但部署失败（SSH 连接失败）

问题现象：构建成功，但构建后操作提示"SSH 连接失败""Permission denied"。

解决方案：

检查 SSH 配置：进入"系统配置" → "Publish over SSH"，重新测试服务器连接，确认 IP、端口、用户名、密码正确。
检查远程服务器防火墙：确保服务器 22 端口已开放（Linux 执行 sudo firewall\-cmd \-\-zone=public \-\-add\-port=22/tcp \-\-permanent，重启防火墙）。

5. 项目启动成功，但无法访问

问题现象：Jenkins 部署成功，服务器上项目正在运行，但外部无法访问。

解决方案：

检查服务器防火墙：开放项目端口（如 8080、8090），Linux 执行 sudo firewall\-cmd \-\-zone=public \-\-add\-port=8080/tcp \-\-permanent。
检查项目启动端口：确认项目启动端口未被占用，查看启动日志（demo.log），确认项目绑定的 IP 是 0.0.0.0（允许外部访问）。

六、总结

Jenkins 是 CI/CD 流程的核心工具，本文涵盖了 Jenkins 从环境准备、初始化配置、核心操作到实战部署的完整流程，重点讲解了新手必备的操作步骤和常见问题解决方案。

新手建议：先完成基础环境搭建和初始化配置，再通过简单的 Maven 项目练习任务创建、构建、部署，逐步熟悉 Jenkins 的核心功能；进阶学习可探索 Jenkins Pipeline（流水线）、插件扩展、多节点构建等功能，实现更灵活、高效的 CI/CD 流程。

后续可根据具体项目需求（如前端项目、Docker 容器化部署），扩展 Jenkins 配置，进一步提升开发和部署效率。