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/终端执行）：

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 权限）：

# 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 安装（推荐）

# 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 功能扩展的核心，日常需根据项目需求安装对应插件，操作步骤：

1. 进入 Jenkins 主页面，点击左侧"系统管理" → "插件管理"。

2. 切换到"可选插件"标签页，在搜索框中输入插件名称（如 Git、Maven），勾选对应插件，点击"直接安装"。

3. 安装完成后，部分插件需要重启 Jenkins 才能生效，点击页面提示的"重启 Jenkins"即可。

4. 卸载插件：切换到"已安装"标签页，找到需卸载的插件，点击"卸载"，重启 Jenkins 生效。

5. 更新插件：切换到"已安装"标签页，若插件有更新，会显示"可更新"，勾选后点击"下载待更新插件并重启 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）创建任务

1. 进入 Jenkins 主页面，点击左侧"新建任务"。

2. 填写任务名称（如 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）执行任务与查看结果

1. 配置完成后，点击页面底部"保存"，返回任务页面。

2. 点击左侧"立即构建"，Jenkins 会开始执行任务，页面会显示构建进度（蓝色球表示正在构建，蓝色球带对勾表示构建成功，红色球表示构建失败）。

3. 查看构建详情：点击构建记录（如 #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. 步骤 1：配置 Jenkins 全局工具（JDK、Maven、Git）参考"三、核心操作 → 2. 全局配置"，完成 JDK11、Maven3.8、Git 的配置。

2. 步骤 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. 步骤 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. 步骤 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 配置，进一步提升开发和部署效率。