Jenkins 学习总结

谁家秋院无风入？何处秋窗无雨声？

[1 工具介绍](#1 工具介绍)
[2 项目类型](#2 项目类型)
[3 Jenkinsfile](#3 Jenkinsfile)
- [3.1 顶级块指令（pipeline）](#3.1 顶级块指令（pipeline）)
  - agent - 执行节点
  - triggers - 触发器
  - parameters - 等待输入
  - options - 运行选项
  - stages - 构建阶段
- [3.2 阶段块指令（stages）](#3.2 阶段块指令（stages）)
  - tools - 编译工具集
  - environment - 环境变量
  - input - 等待输入
  - steps - 动作执行集
  - post - 构建后操作
  - when - 条件判断
  - parallel - 并行任务
- [3.3 动作指令（steps）](#3.3 动作指令（steps）)
  - echo - 输出日志
  - sh/bat - 执行 Shell 命令
  - git/checkout - 拉取代码
  - input - 人工确认
  - retry - 失败重试
  - timeout - 超时控制
  - archiveArtifacts - 文件存档
[4 系统管理](#4 系统管理)
[5 常用插件](#5 常用插件)
[6 杂七杂八](#6 杂七杂八)

1、工具介绍

Jenkins 是目前最经典、最广泛使用的 持续集成（CI）与持续交付（CD）自动化平台 ，它的核心作用是：把原本需要人工执行的软件构建、测试、打包、部署的繁琐流程进行自动化处理。

注：什么是 CI 和 CD ？

CI（持续集成）：指开发提交代码之后，工具会自动帮研发完成 编译构建、代码测试、软件打包 的整个过程。

CD（持续交付）：指软件被打包之后，工具会自动帮运维完成软件 部署发布 的过程，该过程可能包含测试环境和生产环境。

2、项目类型

在 Jenkins 中创建自动化任务时，会发现它支持 5 种项目类型，而这些项目类型又分别有着适合自己的应用场景。因此，各项目类型的作用和适用场景应该被我们最先了解：

Freestyle ：这是最经典的项目类型，适合新手入门练手。用户只需在页面上点选配置，不用写一行代码，便可生成构建/部署的流程任务。【注：只适合 单个项目单分支 的简单任务】
Pipeline ：这是最推荐的项目类型。用户通过编写 Jenkinsfile 文件来制定软件在构建/部署任务中所需的各种配置信息，所有的参数配置均体现在 Jenkinsfile 文件中，并根据文件内容自动生成流水线任务。【注：适合 单个项目单分支 的复杂任务】
Multibranch Pipeline ：这是 Pipeline 的升级版。可自动扫描 Git 多个分支，并为每个拥有 Jenkinsfile 文件的分支自动生成流水线任务。【注：适合 单个项目多分支 的复杂任务】
Organization Folder ：这是 Multibranch 的升级版。可自动扫描指定组织中所有项目的所有分支，并为每个拥有 Jenkinsfile 文件的分支自动生成流水线任务。【注：适合 组织项目多分支 的复杂任务。】
Matrix Project：类似 Freestyle 的升级版。将一个任务在多个 Agent 下执行。【注：这种方式在 Pipeline 中是通过自定义 agent + tools 来实现的，但现在正逐渐被淘汰。】

其中，使用最广泛的项目类型当属 Pipeline，而该项目类型又依赖于 Jenkinsfile 文件。因此，学会如何编写 Jenkinsfile 文件非常重要。

注：一个流水线任务通常一定包含：源码管理（SCM）、构建等动作，其中 SCM 在 Pipeline 项目中需要在 jenkinsfile 文件中通过 git 指令去拉取，而在其它类型的项目中，一般都是在项目的 configure 页面中去指定。

3、Jenkinsfile

【1】Jenkinsfile 支持使用两种语法进行编写：声明式和脚本化，其中声明式语法更易于编写和阅读。因此，下面出现的 Jenkinsfile 文件都以声明式语法为主。例如：

groovy 复制代码

pipeline {
    agent any 		//流水线任务被执行节点，必须
    triggers {		//触发器，非必须
        cron('H */4 * * 1-5')
    }
    stages {		//阶段动作，必须
        stage('Test') { 
            steps {
                echo "ok"
            }
        }
    }
}

注：以上 Jenkinsfile 文件定义了一个 stage 任务会在默认的 agent 机器上被执行，触发执行的时间是在每周一到周五，每隔 4 小时自动触发一次，stage 任务在每次被执行结束之后，不管成功与否，都还会再执行一个 post 任务。

【2】在大多数流水线任务中，其任务流程基本都是：构建、测试、部署这三个阶段，而将其用 精简必要 的代码表示出来则是：

groovy 复制代码

pipeline {
    agent any 
    stages {
        stage('Build') { 
            steps {
                // 定义构建阶段的指令
            }
        }
        stage('Test') { 
            steps {
                // 定义测试阶段的指令
            }
        }
        stage('Deploy') { 
            steps {
                // 定义部署阶段的指令
            }
        }
    }
}

【3 】Jenkinsfile 支持的指令众多，官方将其分为两大类：声明指令、片段指令。本人为了便于理解，将其分为了三大类：顶级块指令、阶段块指令、动作指令 。顶级块指令一般都保持在最外层，即仅次于 pipeline 的指令； 阶段块指令在使用上比较灵活，一般可在 pipeline、stage 块之间灵活引用； 动作指令是指仅被包含在 steps 块中的指令。

【4】定义 Jenkinsfile 的时候，在涉及到登录凭证的时候，如果将这些凭证信息写在 Jenkinsfile 文件中则可能会发生泄密，因此为了安全起见，Jenkinsfile 支持先在"管理 Jenkins-凭证"页面创建凭证信息及其 ID 名称，然后在 Jenkinsfile 中直接引用 ID 名称即可。 与凭证类似的情况还有 Agent，如先在"管理 Jenkins"中的 Node、Clound 页面创建环境节点及其 ID 名称，然后在 Jenkinsfile 中引用 ID 即可。

【5】指令语法参考帮助：（1）任意新建一个 Pipeline 项目，然后打开它并进入"pipeline syntax"页面，即可借助系统自带的语法生成器来生成 Jenkinsfile 指令。（2）参考官方文档。（3）指令并非都来自官方，当安装不同的插件时便可能会带入不同的指令。

3.1、顶级块指令（pipeline）

groovy 复制代码

pipeline {
    //这里是一些顶级块指令
}

3.1.1、agent - 执行节点

agent 指令决定了软件构建部署的任务应该在哪台机器上被执行。值为 any 时，在默认情况下，它是在 Jenkins 服务所属的服务器上被执行；但如果配置了多个 node 节点的话，默认 Jenkins 将会以负载均衡的方式将任务随机分发在闲置的机器上。

agent 支持的类型有：docker slave、node、docker cloud，具体配置方法如下：

docker slave：在"Manage Jenkins-System-Docker Slaves"处配置，默认是指 Jenkins 服务所在机器的 Docker 服务，也可配置为远端机器上开放的 Docker 服务。
node：在"Manage Jenkins-Nodes"处配置，默认是指 Jenkins 服务所在机器，也可配置为远端的 Linux 机器。
docker cloud：在"Manage Jenkins-Clouds"处配置，此时还需要配置 "Docker Agent templates"，以供 agent 通过 label 使用。

groovy 复制代码

//docker slave 用法
pipeline {
    agent {
        docker {
            image 'maven:3-alpine'
            label 'my-defined-label'
            args  '-v /tmp:/tmp'
        }
	}
    stages { 
        stage('Example') {
            steps {
                echo 'Hello World'
            }
        }
    }
}

//node、docker cloud 用法
pipeline {
    agent {
    	node {
      	  label 'my-defined-label'
    	  customWorkspace '/some/other/path'
    }
}
    stages { 
        stage('Example') {
            steps {
                echo 'Hello World'
            }
        }
    }
}

注：（1）流水线任务在每次运行时，被使用到的 docker 容器都会被重新创建，待结束之后再将容器销毁。（2）如果一些容器在被加载的时候需要频繁加载一些文件，此时便可通过容器的卷功能将需要加载的文件缓存一份到本地，这样下次容器被启动的时候就省去了资源被重新被加载的过程。（3）agent 指令不能算是单纯的顶级块指令，因为它也可以出现在 stage 块中，但由于它是必须要出现在顶级块中的指令，因此将其也归类为顶级块指令。

3.1.2、triggers - 触发器

triggers 指令定义了流水线任务该如何被自动触发的方法。

triggers 支持的类型有：cron、pollSCM、githubPush，具体功能如下：

cron：定时触发任务。
pollSCM：定时检查源代码的更新状态，只在检测到源代码有更新状态时，它才会触发任务。
Hook：需配置 Git 服务器的 WebHook 功能，让其在检测到代码更新时，自动向远端的 Jenkins 服务器发送一个 HTTP 请求，以触发流水线任务。

groovy 复制代码

pipeline {
    agent any
    triggers {
    cron('H */4 * * 1-5')
  //pollSCM('H */4 * * 1-5')
}
    stages { 
        stage('Example') {
            steps {
                echo 'Hello World'
            }
        }
    }
}

注：cron 定时语法 MINUTE HOUR DayOfMonth MONTH DayOfWeek。

为了允许定期计划的任务在系统上产生均匀的负载，应尽可能使用符号 H（"哈希"）。例如，使用 0 0 * * * 会发生在同一时刻执行十几个日常作业导致午夜出现大幅峰值。相比之下，使用 H H * * * 仍会每天执行每个作业一次，但不是在同一时间去执行所有作业，这样能够更好地利用有限的资源。

H 符号可以与范围一起使用。例如，H H(0-7) * * * 表示 12:00 AM（午夜）到 7:59 AM 之间的某个时间；还可以使用 H 的步长间隔。例如，H/15 * * * * 表示每 15 分钟去执行一次。

注意：Multibranch Pipeline 和 Organization Folder 项目类型的任务均拥有两个触发器，一个触发器用于定时检测多项目多分支增减的动态情况，另一个触发器则是 Jenkinsfile 中定义的单分支触发器，它们分别各自运行。

3.1.3、parameters - 等待输入

parameters 指令在触发流水线任务之前会为用户弹出一个参数请求的提示框，要求你输入一个值之后才能开始后续的任务构建。这些参数值可通过 params 对象提供给流水线进行调用。

groovy 复制代码

pipeline {
    agent any
    parameters {
        string(name: 'PERSON', defaultValue: 'Mr Jenkins', description: 'Who should I say hello to?')
    }
    stages {
        stage('Example') {
            steps {
                echo "Hello ${params.PERSON}"
            }
        }
    }
}

注：在执行某些比较重要且需要管理员决策的构建任务时，这个指令的功能会非常有用。

3.1.4、options - 运行选项

options 指令允许从流水线内部配置特定于流水线的选项。它们类似于 Freestyle 项目类型中"Configure-General"中的选项。

groovy 复制代码

pipeline {
    agent any
    options {
        timeout(time: 1, unit: 'HOURS') //指定一个小时的全局执行超时, 在此之后，Jenkins 将中止流水线运行。
    }
    stages {
        stage('Example') {
            steps {
                echo 'Hello World'
            }
        }
    }
}

3.1.5、stages - 构建阶段

stages 指令是流水线中最主要的部分，它用来描述构建任务应该如何进行。

groovy 复制代码

pipeline {
    agent any
    stages { 
        stage('Example') {
            steps {
                echo 'Hello World'
            }
        }
    }
}

3.2、阶段块指令（stage）

groovy 复制代码

pipeline {
    agent any
    //（2）或这里也可以是一些全局有效的阶段块指令
    stages {
        stage('Example') {
            //（1）这里是一些局部有效的阶段块指令
        }
    }
}

注：在声明式 Pipeline 里，stages 块下面顶层只能放 stage 块，不能直接放 agent、steps、environment 这类其它指令。

3.2.1、tools - 编译工具集

tools 指令可指定在构建机器 agent 下应该使用哪种版本的构建工具去构建应用。例如，在构建 java 应用的时候，是该用 JDK8 呢还是 JDK 21 呢？但 在使用它之前需要先在"Manage Jenkins-Tools"页面去事先定义好各种构建工具对应软件版本的安装路径，以便 Jenkins 能够找的到构建工具。（注：Jenkins 支持指定已安装的路径、也支持在线安装在新路径。）

groovy 复制代码

pipeline {
    agent any
    tools {
        jdk 'jdk-8' //该名称取决于在 "Manage Jenkins-Tools" 中自定义的工具名称。
    }
    stages {
        stage('Example') {
            steps {
                sh 'java -version'
            }
        }
    }
}

注意：由于 Docker 容器技术的发展，现在一些专用于构建的容器类型的 agent 自身已装备好对应的构建工具，因此这个 tools 指令在这种场景之下便无需再用了。

3.2.2、environment - 环境变量

environment 指令是用来 定义 agent 环境变量 的，它能够把一些变量提前统一声明，让整个流水线或某个阶段都能直接使用。

groovy 复制代码

pipeline {
    agent any
    environment {
        JAVA_HOME = '/opt/java'
        APP_ENV = 'prod'
    }
    stages {
        stage('test') {
            steps {
                echo "${JAVA_HOME}"
                echo "${APP_ENV}"
            }
        }
    }
}

3.2.3、input - 等待输入

input 指令与 parameters 指令比较像，都会为用户弹出一个参数请求的提示框等待输入之后再继续，但二者之间的区别在于：input 可以用于 stages 块中，而 parameters 只能用于 pipeline 块中。

groovy 复制代码

pipeline {
    agent any
    stages {
        stage('Example') {
            input {
                message "Should we continue?"
                ok "Yes, we should."
                submitter "alice,bob"
                parameters {
                    string(name: 'PERSON', defaultValue: 'Mr Jenkins', description: 'Who should I say hello to?')
                }
            }
            steps {
                echo "Hello, ${PERSON}, nice to meet you."
            }
        }
    }
}

3.2.4、steps - 动作执行集

steps 指令中定义的是一个或多个动作指令，是 stage 块中最重要的一个指令，它才是实际用来描述构建任务应该如何进行的核心。

groovy 复制代码

pipeline {
    agent any
    stages {
        stage('Example') {
            steps { 
                echo 'Hello World'
            }
        }
    }
}

3.2.5、post - 构建后操作

post 指令可根据流水线或阶段的完成情况来决定是否运行块内的 动作指令。

groovy 复制代码

pipeline {
    agent any
    stages {
        stage('Example') {
            steps {
                echo 'Hello World'
            }
        }
    }
    post { 
        always { 
            echo 'I will always say Hello again!'
        }
    }
}

注意：post 与 steps 相似的地方在于，它们包含的都是动作指令，steps 可以使用的指令 post 一样可以使用。

3.2.6、when - 条件判断

when 指令会根据给定的条件来决定是否应该执行当前 stage 中的 steps 任务。【注：该指令参数较多可参考此说明】

groovy 复制代码

pipeline {
    agent any
    stages {
        stage('Example Build') {
            steps {
                echo 'Hello World'
            }
        }
        stage('Example Deploy') {
            when {	//当前分支的名称是 test 且当前 agent 中的环境变量 var 的值是 ok 时，条件为真继续执行。
                branch 'test'
                environment name: 'var', value: 'ok'
            }
            steps {
                echo 'Deploying'
            }
        }
    }
}

3.2.7、parallel - 并行任务

parallel 指令支持多个 stage 任务可以并行执行，而不是只能自上而下执行。另外请注意：一个 stage 必须只有一个 steps 或 parallel 块，二者不能同时出现。

groovy 复制代码

pipeline {
    agent any
    stages {
        stage('Non-Parallel Stage') {
            steps {
                echo 'This stage will be executed first.'
            }
        }
        stage('Parallel Stage') {
            when {
                branch 'master'
            }
            failFast true
            parallel {
                stage('Branch A') {
                    agent {
                        label "for-branch-a"
                    }
                    steps {
                        echo "On Branch A"
                    }
                }
                stage('Branch B') {
                    agent {
                        label "for-branch-b"
                    }
                    steps {
                        echo "On Branch B"
                    }
                }
            }
        }
    }
}

3.3、动作指令（steps）

groovy 复制代码

pipeline {
    agent any
    stages {
        stage('Example') {
            steps { 
                //这里是一些实际执行任务构建的动作指令
            }
        }
    }
}

3.3.1、echo - 输出日志

groovy 复制代码

echo 'hello'

3.3.2、sh/bat - 执行 Shell 命令

groovy 复制代码

sh 'pwd'
sh 'mvn clean package'

3.3.3、git/checkout - 拉取代码

groovy 复制代码

git branch: 'main', credentialsId: 'git-login', url: 'https://github.com/user/demo.git'

checkout scm	//这里的 scm 代表着在 Jenkins 中已配置好的源代码仓库，因此在 Jenkinsfile 中便不需要再配置仓库地址这些信息了。

注：sh 'git clone ...' 也能完成拉代码，但 steps 里的 git 指令仍然有存在价值，因为它是 Jenkins 对 Git 操作的"深度集成封装"，它支持：（1）使用 Jenkins 中提供的凭证。（2）自动进入 Jenkins SCM 管理体系，例如可以自动拉取指定的分支、还有一些相关的日志记录。

3.3.4、input - 人工确认

groovy 复制代码

input '是否继续发布？'

3.3.5、retry - 失败重试

groovy 复制代码

retry(3) {
    sh 'curl http://service'
}

3.3.6、timeout - 超时控制

groovy 复制代码

timeout(time: 5, unit: 'MINUTES') {
    sh './long_task.sh'
}

3.3.7、archiveArtifacts - 文件存档

groovy 复制代码

archiveArtifacts artifacts: '*.jar'

注：构建后存档的文件，需进入流水线任务的 Status 页面的 Builds 记录中对应的构建记录页面中的 Workspaces 工作区去下载存档出来的文件。

4、系统管理

HTTP 代理："Manage Jenkins" - System - "HTTP Proxy Configuration"。
凭证管理："Manage Jenkins" - Credentials【全局凭证】、http://Jenkins-URL/user/admin/credentials/【用户凭证】。
各插件（GitHub/Git/Docker/SMTP/等）相关联的服务器连接配置："Manage Jenkins" - System。

5、常用插件

Localization: Chinese (Simplified)：中文汉化包。
Blue Ocean：图形化展示流水线。【位置：首页-右上角三道杠-打开 Blue Ocean】
AnsiColor：为任务构建的控制台输出的日志添加上颜色，便于更直观的看日志。【用法：（1）任务配置开启 Color ANSI 功能。（2）在 shell 脚本中使用 echo -e "\E[1;31m test \E[0m" 为输出上色。】
Job Configuration History：Jenkins 任务配置备份恢复。【位置：打开任一任务，在 Configure 中随便修改一些配置之后，在任务左侧栏的 Job Config History 菜单便可以看到备份记录。】
Docker Pipeline：支持在 Jenkinsfile 文件中使用 Docker 容器作为 Agent。【用法：agent {docker{image 'maven:3.6.3-jdk-11'}}】

6、杂七杂八

Jenkins 重启：http://Jenkins-URL/restart
任务构建记录中的"replay"回放功能，能够对当前任务的 Jenkinsfile 文件进行配置修改，然后再运行该构建任务。【注：这个功能还是挺不错的】
Blue Ocean 不光能够以图形化的方式查看流水线的构建过程，还能够对流水线的 Jenkinsfile 文件以图形化的方式进行修改，不过这个修改功能只对 GitHub 仓库的流水线任务有效，而由于 GitHub 对通过 API 读写仓库的行为进行了限制，因此这个功能时常就出现转圈等待的问题，体验很不好。所以一般只是利用了 Blue Ocean 的图形化查看功能，不使用其图形化编辑功能。
Jenkins 官方制作的一些 Agent 容器：https://hub.docker.com/u/jenkins。
参考文章：二丫讲梵、Jenkins 中文手册
故障参考：二丫讲梵

Jenkins 学习总结

导航

1、工具介绍

2、项目类型

3、Jenkinsfile

3.1、顶级块指令（pipeline）

3.1.1、agent - 执行节点

3.1.2、triggers - 触发器

3.1.3、parameters - 等待输入

3.1.4、options - 运行选项

3.1.5、stages - 构建阶段

3.2、阶段块指令（stage）

3.2.1、tools - 编译工具集

3.2.2、environment - 环境变量

3.2.3、input - 等待输入

3.2.4、steps - 动作执行集

3.2.5、post - 构建后操作

3.2.6、when - 条件判断

3.2.7、parallel - 并行任务

3.3、动作指令（steps）

3.3.1、echo - 输出日志

3.3.2、sh/bat - 执行 Shell 命令

3.3.3、git/checkout - 拉取代码

3.3.4、input - 人工确认

3.3.5、retry - 失败重试

3.3.6、timeout - 超时控制

3.3.7、archiveArtifacts - 文件存档

4、系统管理

5、常用插件

6、杂七杂八