Article

持续集成 Jenkins

更新于：2026-07-15

第一章：Jenkins 简介与核心概念

1.1 什么是 Jenkins

概念名称说明注意事项
Jenkins开源的自动化服务器，用于支持软件项目的持续集成和持续交付（CI/CD）。它通过插件架构提供高度可扩展性，能够自动化构建、测试、部署等任务。Jenkins 使用 Java 编写，需运行在 Java 环境（JRE/JDK）之上；适用于各种平台和开发语言。
自动化服务器一种能够在代码变更后自动执行预定义任务（如编译、测试、部署）的服务程序。不同于普通脚本调度工具，Jenkins 提供 Web 界面、任务依赖管理、日志追踪和丰富的插件生态。
CI/CD 支持Jenkins 的核心用途是实现持续集成与持续交付流程的自动化。它本身不强制使用特定流程模型，用户可根据项目需求自定义流水线逻辑。
插件架构Jenkins 功能主要通过插件扩展，拥有超过 1800 个官方插件。插件质量参差不齐，部分插件可能不再维护，安装前应检查兼容性和更新记录。

1.2 持续集成（CI）与持续交付（CD）概述

概念名称说明注意事项
持续集成（Continuous Integration, CI）开发人员频繁地（通常每天多次）将代码集成到共享主干（mainline），每次集成都通过自动化构建（包括编译、测试）来验证，以便尽早发现集成错误。必须配合版本控制系统（如 Git）使用；建议每次提交都触发一次构建。
持续交付（Continuous Delivery, CD）在持续集成的基础上，确保软件可以随时以安全、可靠的方式发布到生产环境。通常包括自动化测试、预发布环境部署、人工审批等环节。强调”可发布”状态，但不一定自动发布；发布决策可由团队控制。
持续部署（Continuous Deployment）是持续交付的延伸，指每一次通过自动化测试的代码变更都会自动部署到生产环境，无需人工干预。对测试覆盖率和自动化程度要求极高；适用于高成熟度团队。
构建（Build）将源代码转换为可执行程序或部署包的过程，例如 Java 项目中的编译、打包（jar/war）。“构建”在 Jenkins 中泛指一次任务执行，不仅限于编译。
测试自动化在 CI 阶段自动运行单元测试、集成测试等，确保新代码不会破坏现有功能。建议结合代码覆盖率工具（如 JaCoCo）监控测试质量。
反馈快速化CI/CD 的目标之一是让开发人员尽快获得构建和测试结果反馈，通常在几分钟内完成。构建时间过长会影响开发效率，应优化构建流程。

1.3 Jenkins 架构与核心组件

组件名称说明注意事项
主节点（Master Node）Jenkins 的核心控制节点，负责管理任务调度、用户界面展示、插件加载、代理节点协调等工作。主节点不应直接执行构建任务，以免资源争用影响系统稳定性。
Web UI（Web 用户界面）基于 Web 的图形化操作界面，用于配置任务、查看构建历史、管理插件和用户权限。默认监听 8080 端口；可通过反向代理增强安全性。
Job/Task（任务）Jenkins 中的基本执行单元，代表一个自动化流程，如构建、测试或部署。支持多种类型：自由风格项目、Pipeline、多分支 Pipeline 等。
Plugin System（插件系统）Jenkins 功能扩展机制，几乎所有外部集成（Git、Docker、Kubernetes）都通过插件实现。插件之间可能存在依赖关系，升级时需注意兼容性。
Build Queue（构建队列）当没有可用代理节点或资源不足时，任务会进入等待队列，按优先级排队执行。可通过标签（Label）和节点分配策略优化调度效率。
Configuration as CodeJenkins 支持将配置保存为 XML 文件或 Jenkinsfile，便于版本化管理和迁移。推荐使用”Job DSL”或”Configuration as Code (CasC)“插件实现完全代码化配置。

1.4 Jenkins 主节点与代理节点（Master-Agent）模型

概念名称说明注意事项
代理节点（Agent Node）又称”从节点”或”执行节点”，是实际执行构建任务的工作机器，可以是物理机、虚拟机或容器。代理节点必须能与主节点网络互通，并安装 Java 运行环境。
分布式构建利用多个代理节点并行执行不同任务，提升整体构建效率和资源利用率。适合大型团队或高并发构建场景。
节点通信方式主节点与代理节点之间通过 JNLP（Java Network Launch Protocol）或 SSH 协议建立连接。JNLP 需要开放特定端口；SSH 方式更常见于 Linux 环境。
标签（Label）为代理节点打上标签（如 linux、docker、high-mem），任务可指定在具有特定标签的节点上运行。合理使用标签可实现精细化资源调度，例如前端项目指定 nodejs 标签节点。
临时代理（Ephemeral Agent）动态创建的代理节点，常用于 Kubernetes 或云环境，任务结束后自动销毁。节省资源，适合短时高负载场景。
工作目录（Workspace）每个任务在代理节点上拥有独立的工作空间，用于存放源码副本和构建产物。多次构建间可选择是否保留工作区以提高效率（如依赖缓存）。
资源隔离不同代理节点可运行不同操作系统或环境，实现跨平台构建测试。例如：Windows 节点用于 .NET 构建，Linux 节点用于 Java 构建。

第二章：Jenkins 安装与环境搭建

2.1 在 Windows 上安装 Jenkins

方法名称语法/操作步骤用途代码示例注意事项
下载 Jenkins WAR 包访问 https://www.jenkins.io/download/，选择 Generic Java package (.war)获取 Jenkins 核心程序文件无（手动下载）确保从官方站点下载，避免第三方修改版本。
安装 Java 环境安装 JDK 8 或更高版本，并配置 JAVA_HOME 环境变量提供 Jenkins 运行所需的 Java 支持set JAVA_HOME=C:\Program Files\Java\jdk1.8.0_301 set PATH=%JAVA_HOME%\bin;%PATH%必须使用支持的 Java 版本；建议使用 LTS 版本。
启动 Jenkins（命令行）java -jar jenkins.war --httpPort=8080以独立进程方式启动 Jenkins 服务java -jar jenkins.war --httpPort=8080首次运行会生成管理员密码文件，路径在控制台输出中提示。
安装为 Windows 服务使用 NSSM (Non-Sucking Service Manager) 或 Jenkins 自带工具安装为系统服务实现 Jenkins 开机自启和后台运行nssm install Jenkins "C:\Program Files\Java\jdk1.8.0_301\bin\java.exe" -jar "C:\jenkins\jenkins.war"推荐生产环境使用服务方式运行，避免关闭终端后服务中断。
指定自定义工作目录设置 JENKINS_HOME 环境变量将 Jenkins 数据存储位置从默认用户目录迁移至指定路径set JENKINS_HOME=D:\jenkins_home建议提前设置，便于备份与迁移；需确保目录有读写权限。

2.2 在 Linux 上安装 Jenkins（Ubuntu/CentOS）

方法名称语法/操作步骤用途代码示例注意事项
添加 Jenkins 仓库密钥（Ubuntu）wget -q -O - https://pkg.jenkins.io/debian-stable/jenkins.io.key | sudo apt-key add -验证 Jenkins 软件包来源合法性wget -q -O - https://pkg.jenkins.io/debian-stable/jenkins.io.key | sudo apt-key add -若 apt-key 已弃用，可改用 gpg 并放入 /etc/apt/trusted.gpg.d/
添加 Jenkins 仓库（Ubuntu）echo deb https://pkg.jenkins.io/debian-stable binary/ | sudo tee /etc/apt/sources.list.d/jenkins.list添加 Jenkins 官方 APT 源echo deb https://pkg.jenkins.io/debian-stable binary/ | sudo tee /etc/apt/sources.list.d/jenkins.list使用 stable 分支确保版本稳定性。
更新软件包索引（Ubuntu）sudo apt update同步最新软件包信息sudo apt update必须在添加源后执行。
安装 Jenkins（Ubuntu）sudo apt install jenkins安装 Jenkins 及其依赖sudo apt install jenkins默认安装 OpenJDK 若未预装 Java。
启动 Jenkins 服务（Systemd）sudo systemctl start jenkins sudo systemctl enable jenkins启动并设置开机自启sudo systemctl status jenkins检查状态确认是否正常运行。
安装 Java（CentOS）sudo yum install java-17-openjdk-devel安装 Jenkins 所需的 Java 环境sudo yum install java-17-openjdk-develJenkins 推荐使用 Java 17+（Jenkins 2.356+）。
添加 Jenkins 仓库（CentOS）sudo wget -O /etc/yum.repos.d/jenkins.repo https://pkg.jenkins.io/redhat-stable/jenkins.repo sudo rpm --import https://pkg.jenkins.io/redhat-stable/jenkins.io.key添加 YUM 源sudo rpm --import https://pkg.jenkins.io/redhat-stable/jenkins.io.key注意区分 stable 和 latest 版本源。
安装 Jenkins（CentOS）sudo yum install jenkins安装 Jenkins RPM 包sudo yum install jenkins安装路径通常为 /usr/lib/jenkins。
防火墙开放端口sudo ufw allow 8080（Ubuntu） sudo firewall-cmd --permanent --add-port=8080/tcp（CentOS）允许外部访问 Jenkins Web 界面sudo firewall-cmd --reload若启用防火墙，必须放行 8080 端口。

2.3 使用 Docker 安装 Jenkins

方法名称语法/操作步骤用途代码示例注意事项
拉取 Jenkins 官方镜像docker pull jenkins/jenkins:lts获取稳定版 Jenkins 镜像docker pull jenkins/jenkins:lts推荐使用 lts 标签以获得长期支持版本。
创建持久化数据卷docker volume create jenkins-data持久化 Jenkins 配置与插件数据docker volume create jenkins-data避免容器重启后数据丢失。
启动 Jenkins 容器docker run -d -p 8080:8080 -p 50000:50000 -v jenkins-data:/var/jenkins_home --name jenkins jenkins/jenkins:lts运行 Jenkins 容器并映射端口和数据卷docker run -d -p 8080:8080 -p 50000:50000 -v jenkins-data:/var/jenkins_home --name jenkins jenkins/jenkins:lts-p 50000 用于代理节点通信；-v 实现数据持久化。
使用本地目录挂载docker run -d -v /path/to/jenkins/home:/var/jenkins_home ...将宿主机目录作为 Jenkins 工作目录docker run -d -v /data/jenkins:/var/jenkins_home -p 8080:8080 --name jenkins jenkins/jenkins:lts确保宿主机目录存在且有读写权限（chown -R 1000:1000 /data/jenkins）。
查看初始管理员密码docker exec jenkins cat /var/jenkins_home/secrets/initialAdminPassword获取首次登录密码docker logs jenkins | grep password密码仅首次生成一次，务必记录。
进入容器终端docker exec -it jenkins bash调试或手动安装插件/工具docker exec -it jenkins bash容器内用户为 jenkins（UID 1000），部分操作需 sudo 权限模拟。

2.4 初始配置与插件推荐安装

方法名称语法/操作步骤用途代码示例注意事项
安装向导（Setup Wizard）首次启动后访问 http://:8080 进入图形化配置流程引导完成基本安全与插件设置无（Web 界面操作）必须完成此步骤才能使用 Jenkins。
输入管理员密码从 /var/jenkins_home/secrets/initialAdminPassword 文件获取解锁初始设置界面sudo cat /var/jenkins_home/secrets/initialAdminPassword若使用 Docker，需进入容器或挂载目录查看。
安装推荐插件在”Customize Jenkins”页面选择”Install suggested plugins”快速安装常用核心插件集无（勾选选项）包含 Git、SSH、Pipeline、Matrix Authorization 等基础功能。
选择插件安装方式Install suggested plugins 或 Select plugins to install自定义插件集合无新手建议选择推荐插件。
创建首个管理员用户填写用户名、密码、邮箱等信息避免使用默认 admin 账户，提升安全性无（表单输入）记住凭据，后续登录使用此账户。
配置 Jenkins URL设置 Jenkins 实例的公共访问地址用于邮件通知、Webhook 回调等场景http://your-domain.com:8080若后期更改需在”系统管理 > 系统配置”中更新。
推荐插件列表Git Plugin, GitHub Plugin, Pipeline, Credentials Binding, Docker Pipeline, Email Extension, Workspace Cleanup, Blue Ocean增强版本控制、流水线、安全、通知等功能无可在”系统管理 > 插件管理”中单独安装。

2.5 访问 Jenkins Web 界面与首次登录设置

方法名称语法/操作步骤用途代码示例注意事项
访问 Jenkins 地址浏览器打开 http://<服务器IP或域名>:8080进入 Jenkins 登录首页http://192.168.1.100:8080确保网络可达且防火墙已放行端口。
查看初始密码查看日志或 secrets 文件输出获取解锁 Jenkins 所需的一次性密码docker logs jenkins | grep password cat $JENKINS_HOME/secrets/initialAdminPassword若复制粘贴失败，尝试手动输入。
解锁 Jenkins在登录页输入初始管理员密码进入插件安装阶段无（输入密码）密码输入错误多次可能导致锁定。
跳过插件安装（高级）点击”Continue as admin”或”Skip plugin installation”手动控制插件安装过程无不推荐生产环境跳过，可能导致功能缺失。
修改系统配置（首次）登录后进入”Manage Jenkins > Configure System”设置邮件服务器、全局变量、构建工具路径等无（Web 表单）建议尽早配置邮件通知和 JDK/Maven 路径。
更改监听端口（可选）启动时指定 —httpPort 参数或修改 systemd 配置避免端口冲突或符合安全策略java -jar jenkins.war --httpPort=9090若使用反向代理（如 Nginx），可改为内网端口。
启用 CSRF 保护在”Configure Global Security”中启用”Prevent Cross Site Request Forgery exploits”防止跨站请求伪造攻击默认启用生产环境必须开启。
备份 JENKINS_HOME定期复制整个 JENKINS_HOME 目录实现 Jenkins 配置与数据的完整备份cp -r /var/jenkins_home /backup/jenkins_home_$(date +%F)最简单的备份方式，恢复时直接替换目录即可。

第三章：Jenkins 用户管理与权限控制

3.1 用户创建与管理

方法名称语法/操作步骤用途代码示例注意事项
创建本地用户（Web 界面）“Manage Jenkins” > “Manage Users” > “Create User”在 Jenkins 内部用户数据库中添加新用户无（填写用户名、密码、全名、邮箱等表单）适用于未集成外部认证系统的小型团队。
删除用户在”Manage Users”列表中点击用户后选择”Delete”移除不再需要的用户账户无删除用户不会自动清除其构建历史记录。
查看用户详情点击用户进入其详情页面查看用户的构建活动、权限分配等信息无可用于审计和权限排查。
修改用户信息在用户详情页点击”Configure”更新用户密码、邮箱或全名无普通用户只能修改自身信息；管理员可修改所有用户。
启用/禁用用户通过插件如 “Matrix Authorization Strategy” 或脚本控制临时禁止某用户登录或执行操作无（需结合安全域配置）更安全的做法是移除权限而非删除用户。
使用 CLI 创建用户java -jar jenkins-cli.jar -s http://localhost:8080/ create-user username password fullname email通过命令行批量创建用户java -jar jenkins-cli.jar -s http://localhost:8080/ create-user dev1 pass123 "Developer One" dev1@company.com需提前配置好 CLI 访问权限，适合自动化场景。

3.2 角色-Based 访问控制（Role-Based Strategy）配置

方法名称语法/操作步骤用途代码示例注意事项
安装 Role-Based Strategy 插件”Manage Jenkins” > “Manage Plugins” > 搜索并安装 “Role-based Authorization Strategy”实现基于角色的细粒度权限管理无必须先安装插件才能启用该策略。
启用 Role-Based 策略”Manage Jenkins” > “Configure Global Security” > “Authorization” > 选择 “Role-Based Strategy”开启角色权限模型无切换后原有矩阵权限将失效。
创建全局角色（Global Roles）“Manage Jenkins” > “Manage and Assign Roles” > “Manage Roles” > “Global roles” > Add定义适用于整个 Jenkins 实例的角色名称：Admin，权限：Overall/Administer, Job/Read 等Admin 角色应仅分配给少数管理员。
创建项目角色（Project Roles）在 “Project roles” 中添加角色并设置模式匹配规则定义针对特定任务的访问权限名称：dev-team-a，Pattern: ^team-a-.*，权限：Job/Build, Job/Read支持正则表达式匹配任务名称。
创建代理角色（Agent Roles）在 “Agent roles” 中定义节点相关权限角色控制对代理节点的访问和操作权限名称：node-admin，权限：Agent/Connect, Agent/Configure通常用于运维人员管理节点。
分配角色给用户”Manage and Assign Roles” > “Assign Roles” > 选择用户并勾选对应角色将已定义的角色关联到具体用户或用户组用户 dev1 → 全局角色 Developer + 项目角色 dev-team-a一个用户可拥有多个角色。
使用正则表达式匹配任务在 Project Roles 的 Pattern 字段输入正则表达式实现动态任务权限分配^frontend-.* 匹配所有以前端开头的任务正则语法错误会导致权限不生效。

3.3 项目级权限管理

方法名称语法/操作步骤用途代码示例注意事项
启用项目级权限确保已使用 “Role-Based Strategy” 或 “Project-based Matrix Authorization Strategy”对单个任务设置独立访问控制无必须在全局安全设置中启用支持项目级权限的策略。
配置单个任务的权限进入任务配置页 > 勾选 “This project is pre-operated” > “Restrict where this project can be run” 和 “Security” 部分限制谁可以查看、构建或配置该任务无（Web 表单）权限继承自全局设置，除非显式覆盖。
添加项目级用户/角色在任务配置的安全区域添加特定用户或角色给特定任务赋予额外访问权限用户 qa-team → 权限：Job/Build, Job/Read适用于跨团队协作项目。
使用 “Project-based Matrix Authorization Strategy” 插件安装插件并在任务配置中启用矩阵权限在每个任务中直接定义权限矩阵无提供比全局策略更灵活的控制能力。
限制构建触发权限在任务配置中取消非相关人员的 “Build” 权限防止未经授权的构建执行仅允许 dev-leads 用户拥有 Job/Build 权限结合参数化构建和审批流程更佳。
隐藏敏感任务不授予普通用户 Job/Read 权限使任务在任务列表中不可见无是实现权限隔离的有效手段。
继承与覆盖机制默认继承全局权限，可通过项目设置覆盖平衡统一管理和个性化需求无建议保持一致性，避免过度定制增加维护成本。

3.4 安全设置与最佳实践

方法名称语法/操作步骤用途代码示例注意事项
启用安全域（Security Realm）“Configure Global Security” > “Security Realm” > 选择 “Jenkins’ own user database” 或 “LDAP”定义用户认证来源选择 LDAP 可集成企业 AD生产环境推荐使用 LDAP/OAuth2 统一认证。
强制使用 HTTPS配置反向代理（Nginx/Apache）启用 SSL/TLS加密 Web 流量防止凭证泄露参见下方代码示例自签证书需在客户端信任，否则浏览器报错。
设置会话超时时间在 “Configure Global Security” 中设置 “Session timeout”减少未授权访问风险输入分钟数（如 30）过短影响用户体验，过长增加安全风险。
禁用脚本控制台（Script Console）移除非管理员用户的 “Script/Run” 权限防止 Groovy 脚本执行导致 RCE无脚本控制台功能强大但极其危险，生产环境应严格限制。
定期更新 Jenkins 与插件”Manage Jenkins” > “Manage Plugins” > “Updates” > 安装更新修复已知漏洞建议每周检查一次更新重大版本升级前应在测试环境验证兼容性。
备份 JENKINS_HOME 目录定期复制 $JENKINS_HOME 到安全位置实现完整配置与数据备份tar -czf jenkins-backup-$(date +%F).tar.gz /var/jenkins_home包含 jobs、users、plugins、credentials 等所有信息。
启用审计日志（Audit Logging）使用插件如 “Audit Trail” 记录关键操作追踪用户行为，满足合规要求无（插件自动记录登录、任务修改等事件）日志应集中存储并定期归档。
最小权限原则仅授予用户完成工作所需的最低权限降低误操作和恶意行为影响例如：开发者只需 Job/Build 和 Job/Read避免随意分配 Admin 权限。

HTTPS 反向代理配置示例（Nginx）：

server {
    listen 443 ssl;
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    location / {
        proxy_pass http://localhost:8080;
    }
}

第四章：Jenkins 任务（Job）基础

4.1 创建自由风格项目（Freestyle Project）

方法名称语法/操作步骤用途代码示例注意事项
新建自由风格项目进入 Jenkins 主页 > 点击”新建任务” > 输入名称 > 选择”构建一个自由风格的项目”创建最基础的任务类型，适用于简单自动化流程无（Web 界面操作）自由风格项目灵活性高，适合学习和轻量级任务。
配置任务描述在项目主页点击”配置” > 在”描述”字段输入文本为任务添加说明信息，便于团队理解用途部署前端静态资源到测试环境支持 HTML 标签格式化内容。
启用/禁用任务在项目主页点击”启用”或”禁用”暂时停止任务执行而不删除无禁用后仍保留构建历史和配置。
复制现有任务”新建任务” > 选择”复制现有项目” > 输入新名称并指定源任务快速创建结构相似的任务，减少重复配置源任务：build-frontend，新任务：build-backend修改后需检查路径、参数等是否适配。
删除任务在项目主页点击”删除项目”彻底移除任务及其所有构建历史无删除操作不可逆，请谨慎执行。
设置任务图标/颜色（通过插件）使用 “Build Monitor View” 等插件自定义显示样式在仪表盘中突出关键任务状态无提升可视化监控效率。

4.2 配置源码管理（SCM）：Git 与 SVN

方法名称语法/操作步骤用途代码示例注意事项
启用 Git 源码管理在任务配置中 > “源码管理” > 选择”Git”从 Git 仓库拉取代码进行构建Repository URL: https://github.com/user/repo.git需提前安装 Git Plugin。
配置 Git 仓库地址填写 Repository URL 字段指定代码仓库位置https://github.com/jenkinsci/jenkins.git支持 HTTPS 和 SSH 协议。
设置 Git 凭据使用”添加”按钮配置用户名/密码或 SSH 私钥认证访问私有仓库类型：Username with password 或 SSH Username with private key私钥应使用 Jenkins Credentials Store 管理。
指定分支在 “Branches to build” 中填写分支名控制构建特定分支代码*/main 或 */develop默认为 */main。
启用 SVN 源码管理在任务配置中 > “源码管理” > 选择”Subversion”从 SVN 仓库检出代码Repository URL: http://svn.company.com/svn/project/trunk需安装 Subversion Plugin。
配置 SVN 凭据添加用户名/密码类型凭据认证访问 SVN 服务器Domain: company.com, Username: jenkins, Password: ***支持 Windows 域账户。
定义本地检出目录使用 “Check-out to a sub-directory” 或自定义 workspace 路径将代码检出到指定子目录sub-project-a避免覆盖已有文件。
高级 Git 配置点击”高级”按钮设置更多选项自定义克隆行为、超时等Clone depth: 1, Timeout (minutes): 10浅克隆可加快速度但不包含完整历史。

4.3 构建触发器：定时构建与远程触发

方法名称语法/操作步骤用途代码示例注意事项
定时构建（Build periodically）在”构建触发器”中勾选 > 输入 cron 表达式按固定时间间隔自动触发构建H 2 * * *（每天凌晨2点）H 表示”哈希”，分散负载避免峰值。
Cron 语法格式分 时 日 月 周定义触发时间规则H/15 * * * *（每15分钟一次）不支持秒级精度；H 可替代具体数字。
GitHub Webhook 触发勾选”GitHub hook trigger for GITScm polling”当代码推送到 GitHub 时自动触发构建无（需在 GitHub 仓库设置 Webhook）必须配合 GitHub Integration Plugin 使用。
轮询 SCM（Poll SCM）勾选并输入 cron 表达式定期检查代码库变更，有更新则构建H/5 * * * *（每5分钟检查一次）消耗资源较多，建议用 Webhook 替代。
远程触发构建（Trigger builds remotely）勾选并设置认证令牌（Token）允许外部系统通过 HTTP 请求触发构建Token: my-secret-tokenURL 格式：http://jenkins/job/job-name/build?token=my-secret-token
使用身份验证令牌在远程触发时添加 token 参数防止未授权调用curl -X POST http://jenkins/job/deploy-prod/build?token=abc123建议使用长随机字符串作为 token。
构建另一个项目（Build after other projects are built）指定上游项目名称和触发条件实现任务依赖链项目名：build-app，条件：成功支持失败、不稳定等状态判断。

4.4 执行 Shell/Windows 批处理命令

方法名称语法/操作步骤用途代码示例注意事项
添加构建步骤：执行 Shell在”构建”部分点击”增加构建步骤” > “执行 Shell”在 Linux/Unix 环境下运行命令见下方代码示例默认使用 /bin/sh -xe 执行，-x 显示命令，-e 出错退出。
Shell 脚本中的变量使用使用 BUILD_NUMBER、JOB_NAME 等内置变量动态生成文件名或路径echo "Building version $BUILD_NUMBER of $JOB_NAME"完整变量列表见 Jenkins 环境变量文档。
添加构建步骤：执行 Windows 批处理在”构建”部分点击”增加构建步骤” > “执行 Windows 批处理”在 Windows 代理节点上运行 .bat 或 .cmd 文件echo Starting... call mvn clean package使用 cmd /c 执行，支持标准批处理语法。
设置脚本编码（Windows）在批处理步骤中指定”Use custom workspace”或系统区域设置避免中文乱码问题chcp 65001 >nul（切换到 UTF-8）特别是在处理非英文路径时。
多行脚本支持在文本框中直接输入多行命令组织复杂构建逻辑mkdir dist cp -r src/* dist/ zip -r dist.zip dist/注意缩进不影响执行，但建议保持可读性。
脚本退出码处理命令返回非零退出码时构建失败控制构建成功/失败状态exit 1（标记失败） exit 0（标记成功）Jenkins 根据最后一条命令的退出码判断结果。
使用管道和重定向结合 shell 重定向操作符捕获输出、日志记录等npm run test > test.log 2>&1可用于调试或归档中间结果。

Shell 构建步骤示例：

#!/bin/bash
echo "Starting build..."
npm install
npm run build

4.5 构建后操作：归档、邮件通知、清理

方法名称语法/操作步骤用途代码示例注意事项
归档构建产物（Archive the artifacts）在”构建后操作”中添加 > 设置”文件”路径保存生成的文件（如 jar、zip）供后续下载或部署dist/*.zip 或 target/*.jar支持通配符；产物保存在 Jenkins 服务器上。
设置归档文件路径使用相对路径（基于 workspace）指定要归档的文件位置build/output/*.war路径错误将导致”没有匹配的文件”警告。
归档测试报告（Publish JUnit test result report）添加该操作 > 设置测试报告 XML 路径展示单元测试结果和历史趋势**/test-reports/*.xml需测试框架输出兼容 JUnit 格式的报告。
发送邮件通知（E-mail Notification）添加该操作 > 输入收件人列表构建失败或状态变更时发送邮件dev-team@company.com, qa-lead@company.com需提前在系统设置中配置 SMTP 服务器。
使用 Email Extension Plugin替代默认邮件功能，支持更灵活模板自定义邮件主题、内容、收件人策略$DEFAULT_SUBJECT $DEFAULT_CONTENT支持 HTML、附件、条件发送等高级功能。
构建后清理工作空间（Delete workspace after build）添加”构建后操作” > “Delete workspace when build is done”释放磁盘空间，避免残留文件影响下次构建无建议在调试完成后启用。
条件化清理（Workspace Cleanup Plugin）使用高级清理策略，如保留最近 N 次构建的工作区平衡磁盘使用与调试需求保留策略：按数量保留，最大 3 个可结合标签或路径进行精细控制。
触发下游项目添加”构建其他项目”操作实现构建流水线串联项目名：deploy-staging, 参数：VERSION=$BUILD_NUMBER支持同步或异步触发。

第五章：Jenkins Pipeline 入门

5.1 什么是 Jenkins Pipeline

概念名称说明注意事项
Jenkins Pipeline一套插件，支持在 Jenkins 中实现持续交付流水线即代码（Pipeline as Code）。它允许将构建、测试、部署等流程定义为可版本控制的脚本。Pipeline 是 Jenkins 2.0 的核心特性，取代传统自由风格项目的复杂配置。
流水线即代码（Pipeline as Code）使用代码（Groovy 脚本）定义 CI/CD 流程，存入源码仓库（如 Git），实现版本化、复用和审查。推荐将 Jenkinsfile 提交到项目仓库，与代码一同管理。
Pipeline 任务类型Jenkins 中的一种任务形式，用于运行基于 Groovy 的流水线脚本，支持声明式和脚本式两种语法。创建任务时选择 “Pipeline” 类型。
持久化与暂停能力Pipeline 支持长时间运行、跨节点执行，并可在等待人工审批等操作时暂停，状态持久保存。即使 Jenkins 重启，运行中的 Pipeline 也能恢复。
可视化阶段视图Pipeline 运行时可在 Web 界面查看各阶段（Stage）的执行状态和耗时，便于监控和调试。需在脚本中合理划分 stages 以获得清晰视图。
支持复杂流程控制包括条件判断、循环、并行执行、错误处理（try/catch）、超时控制等高级逻辑。相比自由风格项目，具备更强的表达能力。

5.2 声明式 Pipeline 与脚本式 Pipeline 对比

对比项声明式 Pipeline（Declarative Pipeline）脚本式 Pipeline（Scripted Pipeline）注意事项
语法类型基于预定义结构的声明式语法，更像配置文件基于 Groovy DSL 的编程式语法，更像脚本声明式更易读、易学，适合大多数场景。
根块（Root Block）pipeline { ... }node { ... }声明式必须以 pipeline 开始。
结构要求强制结构化：必须包含 agent、stages、steps 等块灵活，可自由编写 Groovy 代码声明式有助于规范代码结构。
错误处理使用 options { timeout }、post 块处理失败使用 Groovy 的 try/catch/finally脚本式在异常处理上更灵活。
条件执行使用 when 指令使用 Groovy 的 if/else声明式的 when 更简洁。
并行执行使用 parallel 指令使用 parallel 步骤两者都支持并行构建。
可扩展性通过 script 块嵌入 Groovy 代码扩展功能完全自由，可调用任意 Groovy 方法脚本式功能更强但易写出难以维护的代码。
学习曲线较低，适合初学者较高，需了解 Groovy 语法推荐新手从声明式入手。
社区趋势Jenkins 官方推荐，持续增强新功能传统方式，功能稳定但更新较少新项目建议优先使用声明式。

5.3 Pipeline 基本语法结构（pipeline, agent, stages, steps）

结构名称语法用途代码示例注意事项
pipelinepipeline { ... }所有声明式 Pipeline 的根容器，必须包含pipeline { agent any stages { ... } }每个 Jenkinsfile 必须有一个且仅一个 pipeline 块。
agentagent { ... }指定 Pipeline 或 stage 在哪个代理节点上执行agent any agent none agent { label 'linux' }any 表示任意可用节点；none 用于顶层定义，由 stage 自行指定。
stagesstages { ... }包含一个或多个 stage 的容器，定义构建的逻辑阶段stages { stage('Build') { ... } stage('Test') { ... } }必须包含至少一个 stage。
stagestage('Stage Name') { ... }定义流水线中的一个阶段，如构建、测试、部署stage('Build') { steps { sh 'make' } }每个 stage 包含 steps 块，用于执行具体操作。
stepssteps { ... }包含一个或多个具体执行命令的容器steps { sh 'echo "Hello"' script { def version = getVersion() } }是实际执行命令的地方，支持 shell、Groovy 脚本等。
scriptscript { ... }在声明式 Pipeline 中嵌入任意 Groovy 代码script { if (env.BRANCH_NAME == 'main') { deployProd() } }用于复杂逻辑处理，如变量计算、条件判断等。

5.4 使用 Jenkinsfile 管理 Pipeline 代码

方法名称语法/操作步骤用途代码示例注意事项
创建 Jenkinsfile在项目根目录创建名为 Jenkinsfile 的文本文件存放 Pipeline 脚本代码touch Jenkinsfile文件名区分大小写，必须为 Jenkinsfile（无后缀）。
使用 SCM 中的 Jenkinsfile在 Pipeline 任务配置中选择 “Pipeline script from SCM”从代码仓库加载 JenkinsfileRepository URL: https://github.com/user/project.git Script Path: Jenkinsfile推荐做法，实现代码与流程共管。
编写声明式 Pipeline 脚本在 Jenkinsfile 中编写 pipeline 块定义完整的 CI/CD 流程见下方代码示例确保语法正确，否则构建失败。
本地测试 Jenkinsfile使用 Jenkinsfile Runner 或在线语法检查工具验证脚本语法和逻辑无（工具辅助）减少提交后才发现错误的风险。
版本控制 Jenkinsfile将 Jenkinsfile 提交到 Git/SVN 仓库实现变更追踪、代码审查和回滚git add Jenkinsfile git commit -m "Add pipeline" git push与应用代码一起评审，确保流程一致性。
多分支 Pipeline 自动发现使用 “Multibranch Pipeline” 任务类型自动为每个分支创建独立 Pipeline无（Jenkins 自动扫描）要求每个分支都有 Jenkinsfile。
设置默认分支在 Multibranch 配置中指定 “Discover branches” 策略控制哪些分支触发 Pipeline策略：All branches可过滤特定分支（如忽略 feature/*）。
处理语法错误查看构建日志中的 “WorkflowScript: X: “调试 Jenkinsfile 语法问题WorkflowScript: 5: Missing required parameter: ‘stages’常见错误包括括号不匹配、缺少必填块等。

声明式 Pipeline 示例（Jenkinsfile）：

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                sh 'mvn clean package'
            }
        }
    }
}

第六章：Jenkinsfile 与高级 Pipeline 语法

6.1 agent 指令详解（any, label, docker, none）

方法名称语法用途代码示例注意事项
agent anyagent any在任意可用的代理节点上运行 Pipelinepipeline { agent any stages { ... } }最常用，适用于大多数场景。
agent noneagent none不在顶层指定执行节点，由每个 stage 自行定义pipeline { agent none stages { stage('Build') { agent { label 'linux' } steps { ... } } } }用于多平台或不同阶段需在不同节点运行的场景。
agent labelagent { label 'label-name' }指定在具有特定标签的节点上运行agent { label 'docker-build' }标签需提前在节点配置中定义。
agent nodeagent { node { label 'linux && amd64' } }使用更复杂的节点选择条件agent { node { label 'ubuntu && high-mem' } }支持逻辑表达式（&&, ||）。
agent dockeragent { docker 'image-name' }在指定的 Docker 镜像容器中运行 Pipelineagent { docker 'maven:3.8.6-jdk-11' }需 Jenkins 主机安装 Docker 并配置权限。
agent dockerfileagent { dockerfile true }使用项目根目录下的 Dockerfile 构建并运行容器agent { dockerfile true } 或 agent { dockerfile 'Dockerfile.build' }支持指定 Dockerfile 路径。
agent inheritagent inherit在嵌套 stage 中继承父级 agent 配置stage('Sub-stage') { agent inherit steps { ... } }仅在 stage 级别使用，声明式 Pipeline 中较少见。

6.2 stages 与 stage：定义构建阶段

方法名称语法用途代码示例注意事项
stagesstages { ... }容器块，包含一个或多个 stagestages { stage('Build') { steps { sh 'make' } } stage('Test') { steps { sh 'make test' } } }必须包含至少一个 stage。
stagestage('Stage Name') { ... }定义流水线中的一个逻辑阶段stage('Deploy') { steps { sh './deploy.sh' } }阶段名称应清晰描述其功能。
嵌套 stagestage('Outer') { stages { stage('Inner A') { ... } stage('Inner B') { ... } } }在一个 stage 内部定义多个子阶段stage('Build') { stages { stage('Compile') { steps { ... } } stage('Package') { steps { ... } } } }可实现更细粒度的可视化和控制。
可选阶段（when）stage('Deploy Prod') { when { branch 'main' } steps { ... } }根据条件决定是否执行该阶段when { expression { env.DEPLOY_ENV == 'prod' } }支持 branch、environment、expression 等条件。
并行阶段parallel { stage('Frontend') { ... } stage('Backend') { ... } }并行执行多个 stage，提升效率见下方代码示例并行阶段独立运行，失败一个可能导致整体失败。
阶段超时options { timeout(time: 10, unit: 'MINUTES') }为单个阶段设置执行超时stage('Long Task') { options { timeout(time: 5, unit: 'MINUTES') } steps { ... } }超时后阶段标记为失败。

6.3 steps：执行具体操作

方法名称语法用途代码示例注意事项
shsh 'command'在 Linux/Unix 节点上执行 shell 命令steps { sh 'mvn clean package' sh 'echo $BUILD_NUMBER' }默认使用 /bin/sh 执行。
batbat 'command'在 Windows 节点上执行批处理命令steps { bat 'call mvn clean package' bat 'echo %BUILD_NUMBER%' }使用 cmd /c 执行。
scriptscript { ... }执行 Groovy 脚本，用于复杂逻辑steps { script { def version = sh(script: 'git describe --tags', returnStdout: true).trim() env.APP_VERSION = version } }可访问 Jenkins API 和变量。
echoecho 'message'输出信息到构建日志echo 'Starting deployment...'用于调试和流程提示。
sleepsleep(time: 30, unit: 'SECONDS')暂停执行一段时间sleep(time: 2, unit: 'MINUTES')可用于等待外部系统响应。
archiveArtifactsarchiveArtifacts artifacts: 'target/*.jar', allowEmptyArchive: true归档构建产物archiveArtifacts 'dist/*.zip'allowEmptyArchive 防止无文件时报错。
junitjunit 'test-results/*.xml'发布 JUnit 测试报告junit 'build/test-results/test/*.xml'需测试框架生成兼容格式。
checkoutcheckout scm检出当前任务的源码（通常自动执行）checkout([$class: 'GitSCM', ...])自定义 SCM 行为时使用。

6.4 script 块：在声明式 Pipeline 中使用 Groovy

方法名称语法用途代码示例注意事项
script 块script { ... }在声明式 Pipeline 中嵌入任意 Groovy 代码steps { script { def list = [1,2,3] list.each { println it } } }是声明式 Pipeline 扩展功能的主要方式。
定义变量script { def version = '1.0' }在 Groovy 上下文中声明变量script { env.BUILD_TAG = "v${env.BUILD_NUMBER}" }可修改环境变量或创建临时变量。
条件逻辑script { if (condition) { ... } }实现复杂条件判断script { if (env.BRANCH_NAME == 'main') { env.DEPLOY_ENV = 'prod' } else { env.DEPLOY_ENV = 'staging' } }Groovy 语法，支持 if/else、switch 等。
循环处理script { for (item in list) { ... } }遍历集合或执行重复操作script { ['dev', 'test', 'prod'].each { env -> sh "deploy.sh $env" } }避免无限循环。
调用函数script { def ver = getBuildVersion() }调用自定义或共享库函数script { def version = sh(script: 'git describe --tags', returnStdout: true).trim() }可封装重复逻辑。
异常处理script { try { ... } catch (e) { ... } }捕获和处理错误script { try { sh 'risky-command' } catch (Exception e) { echo "Warning: ${e}" } }防止脚本因单个错误中断。
返回值处理script { return sh(...) }从 script 块返回值供后续使用script { def output = sh(script: 'whoami', returnStdout: true).trim() env.USER = output }使用 returnStdout: true 获取命令输出。

6.5 environment：环境变量定义

方法名称语法用途代码示例注意事项
environment 块environment { KEY = 'value' }定义环境变量，供整个 Pipeline 使用environment { APP_NAME = 'my-app' DEBUG = 'true' }可在 steps 中通过 env.KEY 访问。
动态变量（script）environment { VERSION = script { ... } }使用 Groovy 脚本动态生成变量值environment { VERSION = script { return sh(script: 'git describe --tags', returnStdout: true).trim() } }脚本在 Pipeline 开始时执行一次。
credentialsenvironment { USER = credentials('cred-id') }从 Jenkins 凭据存储中加载敏感信息environment { DB_USER = credentials('db-username') DB_PASS = credentials('db-password') }自动解密并设置为环境变量，避免明文暴露。
内置环境变量引用environment { MY_BUILD = '$BUILD_NUMBER' }使用 Jenkins 内置变量environment { BUILD_TAG = 'jenkins-${JOB_NAME}-${BUILD_NUMBER}' }支持大多数内置变量插值。
阶段级 environmentstage('Deploy') { environment { ENV = 'prod' } steps { ... } }为特定阶段定义环境变量变量仅在该 stage 内有效优先级高于全局 environment。
敏感信息保护使用 credentials() 或 Secret Text 类型防止密码、密钥等泄露credentials('aws-secret-key')日志中会自动屏蔽。

6.6 parameters：参数化构建

方法名称语法用途代码示例注意事项
parameters 块parameters { ... }定义构建时可输入的参数parameters { string(name: 'VERSION', defaultValue: '1.0', description: 'App version') }必须在 pipeline 块内定义。
string 参数string(name: 'KEY', defaultValue: 'val', description: '...')字符串输入参数string(name: 'TAG', defaultValue: 'latest', description: 'Docker tag')最常用参数类型。
booleanParambooleanParam(name: 'DEBUG', defaultValue: true, description: 'Enable debug?')布尔值（复选框）参数booleanParam(name: 'CLEAN', defaultValue: false)构建时显示为勾选框。
choicechoice(choices: ['dev','staging','prod'], name: 'ENV', description: 'Target environment')下拉选择参数choice(choices: '''dev\nstaging\nprod''', name: 'DEPLOY_ENV')choices 为多行字符串。
texttext(name: 'NOTES', defaultValue: '', description: 'Release notes')多行文本输入text(name: 'SCRIPT', defaultValue: '#!/bin/bash\n')适合输入脚本或长文本。
passwordpassword(name: 'SECRET', defaultValue: '', description: 'Secret token')密码输入（隐藏显示）password(name: 'API_KEY', description: 'External API key')输入内容在 UI 和日志中隐藏。
在脚本中使用参数steps { sh "echo $VERSION" }通过变量名访问参数值echo "Deploying $DEPLOY_ENV environment"参数自动作为环境变量注入。

6.7 options：构建选项（超时、重试、时间戳等）

方法名称语法用途代码示例注意事项
timeoutoptions { timeout(time: 1, unit: 'HOURS') }设置整个 Pipeline 的最大执行时间options { timeout(time: 30, unit: 'MINUTES') }超时后构建失败。
retryoptions { retry(3) }构建失败时自动重试指定次数options { retry(2) }每次失败后立即重试，适用于不稳定外部依赖。
timestampsoptions { timestamps() }在构建日志中添加时间戳options { timestamps() ansiColor('xterm') }便于分析各步骤耗时。
buildDiscarderoptions { buildDiscarder(logRotator(daysToKeep: 7, numToKeep: 10)) }自动清理旧的构建记录logRotator(daysToKeep: 30, numToKeep: 50)节省磁盘空间。
disableConcurrentBuildsoptions { disableConcurrentBuilds() }禁止并发构建，确保串行执行options { disableConcurrentBuilds() timeout(time: 1, unit: 'HOURS') }避免资源冲突或数据竞争。
skipDefaultCheckoutoptions { skipDefaultCheckout() }跳过默认的源码检出操作options { skipDefaultCheckout() }当使用自定义 checkout 逻辑时使用。
checkoutToSubdirectoryoptions { checkoutToSubdirectory('src') }将源码检出到子目录options { checkoutToSubdirectory('project-a') }避免覆盖工作区其他文件。
ansiColoroptions { ansiColor('xterm') }启用 ANSI 颜色输出，美化日志options { ansiColor('xterm') }需安装 AnsiColor Plugin。

6.8 triggers：触发器（cron, webhook, pollSCM）

方法名称语法用途代码示例注意事项
crontriggers { cron('H */4 * * *') }定时触发构建triggers { cron('0 2 * * *') // 每天凌晨2点 }使用 Jenkins cron 语法，H 表示哈希。
pollSCMtriggers { pollSCM('H/15 * * * *') }定期检查源码变更，有更新则构建triggers { pollSCM('H/10 * * * *') // 每10分钟检查 }消耗资源，推荐用 Webhook 替代。
upstreamtriggers { upstream(upstreamProjects: 'job1,job2', threshold: hudson.model.Result.SUCCESS) }当上游项目构建成功后触发triggers { upstream(upstreamProjects: 'build-app', threshold: SUCCESS) }实现任务依赖链。
Generic Webhook Trigger需安装插件，配置自定义 Webhook响应外部系统（如 GitLab、自定义服务）的 HTTP 请求见插件文档支持解析 JSON、过滤条件等高级功能。
GitHub Hooktriggers { githubPush() }响应 GitHub 的 push 事件triggers { githubPush() }需在 GitHub 仓库设置 Webhook URL。
多触发器组合triggers { cron(...); githubPush() }同时启用多种触发方式triggers { cron('H 8 * * 1-5') githubPush() }任一条件满足即可触发构建。

6.9 post：构建后操作（always, success, failure 等）

方法名称语法用途代码示例注意事项
postpost { ... }定义构建完成后执行的操作，根据构建状态分支处理post { success { ... } failure { ... } }通常放在 pipeline 块末尾。
alwaysalways { ... }无论构建成功或失败都执行always { echo 'Build finished' }适合清理、通知等通用操作。
successsuccess { ... }仅当构建成功时执行success { emailext(subject: 'Success', body: '...', to: 'team@company.com') }用于发送成功通知、触发下游部署。
failurefailure { ... }仅当构建失败时执行failure { emailext(subject: 'Failed', body: '...', to: 'dev-lead@company.com') }用于告警和故障排查。
unstableunstable { ... }当构建结果为”不稳定”（如测试失败）时执行unstable { echo 'Tests failed but build succeeded' }常用于发送质量警告。
changedchanged { ... }仅当本次构建状态与上次不同时执行changed { echo 'Status changed to unstable' }避免重复通知。
cleanupcleanup { ... }最终清理操作，即使构建被中止也执行cleanup { sh 'rm -rf temp/' }Jenkins 2.173+ 支持，确保资源释放。
通知集成emailext, slackSend, webhook发送邮件、Slack 消息或调用 Webhookemailext(...) slackSend(message: 'Build failed')需安装对应插件（Email Extension, Slack）。

第一章：Jenkins 简介与核心概念

1.1 什么是 Jenkins

概念名称说明注意事项
Jenkins开源的自动化服务器，用于支持软件项目的持续集成和持续交付（CI/CD）。它通过插件架构提供高度可扩展性，能够自动化构建、测试、部署等任务。Jenkins 使用 Java 编写，需运行在 Java 环境（JRE/JDK）之上；适用于各种平台和开发语言。
自动化服务器一种能够在代码变更后自动执行预定义任务（如编译、测试、部署）的服务程序。不同于普通脚本调度工具，Jenkins 提供 Web 界面、任务依赖管理、日志追踪和丰富的插件生态。
CI/CD 支持Jenkins 的核心用途是实现持续集成与持续交付流程的自动化。它本身不强制使用特定流程模型，用户可根据项目需求自定义流水线逻辑。
插件架构Jenkins 功能主要通过插件扩展，拥有超过 1800 个官方插件。插件质量参差不齐，部分插件可能不再维护，安装前应检查兼容性和更新记录。

1.2 持续集成（CI）与持续交付（CD）概述

概念名称说明注意事项
持续集成（Continuous Integration, CI）开发人员频繁地（通常每天多次）将代码集成到共享主干（mainline），每次集成都通过自动化构建（包括编译、测试）来验证，以便尽早发现集成错误。必须配合版本控制系统（如 Git）使用；建议每次提交都触发一次构建。
持续交付（Continuous Delivery, CD）在持续集成的基础上，确保软件可以随时以安全、可靠的方式发布到生产环境。通常包括自动化测试、预发布环境部署、人工审批等环节。强调”可发布”状态，但不一定自动发布；发布决策可由团队控制。
持续部署（Continuous Deployment）是持续交付的延伸，指每一次通过自动化测试的代码变更都会自动部署到生产环境，无需人工干预。对测试覆盖率和自动化程度要求极高；适用于高成熟度团队。
构建（Build）将源代码转换为可执行程序或部署包的过程，例如 Java 项目中的编译、打包（jar/war）。“构建”在 Jenkins 中泛指一次任务执行，不仅限于编译。
测试自动化在 CI 阶段自动运行单元测试、集成测试等，确保新代码不会破坏现有功能。建议结合代码覆盖率工具（如 JaCoCo）监控测试质量。
反馈快速化CI/CD 的目标之一是让开发人员尽快获得构建和测试结果反馈，通常在几分钟内完成。构建时间过长会影响开发效率，应优化构建流程。

1.3 Jenkins 架构与核心组件

组件名称说明注意事项
主节点（Master Node）Jenkins 的核心控制节点，负责管理任务调度、用户界面展示、插件加载、代理节点协调等工作。主节点不应直接执行构建任务，以免资源争用影响系统稳定性。
Web UI（Web 用户界面）基于 Web 的图形化操作界面，用于配置任务、查看构建历史、管理插件和用户权限。默认监听 8080 端口；可通过反向代理增强安全性。
Job/Task（任务）Jenkins 中的基本执行单元，代表一个自动化流程，如构建、测试或部署。支持多种类型：自由风格项目、Pipeline、多分支 Pipeline 等。
Plugin System（插件系统）Jenkins 功能扩展机制，几乎所有外部集成（Git、Docker、Kubernetes）都通过插件实现。插件之间可能存在依赖关系，升级时需注意兼容性。
Build Queue（构建队列）当没有可用代理节点或资源不足时，任务会进入等待队列，按优先级排队执行。可通过标签（Label）和节点分配策略优化调度效率。
Configuration as CodeJenkins 支持将配置保存为 XML 文件或 Jenkinsfile，便于版本化管理和迁移。推荐使用”Job DSL”或”Configuration as Code (CasC)“插件实现完全代码化配置。

1.4 Jenkins 主节点与代理节点（Master-Agent）模型

概念名称说明注意事项
代理节点（Agent Node）又称”从节点”或”执行节点”，是实际执行构建任务的工作机器，可以是物理机、虚拟机或容器。代理节点必须能与主节点网络互通，并安装 Java 运行环境。
分布式构建利用多个代理节点并行执行不同任务，提升整体构建效率和资源利用率。适合大型团队或高并发构建场景。
节点通信方式主节点与代理节点之间通过 JNLP（Java Network Launch Protocol）或 SSH 协议建立连接。JNLP 需要开放特定端口；SSH 方式更常见于 Linux 环境。
标签（Label）为代理节点打上标签（如 linux、docker、high-mem），任务可指定在具有特定标签的节点上运行。合理使用标签可实现精细化资源调度，例如前端项目指定 nodejs 标签节点。
临时代理（Ephemeral Agent）动态创建的代理节点，常用于 Kubernetes 或云环境，任务结束后自动销毁。节省资源，适合短时高负载场景。
工作目录（Workspace）每个任务在代理节点上拥有独立的工作空间，用于存放源码副本和构建产物。多次构建间可选择是否保留工作区以提高效率（如依赖缓存）。
资源隔离不同代理节点可运行不同操作系统或环境，实现跨平台构建测试。例如：Windows 节点用于 .NET 构建，Linux 节点用于 Java 构建。

第二章：Jenkins 安装与环境搭建

2.1 在 Windows 上安装 Jenkins

方法名称语法/操作步骤用途代码示例注意事项
下载 Jenkins WAR 包访问 https://www.jenkins.io/download/，选择 Generic Java package (.war)获取 Jenkins 核心程序文件无（手动下载）确保从官方站点下载，避免第三方修改版本。
安装 Java 环境安装 JDK 8 或更高版本，并配置 JAVA_HOME 环境变量提供 Jenkins 运行所需的 Java 支持set JAVA_HOME=C:\Program Files\Java\jdk1.8.0_301 set PATH=%JAVA_HOME%\bin;%PATH%必须使用支持的 Java 版本；建议使用 LTS 版本。
启动 Jenkins（命令行）java -jar jenkins.war --httpPort=8080以独立进程方式启动 Jenkins 服务java -jar jenkins.war --httpPort=8080首次运行会生成管理员密码文件，路径在控制台输出中提示。
安装为 Windows 服务使用 NSSM (Non-Sucking Service Manager) 或 Jenkins 自带工具安装为系统服务实现 Jenkins 开机自启和后台运行nssm install Jenkins "C:\Program Files\Java\jdk1.8.0_301\bin\java.exe" -jar "C:\jenkins\jenkins.war"推荐生产环境使用服务方式运行，避免关闭终端后服务中断。
指定自定义工作目录设置 JENKINS_HOME 环境变量将 Jenkins 数据存储位置从默认用户目录迁移至指定路径set JENKINS_HOME=D:\jenkins_home建议提前设置，便于备份与迁移；需确保目录有读写权限。

2.2 在 Linux 上安装 Jenkins（Ubuntu/CentOS）

方法名称语法/操作步骤用途代码示例注意事项
添加 Jenkins 仓库密钥（Ubuntu）wget -q -O - https://pkg.jenkins.io/debian-stable/jenkins.io.key | sudo apt-key add -验证 Jenkins 软件包来源合法性wget -q -O - https://pkg.jenkins.io/debian-stable/jenkins.io.key | sudo apt-key add -若 apt-key 已弃用，可改用 gpg 并放入 /etc/apt/trusted.gpg.d/
添加 Jenkins 仓库（Ubuntu）echo deb https://pkg.jenkins.io/debian-stable binary/ | sudo tee /etc/apt/sources.list.d/jenkins.list添加 Jenkins 官方 APT 源echo deb https://pkg.jenkins.io/debian-stable binary/ | sudo tee /etc/apt/sources.list.d/jenkins.list使用 stable 分支确保版本稳定性。
更新软件包索引（Ubuntu）sudo apt update同步最新软件包信息sudo apt update必须在添加源后执行。
安装 Jenkins（Ubuntu）sudo apt install jenkins安装 Jenkins 及其依赖sudo apt install jenkins默认安装 OpenJDK 若未预装 Java。
启动 Jenkins 服务（Systemd）sudo systemctl start jenkins sudo systemctl enable jenkins启动并设置开机自启sudo systemctl status jenkins检查状态确认是否正常运行。
安装 Java（CentOS）sudo yum install java-17-openjdk-devel安装 Jenkins 所需的 Java 环境sudo yum install java-17-openjdk-develJenkins 推荐使用 Java 17+（Jenkins 2.356+）。
添加 Jenkins 仓库（CentOS）sudo wget -O /etc/yum.repos.d/jenkins.repo https://pkg.jenkins.io/redhat-stable/jenkins.repo sudo rpm --import https://pkg.jenkins.io/redhat-stable/jenkins.io.key添加 YUM 源sudo rpm --import https://pkg.jenkins.io/redhat-stable/jenkins.io.key注意区分 stable 和 latest 版本源。
安装 Jenkins（CentOS）sudo yum install jenkins安装 Jenkins RPM 包sudo yum install jenkins安装路径通常为 /usr/lib/jenkins。
防火墙开放端口sudo ufw allow 8080（Ubuntu） sudo firewall-cmd --permanent --add-port=8080/tcp（CentOS）允许外部访问 Jenkins Web 界面sudo firewall-cmd --reload若启用防火墙，必须放行 8080 端口。

2.3 使用 Docker 安装 Jenkins

方法名称语法/操作步骤用途代码示例注意事项
拉取 Jenkins 官方镜像docker pull jenkins/jenkins:lts获取稳定版 Jenkins 镜像docker pull jenkins/jenkins:lts推荐使用 lts 标签以获得长期支持版本。
创建持久化数据卷docker volume create jenkins-data持久化 Jenkins 配置与插件数据docker volume create jenkins-data避免容器重启后数据丢失。
启动 Jenkins 容器docker run -d -p 8080:8080 -p 50000:50000 -v jenkins-data:/var/jenkins_home --name jenkins jenkins/jenkins:lts运行 Jenkins 容器并映射端口和数据卷docker run -d -p 8080:8080 -p 50000:50000 -v jenkins-data:/var/jenkins_home --name jenkins jenkins/jenkins:lts-p 50000 用于代理节点通信；-v 实现数据持久化。
使用本地目录挂载docker run -d -v /path/to/jenkins/home:/var/jenkins_home ...将宿主机目录作为 Jenkins 工作目录docker run -d -v /data/jenkins:/var/jenkins_home -p 8080:8080 --name jenkins jenkins/jenkins:lts确保宿主机目录存在且有读写权限（chown -R 1000:1000 /data/jenkins）。
查看初始管理员密码docker exec jenkins cat /var/jenkins_home/secrets/initialAdminPassword获取首次登录密码docker logs jenkins | grep password密码仅首次生成一次，务必记录。
进入容器终端docker exec -it jenkins bash调试或手动安装插件/工具docker exec -it jenkins bash容器内用户为 jenkins（UID 1000），部分操作需 sudo 权限模拟。

2.4 初始配置与插件推荐安装

方法名称语法/操作步骤用途代码示例注意事项
安装向导（Setup Wizard）首次启动后访问 http://:8080 进入图形化配置流程引导完成基本安全与插件设置无（Web 界面操作）必须完成此步骤才能使用 Jenkins。
输入管理员密码从 /var/jenkins_home/secrets/initialAdminPassword 文件获取解锁初始设置界面sudo cat /var/jenkins_home/secrets/initialAdminPassword若使用 Docker，需进入容器或挂载目录查看。
安装推荐插件在”Customize Jenkins”页面选择”Install suggested plugins”快速安装常用核心插件集无（勾选选项）包含 Git、SSH、Pipeline、Matrix Authorization 等基础功能。
选择插件安装方式Install suggested plugins 或 Select plugins to install自定义插件集合无新手建议选择推荐插件。
创建首个管理员用户填写用户名、密码、邮箱等信息避免使用默认 admin 账户，提升安全性无（表单输入）记住凭据，后续登录使用此账户。
配置 Jenkins URL设置 Jenkins 实例的公共访问地址用于邮件通知、Webhook 回调等场景http://your-domain.com:8080若后期更改需在”系统管理 > 系统配置”中更新。
推荐插件列表Git Plugin, GitHub Plugin, Pipeline, Credentials Binding, Docker Pipeline, Email Extension, Workspace Cleanup, Blue Ocean增强版本控制、流水线、安全、通知等功能无可在”系统管理 > 插件管理”中单独安装。

2.5 访问 Jenkins Web 界面与首次登录设置

方法名称语法/操作步骤用途代码示例注意事项
访问 Jenkins 地址浏览器打开 http://<服务器IP或域名>:8080进入 Jenkins 登录首页http://192.168.1.100:8080确保网络可达且防火墙已放行端口。
查看初始密码查看日志或 secrets 文件输出获取解锁 Jenkins 所需的一次性密码docker logs jenkins | grep password cat $JENKINS_HOME/secrets/initialAdminPassword若复制粘贴失败，尝试手动输入。
解锁 Jenkins在登录页输入初始管理员密码进入插件安装阶段无（输入密码）密码输入错误多次可能导致锁定。
跳过插件安装（高级）点击”Continue as admin”或”Skip plugin installation”手动控制插件安装过程无不推荐生产环境跳过，可能导致功能缺失。
修改系统配置（首次）登录后进入”Manage Jenkins > Configure System”设置邮件服务器、全局变量、构建工具路径等无（Web 表单）建议尽早配置邮件通知和 JDK/Maven 路径。
更改监听端口（可选）启动时指定 —httpPort 参数或修改 systemd 配置避免端口冲突或符合安全策略java -jar jenkins.war --httpPort=9090若使用反向代理（如 Nginx），可改为内网端口。
启用 CSRF 保护在”Configure Global Security”中启用”Prevent Cross Site Request Forgery exploits”防止跨站请求伪造攻击默认启用生产环境必须开启。
备份 JENKINS_HOME定期复制整个 JENKINS_HOME 目录实现 Jenkins 配置与数据的完整备份cp -r /var/jenkins_home /backup/jenkins_home_$(date +%F)最简单的备份方式，恢复时直接替换目录即可。

第三章：Jenkins 用户管理与权限控制

3.1 用户创建与管理

方法名称语法/操作步骤用途代码示例注意事项
创建本地用户（Web 界面）“Manage Jenkins” > “Manage Users” > “Create User”在 Jenkins 内部用户数据库中添加新用户无（填写用户名、密码、全名、邮箱等表单）适用于未集成外部认证系统的小型团队。
删除用户在”Manage Users”列表中点击用户后选择”Delete”移除不再需要的用户账户无删除用户不会自动清除其构建历史记录。
查看用户详情点击用户进入其详情页面查看用户的构建活动、权限分配等信息无可用于审计和权限排查。
修改用户信息在用户详情页点击”Configure”更新用户密码、邮箱或全名无普通用户只能修改自身信息；管理员可修改所有用户。
启用/禁用用户通过插件如 “Matrix Authorization Strategy” 或脚本控制临时禁止某用户登录或执行操作无（需结合安全域配置）更安全的做法是移除权限而非删除用户。
使用 CLI 创建用户java -jar jenkins-cli.jar -s http://localhost:8080/ create-user username password fullname email通过命令行批量创建用户java -jar jenkins-cli.jar -s http://localhost:8080/ create-user dev1 pass123 "Developer One" dev1@company.com需提前配置好 CLI 访问权限，适合自动化场景。

3.2 角色-Based 访问控制（Role-Based Strategy）配置

方法名称语法/操作步骤用途代码示例注意事项
安装 Role-Based Strategy 插件”Manage Jenkins” > “Manage Plugins” > 搜索并安装 “Role-based Authorization Strategy”实现基于角色的细粒度权限管理无必须先安装插件才能启用该策略。
启用 Role-Based 策略”Manage Jenkins” > “Configure Global Security” > “Authorization” > 选择 “Role-Based Strategy”开启角色权限模型无切换后原有矩阵权限将失效。
创建全局角色（Global Roles）“Manage Jenkins” > “Manage and Assign Roles” > “Manage Roles” > “Global roles” > Add定义适用于整个 Jenkins 实例的角色名称：Admin，权限：Overall/Administer, Job/Read 等Admin 角色应仅分配给少数管理员。
创建项目角色（Project Roles）在 “Project roles” 中添加角色并设置模式匹配规则定义针对特定任务的访问权限名称：dev-team-a，Pattern: ^team-a-.*，权限：Job/Build, Job/Read支持正则表达式匹配任务名称。
创建代理角色（Agent Roles）在 “Agent roles” 中定义节点相关权限角色控制对代理节点的访问和操作权限名称：node-admin，权限：Agent/Connect, Agent/Configure通常用于运维人员管理节点。
分配角色给用户”Manage and Assign Roles” > “Assign Roles” > 选择用户并勾选对应角色将已定义的角色关联到具体用户或用户组用户 dev1 → 全局角色 Developer + 项目角色 dev-team-a一个用户可拥有多个角色。
使用正则表达式匹配任务在 Project Roles 的 Pattern 字段输入正则表达式实现动态任务权限分配^frontend-.* 匹配所有以前端开头的任务正则语法错误会导致权限不生效。

3.3 项目级权限管理

方法名称语法/操作步骤用途代码示例注意事项
启用项目级权限确保已使用 “Role-Based Strategy” 或 “Project-based Matrix Authorization Strategy”对单个任务设置独立访问控制无必须在全局安全设置中启用支持项目级权限的策略。
配置单个任务的权限进入任务配置页 > 勾选 “This project is pre-operated” > “Restrict where this project can be run” 和 “Security” 部分限制谁可以查看、构建或配置该任务无（Web 表单）权限继承自全局设置，除非显式覆盖。
添加项目级用户/角色在任务配置的安全区域添加特定用户或角色给特定任务赋予额外访问权限用户 qa-team → 权限：Job/Build, Job/Read适用于跨团队协作项目。
使用 “Project-based Matrix Authorization Strategy” 插件安装插件并在任务配置中启用矩阵权限在每个任务中直接定义权限矩阵无提供比全局策略更灵活的控制能力。
限制构建触发权限在任务配置中取消非相关人员的 “Build” 权限防止未经授权的构建执行仅允许 dev-leads 用户拥有 Job/Build 权限结合参数化构建和审批流程更佳。
隐藏敏感任务不授予普通用户 Job/Read 权限使任务在任务列表中不可见无是实现权限隔离的有效手段。
继承与覆盖机制默认继承全局权限，可通过项目设置覆盖平衡统一管理和个性化需求无建议保持一致性，避免过度定制增加维护成本。

3.4 安全设置与最佳实践

方法名称语法/操作步骤用途代码示例注意事项
启用安全域（Security Realm）“Configure Global Security” > “Security Realm” > 选择 “Jenkins’ own user database” 或 “LDAP”定义用户认证来源选择 LDAP 可集成企业 AD生产环境推荐使用 LDAP/OAuth2 统一认证。
强制使用 HTTPS配置反向代理（Nginx/Apache）启用 SSL/TLS加密 Web 流量防止凭证泄露参见下方代码示例自签证书需在客户端信任，否则浏览器报错。
设置会话超时时间在 “Configure Global Security” 中设置 “Session timeout”减少未授权访问风险输入分钟数（如 30）过短影响用户体验，过长增加安全风险。
禁用脚本控制台（Script Console）移除非管理员用户的 “Script/Run” 权限防止 Groovy 脚本执行导致 RCE无脚本控制台功能强大但极其危险，生产环境应严格限制。
定期更新 Jenkins 与插件”Manage Jenkins” > “Manage Plugins” > “Updates” > 安装更新修复已知漏洞建议每周检查一次更新重大版本升级前应在测试环境验证兼容性。
备份 JENKINS_HOME 目录定期复制 $JENKINS_HOME 到安全位置实现完整配置与数据备份tar -czf jenkins-backup-$(date +%F).tar.gz /var/jenkins_home包含 jobs、users、plugins、credentials 等所有信息。
启用审计日志（Audit Logging）使用插件如 “Audit Trail” 记录关键操作追踪用户行为，满足合规要求无（插件自动记录登录、任务修改等事件）日志应集中存储并定期归档。
最小权限原则仅授予用户完成工作所需的最低权限降低误操作和恶意行为影响例如：开发者只需 Job/Build 和 Job/Read避免随意分配 Admin 权限。

HTTPS 反向代理配置示例（Nginx）：

server {
    listen 443 ssl;
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    location / {
        proxy_pass http://localhost:8080;
    }
}

第四章：Jenkins 任务（Job）基础

4.1 创建自由风格项目（Freestyle Project）

方法名称语法/操作步骤用途代码示例注意事项
新建自由风格项目进入 Jenkins 主页 > 点击”新建任务” > 输入名称 > 选择”构建一个自由风格的项目”创建最基础的任务类型，适用于简单自动化流程无（Web 界面操作）自由风格项目灵活性高，适合学习和轻量级任务。
配置任务描述在项目主页点击”配置” > 在”描述”字段输入文本为任务添加说明信息，便于团队理解用途部署前端静态资源到测试环境支持 HTML 标签格式化内容。
启用/禁用任务在项目主页点击”启用”或”禁用”暂时停止任务执行而不删除无禁用后仍保留构建历史和配置。
复制现有任务”新建任务” > 选择”复制现有项目” > 输入新名称并指定源任务快速创建结构相似的任务，减少重复配置源任务：build-frontend，新任务：build-backend修改后需检查路径、参数等是否适配。
删除任务在项目主页点击”删除项目”彻底移除任务及其所有构建历史无删除操作不可逆，请谨慎执行。
设置任务图标/颜色（通过插件）使用 “Build Monitor View” 等插件自定义显示样式在仪表盘中突出关键任务状态无提升可视化监控效率。

4.2 配置源码管理（SCM）：Git 与 SVN

方法名称语法/操作步骤用途代码示例注意事项
启用 Git 源码管理在任务配置中 > “源码管理” > 选择”Git”从 Git 仓库拉取代码进行构建Repository URL: https://github.com/user/repo.git需提前安装 Git Plugin。
配置 Git 仓库地址填写 Repository URL 字段指定代码仓库位置https://github.com/jenkinsci/jenkins.git支持 HTTPS 和 SSH 协议。
设置 Git 凭据使用”添加”按钮配置用户名/密码或 SSH 私钥认证访问私有仓库类型：Username with password 或 SSH Username with private key私钥应使用 Jenkins Credentials Store 管理。
指定分支在 “Branches to build” 中填写分支名控制构建特定分支代码*/main 或 */develop默认为 */main。
启用 SVN 源码管理在任务配置中 > “源码管理” > 选择”Subversion”从 SVN 仓库检出代码Repository URL: http://svn.company.com/svn/project/trunk需安装 Subversion Plugin。
配置 SVN 凭据添加用户名/密码类型凭据认证访问 SVN 服务器Domain: company.com, Username: jenkins, Password: ***支持 Windows 域账户。
定义本地检出目录使用 “Check-out to a sub-directory” 或自定义 workspace 路径将代码检出到指定子目录sub-project-a避免覆盖已有文件。
高级 Git 配置点击”高级”按钮设置更多选项自定义克隆行为、超时等Clone depth: 1, Timeout (minutes): 10浅克隆可加快速度但不包含完整历史。

4.3 构建触发器：定时构建与远程触发

方法名称语法/操作步骤用途代码示例注意事项
定时构建（Build periodically）在”构建触发器”中勾选 > 输入 cron 表达式按固定时间间隔自动触发构建H 2 * * *（每天凌晨2点）H 表示”哈希”，分散负载避免峰值。
Cron 语法格式分 时 日 月 周定义触发时间规则H/15 * * * *（每15分钟一次）不支持秒级精度；H 可替代具体数字。
GitHub Webhook 触发勾选”GitHub hook trigger for GITScm polling”当代码推送到 GitHub 时自动触发构建无（需在 GitHub 仓库设置 Webhook）必须配合 GitHub Integration Plugin 使用。
轮询 SCM（Poll SCM）勾选并输入 cron 表达式定期检查代码库变更，有更新则构建H/5 * * * *（每5分钟检查一次）消耗资源较多，建议用 Webhook 替代。
远程触发构建（Trigger builds remotely）勾选并设置认证令牌（Token）允许外部系统通过 HTTP 请求触发构建Token: my-secret-tokenURL 格式：http://jenkins/job/job-name/build?token=my-secret-token
使用身份验证令牌在远程触发时添加 token 参数防止未授权调用curl -X POST http://jenkins/job/deploy-prod/build?token=abc123建议使用长随机字符串作为 token。
构建另一个项目（Build after other projects are built）指定上游项目名称和触发条件实现任务依赖链项目名：build-app，条件：成功支持失败、不稳定等状态判断。

4.4 执行 Shell/Windows 批处理命令

方法名称语法/操作步骤用途代码示例注意事项
添加构建步骤：执行 Shell在”构建”部分点击”增加构建步骤” > “执行 Shell”在 Linux/Unix 环境下运行命令见下方代码示例默认使用 /bin/sh -xe 执行，-x 显示命令，-e 出错退出。
Shell 脚本中的变量使用使用 BUILD_NUMBER、JOB_NAME 等内置变量动态生成文件名或路径echo "Building version $BUILD_NUMBER of $JOB_NAME"完整变量列表见 Jenkins 环境变量文档。
添加构建步骤：执行 Windows 批处理在”构建”部分点击”增加构建步骤” > “执行 Windows 批处理”在 Windows 代理节点上运行 .bat 或 .cmd 文件echo Starting... call mvn clean package使用 cmd /c 执行，支持标准批处理语法。
设置脚本编码（Windows）在批处理步骤中指定”Use custom workspace”或系统区域设置避免中文乱码问题chcp 65001 >nul（切换到 UTF-8）特别是在处理非英文路径时。
多行脚本支持在文本框中直接输入多行命令组织复杂构建逻辑mkdir dist cp -r src/* dist/ zip -r dist.zip dist/注意缩进不影响执行，但建议保持可读性。
脚本退出码处理命令返回非零退出码时构建失败控制构建成功/失败状态exit 1（标记失败） exit 0（标记成功）Jenkins 根据最后一条命令的退出码判断结果。
使用管道和重定向结合 shell 重定向操作符捕获输出、日志记录等npm run test > test.log 2>&1可用于调试或归档中间结果。

Shell 构建步骤示例：

#!/bin/bash
echo "Starting build..."
npm install
npm run build

4.5 构建后操作：归档、邮件通知、清理

方法名称语法/操作步骤用途代码示例注意事项
归档构建产物（Archive the artifacts）在”构建后操作”中添加 > 设置”文件”路径保存生成的文件（如 jar、zip）供后续下载或部署dist/*.zip 或 target/*.jar支持通配符；产物保存在 Jenkins 服务器上。
设置归档文件路径使用相对路径（基于 workspace）指定要归档的文件位置build/output/*.war路径错误将导致”没有匹配的文件”警告。
归档测试报告（Publish JUnit test result report）添加该操作 > 设置测试报告 XML 路径展示单元测试结果和历史趋势**/test-reports/*.xml需测试框架输出兼容 JUnit 格式的报告。
发送邮件通知（E-mail Notification）添加该操作 > 输入收件人列表构建失败或状态变更时发送邮件dev-team@company.com, qa-lead@company.com需提前在系统设置中配置 SMTP 服务器。
使用 Email Extension Plugin替代默认邮件功能，支持更灵活模板自定义邮件主题、内容、收件人策略$DEFAULT_SUBJECT $DEFAULT_CONTENT支持 HTML、附件、条件发送等高级功能。
构建后清理工作空间（Delete workspace after build）添加”构建后操作” > “Delete workspace when build is done”释放磁盘空间，避免残留文件影响下次构建无建议在调试完成后启用。
条件化清理（Workspace Cleanup Plugin）使用高级清理策略，如保留最近 N 次构建的工作区平衡磁盘使用与调试需求保留策略：按数量保留，最大 3 个可结合标签或路径进行精细控制。
触发下游项目添加”构建其他项目”操作实现构建流水线串联项目名：deploy-staging, 参数：VERSION=$BUILD_NUMBER支持同步或异步触发。

第五章：Jenkins Pipeline 入门

5.1 什么是 Jenkins Pipeline

概念名称说明注意事项
Jenkins Pipeline一套插件，支持在 Jenkins 中实现持续交付流水线即代码（Pipeline as Code）。它允许将构建、测试、部署等流程定义为可版本控制的脚本。Pipeline 是 Jenkins 2.0 的核心特性，取代传统自由风格项目的复杂配置。
流水线即代码（Pipeline as Code）使用代码（Groovy 脚本）定义 CI/CD 流程，存入源码仓库（如 Git），实现版本化、复用和审查。推荐将 Jenkinsfile 提交到项目仓库，与代码一同管理。
Pipeline 任务类型Jenkins 中的一种任务形式，用于运行基于 Groovy 的流水线脚本，支持声明式和脚本式两种语法。创建任务时选择 “Pipeline” 类型。
持久化与暂停能力Pipeline 支持长时间运行、跨节点执行，并可在等待人工审批等操作时暂停，状态持久保存。即使 Jenkins 重启，运行中的 Pipeline 也能恢复。
可视化阶段视图Pipeline 运行时可在 Web 界面查看各阶段（Stage）的执行状态和耗时，便于监控和调试。需在脚本中合理划分 stages 以获得清晰视图。
支持复杂流程控制包括条件判断、循环、并行执行、错误处理（try/catch）、超时控制等高级逻辑。相比自由风格项目，具备更强的表达能力。

5.2 声明式 Pipeline 与脚本式 Pipeline 对比

对比项声明式 Pipeline（Declarative Pipeline）脚本式 Pipeline（Scripted Pipeline）注意事项
语法类型基于预定义结构的声明式语法，更像配置文件基于 Groovy DSL 的编程式语法，更像脚本声明式更易读、易学，适合大多数场景。
根块（Root Block）pipeline { ... }node { ... }声明式必须以 pipeline 开始。
结构要求强制结构化：必须包含 agent、stages、steps 等块灵活，可自由编写 Groovy 代码声明式有助于规范代码结构。
错误处理使用 options { timeout }、post 块处理失败使用 Groovy 的 try/catch/finally脚本式在异常处理上更灵活。
条件执行使用 when 指令使用 Groovy 的 if/else声明式的 when 更简洁。
并行执行使用 parallel 指令使用 parallel 步骤两者都支持并行构建。
可扩展性通过 script 块嵌入 Groovy 代码扩展功能完全自由，可调用任意 Groovy 方法脚本式功能更强但易写出难以维护的代码。
学习曲线较低，适合初学者较高，需了解 Groovy 语法推荐新手从声明式入手。
社区趋势Jenkins 官方推荐，持续增强新功能传统方式，功能稳定但更新较少新项目建议优先使用声明式。

5.3 Pipeline 基本语法结构（pipeline, agent, stages, steps）

结构名称语法用途代码示例注意事项
pipelinepipeline { ... }所有声明式 Pipeline 的根容器，必须包含pipeline { agent any stages { ... } }每个 Jenkinsfile 必须有一个且仅一个 pipeline 块。
agentagent { ... }指定 Pipeline 或 stage 在哪个代理节点上执行agent any agent none agent { label 'linux' }any 表示任意可用节点；none 用于顶层定义，由 stage 自行指定。
stagesstages { ... }包含一个或多个 stage 的容器，定义构建的逻辑阶段stages { stage('Build') { ... } stage('Test') { ... } }必须包含至少一个 stage。
stagestage('Stage Name') { ... }定义流水线中的一个阶段，如构建、测试、部署stage('Build') { steps { sh 'make' } }每个 stage 包含 steps 块，用于执行具体操作。
stepssteps { ... }包含一个或多个具体执行命令的容器steps { sh 'echo "Hello"' script { def version = getVersion() } }是实际执行命令的地方，支持 shell、Groovy 脚本等。
scriptscript { ... }在声明式 Pipeline 中嵌入任意 Groovy 代码script { if (env.BRANCH_NAME == 'main') { deployProd() } }用于复杂逻辑处理，如变量计算、条件判断等。

5.4 使用 Jenkinsfile 管理 Pipeline 代码

方法名称语法/操作步骤用途代码示例注意事项
创建 Jenkinsfile在项目根目录创建名为 Jenkinsfile 的文本文件存放 Pipeline 脚本代码touch Jenkinsfile文件名区分大小写，必须为 Jenkinsfile（无后缀）。
使用 SCM 中的 Jenkinsfile在 Pipeline 任务配置中选择 “Pipeline script from SCM”从代码仓库加载 JenkinsfileRepository URL: https://github.com/user/project.git Script Path: Jenkinsfile推荐做法，实现代码与流程共管。
编写声明式 Pipeline 脚本在 Jenkinsfile 中编写 pipeline 块定义完整的 CI/CD 流程见下方代码示例确保语法正确，否则构建失败。
本地测试 Jenkinsfile使用 Jenkinsfile Runner 或在线语法检查工具验证脚本语法和逻辑无（工具辅助）减少提交后才发现错误的风险。
版本控制 Jenkinsfile将 Jenkinsfile 提交到 Git/SVN 仓库实现变更追踪、代码审查和回滚git add Jenkinsfile git commit -m "Add pipeline" git push与应用代码一起评审，确保流程一致性。
多分支 Pipeline 自动发现使用 “Multibranch Pipeline” 任务类型自动为每个分支创建独立 Pipeline无（Jenkins 自动扫描）要求每个分支都有 Jenkinsfile。
设置默认分支在 Multibranch 配置中指定 “Discover branches” 策略控制哪些分支触发 Pipeline策略：All branches可过滤特定分支（如忽略 feature/*）。
处理语法错误查看构建日志中的 “WorkflowScript: X: “调试 Jenkinsfile 语法问题WorkflowScript: 5: Missing required parameter: ‘stages’常见错误包括括号不匹配、缺少必填块等。

声明式 Pipeline 示例（Jenkinsfile）：

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                sh 'mvn clean package'
            }
        }
    }
}

第六章：Jenkinsfile 与高级 Pipeline 语法

6.1 agent 指令详解（any, label, docker, none）

方法名称语法用途代码示例注意事项
agent anyagent any在任意可用的代理节点上运行 Pipelinepipeline { agent any stages { ... } }最常用，适用于大多数场景。
agent noneagent none不在顶层指定执行节点，由每个 stage 自行定义pipeline { agent none stages { stage('Build') { agent { label 'linux' } steps { ... } } } }用于多平台或不同阶段需在不同节点运行的场景。
agent labelagent { label 'label-name' }指定在具有特定标签的节点上运行agent { label 'docker-build' }标签需提前在节点配置中定义。
agent nodeagent { node { label 'linux && amd64' } }使用更复杂的节点选择条件agent { node { label 'ubuntu && high-mem' } }支持逻辑表达式（&&, ||）。
agent dockeragent { docker 'image-name' }在指定的 Docker 镜像容器中运行 Pipelineagent { docker 'maven:3.8.6-jdk-11' }需 Jenkins 主机安装 Docker 并配置权限。
agent dockerfileagent { dockerfile true }使用项目根目录下的 Dockerfile 构建并运行容器agent { dockerfile true } 或 agent { dockerfile 'Dockerfile.build' }支持指定 Dockerfile 路径。
agent inheritagent inherit在嵌套 stage 中继承父级 agent 配置stage('Sub-stage') { agent inherit steps { ... } }仅在 stage 级别使用，声明式 Pipeline 中较少见。

6.2 stages 与 stage：定义构建阶段

方法名称语法用途代码示例注意事项
stagesstages { ... }容器块，包含一个或多个 stagestages { stage('Build') { steps { sh 'make' } } stage('Test') { steps { sh 'make test' } } }必须包含至少一个 stage。
stagestage('Stage Name') { ... }定义流水线中的一个逻辑阶段stage('Deploy') { steps { sh './deploy.sh' } }阶段名称应清晰描述其功能。
嵌套 stagestage('Outer') { stages { stage('Inner A') { ... } stage('Inner B') { ... } } }在一个 stage 内部定义多个子阶段stage('Build') { stages { stage('Compile') { steps { ... } } stage('Package') { steps { ... } } } }可实现更细粒度的可视化和控制。
可选阶段（when）stage('Deploy Prod') { when { branch 'main' } steps { ... } }根据条件决定是否执行该阶段when { expression { env.DEPLOY_ENV == 'prod' } }支持 branch、environment、expression 等条件。
并行阶段parallel { stage('Frontend') { ... } stage('Backend') { ... } }并行执行多个 stage，提升效率见下方代码示例并行阶段独立运行，失败一个可能导致整体失败。
阶段超时options { timeout(time: 10, unit: 'MINUTES') }为单个阶段设置执行超时stage('Long Task') { options { timeout(time: 5, unit: 'MINUTES') } steps { ... } }超时后阶段标记为失败。

6.3 steps：执行具体操作

方法名称语法用途代码示例注意事项
shsh 'command'在 Linux/Unix 节点上执行 shell 命令steps { sh 'mvn clean package' sh 'echo $BUILD_NUMBER' }默认使用 /bin/sh 执行。
batbat 'command'在 Windows 节点上执行批处理命令steps { bat 'call mvn clean package' bat 'echo %BUILD_NUMBER%' }使用 cmd /c 执行。
scriptscript { ... }执行 Groovy 脚本，用于复杂逻辑steps { script { def version = sh(script: 'git describe --tags', returnStdout: true).trim() env.APP_VERSION = version } }可访问 Jenkins API 和变量。
echoecho 'message'输出信息到构建日志echo 'Starting deployment...'用于调试和流程提示。
sleepsleep(time: 30, unit: 'SECONDS')暂停执行一段时间sleep(time: 2, unit: 'MINUTES')可用于等待外部系统响应。
archiveArtifactsarchiveArtifacts artifacts: 'target/*.jar', allowEmptyArchive: true归档构建产物archiveArtifacts 'dist/*.zip'allowEmptyArchive 防止无文件时报错。
junitjunit 'test-results/*.xml'发布 JUnit 测试报告junit 'build/test-results/test/*.xml'需测试框架生成兼容格式。
checkoutcheckout scm检出当前任务的源码（通常自动执行）checkout([$class: 'GitSCM', ...])自定义 SCM 行为时使用。

6.4 script 块：在声明式 Pipeline 中使用 Groovy

方法名称语法用途代码示例注意事项
script 块script { ... }在声明式 Pipeline 中嵌入任意 Groovy 代码steps { script { def list = [1,2,3] list.each { println it } } }是声明式 Pipeline 扩展功能的主要方式。
定义变量script { def version = '1.0' }在 Groovy 上下文中声明变量script { env.BUILD_TAG = "v${env.BUILD_NUMBER}" }可修改环境变量或创建临时变量。
条件逻辑script { if (condition) { ... } }实现复杂条件判断script { if (env.BRANCH_NAME == 'main') { env.DEPLOY_ENV = 'prod' } else { env.DEPLOY_ENV = 'staging' } }Groovy 语法，支持 if/else、switch 等。
循环处理script { for (item in list) { ... } }遍历集合或执行重复操作script { ['dev', 'test', 'prod'].each { env -> sh "deploy.sh $env" } }避免无限循环。
调用函数script { def ver = getBuildVersion() }调用自定义或共享库函数script { def version = sh(script: 'git describe --tags', returnStdout: true).trim() }可封装重复逻辑。
异常处理script { try { ... } catch (e) { ... } }捕获和处理错误script { try { sh 'risky-command' } catch (Exception e) { echo "Warning: ${e}" } }防止脚本因单个错误中断。
返回值处理script { return sh(...) }从 script 块返回值供后续使用script { def output = sh(script: 'whoami', returnStdout: true).trim() env.USER = output }使用 returnStdout: true 获取命令输出。

6.5 environment：环境变量定义

方法名称语法用途代码示例注意事项
environment 块environment { KEY = 'value' }定义环境变量，供整个 Pipeline 使用environment { APP_NAME = 'my-app' DEBUG = 'true' }可在 steps 中通过 env.KEY 访问。
动态变量（script）environment { VERSION = script { ... } }使用 Groovy 脚本动态生成变量值environment { VERSION = script { return sh(script: 'git describe --tags', returnStdout: true).trim() } }脚本在 Pipeline 开始时执行一次。
credentialsenvironment { USER = credentials('cred-id') }从 Jenkins 凭据存储中加载敏感信息environment { DB_USER = credentials('db-username') DB_PASS = credentials('db-password') }自动解密并设置为环境变量，避免明文暴露。
内置环境变量引用environment { MY_BUILD = '$BUILD_NUMBER' }使用 Jenkins 内置变量environment { BUILD_TAG = 'jenkins-${JOB_NAME}-${BUILD_NUMBER}' }支持大多数内置变量插值。
阶段级 environmentstage('Deploy') { environment { ENV = 'prod' } steps { ... } }为特定阶段定义环境变量变量仅在该 stage 内有效优先级高于全局 environment。
敏感信息保护使用 credentials() 或 Secret Text 类型防止密码、密钥等泄露credentials('aws-secret-key')日志中会自动屏蔽。

6.6 parameters：参数化构建

方法名称语法用途代码示例注意事项
parameters 块parameters { ... }定义构建时可输入的参数parameters { string(name: 'VERSION', defaultValue: '1.0', description: 'App version') }必须在 pipeline 块内定义。
string 参数string(name: 'KEY', defaultValue: 'val', description: '...')字符串输入参数string(name: 'TAG', defaultValue: 'latest', description: 'Docker tag')最常用参数类型。
booleanParambooleanParam(name: 'DEBUG', defaultValue: true, description: 'Enable debug?')布尔值（复选框）参数booleanParam(name: 'CLEAN', defaultValue: false)构建时显示为勾选框。
choicechoice(choices: ['dev','staging','prod'], name: 'ENV', description: 'Target environment')下拉选择参数choice(choices: '''dev\nstaging\nprod''', name: 'DEPLOY_ENV')choices 为多行字符串。
texttext(name: 'NOTES', defaultValue: '', description: 'Release notes')多行文本输入text(name: 'SCRIPT', defaultValue: '#!/bin/bash\n')适合输入脚本或长文本。
passwordpassword(name: 'SECRET', defaultValue: '', description: 'Secret token')密码输入（隐藏显示）password(name: 'API_KEY', description: 'External API key')输入内容在 UI 和日志中隐藏。
在脚本中使用参数steps { sh "echo $VERSION" }通过变量名访问参数值echo "Deploying $DEPLOY_ENV environment"参数自动作为环境变量注入。

6.7 options：构建选项（超时、重试、时间戳等）

方法名称语法用途代码示例注意事项
timeoutoptions { timeout(time: 1, unit: 'HOURS') }设置整个 Pipeline 的最大执行时间options { timeout(time: 30, unit: 'MINUTES') }超时后构建失败。
retryoptions { retry(3) }构建失败时自动重试指定次数options { retry(2) }每次失败后立即重试，适用于不稳定外部依赖。
timestampsoptions { timestamps() }在构建日志中添加时间戳options { timestamps() ansiColor('xterm') }便于分析各步骤耗时。
buildDiscarderoptions { buildDiscarder(logRotator(daysToKeep: 7, numToKeep: 10)) }自动清理旧的构建记录logRotator(daysToKeep: 30, numToKeep: 50)节省磁盘空间。
disableConcurrentBuildsoptions { disableConcurrentBuilds() }禁止并发构建，确保串行执行options { disableConcurrentBuilds() timeout(time: 1, unit: 'HOURS') }避免资源冲突或数据竞争。
skipDefaultCheckoutoptions { skipDefaultCheckout() }跳过默认的源码检出操作options { skipDefaultCheckout() }当使用自定义 checkout 逻辑时使用。
checkoutToSubdirectoryoptions { checkoutToSubdirectory('src') }将源码检出到子目录options { checkoutToSubdirectory('project-a') }避免覆盖工作区其他文件。
ansiColoroptions { ansiColor('xterm') }启用 ANSI 颜色输出，美化日志options { ansiColor('xterm') }需安装 AnsiColor Plugin。

6.8 triggers：触发器（cron, webhook, pollSCM）

方法名称语法用途代码示例注意事项
crontriggers { cron('H */4 * * *') }定时触发构建triggers { cron('0 2 * * *') // 每天凌晨2点 }使用 Jenkins cron 语法，H 表示哈希。
pollSCMtriggers { pollSCM('H/15 * * * *') }定期检查源码变更，有更新则构建triggers { pollSCM('H/10 * * * *') // 每10分钟检查 }消耗资源，推荐用 Webhook 替代。
upstreamtriggers { upstream(upstreamProjects: 'job1,job2', threshold: hudson.model.Result.SUCCESS) }当上游项目构建成功后触发triggers { upstream(upstreamProjects: 'build-app', threshold: SUCCESS) }实现任务依赖链。
Generic Webhook Trigger需安装插件，配置自定义 Webhook响应外部系统（如 GitLab、自定义服务）的 HTTP 请求见插件文档支持解析 JSON、过滤条件等高级功能。
GitHub Hooktriggers { githubPush() }响应 GitHub 的 push 事件triggers { githubPush() }需在 GitHub 仓库设置 Webhook URL。
多触发器组合triggers { cron(...); githubPush() }同时启用多种触发方式triggers { cron('H 8 * * 1-5') githubPush() }任一条件满足即可触发构建。

6.9 post：构建后操作（always, success, failure 等）

方法名称语法用途代码示例注意事项
postpost { ... }定义构建完成后执行的操作，根据构建状态分支处理post { success { ... } failure { ... } }通常放在 pipeline 块末尾。
alwaysalways { ... }无论构建成功或失败都执行always { echo 'Build finished' }适合清理、通知等通用操作。
successsuccess { ... }仅当构建成功时执行success { emailext(subject: 'Success', body: '...', to: 'team@company.com') }用于发送成功通知、触发下游部署。
failurefailure { ... }仅当构建失败时执行failure { emailext(subject: 'Failed', body: '...', to: 'dev-lead@company.com') }用于告警和故障排查。
unstableunstable { ... }当构建结果为”不稳定”（如测试失败）时执行unstable { echo 'Tests failed but build succeeded' }常用于发送质量警告。
changedchanged { ... }仅当本次构建状态与上次不同时执行changed { echo 'Status changed to unstable' }避免重复通知。
cleanupcleanup { ... }最终清理操作，即使构建被中止也执行cleanup { sh 'rm -rf temp/' }Jenkins 2.173+ 支持，确保资源释放。
通知集成emailext, slackSend, webhook发送邮件、Slack 消息或调用 Webhookemailext(...) slackSend(message: 'Build failed')需安装对应插件（Email Extension, Slack）。

第四章：Jenkins 任务（Job）基础

4.1 创建自由风格项目（Freestyle Project）

方法名称语法/操作步骤用途代码示例注意事项
新建自由风格项目进入 Jenkins 主页 > 点击”新建任务” > 输入名称 > 选择”构建一个自由风格的项目”创建最基础的任务类型，适用于简单自动化流程无（Web 界面操作）自由风格项目灵活性高，适合学习和轻量级任务。
配置任务描述在项目主页点击”配置” > 在”描述”字段输入文本为任务添加说明信息，便于团队理解用途部署前端静态资源到测试环境支持 HTML 标签格式化内容。
启用/禁用任务在项目主页点击”启用”或”禁用”暂时停止任务执行而不删除无禁用后仍保留构建历史和配置。
复制现有任务”新建任务” > 选择”复制现有项目” > 输入新名称并指定源任务快速创建结构相似的任务，减少重复配置源任务：build-frontend，新任务：build-backend修改后需检查路径、参数等是否适配。
删除任务在项目主页点击”删除项目”彻底移除任务及其所有构建历史无删除操作不可逆，请谨慎执行。
设置任务图标/颜色（通过插件）使用 “Build Monitor View” 等插件自定义显示样式在仪表盘中突出关键任务状态无提升可视化监控效率。

4.2 配置源码管理（SCM）：Git 与 SVN

方法名称语法/操作步骤用途代码示例注意事项
启用 Git 源码管理在任务配置中 > “源码管理” > 选择”Git”从 Git 仓库拉取代码进行构建Repository URL: https://github.com/user/repo.git需提前安装 Git Plugin。
配置 Git 仓库地址填写 Repository URL 字段指定代码仓库位置https://github.com/jenkinsci/jenkins.git支持 HTTPS 和 SSH 协议。
设置 Git 凭据使用”添加”按钮配置用户名/密码或 SSH 私钥认证访问私有仓库类型：Username with password 或 SSH Username with private key私钥应使用 Jenkins Credentials Store 管理。
指定分支在 “Branches to build” 中填写分支名控制构建特定分支代码*/main 或 */develop默认为 */main。
启用 SVN 源码管理在任务配置中 > “源码管理” > 选择”Subversion”从 SVN 仓库检出代码Repository URL: http://svn.company.com/svn/project/trunk需安装 Subversion Plugin。
配置 SVN 凭据添加用户名/密码类型凭据认证访问 SVN 服务器Domain: company.com, Username: jenkins, Password: ***支持 Windows 域账户。
定义本地检出目录使用 “Check-out to a sub-directory” 或自定义 workspace 路径将代码检出到指定子目录sub-project-a避免覆盖已有文件。
高级 Git 配置点击”高级”按钮设置更多选项自定义克隆行为、超时等Clone depth: 1, Timeout (minutes): 10浅克隆可加快速度但不包含完整历史。

4.3 构建触发器：定时构建与远程触发

方法名称语法/操作步骤用途代码示例注意事项
定时构建（Build periodically）在”构建触发器”中勾选 > 输入 cron 表达式按固定时间间隔自动触发构建H 2 * * *（每天凌晨2点）H 表示”哈希”，分散负载避免峰值。
Cron 语法格式分 时 日 月 周定义触发时间规则H/15 * * * *（每15分钟一次）不支持秒级精度；H 可替代具体数字。
GitHub Webhook 触发勾选”GitHub hook trigger for GITScm polling”当代码推送到 GitHub 时自动触发构建无（需在 GitHub 仓库设置 Webhook）必须配合 GitHub Integration Plugin 使用。
轮询 SCM（Poll SCM）勾选并输入 cron 表达式定期检查代码库变更，有更新则构建H/5 * * * *（每5分钟检查一次）消耗资源较多，建议用 Webhook 替代。
远程触发构建（Trigger builds remotely）勾选并设置认证令牌（Token）允许外部系统通过 HTTP 请求触发构建Token: my-secret-tokenURL 格式：http://jenkins/job/job-name/build?token=my-secret-token
使用身份验证令牌在远程触发时添加 token 参数防止未授权调用curl -X POST http://jenkins/job/deploy-prod/build?token=abc123建议使用长随机字符串作为 token。
构建另一个项目（Build after other projects are built）指定上游项目名称和触发条件实现任务依赖链项目名：build-app，条件：成功支持失败、不稳定等状态判断。

4.4 执行 Shell/Windows 批处理命令

方法名称语法/操作步骤用途代码示例注意事项
添加构建步骤：执行 Shell在”构建”部分点击”增加构建步骤” > “执行 Shell”在 Linux/Unix 环境下运行命令见下方代码示例默认使用 /bin/sh -xe 执行，-x 显示命令，-e 出错退出。
Shell 脚本中的变量使用使用 BUILD_NUMBER、JOB_NAME 等内置变量动态生成文件名或路径echo "Building version $BUILD_NUMBER of $JOB_NAME"完整变量列表见 Jenkins 环境变量文档。
添加构建步骤：执行 Windows 批处理在”构建”部分点击”增加构建步骤” > “执行 Windows 批处理”在 Windows 代理节点上运行 .bat 或 .cmd 文件echo Starting... call mvn clean package使用 cmd /c 执行，支持标准批处理语法。
设置脚本编码（Windows）在批处理步骤中指定”Use custom workspace”或系统区域设置避免中文乱码问题chcp 65001 >nul（切换到 UTF-8）特别是在处理非英文路径时。
多行脚本支持在文本框中直接输入多行命令组织复杂构建逻辑mkdir dist cp -r src/* dist/ zip -r dist.zip dist/注意缩进不影响执行，但建议保持可读性。
脚本退出码处理命令返回非零退出码时构建失败控制构建成功/失败状态exit 1（标记失败） exit 0（标记成功）Jenkins 根据最后一条命令的退出码判断结果。
使用管道和重定向结合 shell 重定向操作符捕获输出、日志记录等npm run test > test.log 2>&1可用于调试或归档中间结果。

Shell 构建步骤示例：

#!/bin/bash
echo "Starting build..."
npm install
npm run build

4.5 构建后操作：归档、邮件通知、清理

方法名称语法/操作步骤用途代码示例注意事项
归档构建产物（Archive the artifacts）在”构建后操作”中添加 > 设置”文件”路径保存生成的文件（如 jar、zip）供后续下载或部署dist/*.zip 或 target/*.jar支持通配符；产物保存在 Jenkins 服务器上。
设置归档文件路径使用相对路径（基于 workspace）指定要归档的文件位置build/output/*.war路径错误将导致”没有匹配的文件”警告。
归档测试报告（Publish JUnit test result report）添加该操作 > 设置测试报告 XML 路径展示单元测试结果和历史趋势**/test-reports/*.xml需测试框架输出兼容 JUnit 格式的报告。
发送邮件通知（E-mail Notification）添加该操作 > 输入收件人列表构建失败或状态变更时发送邮件dev-team@company.com, qa-lead@company.com需提前在系统设置中配置 SMTP 服务器。
使用 Email Extension Plugin替代默认邮件功能，支持更灵活模板自定义邮件主题、内容、收件人策略$DEFAULT_SUBJECT $DEFAULT_CONTENT支持 HTML、附件、条件发送等高级功能。
构建后清理工作空间（Delete workspace after build）添加”构建后操作” > “Delete workspace when build is done”释放磁盘空间，避免残留文件影响下次构建无建议在调试完成后启用。
条件化清理（Workspace Cleanup Plugin）使用高级清理策略，如保留最近 N 次构建的工作区平衡磁盘使用与调试需求保留策略：按数量保留，最大 3 个可结合标签或路径进行精细控制。
触发下游项目添加”构建其他项目”操作实现构建流水线串联项目名：deploy-staging, 参数：VERSION=$BUILD_NUMBER支持同步或异步触发。

第五章：Jenkins Pipeline 入门

5.1 什么是 Jenkins Pipeline

概念名称说明注意事项
Jenkins Pipeline一套插件，支持在 Jenkins 中实现持续交付流水线即代码（Pipeline as Code）。它允许将构建、测试、部署等流程定义为可版本控制的脚本。Pipeline 是 Jenkins 2.0 的核心特性，取代传统自由风格项目的复杂配置。
流水线即代码（Pipeline as Code）使用代码（Groovy 脚本）定义 CI/CD 流程，存入源码仓库（如 Git），实现版本化、复用和审查。推荐将 Jenkinsfile 提交到项目仓库，与代码一同管理。
Pipeline 任务类型Jenkins 中的一种任务形式，用于运行基于 Groovy 的流水线脚本，支持声明式和脚本式两种语法。创建任务时选择 “Pipeline” 类型。
持久化与暂停能力Pipeline 支持长时间运行、跨节点执行，并可在等待人工审批等操作时暂停，状态持久保存。即使 Jenkins 重启，运行中的 Pipeline 也能恢复。
可视化阶段视图Pipeline 运行时可在 Web 界面查看各阶段（Stage）的执行状态和耗时，便于监控和调试。需在脚本中合理划分 stages 以获得清晰视图。
支持复杂流程控制包括条件判断、循环、并行执行、错误处理（try/catch）、超时控制等高级逻辑。相比自由风格项目，具备更强的表达能力。

5.2 声明式 Pipeline 与脚本式 Pipeline 对比

对比项声明式 Pipeline（Declarative Pipeline）脚本式 Pipeline（Scripted Pipeline）注意事项
语法类型基于预定义结构的声明式语法，更像配置文件基于 Groovy DSL 的编程式语法，更像脚本声明式更易读、易学，适合大多数场景。
根块（Root Block）pipeline { ... }node { ... }声明式必须以 pipeline 开始。
结构要求强制结构化：必须包含 agent、stages、steps 等块灵活，可自由编写 Groovy 代码声明式有助于规范代码结构。
错误处理使用 options { timeout }、post 块处理失败使用 Groovy 的 try/catch/finally脚本式在异常处理上更灵活。
条件执行使用 when 指令使用 Groovy 的 if/else声明式的 when 更简洁。
并行执行使用 parallel 指令使用 parallel 步骤两者都支持并行构建。
可扩展性通过 script 块嵌入 Groovy 代码扩展功能完全自由，可调用任意 Groovy 方法脚本式功能更强但易写出难以维护的代码。
学习曲线较低，适合初学者较高，需了解 Groovy 语法推荐新手从声明式入手。
社区趋势Jenkins 官方推荐，持续增强新功能传统方式，功能稳定但更新较少新项目建议优先使用声明式。

5.3 Pipeline 基本语法结构（pipeline, agent, stages, steps）

结构名称语法用途代码示例注意事项
pipelinepipeline { ... }所有声明式 Pipeline 的根容器，必须包含pipeline { agent any stages { ... } }每个 Jenkinsfile 必须有一个且仅一个 pipeline 块。
agentagent { ... }指定 Pipeline 或 stage 在哪个代理节点上执行agent any agent none agent { label 'linux' }any 表示任意可用节点；none 用于顶层定义，由 stage 自行指定。
stagesstages { ... }包含一个或多个 stage 的容器，定义构建的逻辑阶段stages { stage('Build') { ... } stage('Test') { ... } }必须包含至少一个 stage。
stagestage('Stage Name') { ... }定义流水线中的一个阶段，如构建、测试、部署stage('Build') { steps { sh 'make' } }每个 stage 包含 steps 块，用于执行具体操作。
stepssteps { ... }包含一个或多个具体执行命令的容器steps { sh 'echo "Hello"' script { def version = getVersion() } }是实际执行命令的地方，支持 shell、Groovy 脚本等。
scriptscript { ... }在声明式 Pipeline 中嵌入任意 Groovy 代码script { if (env.BRANCH_NAME == 'main') { deployProd() } }用于复杂逻辑处理，如变量计算、条件判断等。

5.4 使用 Jenkinsfile 管理 Pipeline 代码

方法名称语法/操作步骤用途代码示例注意事项
创建 Jenkinsfile在项目根目录创建名为 Jenkinsfile 的文本文件存放 Pipeline 脚本代码touch Jenkinsfile文件名区分大小写，必须为 Jenkinsfile（无后缀）。
使用 SCM 中的 Jenkinsfile在 Pipeline 任务配置中选择 “Pipeline script from SCM”从代码仓库加载 JenkinsfileRepository URL: https://github.com/user/project.git Script Path: Jenkinsfile推荐做法，实现代码与流程共管。
编写声明式 Pipeline 脚本在 Jenkinsfile 中编写 pipeline 块定义完整的 CI/CD 流程见下方代码示例确保语法正确，否则构建失败。
本地测试 Jenkinsfile使用 Jenkinsfile Runner 或在线语法检查工具验证脚本语法和逻辑无（工具辅助）减少提交后才发现错误的风险。
版本控制 Jenkinsfile将 Jenkinsfile 提交到 Git/SVN 仓库实现变更追踪、代码审查和回滚git add Jenkinsfile git commit -m "Add pipeline" git push与应用代码一起评审，确保流程一致性。
多分支 Pipeline 自动发现使用 “Multibranch Pipeline” 任务类型自动为每个分支创建独立 Pipeline无（Jenkins 自动扫描）要求每个分支都有 Jenkinsfile。
设置默认分支在 Multibranch 配置中指定 “Discover branches” 策略控制哪些分支触发 Pipeline策略：All branches可过滤特定分支（如忽略 feature/*）。
处理语法错误查看构建日志中的 “WorkflowScript: X: “调试 Jenkinsfile 语法问题WorkflowScript: 5: Missing required parameter: ‘stages’常见错误包括括号不匹配、缺少必填块等。

声明式 Pipeline 示例（Jenkinsfile）：

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                sh 'mvn clean package'
            }
        }
    }
}

第六章：Jenkinsfile 与高级 Pipeline 语法

6.1 agent 指令详解（any, label, docker, none）

方法名称语法用途代码示例注意事项
agent anyagent any在任意可用的代理节点上运行 Pipelinepipeline { agent any stages { ... } }最常用，适用于大多数场景。
agent noneagent none不在顶层指定执行节点，由每个 stage 自行定义pipeline { agent none stages { stage('Build') { agent { label 'linux' } steps { ... } } } }用于多平台或不同阶段需在不同节点运行的场景。
agent labelagent { label 'label-name' }指定在具有特定标签的节点上运行agent { label 'docker-build' }标签需提前在节点配置中定义。
agent nodeagent { node { label 'linux && amd64' } }使用更复杂的节点选择条件agent { node { label 'ubuntu && high-mem' } }支持逻辑表达式（&&, ||）。
agent dockeragent { docker 'image-name' }在指定的 Docker 镜像容器中运行 Pipelineagent { docker 'maven:3.8.6-jdk-11' }需 Jenkins 主机安装 Docker 并配置权限。
agent dockerfileagent { dockerfile true }使用项目根目录下的 Dockerfile 构建并运行容器agent { dockerfile true } 或 agent { dockerfile 'Dockerfile.build' }支持指定 Dockerfile 路径。
agent inheritagent inherit在嵌套 stage 中继承父级 agent 配置stage('Sub-stage') { agent inherit steps { ... } }仅在 stage 级别使用，声明式 Pipeline 中较少见。

6.2 stages 与 stage：定义构建阶段

方法名称语法用途代码示例注意事项
stagesstages { ... }容器块，包含一个或多个 stagestages { stage('Build') { steps { sh 'make' } } stage('Test') { steps { sh 'make test' } } }必须包含至少一个 stage。
stagestage('Stage Name') { ... }定义流水线中的一个逻辑阶段stage('Deploy') { steps { sh './deploy.sh' } }阶段名称应清晰描述其功能。
嵌套 stagestage('Outer') { stages { stage('Inner A') { ... } stage('Inner B') { ... } } }在一个 stage 内部定义多个子阶段stage('Build') { stages { stage('Compile') { steps { ... } } stage('Package') { steps { ... } } } }可实现更细粒度的可视化和控制。
可选阶段（when）stage('Deploy Prod') { when { branch 'main' } steps { ... } }根据条件决定是否执行该阶段when { expression { env.DEPLOY_ENV == 'prod' } }支持 branch、environment、expression 等条件。
并行阶段parallel { stage('Frontend') { ... } stage('Backend') { ... } }并行执行多个 stage，提升效率见下方代码示例并行阶段独立运行，失败一个可能导致整体失败。
阶段超时options { timeout(time: 10, unit: 'MINUTES') }为单个阶段设置执行超时stage('Long Task') { options { timeout(time: 5, unit: 'MINUTES') } steps { ... } }超时后阶段标记为失败。

6.3 steps：执行具体操作

方法名称语法用途代码示例注意事项
shsh 'command'在 Linux/Unix 节点上执行 shell 命令steps { sh 'mvn clean package' sh 'echo $BUILD_NUMBER' }默认使用 /bin/sh 执行。
batbat 'command'在 Windows 节点上执行批处理命令steps { bat 'call mvn clean package' bat 'echo %BUILD_NUMBER%' }使用 cmd /c 执行。
scriptscript { ... }执行 Groovy 脚本，用于复杂逻辑steps { script { def version = sh(script: 'git describe --tags', returnStdout: true).trim() env.APP_VERSION = version } }可访问 Jenkins API 和变量。
echoecho 'message'输出信息到构建日志echo 'Starting deployment...'用于调试和流程提示。
sleepsleep(time: 30, unit: 'SECONDS')暂停执行一段时间sleep(time: 2, unit: 'MINUTES')可用于等待外部系统响应。
archiveArtifactsarchiveArtifacts artifacts: 'target/*.jar', allowEmptyArchive: true归档构建产物archiveArtifacts 'dist/*.zip'allowEmptyArchive 防止无文件时报错。
junitjunit 'test-results/*.xml'发布 JUnit 测试报告junit 'build/test-results/test/*.xml'需测试框架生成兼容格式。
checkoutcheckout scm检出当前任务的源码（通常自动执行）checkout([$class: 'GitSCM', ...])自定义 SCM 行为时使用。

6.4 script 块：在声明式 Pipeline 中使用 Groovy

方法名称语法用途代码示例注意事项
script 块script { ... }在声明式 Pipeline 中嵌入任意 Groovy 代码steps { script { def list = [1,2,3] list.each { println it } } }是声明式 Pipeline 扩展功能的主要方式。
定义变量script { def version = '1.0' }在 Groovy 上下文中声明变量script { env.BUILD_TAG = "v${env.BUILD_NUMBER}" }可修改环境变量或创建临时变量。
条件逻辑script { if (condition) { ... } }实现复杂条件判断script { if (env.BRANCH_NAME == 'main') { env.DEPLOY_ENV = 'prod' } else { env.DEPLOY_ENV = 'staging' } }Groovy 语法，支持 if/else、switch 等。
循环处理script { for (item in list) { ... } }遍历集合或执行重复操作script { ['dev', 'test', 'prod'].each { env -> sh "deploy.sh $env" } }避免无限循环。
调用函数script { def ver = getBuildVersion() }调用自定义或共享库函数script { def version = sh(script: 'git describe --tags', returnStdout: true).trim() }可封装重复逻辑。
异常处理script { try { ... } catch (e) { ... } }捕获和处理错误script { try { sh 'risky-command' } catch (Exception e) { echo "Warning: ${e}" } }防止脚本因单个错误中断。
返回值处理script { return sh(...) }从 script 块返回值供后续使用script { def output = sh(script: 'whoami', returnStdout: true).trim() env.USER = output }使用 returnStdout: true 获取命令输出。

6.5 environment：环境变量定义

方法名称语法用途代码示例注意事项
environment 块environment { KEY = 'value' }定义环境变量，供整个 Pipeline 使用environment { APP_NAME = 'my-app' DEBUG = 'true' }可在 steps 中通过 env.KEY 访问。
动态变量（script）environment { VERSION = script { ... } }使用 Groovy 脚本动态生成变量值environment { VERSION = script { return sh(script: 'git describe --tags', returnStdout: true).trim() } }脚本在 Pipeline 开始时执行一次。
credentialsenvironment { USER = credentials('cred-id') }从 Jenkins 凭据存储中加载敏感信息environment { DB_USER = credentials('db-username') DB_PASS = credentials('db-password') }自动解密并设置为环境变量，避免明文暴露。
内置环境变量引用environment { MY_BUILD = '$BUILD_NUMBER' }使用 Jenkins 内置变量environment { BUILD_TAG = 'jenkins-${JOB_NAME}-${BUILD_NUMBER}' }支持大多数内置变量插值。
阶段级 environmentstage('Deploy') { environment { ENV = 'prod' } steps { ... } }为特定阶段定义环境变量变量仅在该 stage 内有效优先级高于全局 environment。
敏感信息保护使用 credentials() 或 Secret Text 类型防止密码、密钥等泄露credentials('aws-secret-key')日志中会自动屏蔽。

6.6 parameters：参数化构建

方法名称语法用途代码示例注意事项
parameters 块parameters { ... }定义构建时可输入的参数parameters { string(name: 'VERSION', defaultValue: '1.0', description: 'App version') }必须在 pipeline 块内定义。
string 参数string(name: 'KEY', defaultValue: 'val', description: '...')字符串输入参数string(name: 'TAG', defaultValue: 'latest', description: 'Docker tag')最常用参数类型。
booleanParambooleanParam(name: 'DEBUG', defaultValue: true, description: 'Enable debug?')布尔值（复选框）参数booleanParam(name: 'CLEAN', defaultValue: false)构建时显示为勾选框。
choicechoice(choices: ['dev','staging','prod'], name: 'ENV', description: 'Target environment')下拉选择参数choice(choices: '''dev\nstaging\nprod''', name: 'DEPLOY_ENV')choices 为多行字符串。
texttext(name: 'NOTES', defaultValue: '', description: 'Release notes')多行文本输入text(name: 'SCRIPT', defaultValue: '#!/bin/bash\n')适合输入脚本或长文本。
passwordpassword(name: 'SECRET', defaultValue: '', description: 'Secret token')密码输入（隐藏显示）password(name: 'API_KEY', description: 'External API key')输入内容在 UI 和日志中隐藏。
在脚本中使用参数steps { sh "echo $VERSION" }通过变量名访问参数值echo "Deploying $DEPLOY_ENV environment"参数自动作为环境变量注入。

6.7 options：构建选项（超时、重试、时间戳等）

方法名称语法用途代码示例注意事项
timeoutoptions { timeout(time: 1, unit: 'HOURS') }设置整个 Pipeline 的最大执行时间options { timeout(time: 30, unit: 'MINUTES') }超时后构建失败。
retryoptions { retry(3) }构建失败时自动重试指定次数options { retry(2) }每次失败后立即重试，适用于不稳定外部依赖。
timestampsoptions { timestamps() }在构建日志中添加时间戳options { timestamps() ansiColor('xterm') }便于分析各步骤耗时。
buildDiscarderoptions { buildDiscarder(logRotator(daysToKeep: 7, numToKeep: 10)) }自动清理旧的构建记录logRotator(daysToKeep: 30, numToKeep: 50)节省磁盘空间。
disableConcurrentBuildsoptions { disableConcurrentBuilds() }禁止并发构建，确保串行执行options { disableConcurrentBuilds() timeout(time: 1, unit: 'HOURS') }避免资源冲突或数据竞争。
skipDefaultCheckoutoptions { skipDefaultCheckout() }跳过默认的源码检出操作options { skipDefaultCheckout() }当使用自定义 checkout 逻辑时使用。
checkoutToSubdirectoryoptions { checkoutToSubdirectory('src') }将源码检出到子目录options { checkoutToSubdirectory('project-a') }避免覆盖工作区其他文件。
ansiColoroptions { ansiColor('xterm') }启用 ANSI 颜色输出，美化日志options { ansiColor('xterm') }需安装 AnsiColor Plugin。

6.8 triggers：触发器（cron, webhook, pollSCM）

方法名称语法用途代码示例注意事项
crontriggers { cron('H */4 * * *') }定时触发构建triggers { cron('0 2 * * *') // 每天凌晨2点 }使用 Jenkins cron 语法，H 表示哈希。
pollSCMtriggers { pollSCM('H/15 * * * *') }定期检查源码变更，有更新则构建triggers { pollSCM('H/10 * * * *') // 每10分钟检查 }消耗资源，推荐用 Webhook 替代。
upstreamtriggers { upstream(upstreamProjects: 'job1,job2', threshold: hudson.model.Result.SUCCESS) }当上游项目构建成功后触发triggers { upstream(upstreamProjects: 'build-app', threshold: SUCCESS) }实现任务依赖链。
Generic Webhook Trigger需安装插件，配置自定义 Webhook响应外部系统（如 GitLab、自定义服务）的 HTTP 请求见插件文档支持解析 JSON、过滤条件等高级功能。
GitHub Hooktriggers { githubPush() }响应 GitHub 的 push 事件triggers { githubPush() }需在 GitHub 仓库设置 Webhook URL。
多触发器组合triggers { cron(...); githubPush() }同时启用多种触发方式triggers { cron('H 8 * * 1-5') githubPush() }任一条件满足即可触发构建。

6.9 post：构建后操作（always, success, failure 等）

方法名称语法用途代码示例注意事项
postpost { ... }定义构建完成后执行的操作，根据构建状态分支处理post { success { ... } failure { ... } }通常放在 pipeline 块末尾。
alwaysalways { ... }无论构建成功或失败都执行always { echo 'Build finished' }适合清理、通知等通用操作。
successsuccess { ... }仅当构建成功时执行success { emailext(subject: 'Success', body: '...', to: 'team@company.com') }用于发送成功通知、触发下游部署。
failurefailure { ... }仅当构建失败时执行failure { emailext(subject: 'Failed', body: '...', to: 'dev-lead@company.com') }用于告警和故障排查。
unstableunstable { ... }当构建结果为”不稳定”（如测试失败）时执行unstable { echo 'Tests failed but build succeeded' }常用于发送质量警告。
changedchanged { ... }仅当本次构建状态与上次不同时执行changed { echo 'Status changed to unstable' }避免重复通知。
cleanupcleanup { ... }最终清理操作，即使构建被中止也执行cleanup { sh 'rm -rf temp/' }Jenkins 2.173+ 支持，确保资源释放。
通知集成emailext, slackSend, webhook发送邮件、Slack 消息或调用 Webhookemailext(...) slackSend(message: 'Build failed')需安装对应插件（Email Extension, Slack）。

第七章：Jenkins 插件生态与常用插件

7.1 插件管理：安装、更新与卸载

方法名称语法/操作步骤用途代码示例注意事项
安装插件（Web 界面）“Manage Jenkins” > “Manage Plugins” > “Available” 标签页 > 搜索并勾选插件 > 点击”Install without restart”安装新插件扩展 Jenkins 功能无（图形化操作）建议勾选”安装后重启”以确保稳定加载。
批量安装插件在”Available”标签页中选择多个插件同时安装快速部署常用插件集例如：Git Plugin, Email Extension, Blue Ocean注意依赖关系，避免冲突。
更新插件”Manage Jenkins” > “Manage Plugins” > “Updates” 标签页 > 选择要更新的插件 > 安装修复漏洞、获取新功能建议定期检查更新更新前建议备份 JENKINS_HOME。
卸载插件”Manage Plugins” > “Installed” 标签页 > 找到插件 > 勾选并点击”Uninstall”移除不再需要的插件无卸载后相关配置和任务可能失效，请谨慎操作。
手动上传插件（HPI 文件）“Advanced” 标签页 > “Upload Plugin” > 选择本地 .hpi 文件在无网络环境或测试未发布插件时使用无需确保插件兼容当前 Jenkins 版本。
查看插件依赖安装时系统自动提示依赖项了解插件所需前置组件如 Blue Ocean 需要多个子插件Jenkins 会自动安装依赖，除非禁用。
禁用插件在”Installed”列表中点击”Disable”临时关闭插件功能而不删除用于排查问题或性能调优禁用后相关功能立即不可用。

7.2 Git Plugin 与 GitHub Integration

方法名称语法/操作步骤用途代码示例注意事项
Git Plugin 基本配置任务配置中 > “源码管理” > 选择 Git > 填写仓库 URL 和凭据拉取代码进行构建Repository URL: https://github.com/user/project.git需提前安装 Git 命令行工具。
使用 SSH 访问私有仓库配置 Jenkins 凭据为 SSH Username with private key安全认证 Git 仓库私钥应使用 Jenkins Credentials Store 存储公钥需添加到 GitHub/GitLab 账户。
GitHub Integration Plugin 安装安装 “GitHub” 插件实现 Jenkins 与 GitHub 深度集成无支持 Webhook 自动触发、状态回写等。
自动触发构建（Webhook）插件自动配置 GitHub Webhook URL：https://<jenkins-url>/github-webhook/Push 或 Pull Request 事件触发构建无需手动设置 Webhook需 Jenkins 可被公网访问。
GitHub 仓库连接配置”Manage Jenkins” > “Configure System” > “GitHub” > 添加 GitHub Server建立 Jenkins 到 GitHub 的连接API URL: https://api.github.com可使用 Personal Access Token 认证。
状态回写（Status Check）构建完成后自动向 GitHub 提交状态（成功/失败）在 PR 页面显示 CI 状态无需额外配置，插件自动处理提升协作效率，便于合并判断。
多分支 Pipeline 支持创建 “Multibranch Pipeline” 任务 > 关联 GitHub 仓库自动发现并为每个分支创建 Pipeline扫描策略：定期或事件驱动要求每个分支包含 Jenkinsfile。

7.3 Email Extension Plugin 配置

方法名称语法/操作步骤用途代码示例注意事项
安装 Email Extension Plugin”Manage Plugins” > 搜索 “Email Extension Plugin” > 安装替代默认邮件功能，提供更灵活的邮件通知无功能远超内置邮件通知。
配置 SMTP 服务器”Manage Jenkins” > “Configure System” > “Extended E-mail Notification” > 设置 SMTP host, port, user, password发送邮件的基础配置SMTP Server: smtp.company.com Port: 587 Use SSL: ✔需确保网络可达且凭据正确。
设置默认发件人在”Default User E-mail Suffix”或”System Admin e-mail address”中配置避免邮件被识别为垃圾邮件System Admin e-mail address: jenkins@company.com建议使用企业邮箱域名。
使用预设内容模板在构建后操作中选择 “Editable Email Notification” > 使用 $DEFAULT_SUBJECT, $DEFAULT_CONTENT快速配置标准邮件内容Subject: $PROJECT_NAME - Build # $BUILD_NUMBER - $BUILD_STATUS!支持大量内置变量。
自定义邮件内容（HTML）编辑 “Content” 字段，使用 HTML + Groovy 变量美化邮件样式，包含构建详情<h3>Build Failed</h3><p>Job: ${JOB_NAME}</p>可结合 CSS 样式提升可读性。
条件化收件人使用 “Triggers” 设置不同状态的收件人列表精准通知相关人员Failure: dev-lead@company.com, qa-team@company.com避免无关人员收到告警。
添加附件在 “Attachments” 字段指定文件路径发送日志、报告等文件**/test-results/*.xml, build.log支持通配符。
测试邮件配置使用 “Test configuration by sending test e-mail” 功能验证邮件能否正常发送输入测试邮箱地址 > 发送排查配置错误的有效手段。

7.4 Blue Ocean 插件使用

方法名称语法/操作步骤用途代码示例注意事项
安装 Blue Ocean安装 “Blue Ocean” 插件（包含多个子插件）提供现代化、用户友好的 Jenkins UI无安装后访问 /blue 路径进入。
访问 Blue Ocean 界面浏览器访问 http://<jenkins-url>/blue使用全新 UI 查看和管理 Pipeline无界面更直观，适合团队协作。
可视化 Pipeline 编辑器在 Blue Ocean 中点击 “Create Pipeline” > 图形化拖拽方式创建 Pipeline无需编写代码即可定义流水线无（GUI 操作）适合初学者快速上手。
实时构建可视化查看 Pipeline 各 stage 的实时执行状态、耗时、日志监控构建进度，快速定位瓶颈无支持并行 stage 的清晰展示。
查看构建详情点击具体构建记录，查看每个 step 的日志输出调试构建失败原因无日志高亮显示错误行。
多分支 Pipeline 管理自动发现 Git 仓库中的分支和 Pull Request统一管理所有分支的 CI 流程无支持 GitHub, Bitbucket, GitLab。
PR 集成与状态展示在 Blue Ocean 中直接查看 PR 构建状态和详情加强代码审查与 CI 的联动无需正确配置 GitHub/GitLab 集成。
用户权限与协作支持基于角色的访问控制，团队成员可共同查看流水线提升团队透明度和协作效率无需配合 Role-Based Strategy 插件使用。

7.5 Credentials Binding Plugin

方法名称语法/操作步骤用途代码示例注意事项
安装 Credentials Binding Plugin该插件通常作为依赖自动安装提供将凭据安全绑定到环境变量或文件的功能无是安全实践的核心插件之一。
在 Jenkinsfile 中使用 withCredentials使用 withCredentials 步骤绑定凭据在构建过程中安全使用密码、密钥等见下方代码示例凭据在内存中使用，不会明文写入日志。
绑定用户名/密码credentialsId 对应 Jenkins 凭据 ID访问需要认证的 API 或服务usernamePassword(...)最常见用法。
绑定 SSH 私钥sshUserPrivateKey(credentialsId: 'key-id', keyFileVariable: 'KEY')使用 SSH 密钥进行远程登录或 Git 操作sh "ssh -i $KEY user@host"避免将私钥硬编码在脚本中。
绑定 secret textstring(credentialsId: 'api-token', variable: 'TOKEN')使用 API Token、密钥等纯文本凭据sh 'curl -H "Authorization: Bearer $TOKEN" ...'适用于 OAuth Token 等场景。
绑定证书文件certificate(credentialsId: 'cert-id', variable: 'CERT')使用 PKCS#12 证书文件$CERT 包含证书路径用于 HTTPS 客户端认证。
凭据作用域在 “Global” 或 “Folder” 级别创建凭据控制凭据的可见范围Folder 级凭据仅该文件夹内任务可用提升安全性，避免越权访问。
凭据 ID 命名规范使用清晰、一致的命名，如 prod-db-password便于管理和审计避免使用 password1 等模糊名称建议包含环境和用途。

withCredentials 使用示例：

withCredentials([
    usernamePassword(credentialsId: 'github-api-creds',
        usernameVariable: 'USER',
        passwordVariable: 'PASS')
]) {
    sh 'curl -u $USER:$PASS https://api.github.com/user'
}

7.6 Pipeline Utility Steps Plugin

方法名称语法/操作步骤用途代码示例注意事项
安装 Pipeline Utility Steps Plugin”Manage Plugins” > 搜索并安装提供读取和操作项目文件的 Pipeline 步骤无适用于 Java、Node.js 等项目。
读取 JSON 文件readJSON file: 'package.json'获取项目配置信息（如版本号）def packageJson = readJSON file: 'package.json' echo "Version: ${packageJson.version}"常用于获取 package.json, config.json 等。
读取 Properties 文件readProperties file: 'version.properties'读取 Java 风格的配置文件def props = readProperties file: 'app.properties' env.APP_NAME = props['app.name']支持 .properties 文件。
读取 XML 文件readXML file: 'pom.xml'解析 Maven 项目的 pom.xmldef pom = readXML file: 'pom.xml' def version = pom.version[0]可提取 groupId, artifactId, version 等。
写入 JSON 文件writeJSON file: 'metadata.json', json: [build: env.BUILD_NUMBER]生成或更新 JSON 文件通常用于归档元数据结合 archiveArtifacts 保存。
写入 Properties 文件writeProperties file: 'build-info.properties', properties: [version: '1.0']生成配置文件供后续步骤使用无支持 key-value 写入。
查找文件findFiles glob: '**/*.jar'搜索工作区中的文件def jars = findFiles glob: 'target/*.jar' echo "Found ${jars.length} JARs"返回文件数组，可获取 name, path, length。
计算文件哈希fileHash file: 'app.jar', algorithm: 'SHA256'生成文件校验码，用于完整性验证def hash = fileHash file: 'dist/app.zip', algorithm: 'MD5'支持 MD5, SHA1, SHA256 等算法。

7.7 Warnings Next Generation Plugin

方法名称语法/操作步骤用途代码示例注意事项
安装 Warnings Next Generation Plugin”Manage Plugins” > 搜索并安装分析构建日志或静态扫描报告，展示代码警告无支持多种工具（编译器、linter、扫描器）。
配置警告解析器在任务配置的”构建后操作”中添加”记录编译警告” > 选择工具类型解析特定格式的警告信息工具：GCC, Java Compiler, ESLint, PMD, SpotBugs 等需确保构建输出或报告格式匹配。
分析编译器警告解析 GCC、MSVC、javac 等编译器输出的 warning识别潜在代码问题无（日志中自动捕获）需在构建命令中启用警告输出（如 -Wall）。
分析 Linter 报告解析 ESLint、Pylint、RuboCop 等工具生成的报告文件统一展示代码风格和质量警告Report files: reports/eslint.json需配置 linter 输出为支持格式（XML, JSON）。
展示警告趋势图在项目主页和构建页面显示警告数量趋势监控代码质量变化无（插件自动生成图表）可设置质量门禁（Quality Gate）。
设置质量门禁（Quality Gate）结合 “Quality Gates” 插件或 Pipeline 条件判断当警告数超过阈值时标记构建为失败见下方代码示例需在 Pipeline 中编程实现。
支持多种报告格式支持 XML (Checkstyle, PMD), JSON (ESLint), 文本日志等兼容主流静态分析工具工具列表见插件文档需正确配置文件路径和解析器。
聚合多工具警告同时配置多个解析器统一管理来自不同工具的警告例如：同时启用 ESLint 和 Pylint提供全面的代码质量视图。

质量门禁 Pipeline 示例：

post {
    unstable {
        script {
            def issues = scanForIssues tool: [eslint()]
            if (issues.size() > 10) {
                currentBuild.result = 'FAILURE'
            }
        }
    }
}

第八章：Jenkins 与版本控制集成

8.1 配置 Git 凭据（Username/Password, SSH Key）

方法名称操作步骤用途示例/说明注意事项
创建 Username/Password 凭据1. 进入 “Manage Jenkins” > “Credentials”
2. 选择域（通常为全局）
3. 点击 “Add Credentials”
4. 类型选择 “Username with password”
5. 输入用户名和密码（或 Personal Access Token）
6. 设置 ID（如 github-user-pass）并保存		用于 HTTPS 方式访问 Git 仓库适用于 GitHub、GitLab、Bitbucket 等基于 HTTPS 的仓库推荐使用 Personal Access Token 替代密码，安全性更高
创建 SSH Key 凭据1. 生成 SSH 密钥对（ssh-keygen -t rsa -b 4096）
2. 将公钥添加到 Git 服务账户（如 GitHub SSH Keys）
3. 在 Jenkins 中 “Add Credentials”
4. 类型选择 “SSH Username with private key”
5. 输入用户名（如 git）
6. 私钥选择 “Enter directly” 并粘贴私钥内容
7. 设置 ID（如 github-ssh-key）并保存		用于 SSH 方式访问 Git 仓库免密登录，适合自动化流程私钥必须保密，切勿提交到代码库
在任务中使用凭据在 Job 配置的 “Source Code Management” > Git 中
选择 “Credentials” 下拉框，选择已创建的凭据 ID		让 Jenkins 能够拉取私有仓库代码仓库 URL 示例：
- HTTPS: https://github.com/user/repo.git
- SSH: git@github.com:user/repo.git		凭据 ID 可在 Jenkinsfile 中通过 credentialsId: 'xxx' 引用
测试凭据连通性使用 ssh -T git@github.com 测试 SSH 连接
或在 Jenkins 任务中执行 “Check out” 测试		验证凭据是否有效SSH 测试应返回 Hi username! You've successfully authenticated...确保 Jenkins 服务器网络可达 Git 服务

8.2 多分支 Pipeline（Multibranch Pipeline）

方法名称操作步骤用途示例/说明注意事项
创建 Multibranch Pipeline 任务1. 新建任务 > 选择 “Multibranch Pipeline”
2. 输入任务名称
3. 点击 “OK”		自动发现并管理多个分支的 CI/CD 流程无需为每个分支手动创建任务是现代 CI/CD 的推荐模式
配置分支源（Branch Source）1. 添加源（如 Git）
2. 填写仓库 URL
3. 选择已配置的凭据
4. 设置扫描策略（定期或事件触发）		定义从哪个仓库扫描分支和 Pull Request支持 GitHub、GitLab、Bitbucket、Git 等可添加多个源（如主仓库 + Fork）
扫描仓库（Scan Repository）手动点击 “Scan Repository Now” 或等待自动扫描触发 Jenkins 扫描仓库中的所有分支扫描后会列出所有匹配的分支首次配置后需手动触发扫描
分支匹配策略在 “Behaviors” 中配置 “Discover branches”控制哪些分支被发现和创建 Pipeline策略：All branches / Exclude branches that are also filed as PRs / Only branches that match a regex可结合正则表达式过滤（如 feature.*）
Pull Request 支持配置 “Discover pull requests” 行为为每个 PR 创建独立的构建任务可选择从 origin 或 both 方向发现 PR便于代码审查前验证 CI 状态
Jenkinsfile 自动发现要求每个分支根目录包含 Jenkinsfile定义该分支的构建流程不同分支可使用不同版本的 Jenkinsfile若无 Jenkinsfile，该分支不会创建 Pipeline
删除过期分支配置 “Prune stale branches” 行为自动删除已从 Git 仓库移除的分支对应的 Pipeline减少 Jenkins 中的无效任务建议启用以保持整洁

8.3 GitHub Webhook 自动触发构建

方法名称操作步骤用途示例/说明注意事项
启用 GitHub Webhook 插件功能确保已安装 “GitHub” 插件
在 Multibranch Pipeline 或 Pipeline 任务中
勾选 “GitHub hook trigger for GITscm polling”		允许 GitHub 通过 HTTP 请求触发构建无需轮询，实时性高是事件驱动 CI 的核心
自动配置 WebhookJenkins 在任务配置中自动生成 Webhook URLGitHub 将事件（push, PR）推送到此 URL格式：https://<jenkins-url>/github-webhook/通常无需手动设置，要求 Jenkins 有公网可访问地址
手动配置 GitHub Webhook1. 进入 GitHub 仓库 > Settings > Webhooks
2. 点击 “Add webhook”
3. Payload URL: Jenkins 的 webhook 地址
4. Content type: application/json
5. Events: 选择 “Just the push event” 或 “Let me select…”（如 push, pull_request）
6. 点击 “Add webhook”		确保事件能正确送达 Jenkins可用事件：push / pull_request / create / delete建议选择最小必要事件集
测试 Webhook在 GitHub Webhook 页面点击 “Test” 或 “Deliver”验证连接是否正常应看到 Jenkins 开始构建对应分支查看 Jenkins 系统日志排错
安全性配置（可选）在 Webhook 中设置 “Secret”验证请求确实来自 GitHubJenkins 需在 GitHub Server 配置中设置相同密钥防止伪造请求
构建触发验证推送代码到 GitHub 仓库验证是否自动触发 Jenkins 构建构建日志应显示 “Started by GitHub push”若未触发，检查防火墙、SSL、插件状态

8.4 GitLab CI 集成

方法名称操作步骤用途示例/说明注意事项
安装 GitLab Plugin”Manage Plugins” > 搜索并安装 “GitLab” 插件实现 Jenkins 与 GitLab 深度集成支持 Webhook、状态回写、Merge Request 构建需要 GitLab API 访问权限
配置 GitLab 连接”Manage Jenkins” > “Configure System” > “GitLab”
添加 GitLab 服务器 URL 和 Credentials（Personal Access Token）		建立 Jenkins 到 GitLab 的信任连接URL 示例：
- SaaS: https://gitlab.com
- 自建: https://gitlab.company.com		Token 需有 api 或 read_repository 权限
配置 Webhook1. 进入 GitLab 项目 > Settings > Webhooks
2. URL: https://<jenkins-url>/project/<job-name>（传统）或 /generic-webhook-trigger/invoke（需插件）
3. 触发事件：Push, Merge Request
4. 添加 Webhook		通过事件自动触发构建Jenkins 任务需启用 “Build when a change is pushed to GitLab”使用 Generic Webhook Trigger 插件更灵活
Merge Request 构建配置 Webhook 触发 MR 事件
在 Jenkinsfile 中使用 if (env.gitlabMergeRequestId) 判断		为每个 Merge Request 执行 CI 流程类似 GitHub PR 构建需在 GitLab 中启用 CI/CD
状态回写（Status Check）GitLab 插件自动将构建状态回传到 GitLab在 MR 页面显示 CI 运行状态显示 “jenkins: success” 或 “failed”提升代码审查效率
使用 GitLab CI/CD 变量在 Jenkinsfile 中访问 GitLab 提供的环境变量获取 MR 信息、源分支等如 env.gitlabSourceBranch, env.gitlabMergeRequestId便于实现条件逻辑
自建 GitLab 证书问题若使用自签名证书，需将证书导入 Jenkins 的 Java 信任库避免 SSL 连接错误keytool -import -alias gitlab -file gitlab.crt -keystore $JAVA_HOME/lib/security/cacerts否则会出现 PKIX path building failed 错误

8.5 SVN 集成与轮询策略

方法名称操作步骤用途示例/说明注意事项
安装 Subversion Plugin”Manage Plugins” > 搜索并安装 “Subversion” 插件支持从 SVN 仓库检出代码Jenkins 内置支持较旧版本，建议安装插件需服务器安装 svn 命令行工具
配置 SVN 仓库 URL在任务配置的 “Source Code Management” > Subversion
填写仓库 URL（如 http://svn.company.com/repo/trunk）		指定代码检出位置支持 http://, https://, svn://, file://需确保 Jenkins 有访问权限
配置 SVN 凭据在 “Credentials” 中添加 Username/Password 或 SSH 凭据
在 SVN 配置中选择该凭据		认证 SVN 仓库访问适用于需要登录的 SVN 服务域名（Realm）有时需匹配
Poll SCM 轮询策略在 “Build Triggers” 中选择 “Poll SCM”
设置 cron 表达式（如 H/5 * * * *）		定期检查 SVN 仓库是否有变更每 5 分钟检查一次即使无变更也会产生请求，消耗资源
轮询 vs 触发器Poll SCM 是轮询机制，无事件通知与 Git Webhook 的实时性对比SVN 原生不支持 Webhook，实时性较差大型仓库建议降低轮询频率
优化轮询频率根据团队提交频率设置合理间隔平衡及时性与资源消耗示例：
- 活跃项目：H/5 * * * *（每 5 分钟）
- 低频项目：H * * * *（每小时）		避免设置过短间隔（如每分钟）
使用 svnnotify 或外部触发配置 SVN 的 post-commit hook 调用 Jenkins API实现近似 Webhook 的实时触发脚本示例：
curl http://jenkins-url/job/job-name/build?token=MYTOKEN		需在 Jenkins 任务中设置触发令牌（Trigger builds remotely）
处理分支和标签在 SVN 中通过不同路径管理分支配置多个任务或使用参数化构建路径示例：
- Trunk: /repo/trunk
- Branch: /repo/branches/v1.0
- Tag: /repo/tags/v1.0.0		不如 Git 分支轻量，管理较复杂

第九章：Jenkins 代理节点（Agent/Node）管理

9.1 代理节点的作用与类型

类型描述用途优点缺点
Master 节点Jenkins 主服务节点，负责调度、UI、插件管理运行轻量级任务、管理任务调度开箱即用，无需额外配置不应运行构建任务，避免资源耗尽影响稳定性
SSH 代理节点通过 SSH 协议连接的远程机器在 Linux/Unix 服务器上执行构建配置简单，支持密码或密钥认证，网络穿透能力强需维护 SSH 服务，密钥管理需谨慎
JNLP 代理节点通过 Java Web Start (JNLP) 协议连接的节点支持 Windows、Linux、macOS 等多种系统安全性高（反向连接），防火墙友好需安装 Java 环境，启动依赖 Jenkins 主节点
永久代理（Permanent Agent）手动配置并长期运行的代理节点固定构建环境（如特定编译器版本）稳定、性能好，适合高频构建资源占用固定，扩展性差
临时/动态代理（Ephemeral Agent）按需创建和销毁（如 Docker、Kubernetes Pod）弹性伸缩，资源高效利用成本低，环境隔离，自动清理启动时间略长，需云平台支持

9.2 配置 SSH 代理节点

步骤操作说明示例/注意事项
1. 准备目标机器确保远程机器安装 sshd 服务，网络可达 Jenkins 主节点sudo systemctl start sshd
2. 创建凭据在 Jenkins 中添加 “Username with password” 或 “SSH Username with private key”推荐使用 SSH 密钥，避免密码暴露
3. 添加节点”Manage Jenkins” > “Manage Nodes and Clouds” > “New Node”
类型选择 “Permanent Agent”		名称：linux-builder-01
4. 配置节点信息- Remote root directory: /home/jenkins/agent
- Launch method: “Launch agents via SSH”
- Host: 192.168.1.100
- Credentials: 选择已创建的 SSH 凭据		目录需存在且代理用户有读写权限
5. 高级 SSH 配置- Host Key Verification Strategy: 首次连接可选 “Manually trusted key Verification Strategy”
- JVM Options: 可设置 -Djava.awt.headless=true		生产环境建议使用 “Known hosts file”
6. 连接验证保存后 Jenkins 自动尝试连接查看日志确认是否成功启动 agent.jar

9.3 配置 JNLP 代理节点

步骤操作说明示例/注意事项
1. 添加节点”New Node” > 类型 “Permanent Agent”名称：windows-builder-01
2. 配置节点信息- Remote root directory: C:\jenkins
- Launch method: “Launch agent via execution of command on the master”
（或 “Let Jenkins control this agent via JNLP”）		Windows 路径使用反斜杠
3. 获取 JNLP 命令保存节点后，点击节点进入，复制 “Launch agent” 命令命令形如：
java -jar agent.jar -jnlpUrl http://jenkins:8080/computer/agent1/slave-agent.jnlp -secret xxx
4. 在代理机器执行命令在目标机器（需安装 Java）运行复制的命令可创建批处理脚本或 Windows 服务自动启动
5. 验证连接Jenkins 节点状态变为 “Online”首次连接可能需确认安全提示

9.4 云代理与动态代理（如 Kubernetes）

方法配置说明优势插件/工具
Kubernetes Plugin将 Jenkins 集成到 Kubernetes 集群
定义 Pod Template，指定容器镜像、资源请求、卷挂载等		按需创建 Pod 作为构建代理，构建完成自动销毁Kubernetes Continuous Deploy Plugin
Pod Template 配置- Label: k8s-agent
- Containers: jnlp（必须）、maven、docker
- Memory/CPU Request: 1Gi, 500m		实现多容器协同构建（如 jnlp + maven + docker）可在 Jenkinsfile 中使用 agent { kubernetes { ... } }
Docker 云代理配置 Docker 主机或 Swarm 作为云资源
定义 Docker 模板镜像（如 jenkins/agent:jdk11）		快速启动轻量级容器代理Docker Plugin
弹性伸缩设置最大代理数、空闲超时（如 5 分钟）高峰期自动扩容，低峰期释放资源节省成本，提高资源利用率
安全上下文在 Pod Template 中设置 runAsUser, fsGroup避免权限问题，提升安全性尤其在挂载主机目录时重要

9.5 节点资源分配与标签（Label）管理

方法操作说明示例/用途
标签（Label）为节点添加标签，用于 Pipeline 中的 agent { label 'xxx' }- linux
- docker-build
- high-mem
- k8s
资源分配在节点配置中设置 “Number of executors”- 普通节点：2-4
- 高性能节点：8+
- 动态代理：通常为 1
使用标签调度 Pipeline在 Jenkinsfile 中指定 agentpipeline { agent { label 'docker-build' } stages { ... } }
多标签组合使用布尔表达式匹配节点agent { label 'linux && high-mem' }
节点监控查看节点 CPU、内存使用情况”Manage Nodes” 页面提供基础监控
工作区管理设置 “Advanced” 中的 “Workspaces”为不同任务分配独立路径

第十章：Jenkins 构建优化与最佳实践

10.1 构建参数化（Parameters）

参数类型用途示例最佳实践
string输入文本（如版本号、标签）VERSION=1.2.3设置默认值，添加描述
choice下拉选择（如环境：dev/test/prod）ENV=prod限制非法输入，提高易用性
booleanParam布尔开关（如是否清理、是否部署）CLEAN_BUILD=true默认关闭高风险操作
text多行文本（如脚本、配置）DEPLOY_SCRIPT=…适合复杂输入
password敏感信息输入（隐藏）DB_PASSWORD=***避免日志泄露

最佳实践：

  • 减少不必要的参数：参数是提升灵活性的关键，但应避免过度参数化
  • 为参数添加清晰描述
  • 使用默认值降低使用门槛
  • 敏感参数使用 password 类型或 Credentials

10.2 构建产物归档与持久化

方法操作示例注意事项
archiveArtifacts归档构建产物（如 JAR、ZIP、Docker 镜像元数据）archiveArtifacts artifacts: 'target/*.jar', allowEmptyArchive: trueallowEmptyArchive: true 防止无文件时报错
junit发布测试报告junit 'test-results/*.xml'用于展示测试趋势
持久化存储将产物上传到外部存储- Nexus/Artifactory（Maven 包）
- S3/GCS（通用文件）
- Harbor（Docker 镜像）		Jenkins 工作区不应作为长期存储

最佳实践：

  • 明确归档范围，避免过大文件：确保关键产物可追溯、可重部署
  • 结合版本号命名产物
  • 定期清理旧产物（使用 buildDiscarder）

10.3 构建日志管理与输出优化

方法操作示例优势
timestamps()添加时间戳options { timestamps(); ansiColor('xterm') }便于分析各步骤耗时
ansiColor()启用 ANSI 颜色ansiColor('xterm')日志更易读，错误突出显示
echo输出关键信息echo "Starting build for ${env.BRANCH_NAME}"提高日志可读性
避免日志爆炸限制 sh 命令输出sh 'long-command > /dev/null 2>&1'减少无用日志
结构化日志使用工具生成 JSON/XML 日志结合 Warnings Plugin 分析便于机器解析和告警

10.4 并行构建与 stage 并行执行

方法语法示例注意事项
parallel在 stages 块中使用 parallel见下方代码示例大幅缩短构建时间

适用场景：

  • 单元测试、集成测试：确保任务无共享状态或资源冲突
  • 多平台构建（Linux/Windows）
  • 多模块独立构建

资源考量： 并行会占用更多代理节点资源，需确保有足够 executors，可结合动态代理弹性扩展。

并行构建示例：

stage('Parallel Tests') {
    parallel {
        stage('Unit') {
            steps { sh 'mvn test' }
        }
        stage('Integration') {
            steps { sh 'mvn verify' }
        }
    }
}

10.5 构建缓存与工作区清理

方法操作示例说明
本地缓存复用 Maven/Gradle/NPM 缓存挂载 ~/.m2, ~/.gradle, ~/.npm 到代理节点显著加快依赖下载
Docker 缓存使用 docker build —cache-from在多阶段构建中复用层减少镜像构建时间
cleanWs()清理工作区见下方代码示例防止残留文件影响下次构建

cleanWs 使用示例：

post {
    always {
        cleanWs()
    }
}

最佳实践：

  • 定期清理旧工作区：平衡缓存复用与环境纯净
  • 使用 .gitignore 忽略构建产物
  • 动态代理天然具备清理优势

10.6 Pipeline 复用：Shared Libraries

概念说明示例优势
共享库（Shared Library）将通用 Pipeline 逻辑封装为可复用的 Groovy 库@Library('my-pipeline-lib') _避免重复代码，统一最佳实践
加载方式Modern SCM（推荐）或 Implicit loading配置在 “Manage Jenkins” > “System” > “Global Pipeline Libraries”支持版本控制（master、branch、tag）
目录结构src/（工具类）、vars/（全局函数）、resources/（资源文件）src/com/company/Utils.groovy
vars/buildApp.groovy
vars/deployApp.groovy		vars/ 下为全局可调用函数，模块化设计
调用函数在 Jenkinsfile 中直接使用buildApp()
deployApp environment: 'prod'		语法简洁，易于维护

最佳实践：

  • 版本化管理共享库：是大型 Jenkins 部署的必备实践
  • 编写单元测试
  • 文档化 API

第十一章：Jenkins 安全与维护

11.1 CSRF 保护与安全配置

配置项操作说明最佳实践
启用 CSRF 保护”Manage Jenkins” > “Configure Global Security” > “CSRF Protection” > 选择 “Default Crumb Issuer”必须启用，防止跨站请求伪造攻击
Crumb 配置”Proxy Compatibility” 勾选（若使用反向代理）
“Enable for APIs” 建议启用		确保 API 调用（如脚本、Webhook）也能受保护
安全域（Security Realm）选择用户认证方式：
- Jenkins 内建数据库（适合小团队）
- LDAP/AD（企业推荐）
- OAuth（GitHub, Google）		集成企业身份系统，统一管理
授权策略（Authorization）设置用户权限：
- Logged-in users can do anything（不推荐）
- Matrix/Project-based Matrix（细粒度控制）
- Role-Based Strategy（推荐）		遵循最小权限原则
代理节点通信安全JNLP 节点使用加密连接
SSH 节点使用密钥认证而非密码		防止中间人攻击
脚本安全沙箱模式限制未经批准的脚本Pipeline 中未批准的脚本需管理员审批

11.2 插件安全与定期更新

实践说明工具/方法
定期检查插件更新插件是主要攻击面，需及时修复已知漏洞”Manage Jenkins” > “Manage Plugins” > “Updates” 标签页
使用 LTS 版插件优先选择长期支持版本，更稳定在插件列表中查看版本类型
最小化插件安装只安装必需插件，减少攻击面定期审查并卸载无用插件
关注安全公告订阅 Jenkins Security Advisories及时响应 CVE 通告
测试更新在生产环境前，先在预发环境测试插件更新避免更新导致构建失败
插件白名单使用 “Plugin Usage Plugin” 分析插件使用情况识别并移除僵尸插件

11.3 备份与恢复 Jenkins 配置

方法操作步骤说明
备份 JENKINS_HOME复制整个 JENKINS_HOME 目录（默认 /var/lib/jenkins）
包含：jobs/（任务配置）、plugins/（插件）、users/（用户）、config.xml（主配置）		最完整、最可靠的备份方式
使用 ThinBackup 插件安装 “ThinBackup” 插件
配置备份目录和计划		支持增量备份，节省空间
备份策略频率：每日或每次重大变更后
存储：异地、加密
验证：定期恢复测试		建议结合 cron 脚本自动化
恢复步骤1. 停止 Jenkins 服务
2. 替换 JENKINS_HOME 目录
3. 启动 Jenkins		确保版本兼容性
备份构建产物？不推荐：产物应归档到 Nexus、S3 等专用存储Jenkins 工作区不是持久化存储

11.4 日志审计与监控

日志类型位置/方法用途
Jenkins 主日志”Manage Jenkins” > “System Log” > “All logs”查看系统级错误、插件加载、安全事件
任务构建日志每个构建的 “Console Output”调试构建失败
审计日志（Audit Trail）使用 “Audit Trail Plugin” 或 “Role-based Authorization Strategy”记录用户操作（如谁修改了任务）
代理节点日志JNLP 或 SSH 代理的控制台输出排查节点连接问题
监控指标集成 Prometheus + Grafana：
- Jenkins Prometheus Plugin
- Exporter 暴露指标		监控构建队列长度、代理节点状态、JVM 内存/GC
告警设置基于监控指标设置告警（如构建失败率突增）快速响应系统异常

11.5 升级 Jenkins 版本

步骤说明注意事项
1. 查看升级路径Jenkins LTS 版本之间可能有中间版本要求参考官方升级指南
2. 备份必须执行完整 JENKINS_HOME 备份升级失败可快速回滚
3. 测试环境验证在预发环境先升级，运行关键 Pipeline验证插件兼容性
4. 停止 Jenkins 服务sudo systemctl stop jenkins避免文件锁问题
5. 更新 Jenkins- Debian/Ubuntu: sudo apt update && sudo apt install jenkins
- WAR: 替换 jenkins.war 文件		确保权限正确
6. 启动 Jenkinssudo systemctl start jenkins观察日志是否有错误
7. 检查插件兼容性登录后查看是否有插件需要更新Jenkins 升级后常提示插件更新
8. 验证功能手动触发几个关键任务确保 CI/CD 流程正常

最佳实践：

  • 选择 LTS（长期支持）版本，降低生产风险
  • 避免跳过多版本升级
  • 利用维护窗口升级

第十二章：Jenkins 与 DevOps 工具链集成

12.1 与 Maven/Gradle 集成构建 Java 项目

工具集成方式示例
Maven1. 安装 “Maven Integration” 插件
2. 在全局工具配置中添加 Maven 安装
3. 任务中选择 “Maven project”
4. 设置 POM 路径和 Goals		clean package -DskipTests
Gradle1. 安装 “Gradle Plugin”
2. 配置 Gradle 安装（或使用 wrapper）
3. 在 Pipeline 中使用 sh 'gradle build'		推荐使用 gradlew 保证版本一致
依赖缓存挂载 ~/.m2 或 ~/.gradle 目录加速构建，减少下载
发布到 Nexus在 pom.xml 配置 distributionManagement
或使用 Gradle maven-publish 插件		结合 Credentials Binding 插件使用密码

12.2 与 Node.js/npm 集成构建前端项目

步骤操作工具/插件
安装 Node.js”Manage Jenkins” > “Global Tool Configuration” > “NodeJS”
添加 Node.js 安装（可指定版本）		NodeJS Plugin
安装 npm/yarnNodeJS 插件自动包含 npm/yarn可配置 .npmrc
构建命令在 Pipeline 中执行sh 'npm install' sh 'npm run build' sh 'npm test'
缓存 node_modules使用 cache 步骤或挂载目录sh 'mkdir -p $HOME/.npm' sh 'npm config set cache $HOME/.npm'
归档产物archiveArtifacts 'dist/**'静态文件可部署到 Nginx、S3 等

12.3 与 Docker 集成：构建与推送镜像

方法操作示例
前提代理节点需安装 Docker 引擎sudo apt install docker.io
权限Jenkins 用户需在 docker 组中sudo usermod -aG docker jenkins
Pipeline 中构建使用 sh 执行 Docker 命令sh 'docker build -t myapp:$BUILD_ID .' sh 'docker tag myapp:$BUILD_ID registry/myapp:latest' sh 'docker push registry/myapp:latest'
使用 Docker Pipeline 插件提供更高级的 Docker DSLscript { docker.build("myapp", ".").push("latest") }
凭证管理使用 withDockerRegistrywithDockerRegistry([credentialsId: 'docker-hub', url: '']) { // 构建和推送 }

12.4 与 Kubernetes 部署集成

方法说明示例
使用 kubectl代理节点安装 kubectl，配置 kubeconfigsh 'kubectl apply -f deployment.yaml' sh 'kubectl set image deployment/myapp container=myapp:$IMAGE_TAG'
凭证管理将 kubeconfig 文件作为 “Secret file” 凭据存储withKubeConfig([credentialsId: 'kubeconfig']) { ... }
Helm 部署使用 Helm 命令行sh 'helm upgrade --install myapp ./chart --set image.tag=$IMAGE_TAG'
金丝雀/蓝绿部署结合 Helm 或 Argo Rollouts 实现需在 Kubernetes 侧配置
优势自动化部署，与 CI 无缝衔接实现真正的持续部署

12.5 与 SonarQube 集成代码质量检测

步骤操作插件
1. 安装 SonarQube 服务器独立部署 SonarQube 服务sonarqube.org
2. 安装 Scanner在 Jenkins 代理安装 SonarScanner或使用 sonar-scanner 命令行
3. 配置 Server”Manage Jenkins” > “Configure System” > “SonarQube servers”添加服务器 URL 和 Token
4. 在 Pipeline 中调用使用 withSonarQubeEnv见下方代码示例
5. 质量门禁（Quality Gate）等待质量门禁结果见下方代码示例

SonarQube 集成 Pipeline 示例：

withSonarQubeEnv('My SonarQube') {
    sh 'mvn sonar:sonar'
}

timeout(time: 1, unit: 'HOURS') {
    def qg = waitForQualityGate()
    if (qg.status != 'OK') {
        error "Quality Gate Failed: ${qg.status}"
    }
}

优势： 代码覆盖率、漏洞、坏味道检测，提升代码质量和可维护性。

12.6 与 Argo CD/Jenkins X 等高级 CD 工具对比

特性JenkinsArgo CDJenkins X
核心定位通用 CI/CD 流水线引擎GitOps CD 专用工具Kubernetes 原生 CI/CD 平台
配置方式Groovy Pipeline、UI 配置声明式 YAML (Kustomize/Helm)声明式 Pipeline + GitOps
部署模型推式（Push-based）拉式（Pull-based, GitOps）混合（CI 推，CD 拉）
学习曲线中等（Groovy 脚本）低（YAML + GitOps 概念）高（需懂 K8s、Helm、Tekton）
灵活性极高，几乎无限定制较低，专注于部署同步高，但受限于 K8s 生态
UI/可视化Blue Ocean（可选）优秀，实时同步状态基于 Tekton Dashboard
适用场景传统环境、复杂 CI 流程、多语言项目纯 Kubernetes 环境，强调 GitOps 和声明式管理云原生团队，希望开箱即用的 CI/CD
维护成本较高（插件、脚本维护）低（声明式配置，易审计）中等（依赖云原生生态）

推荐组合： Jenkins 做 CI → Argo CD 做 CD