持续集成CI实施指南二--Jenkins使用示例

一、 插件

正式介绍使用之前,还需要准备安装一些插件,插件中心使用操作如下:

1.1 进入插件中心

1

1.2 更新插件

2

1.3 安装插件

3

1.4 卸载与降级插件

4

1.5 需要的插件

  • GitLab Plugin
  • Gitlab Hook Plugin
  • Email Extension Plugin (默认安装)
  • Publish Over SSH
  • Timestamper (默认安装)
  • Workspace Cleanup Plugin (默认安装)

二、 使用示例

注:示例为dotnet core项目和nodejs项目,项目来源为Gitlab

2.1 创建项目

创建项目如下图所示,选择自由风格项目

5

2.2 源码管理

6

选择git源,Repo URL建议使用SSH地址,这时会提示没有权限,因为我们还没有将jenkins的public key添加到gitlab上。所以我们需要先拿到jenkins的public key:

  • 在宿主机上执行命令,其中myjenkins是容器名称

    1
    docker exec -it myjenkins /bin/bash
  • 进入jenkins容器后执行命令创建一对ssh的key

    1
    ssh-keygen -t rsa
  • 一路回车键,即可完成key的创建工作,这时我们进入默认目录查看

    1
    cd ~/.ssh
  • 会出现两个文件,一个是’id_rsa’还有一个是’id_rsa.pub’,我们需要查看’id_rsa.pub’文件,并记录下来

    1
    cat id_rsa.pub

    拷贝上面的文件内容,粘贴到记事本或其他文件管理软件并保存(后续操作仍会用到) 如:

    1
    ssh-rsa xxxxxxxxxxxjenkins@xxxxxx
  • 登陆gitlab账号(不要使用个人账号,建议使用部门公共账号、管理员账号),进入设置页面的’SSH KEYS’选项卡,填入拷贝好的public key,然后点’Add key’保存

    7

  • 再回到jenkins,点击’Add’添加认证方式

    8

  • 类型选为’SSH Username with private key’,Private Key选为’From the jenkins master ~/.ssh’,Username和Description可选填,用于备注,然后点’Add’完成添加

    9

  • 使用上面新建的认证方式后,原来红色的报错提醒就消失了,表示认证通过。最后修改一下需要拉取的分支,默认是’master’分支,我这里根据需要改成了’test’分支

    10

上面的配置完成后,jenkins就能从gitlab拉取项目了,可以在项目主菜单左边栏选择’立即构建’,看看是否成功:

11

2.3 构建触发器

通过2.2章节的配置,我们能够点击’立即构建’来主动开始一次构建,实际项目中,我们可能希望提交代码后,自动开始构建,这时需要配置构建触发器。下面演示gitlab触发器配置(需要安装Gitlab Hook Plugin插件):

12

  • 勾选’Build when a change is pushed to GitLab’,记录后面的URL,如本例中的’http://192.168.2.200:8081/project/Dent_WebSite_Test'

  • 点击’高级’展开更多配置项

  • 在’Allowed branches’配置项选择’Filter branches by name’,在’Include’栏填入监听的分支名称,如’test’。表示触发器只监听来自test分支的事件。

  • 点击’Generate’按钮,生成’Secret token’并记录下来

  • 登陆gitlab(权限至少是master、owner或admin),进入jenkins需要配置的对应的项目,’Settings’选项卡,’Intergrations’配置页面。

    13

  • URL填写刚才记录的URL,如’http://192.168.2.200:8081/project/Dent_WebSite_Test'

  • Secret Token填写刚才记录的Secret token

  • 勾选’push events’和’Merge Request event’,表示监听push和merge事件,然后点’Add webhook’,即可看到新建的webhooks

    14

  • 点击’Test’,选择’Push events’,测试看是否返回’HTTP 200’

    15

上面的配置完成后,就可以用git提交代码或者合并代码到test,看看jenkins是否自动开始构建。

PS: 触发器根据实际情况配置,一般来说实际项目中测试环境需要用触发器自动触发构建,而生产环境建议人工构建,避免误操作提交到master分支后冲掉生产环境!

2.4 构建脚本

前面我们已经完成了拉取代码的配置,接下来就要考虑如何’处理’这些源码:

  • 在’构建’栏增加构建步骤,选择’Execute shell’,创建shell脚本

    16

  • 如下图所示,是一个nodejs项目,它依次执行几个命令

    17

    • 需要注意的是每个命令用&&符号隔开,表示当前一个命令执行成功返回exit code = 0 后,下面的指令才执行,否则退出,用于避免前面的指令执行不成功,后面的指令继续执行
    • 点击’高级’展开更多配置,可以看到’Exit code to set build unstable’,默认exit code非0都会触发整个构建为unstable,也可以手动设置,如只监听exit code 为1,才会让构建变成unstable
  • 如下图所示,是一个dotnet core项目的编译shell脚本

    18

    • 这里将编译后的文件放到了workspace的jenkins_publish目录下面,这个workspace就是jenkins拉取git项目所在的目录
    • 最后一句将测试环境的配置文件改名,用于使其生效

2.5 构建环境

2.5.1 Delete workspace before build starts 排除文件夹

一般情况下,我们可能需要每次构建前,都要清空整个工作目录,也就是jenkins拉取git项目的目录,为了防止不必要的、多余的文件产生干扰,这时就需要勾选’构建环境’里面的’Delete workspace before build starts’,前提是安装了’Workspace Cleanup Plugin’插件:

19

也有另外几种情况,比如在nodejs项目中,每次清空工作目录后,执行’npm install’或’cnpm install’都需要很长时间,所以我们想保留’node_modules’文件夹,假如我们这个项目有两个二级目录(分别叫’app’和’frontend’)下面有’node_modules’文件夹,则配置如下所示:

20

  • 点开’高级’配置,添加4个Exclude输入栏
  • ‘ **/node_modules/** ‘表示node_modules文件夹和文件不删除
  • 还需添加两个二级目录’app’和’frontend’,否则只有子文件夹,没有父文件夹,实际上就是不存在任何文件夹
  • 还需添加’ **/.git/** ‘,因为下一次构建时,保留了’app’和’frontend’的’node_modules’文件夹以及文件内容,git不允许pull项目到非空目录,所以’ **/.git/** ‘目录也不能被清除
  • 不要勾选‘Apply pattern also on directories’,可能存在bug,勾选后反而不起作用

2.5.2 Console Output日志加时间戳

如下图所示,勾选’Add timestamps to the Console Output’,前提是安装’Timestamper’插件。这样构建时,在Console Output就能看到时间戳:

21

22

2.6 构建后发布项目

最后,我们要把’编译’或’处理’后的文件发布到指定的服务器上,常用方式为SSH,也可以通过FTP,下面都以SSH作为说明和示例(检查’Publish Over SSH’插件是否安装)。

2.6.1 设置SSH Server

进入’系统管理’里面的’系统设置’,找到’Publish over SSH’:

23

  • Passphrase:不用填写(如果你在2.2节,给jenkins创建ssh key时,一路回车没有添加这一属性,就无需配置)
  • Path to Key:填写’.ssh/id_rsa’,就是2.2节生成的私钥的文件路径
  • 点’增加’按钮,新增一个SSH Server,并点击’高级’展开更多配置
  • Name:SSH Server名称,用于展示和备注
  • Hostname:SSH Server的ip地址
  • Username:SSH Server用于发布服务的用户名,这里使用了www用户
  • Remote Directory: SSH Server用于发布服务的根目录,这里使用了www用户的目录/home/www/
  • Port:SSH Server的SSH服务端口,默认22

jenkins配置完成后,还需要对SSH Server做一些配置:

  • 远程连接到SSH Server上

  • 切换到SSH Server用于发布服务的用户,如www

  • 复制2.2节jenkins公钥的内容(id_rsa.pub),粘贴到该用户的’~/.ssh/authorized_keys’文件中,如果不存在则需要创建

  • 确保’~/.ssh’文件夹权限是700

    1
    chmod 700 ~/.ssh
  • 确保’authorized_keys’文件夹权限是600

    1
    chmod 600 ~/.ssh/authorized_keys
  • 确保’~/.ssh’文件夹及其内容的所有者是用于发布服务的用户

回到jenkins,如下图所示,点击’Test Configuration’,看是否返回Success!

24

2.6.2 发布到SSH Server

进入jenkins的项目,继续完成项目的发布配置,添加’ Send files or execute commands over SSH ‘构建步骤。

25

参考下图配置(示例为nodejs项目):

26

  • Add Transfer Set:添加一个传输
  • Name:选择需要发布的SSH Server
  • 在第一个Transfer处,写一些脚本,清理和重新创建部署目录,由于发布使用www用户,删除某些文件夹可能没有权限,所以需要用’sudo’来执行,’sudo’需要root用户的密码,我们这里需要免密码操作,操作详情可以看3.1章节
  • 在第二个Transfer处,Source files填写需要发布哪些文件
    • 该目录相对于工作目录,也就是jenkins拉取项目的目录,详情可以看3.2章节
    • 所有文件和文件夹填写’ **\** ‘
    • 如果有空文件夹,点开’高级’配置,如图中第5步所示,勾选’Make empty dirs’,否则空文件夹不会被发布
    • 如果要发布指定文件夹下的所有文件以及文件夹,填写’ foldername\ ‘,注意斜杠一定要有
    • 如果要发布多个目录,用英文逗号隔开
  • Remove prefix:如图所示,如果要发布app文件夹下的所有子内容,而不要把app这个文件夹也发布过去,需要在这里配置’app’
  • Remote directory:SSH Server的发布目录,相对于2.6.1章节,SSH Server配置的Remote Directory
  • Exec command:根据实际需求,执行一些命令,图中执行脚本安装nodejs包、重启pm2服务、重启nginx服务

dotnet core的参考配置如下,相对比较简单,发布后重启supervisor和nginx即可:

27

2.7 构建后邮件通知

上面的配置完成后已经能够正常使用,为了每次构建的信息能及时通知到团队,还需要配置邮件通知。

jenkins自带一个简单版的邮件通知功能,但不能满足一些复杂需求和定制需求,所以这里使用’Extended E-mail Notification’插件

2.7.1 配置Extended E-mail Notification

  • 进入’系统管理’里面的’系统设置’,找到’Jenkins Location’,填写’系统管理员邮件地址’:

    28

  • 找到’Extended E-mail Notification’,按下图所示配置:

    29

    • SMTP server:SMTP服务器地址
    • Default user E-mail suffix:默认邮件后缀
    • 点击’高级’展开更多配置
    • 勾选’Use SMTP Authentication’
    • 填写’User Name’,’Password’和’SMTP Port’
    • Default Recipients:默认收件人
  • Default Content就是邮件模板,这里给一个参考:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    <!DOCTYPE html>  
    <html>
    <head>
    <meta charset="UTF-8">
    <title>${ENV, var="JOB_NAME"}-第${BUILD_NUMBER}次构建日志</title>
    </head>
    <body leftmargin="8" marginwidth="0" topmargin="8" marginheight="4"
    offset="0">
    <table width="95%" cellpadding="0" cellspacing="0"
    style="font-size: 11pt; font-family: Tahoma, Arial, Helvetica, sans-serif">
    <tr>
    <td><br />
    <b><font color="#0B610B">构建信息</font></b>
    <hr size="2" width="100%" align="center" /></td>
    </tr>
    <tr>
    <td>
    <ul>
    <li>项目名称 : ${PROJECT_NAME}</li>
    <li>构建编号 : 第${BUILD_NUMBER}次构建</li>
    <li>GIT URL: ${GIT_URL}</li>
    <li>GIT BRANCH: ${GIT_BRANCH}</li>
    <li>GIT COMMIT: ${GIT_COMMIT}</li>
    <li>触发原因: ${CAUSE}</li>
    <li>构建日志: <a href="${BUILD_URL}console">${BUILD_URL}console</a></li>
    <li>构建 Url : <a href="${BUILD_URL}">${BUILD_URL}</a></li>
    <li>工作目录 : <a href="${PROJECT_URL}ws">${PROJECT_URL}ws</a></li>
    <li>项目 Url : <a href="${PROJECT_URL}">${PROJECT_URL}</a></li>
    </ul>
    </td>
    </tr>
    <tr>
    <td><b><font color="#0B610B">变更集</font></b>
    <hr size="2" width="100%" align="center" /></td>
    </tr>
    <tr>
    <td>${JELLY_SCRIPT,template="html"}<br/>
    <hr size="2" width="100%" align="center" /></td>
    </tr>
    </table>
    </body>
    </html>

2.7.2 在项目中使用Extended E-mail Notification

回到jenkins项目配置,添加名为’Editable Email Notification’的构建后操作,配置如下:

30

  • Project Recipient List:项目收件人邮箱列表
  • Default Content:邮件内容模板,默认调用2.7.1章节配置的模板内容,也可以在这里自定义
  • Attach Build Log:是否附件构建日志,一般选择’Attach Build Log’
  • Trigger:点开’高级’,配置触发器,条件有很多,根据需要配置,这里’Recipient List’就是项目收件人邮箱列表

至此,一个’完整’的jenins项目就部署完成了(由于还没有集成测试,所以完整打引号,jenkins集成测试请参见该系列第三篇文章)。

三、 其他

3.1 SSH Server root权限执行命令或脚本

通过SSH Server发布和部署项目往往会遇到权限不够,需要用’sudo’升权限的情况,在自动化流程里,不想使用密码或者暴露密码,那么可以参考下面的方式:

  • 进入SSH Server

  • 切换到root用户

  • 编辑sudoers文件

    1
    vi /etc/sudoers
  • 在文档最后,给www用户添加无需密码的指令或脚本

    1
    www     ALL=(root)      NOPASSWD:/usr/bin/systemctl,/bin/supervisorctl,/usr/bin/rm

    上面的命令表示www用户以sudo执行systemctl、supervisor和rm命令时不需要密码。

    因为给www用户rm权限比较危险,所以这里也可以填某个位置的脚本文件,封装起来相对更安全,根据项目需要自行选择。

  • 在sudoers文件还需注释掉下面的配置,用于允许其他来源的控制台传输sudo命令

    1
    #Defaults    requiretty

3.2 jenkins工作目录相关介绍

jenkins工作目录就是jenkins拉取git项目的目录,可以在jenkins项目左边栏点击’工作空间’查看:

32

在宿主机上,可以进入docker jenkins容器映射的卷查看,如

1
cd /var/lib/docker/volumes/jenkins/_data/workspace/项目名

或者在宿主机上直接进入docker jenkins容器内,在jenkins_home文件夹中查看

1
2
3
docker exec -it myjenkins /bin/bash #宿主机上执行
#进入容器
cd /var/jenkins_home/workspace/项目名

3.3 pm2相关知识介绍

  • 不建议给每个nodejs项目配置局部pm2,建议给SSH Server配置全局的pm2

    1
    sudo npm install pm2 -g
  • pm2作用于每一个用户,如果是用www用户部署的node项目,在root用户下不能用’pm2 status’查看到pm2托管的项目,不要用不同的用户启动pm2,以免项目冲突

  • pm2开机启动方法如下:

    配置完pm2托管的项目后执行命令

    1
    2
    pm2 save
    pm2 startup

    再用root用户执行提示反馈的命令即可

持续集成CI实施指南二--Jenkins使用示例

https://wurang.net/jenkins02_use/

作者

Wu Rang

发布于

2017-11-06

更新于

2021-12-06

许可协议

评论