Jenkins 基础(2)：核心基础篇 —— 吃透项目配置与Pipeline初体验#

2.1 系统配置页整体结构梳理#

点击左侧导航栏的 Manage Jenkins，你会看到配置项被分成了几大类：

• System Configuration（系统配置）：包含系统全局配置（System）和全局工具配置（Global Tool Configuration）。
• Security（安全）：管理用户权限、凭据（Credentials）等。
• Status Information（状态信息）：系统日志、负载统计等。
• Troubleshooting（故障排查）：管理旧数据等。
• Tools and Actions（工具和动作）：插件管理（Plugins）、节点管理（Nodes and Clouds）。

对于初学者，日常打交道最多的就是系统全局配置、全局工具配置、凭据管理和节点管理。

2.2 全局工具配置（重点）：JDK、Maven、Git、Node环境配置#

Global Tool Configuration（全局工具配置） 是重中之重。它告诉 Jenkins：你的 JDK 安装在哪里？Git 命令在哪里？Maven 怎么调用？

自动安装 vs 本地路径

Jenkins 支持勾选 Install automatically（自动安装），但生产环境中，由于网络原因或版本统一的要求，强烈建议取消勾选自动安装，直接指定宿主机（或容器）上已安装好的工具绝对路径。这能避免因为网络波动导致工具下载失败而引发的构建中断。

实战配置示例：

1. JDK 配置：

   • 别名（Name）：jdk-11（建议带上版本号，方便后续在多环境时引用，例如 jdk-8, jdk-17）
   • JAVA_HOME：填写服务器上的绝对路径，例如 /usr/lib/jvm/java-11-openjdk-amd64。

2. Maven 配置：

   • 别名（Name）：maven-3.8.8
   • MAVEN_HOME：/opt/maven/apache-maven-3.8.8

3. Git 配置：

   • 通常保持默认的 git 即可，前提是服务器的环境变量（$PATH）里能直接执行 git 命令。如果不在默认路径，需填写绝对路径，如 /usr/local/bin/git。

4. Node.js 配置（需提前在插件管理中安装 NodeJS Plugin）：

   • 别名：node-16
   • 安装目录：/opt/nodejs/node-v16.14.0-linux-x64

2.3 全局安全配置：用户权限与 RBAC 实战#

默认情况下，Jenkins 允许任何登录用户做任何事，这在团队协作中是非常危险的。进入 Security -> Global Security 进行配置。

• Authentication（认证）：通常选择 Jenkins’ own user database（Jenkins专有用户数据库）。
• 匿名访问：务必确保 Allow anonymous read access（允许匿名用户拥有只读权限）被取消勾选，防止未授权用户查看敏感的构建日志或代码信息。

RBAC 权限控制实战

企业中最常用的是基于角色的权限控制。请先在插件市场安装 Role-based Authorization Strategy 插件。

安装插件后，在授权策略中选择 Role-Based Strategy。接着进入 Manage and Assign Roles：

1. Manage Roles（管理角色）：

   • Global roles（全局角色）：比如创建一个 developer 角色，只勾选 Overall -> Read 权限（仅允许登录和查看控制台）。
   • Item roles（项目角色）：比如创建一个 dev-projects 角色，Pattern（正则匹配）写 dev-.*，并勾选 Job -> Build, Read, Workspace。这意味着拥有该角色的用户，只能看到和构建以 dev- 开头的项目。

2. Assign Roles（分配角色）：

   • 将张三（开发者）分配给 developer 全局角色和 dev-projects 项目角色。这样张三登录后，就不会看到生产环境（如 prod- 开头）的任何项目，也无法进入系统管理修改配置。

2.4 节点管理：主从架构概念与 SSH 节点接入#

Jenkins 原生支持 Master-Slave（主从）架构。

• Master（主节点）：负责管理配置、调度任务、分发构建，不建议在 Master 节点直接执行繁重的构建任务，以免拖垮调度中心。
• Agent/Slave（从节点）：真正干活的机器。

实战：通过 SSH 接入一个 CentOS 从节点

1. 在 Manage Jenkins -> Nodes 中点击 New Node，输入名称（如 build-node-01），选择 Permanent Agent。
2. Remote root directory（远程工作目录）：填入 /opt/jenkins-agent（节点上存放代码和工作空间的路径）。
3. Labels（标签）：填入 centos-build。以后可以在任务中指定只在这个标签的机器上运行。
4. Launch method（启动方式）：选择 Launch agents via SSH。
   • Host：填写从节点的 IP（如 192.168.1.100）。
   • Credentials：添加一个 SSH Username with private key 的凭据，填入从节点 root 用户的私钥。
   • Host Key Verification Strategy：测试环境下可选择 Non verifying Verification Strategy（不验证主机密钥）以快速连通。

保存后，点击 Launch agent，Jenkins 就会自动通过 SSH 登录到该机器，下载并启动 agent.jar，你的分布式构建集群就初具雏形了。

3.1 核心配置模块全景解析#

进入项目配置页，你会看到以下核心选项卡：

1. General（通用）：描述项目信息、设置参数化构建、丢弃旧的构建历史等。
2. Source Code Management（源码管理）：配置 Git/SVN 仓库地址和分支。
3. Build Triggers（构建触发器）：定义任务在什么条件下被触发执行。
4. Build Environment（构建环境）：构建前的准备工作，如注入密码、清空工作空间。
5. Build Steps（构建步骤）：真正的核心动作，执行 Shell 脚本或调用 Maven。
6. Post-build Actions（构建后操作）：构建完成后的收尾工作，如归档产物、发送邮件。

3.2 实战：参数化构建 (Parameterized Build)#

很多时候我们需要在构建时传入变量（比如选择发布哪个分支，或者发布哪个环境）。

在 General 中勾选 This project is parameterized（参数化构建过程）：

• 添加一个 Choice Parameter（选项参数）：
  • Name: ENV
  • Choices: dev 换行 test 换行 prod
  • Description: 请选择要发布的部署环境
• 添加一个 String Parameter（字符串参数）：
  • Name: BRANCH_NAME
  • Default Value: main
  • Description: 请输入要打包的Git分支

在后续的构建步骤中，你就可以通过 ${ENV} 和 ${BRANCH_NAME} 来引用这些变量了。

3.3 源码管理与凭据最佳实践#

在 Source Code Management 中选择 Git：

• Repository URL：填入代码仓库地址（如 http://gitlab.com/mygroup/myproject.git）。
• Credentials：点击 Add，添加可以访问该仓库的凭据。
• Branches to build：将默认的 */master 改为我们上面定义的变量 ${BRANCH_NAME}。

安全提示

不要在配置页面或者 Shell 脚本中到处手填密码明文！所有的密码、私钥、Token 都应该统一在 Manage Jenkins -> Credentials 中创建，在使用时通过下拉框选择或在环境中安全注入。

3.4 构建触发器：Cron 表达式怎么写？#

Jenkins 支持多种触发方式，最常用的有两种：

1. Build periodically（定时构建）：不管代码有没有更新，到了时间就强制构建。类似 Linux 的 Crontab。

   • 语法示例：H 2 * * * （每天凌晨 2 点左右执行一次）。
   • 语法示例：H/15 * * * * （每 15 分钟执行一次）。
   • 注：Jenkins 推荐使用 H (Hash) 而不是固定的数字（如 0），这能让 Jenkins 自动打散同一时间的并发任务，降低系统瞬间负载。

2. Poll SCM（轮询SCM）：定期去代码仓库看有没有新提交，如果有才触发构建。

   • 语法同上，例如 H/5 * * * * 表示每 5 分钟检查一次 Git 仓库。
   • 虽然好用，但高频轮询会增加 Git 服务器的压力，企业中更推荐使用 Gitlab Webhook 实现主动推送触发。

3.5 构建步骤：Shell 脚本实战#

在 Build Steps 中选择 Execute shell。这里是真正干活的地方。我们可以结合前面的参数化变量写一段简单的部署逻辑：

1
#!/bin/bash
2
# 开启遇到错误即退出的严格模式
3
set -e
4

5
echo "===================================="
6
echo "开始执行构建任务..."
7
echo "目标分支: ${BRANCH_NAME}"
8
echo "部署环境: ${ENV}"
9
echo "当前工作目录: $(pwd)"
10
echo "===================================="
11

12
# 假设这是一个 Node.js 项目
13
echo "1. 安装依赖..."
14
npm install --registry=https://registry.npmmirror.com
15

16
echo "2. 开始打包..."
17
# 根据选择的环境变量执行不同的打包命令
18
npm run build:${ENV}
19

20
echo "3. 打包完成，准备分发..."
21
# 将产物压缩
22
tar -zcvf dist-${ENV}.tar.gz ./dist/
23

24
echo "===================================="
25
echo "构建成功！"

3.6 构建后操作：邮件与产物归档#

在 Post-build Actions 中：

• Archive the artifacts（归档成品）：输入 *.tar.gz。这会在 Jenkins 任务页面保留这个压缩包，方便用户直接点击下载。
• E-mail Notification：输入接收人的邮箱地址，勾选 Send e-mail for every unstable build。当构建失败时，自动将失败日志发送给开发者。（需提前在系统配置中配置好 SMTP 服务）。

4.1 什么是Pipeline？与自由风格项目的核心区别#

Pipeline 是一套运行在 Jenkins 上的工作流框架，它允许你使用代码（Groovy 脚本）来定义整个构建、测试、部署流程，即所谓的 Pipeline as Code。

4.2 两种语法选型：声明式 vs 脚本式#

Pipeline 支持两种语法：

• Declarative Pipeline（声明式）：较新的语法，结构化、严格、易读。它提供了预定义的块（如 stages, steps, post），上手门槛低，强烈建议小白和大多数团队优先选择声明式。
• Scripted Pipeline（脚本式）：传统的语法，就是纯粹的 Groovy 代码，极其灵活，但学习成本高，没有严格的结构限制。

一个标准的声明式 Pipeline 骨架及核心指令解析如下：

1
pipeline {
2
    // 1. agent: 指定在哪里执行。any(任意节点), none(不在全局分配), label 'centos-build'(指定标签)
3
    agent any
4

5
    // 2. environment: 定义全局环境变量
6
    environment {
7
        APP_NAME = 'my-awesome-app'
8
        // 使用 credentials 注入机密信息，避免明文泄露
9
        DB_PASS = credentials('mysql-prod-password')
10
    }
11

12
    // 3. parameters: 定义参数化构建参数（代替自由风格的图形化配置）
13
    parameters {
14
        choice(name: 'ENV', choices: ['dev', 'test', 'prod'], description: '部署环境')
15
        string(name: 'BRANCH', defaultValue: 'main', description: '代码分支')
16
    }
17

18
    // 4. stages: 阶段集合，包含了整个流水线的所有阶段
19
    stages {
20
        stage('拉取代码') {
21
            steps {
22
                echo "拉取分支: ${params.BRANCH}"
23
            }
24
        }
25

26
        stage('编译构建') {
27
            // 5. when: 条件判断，满足条件才执行该 stage
28
            when {
29
                environment name: 'ENV', value: 'prod'
30
            }
31
            steps {
32
                echo '当前是生产环境，执行特定的生产编译逻辑...'
33
            }
34
        }
35
    }
36

37
    // 6. post: 无论流水线结果如何，最终都会执行的收尾动作
38
    post {
39
        always {
40
            echo '总是执行：清理工作空间...'
41
            cleanWs()
42
        }
43
        success {
44
            echo '只有成功才执行：发送钉钉/邮件通知...'
45
        }
46
        failure {
47
            echo '只有失败才执行：收集错误日志并告警...'
48
        }
49
    }
50
}

4.3 进阶指令：让你的流水线更健壮#

除了上述基础骨架，声明式 Pipeline 还提供了非常强大的 options 指令，用于控制流水线的全局行为。在企业实战中，以下三个配置几乎是必填项：

1
pipeline {
2
    agent any
3

4
    // options 定义在 pipeline 顶层，控制整体行为
5
    options {
6
        // 1. 超时控制：防止构建卡死（比如 npm install 挂起），浪费节点资源
7
        timeout(time: 1, unit: 'HOURS')
8

9
        // 2. 失败重试：遇到网络抖动等偶发错误时，自动重试指定次数
10
        retry(3)
11

12
        // 3. 时间戳：在控制台输出的每一行日志前加上时间，排查耗时神器
13
        timestamps()
14

15
        // 4. 禁用并发：禁止同一个项目同时跑多次构建，防止资源竞争或部署冲突
16
        disableConcurrentBuilds()
17
    }
18
    // ... stages
19
}

4.4 复杂流程控制：并行构建与人工审批#

传统的自由风格项目只能串行执行，而 Pipeline 轻松支持并发执行（Parallel）和人工干预（Input）。

场景一：并行测试。前端和后端的单元测试可以同时跑，节约整体构建时间。

1
stage('自动化测试') {
2
    parallel { // 开启并行块
3
        stage('前端测试') {
4
            steps {
5
                echo "正在运行 Jest 单元测试..."
6
                sleep 5 // 模拟耗时
7
            }
8
        }
9
        stage('后端测试') {
10
            steps {
11
                echo "正在运行 JUnit 测试..."
12
                sleep 10
13
            }
14
        }
15
    }
16
}

场景二：人工审批发布。测试环境部署后，QA 需要介入测试。测试通过后，运维人员在 Jenkins 界面点击“批准”，才允许部署到生产环境。

1
stage('部署到生产环境') {
2
    steps {
3
        // 流水线会在这里暂停，等待人工点击
4
        input message: '测试是否已通过？是否确认发布到生产环境？',
5
              submitter: 'admin,ops-manager' // 只有特定角色的用户能点击批准
6

7
        echo '审批通过，开始发布生产环境...'
8
    }
9
}

4.5 神器入门：Pipeline语法生成器怎么用#

“既然 Pipeline 是写代码，那我要是不知道怎么用 Git 拉代码，或者不知道怎么发邮件的 Groovy 语法怎么办？”

完全不用慌，因为没人能记住所有的语法。Jenkins 提供了一个神器：Snippet Generator（片段生成器）。

在 Pipeline 配置页面的底部，或者项目视图的左侧菜单中，点击 Pipeline Syntax。 进入片段生成器后：

1. Sample Step 下拉框选择你要做的动作（比如 git: Git，或者 sh: Shell Script）。
2. 像自由风格项目一样，在界面上直观地填入仓库 URL 和凭据下拉框。
3. 点击 Generate Pipeline Script。
4. Jenkins 会自动帮你生成对应的 Groovy 代码（例如 git credentialsId: 'xxx', url: 'http://xxx.git'），你直接复制粘贴到 Jenkinsfile 的 steps 块中即可！

插件支持度与 Replay 功能

1. 几乎所有你安装的 Jenkins 插件（如 Docker、Kubernetes、SonarQube），只要它们支持 Pipeline，都会在 Snippet Generator 的下拉框中提供生成模板。
2. 调试 Pipeline 时，每次都要改代码并提交到 Git 极其麻烦。你可以使用左侧菜单的 Replay（重放） 功能，直接在网页里临时修改代码并运行测试，调通后再统一提交到代码库。