jenkins操作手册——巨详细，一篇足矣

一、持续集成相关概念

1.1、什么是持续集成？

随着软件开发复杂度的不断提高,团队开发成员间如何更好的协同工作以确保软件开发的质量已经成为开发过程中不可回避的问题。尤其是近年来敏捷开发在软件领域越来越火，如何能在不间断变化的需求中快速适应和保证软件的质量显得尤其重要。持续集成正是针对这一问题的一种软件开发实践。它倡导团队开发成员必须经常集成他们的工作，甚至每天都可能发生多次集成。而每次集成都是通过自动化的构建来验证，包括自动编译、发布和测试，从而尽快地发现集成错误，让团队能更快的开发内聚的软件。

1.2、持续集成的原则

• 需要版本控制工具来保障团队成员提交的代码不会导致集成失败。常用的版本控制工具有cvs、subversion、git、sourcesafe等；
• 开发人员需要及时向版本控制库中提交代码，也需要经常性地从版本控制库中更新代码到本地；
• 需要有专门的集成服务器来执行集成构建。根据项目的实际情况，集成构建可以通过代码仓库中代码的变动（如push事件、merge事件等）来自动触发构建，也可以定时启动构建，如每半小时构建一次；
• 必须保证构建的成功。如果构建失败，则修复构建过程中的错误将是优先级最高的工作。一旦修复，需手动启动一次构建。
• 一个自动构建过程，包括自动编译、分发、部署和测试等；
• 一个代码仓库，即需要版本控制工具来保障代码的可维护性，同时作为构建过程的素材库；
• 一个持续集成服务器。即将介绍的Jenkins就是一个配置简单和使用方便的持续集成服务器。

1.3、持续集成系统的组成

二、Jenkins简介和插件

2.1、Jenkins简介

Jenkins是一个开源项目，提供了一种易于使用的持续集成系统，使开发者从繁杂的集成中解脱出来，专注于更重要的业务逻辑实现上。同时Jenkins能实时监控集成中存在的错误，提供详细的日志文件和提醒功能，还能用图表的形式形象的展示项目构建的趋势和稳定性。

2.2、插件介绍

Jenkins提供了大量的插件，这些插件使Jenkins能实现很多复杂的功能。下面列出了部分持续集成所需的插件：

• Email Extension Plugin，邮件通知插件。例如，构建失败或成功后可以发送相关信息到指定的邮箱；
• Publish Over SSH ，用于远程服务器发布，将编译生成的jar、war等文件推送到远程服务器中指定的目录；
• Maven Integration plugin ，Maven集成插件，缺少此插件则新建任务时没有Maven Project选项；
• GitLab，用于从指定的代码仓库中拉取需要构建的代码；
• Sonar scanner，用于构建前或构建后对代码进行扫描；
• Git parameter，基于Git的参数化构建；
• HTML Publisher plugin，用于在Jenkins中配置HTML格式的报告；
• Groovy Label Assignment plugin，用于执行Groovy代码；
• NodeJS plugin，配置JavaScript的运行环境，作为前端代码的打包工具或构建工具；

2.3、插件安装

安装插件的步骤：在面板界面左侧的导航栏中选择Manager Jenkins ---> System Configuration ---> Manager Plugins，在插件管理页面中点击“可选插件”选项卡，然后在输入框中填写需要安装的插件名字。

三、全局工具配置

全局工具配置主要对一些常用工具的名称、版本、路径和配置文件进行设定。在面板左侧的导航栏中点击“系统管理”，进入到“管理Jenkins”界面，选择界面中的System Configuration ---> Global Tool Configuration后进入到“全局工具配置”界面，依次对Maven配置、JDK、Git、Maven、NodeJS、Sonar Scanner等进行配置。

3.1、Maven配置

主要用于Maven的主配置文件settings.xml的设定。settings.xml包含仓库镜像、本地镜像和认证信息等。一般默认的路径有两种：Global Maven Settings --- ${M2_HOME}/conf/settings.xml；User Maven Settings --- ${user.HOME}/.m2/settings.xml。如果两个文件都存在，会对内容进行合并，优先应用当前目录下settings.xml中的设定。

 

3.2、JDK

如果已经安装过JDK，这里需要配置JDK的JAVA_HOME。

3.3、Git

Git的配置也很重要，因为大多数的任务都要获取Git仓库中的代码，所以这里需要配置Git的执行路径。

 

3.4、Maven

主要用于配置Maven的主目录，可以添加多个，用Name来区分。如果系统中已经安装Maven，这里直接填写MAVEN_HOME对应的路径，Jenkins会在Master节点上进行检查，查看该目录是否有效。

 

3.5、SonarQube Scanner

SonarQube Scanner用于代码的静态质量扫描，可以自动安装，也可以手动将其安装在Master服务器上。这里采用的是自动安装，在“版本”下拉选框中选择所要安装的版本号即可。

3.6、NodeJS

NodeJS是一个JavaScript的运行环境，作为打包工具或者构建工具。如果要在Jenkins中实现编译、打包前端代码，则需要安装此软件。

 

四、系统配置

在Jenkins主面板左侧的导航栏中选择“系统管理”，进入到“管理Jenkins”界面，点击此界面中“系统配置”模块下的“系统配置”选项，进入到“配置”界面。

4.1、Jenkins Location

此项是可选的，指定安装Jenkins的HTTP地址。这个值用来在邮件中生产Jenkins链接。此项是有必要的，因为Jenkins无法探测到自己的URL地址。

4.2、SonarQube servers

配置SonarQube所在服务器的信息，建立Jenkins和SonarQube之间的通信。

Name：自定义一个适合的名字；

Server URL：SonarQube所在服务器的URL（IP或域名加端口，端口号默认为9000）；

Server authentication token：这里填写SonarQube服务器当前用户的令牌。

SonarQube令牌的生成方法：登陆SonarQube服务器，选择“头像”--->“我的账号”--->“安全”--->在“生成令牌”文本框中输入自定义的名称，然后点击“生成”按钮。生成的令牌ID只会显示一次，所以如果有需要，可以进行备份

生成SonarQube当前用户的令牌ID后，回到Jenkins的系统配置界面，并定位到“SonarQube servers”模块，点击“Server authentication token”选项的“添加”按钮，选择“Jenkins”，进入到“添加凭据”窗口。

类型：选择Secret text；

Secret：填入SonarQube当前用户生成的令牌ID；

ID：自定义一个名称。

填写完毕后，点击“添加”按钮，然后在“Server authentication token”的下拉选框中选择相应的凭据即可。

4.3、GitLab

配置将要构建的代码所在的GitLab服务器信息，建立Jenkins和GitLab服务器之间的通信。

Connection name：自定义一个名称；

Gitlab host URL：GItLab所在服务器的HTTP地址；

Credentials：添加GitLab API token，该token由GItLab生成。

GitLab API token的生成方法：进入GitLab主页，点击页面右上角的头像，在出现的悬框中点击“Settings”，进入到设置界面。在设置界面左侧的导航栏中点击“Access Token”，进入“Access Token”界面。

Name：自定义一个名称；

Expires at：添加生成token的时间（非必填项）；

Scopes：勾选api复选框；

Create personal access token：点击此按钮后会生成一个token，且生成的token会展示在“Active Personal Access Tokens”列表中。

生成GitLab API token后，回到Jenkins的系统配置界面，并定位到GitLab模块。点击Credentials的“添加”按钮，选择“jenkins”，进入到“添加凭据”窗口。

类型：选择GitLab API token；

API token：填入在GitLab中生成的API token；

ID：自定义一个名称（非必填项）。

所需的信息配置完毕后，点击“Test Connection”按钮，测试Jenkins和GitLab之间的连接是否成功。

4.4、Publish over SSH

若要将构建后生成的jar包（后端）或dist目录文件（前端）推送到远程服务器中，需配置此模块。在此我们选择用户名和密码来连接远程服务器。

Name：自定义一个名称。在Job中使用Publish over SSH插件时，此名称将出现在“SSH Server”中“Name”选项的下拉列表中；

Hostname：服务器的主机名或IP地址；

Username：服务器的用户名；

Remote Directory：远程服务器上真实存在的目录，而且“Username”指定的用户要有访问此文件夹的权限，插件将把文件推送到此目录下；

Use password authentication, or use a different key：勾选此选项，并在“Passphrase / Password”中输入与Username匹配的密码。

配置完后点击“Test Configuration”，测试是否可以连接成功。

 

4.5、Extended E-mail Notification

在Jenkins的使用中邮件提醒是一个常用功能，Jenkins默认安装了 Mailer Plugin插件用于实现此功能，但 Mailer Plugin功能简单不能满足一些复杂需求，如：自定义邮件标题、内容等。Extended E-mail Notification(ext mail)是一个功能更为齐全，使用也更为复杂的插件。下面对此插件的配置做简要的说明。

 

SMTP Server：SMTP服务器的地址；

SMPT Port：SMTP的端口号，默认为25；

SMTP Username：即在Jenkins Location模块中填写的“系统管理员邮件地址”；

SMTP Password：“系统管理员邮件地址”所对应的密码；

Default user E-mail suffix：默认的邮箱后缀；

Default Content Type：默认的邮件内容格式；

Default Recipients：默认收件人的邮箱地址（可填写多个，中间用英文逗号隔开即可）；

Default Subject：邮件标题。例如，$PROJECT_NAME - Build # $BUILD_NUMBER - $BUILD_STATUS!。其中，$PROJECT_NAME为构建项目名称，$BUILD_NUMBER为构建编号，$BUILD_STATUS为构建状态；

Default Content：邮件内容；

 1 <!DOCTYPE html>  
 2 <html>  
 3 <head>  
 4 <meta charset="UTF-8">  
 5 <title>${ENV, var="JOB_NAME"}-第${BUILD_NUMBER}次构建日志</title>  
 6 </head>  
 7    
 8 <body leftmargin="8" marginwidth="0" topmargin="8" marginheight="4"  
 9     offset="0">  
10     <table width="95%" cellpadding="0" cellspacing="0"  
11         style="font-size: 11pt; font-family: Tahoma, Arial, Helvetica, sans-serif">  
12         <tr>  
13             <td>(本邮件由Jenkins系统自动发布，请勿回复！)</td>  
14         </tr>  
15         <tr>  
16             <td><h2>  
17                     <font color="#0000FF">构建结果 - ${BUILD_STATUS}</font>  
18                 </h2></td>  
19         </tr>  
20         <tr>  
21             <td><br />  
22             <b><font color="#0B610B">构建信息</font></b>  
23             <hr size="2" width="100%" align="center" /></td>  
24         </tr>  
25         <tr>  
26             <td>  
27                 <ul>  
28                     <li>项目名称： ${PROJECT_NAME}</li>  
29                     <li>构建编号： 第${BUILD_NUMBER}次构建</li>  
30                     <li>构建状态： ${BUILD_STATUS}</li>  
31                     <li>触发原因： ${CAUSE}</li>  
32                     <li>构建日志： <a href="${BUILD_URL}console">${BUILD_URL}console</a></li>  
33                     <li>构建  Url ： <a href="${BUILD_URL}">${BUILD_URL}</a></li>  
34                     <li>工作目录 ： <a href="${PROJECT_URL}ws">${PROJECT_URL}ws</a></li>  
35                     <li>项目  Url ： <a href="${PROJECT_URL}">${PROJECT_URL}</a></li>  
36                 </ul>  
37             </td>  
38         </tr>  
39         <tr>  
40             <td><b><font color="#0B610B">Changes Since Last  
41                         Successful Build:</font></b>  
42             <hr size="2" width="100%" align="center" /></td>  
43         </tr>  
44         <tr>  
45             <td>  
46                 <ul>  
47                     <li>历史变更记录 : <a href="${PROJECT_URL}changes">${PROJECT_URL}changes</a></li>  
48                 </ul> ${CHANGES_SINCE_LAST_SUCCESS,reverse=true, format="Changes for Build #%n:<br />%c<br />",showPaths=true,changesFormat="<pre>[%a]<br />%m</pre>",pathFormat="    %p"}  
49             </td>  
50         </tr>  
51         <tr>  
52             <td><b>Failed Test Results</b>  
53             <hr size="2" width="100%" align="center" /></td>  
54         </tr>  
55         <tr>  
56             <td><pre style="font-size: 11pt; font-family: Tahoma, Arial, Helvetica, sans-serif">$FAILED_TESTS</pre>  
57                 <br /></td>  
58         </tr>  
59         <tr>  
60             <td><b><font color="#0B610B">构建日志 (最后 100行):</font></b>  
61             <hr size="2" width="100%" align="center" /></td>  
62         </tr>  
63         <!-- <tr>  
64             <td>Test Logs (if test has ran): <a  
65                 href="${PROJECT_URL}ws/TestResult/archive_logs/Log-Build-${BUILD_NUMBER}.zip">${PROJECT_URL}/ws/TestResult/archive_logs/Log-Build-${BUILD_NUMBER}.zip</a>  
66                 <br />  
67             <br />  
68             </td>  
69         </tr> -->  
70         <tr>  
71             <td><textarea cols="80" rows="30" readonly="readonly"  
72                     style="font-family:Courier New">${BUILD_LOG, maxLines=100}  

五、创建Maven项目

5.1、新建任务

首先进入Jenkins主界面，在面板左侧的导航栏中点击“新建任务”，进入“新建任务”界面。

 

进入“新建任务”界面后，在“任务名称”文本框中输入一个合法的名称（该名称最好能简短、清晰地描述所要构建的项目，且不能与已有的任务名称重合），然后选择“构建一个Maven项目”，点击左下角的“确定”按钮，进入任务配置界面。

5.2、General

在“General”选项卡下勾选“丢弃旧的构建”，填写需要保留的构建天数和构建的最大个数。若不及时清理旧的构建，则会消耗服务器的磁盘空间。

 

5.3、源码管理

在“源码管理”模块中选择Git。无论是GitHub还是私有的GitLab，一般都支持两种模式：SSH模式和HTTP模式。

5.3.1 HTTP模式

 

Repository URL：要构建的项目在GitLab中的HTTP地址。首先进入到所要构建的项目在GitLab中的主界面，在项目的URL下拉选框中选择“HTTP”，并点击右侧的“复制”按钮，将复制的HTTP地址粘贴到“Repository URL”文本框中即可。

 

Credentials：点击右侧的“添加”按钮，选择“Jenkins”选项后会弹出一个“添加凭据”弹窗。

 

添加凭据时，类型选择“Username with password”，然后在“用户名”文本框中输入GitLab的登陆账户，“密码”文本框中输入与账户相匹配的密码，“ID”文本框中填入自定义的名称，但不能与已有的凭据ID重合。填写完毕后，点击“添加”按钮，所添加的凭据就会出现在“Credentials”的下拉选框中，在选框中选择相应的凭据即可。

5.3.2 SSH模式

首先登陆Jenkins所在的master服务器，检查在~/.ssh目录下是否有已生成的公钥和私钥。其中，公钥的文件名为id_rsa.pub，私钥的文件名为id_rsa。若公钥和私钥都存在，则将公钥拷贝到GitLab中，私钥拷贝到Jenkins中。

1）将公钥拷贝到GitLab

首先登陆到GitLab中，点击页面右上角的头像，选择Settings-->SSH Keys，进入到“SSH Keys”界面。

Key：将Jenkins所在master服务器上的公钥（id_rsa.pub）拷贝到此文本框中；

Title：填写一个适合的名称；

Add key：点击此按钮将公钥添加到GitLab中；

Your SSH keys：添加到GitLab的公钥会显示在此列表中。