DevOps知识中心
DevOps知识中心

用于作业管理和控制的必备 Jenkins CLI 命令

通过命令行解锁 Jenkins 管理的强大功能。本综合指南详细介绍了远程作业管理所需的关键 Jenkins CLI 命令。学习如何安全地设置 CLI、检索配置，并使用 `create-job`、`copy-job`、`delete-job` 和 `build` 自动化整个作业生命周期。非常适合希望使用 API 令牌将 Jenkins 控制集成到自动化脚本工作流中的管理员和开发人员。

43 浏览量

Jenkins CLI 核心命令：用于作业管理与控制

Jenkins 作为领先的开源自动化服务器，提供了强大的机制来管理 CI/CD 流水线。虽然 Web UI 非常适合进行视觉监督，但为了提高管理效率，特别是在处理数百个作业或重复设置任务时，通常需要自动化。这时，Jenkins 命令行界面 (CLI) 就变得不可或缺。

Jenkins CLI 允许管理员和开发人员通过终端远程与 Jenkins 实例进行交互，从而实现强大的脚本编写能力。本文提供了一份实用指南，介绍管理 Jenkins 作业整个生命周期所需的关键 CLI 命令，包括创建、配置、启用、禁用和删除作业。掌握这些命令对于有效的 Jenkins 管理以及将其整合到 DevOps 工具链中至关重要。

设置 Jenkins CLI

在执行任何命令之前，您必须先建立与 Jenkins Master 的安全连接。这包括下载 CLI 客户端并确保正确的身份验证。

1. 下载 jenkins-cli.jar

CLI 客户端通常直接位于 Jenkins 服务器的特定端点。您可以使用 wget 或 curl 下载它：

wget http://your-jenkins-url:8080/jnlpJars/jenkins-cli.jar
# OR using curl
curl -O http://your-jenkins-url:8080/jnlpJars/jenkins-cli.jar

2. 身份验证方法

Jenkins CLI 连接需要身份验证。最安全且推荐的方法是使用 API 令牌，而不是普通的用户密码。

要生成 API 令牌，请在 Jenkins Web UI 中导航至 用户设置 > 配置 > API 令牌。

所有后续命令都需要身份验证标志，通常使用 -s (服务器 URL) 和 -auth (身份验证凭证) 标志：

java -jar jenkins-cli.jar -s http://your-jenkins-url:8080 -auth USERNAME:API_TOKEN <command>

提示： 为了安全起见，请将您的 API 令牌存储在安全的环境变量中，或者如果已配置，请使用 SSH 密钥身份验证方法，而不是将其直接输入到脚本中。

作业发现的核心命令

在修改作业之前，通常需要列出现有的作业并检索它们的配置。

列出所有作业：list-jobs

此命令显示 Jenkins Master 上配置的所有作业的名称。

java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH list-jobs

检索作业配置：get-job

Jenkins 作业由 XML 配置文件定义。get-job 命令允许您检索此 XML 定义，这对于基于模板创建新作业至关重要。

# 检索 'my-template-job' 的配置并将其保存到文件中
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH get-job my-template-job > template-config.xml

重要的作业管理命令

这些命令处理 Jenkins 作业的基本生命周期操作。

1. 创建新作业：create-job

create-job 命令需要新作业的名称以及定义其参数、构建步骤和触发器的 XML 配置文件。

先决条件： 您必须首先拥有一个有效的 XML 配置文件（例如 new-config.xml），该文件通常是通过修改使用 get-job 检索到的模板而获得的。

# 示例：使用本地 XML 文件创建名为 'project-feature-branch' 的新作业
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH create-job project-feature-branch < new-config.xml

2. 复制现有作业：copy-job

这通常是创建新作业的最快方式，它将现有作业作为模板，并应用一个新名称。此命令有效地复制了源作业的配置。

# 语法：copy-job SOURCE_JOB_NAME DESTINATION_JOB_NAME
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH copy-job original-pipeline new-dev-pipeline

3. 启用和禁用作业：enable-job 和 disable-job

这些命令对于维护、临时停止或管理控制至关重要，用于阻止或允许触发构建。

# 在维护期间停止进一步计划或触发的构建的命令
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH disable-job legacy-project-build

# 重新激活作业的命令
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH enable-job legacy-project-build

4. 删除作业：delete-job

此命令将作业及其构建历史记录和配置从 Jenkins 实例中永久删除。请谨慎使用此命令。

# 永久删除作业
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH delete-job obsolete-test-job

警告： delete-job 命令在 CLI 环境中会立即执行，无需进一步确认。请确保您的脚本在执行此命令之前包含适当的验证步骤。

触发和监控构建

除了配置管理之外，CLI 还经常用于触发构建，特别是那些需要特定参数的构建。

触发构建：build

build 命令为指定的作业启动新的构建。如果作业是参数化的，您可以直接使用 -p 标志传递参数。

# 触发一个简单的、非参数化的构建
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH build nightly-deploy

# 触发一个参数化作业，并传递参数
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH build integration-test -p TARGET_ENV=staging -p BRANCH_NAME=hotfix-123

注意： 如果在 build 命令中使用 -s 标志，CLI 将等待构建完成并报告退出状态。否则，命令在构建排队后会立即返回。

查看构建状态：get-job 和 console

虽然 CLI 无法提供与 Web UI 相媲美的实时流式传输，但您可以检查作业状态并检索控制台输出。

要查看特定构建编号的控制台输出：

# 检索 'my-job' 的第 55 次构建的控制台输出
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH console my-job 55

CLI 脚本编写的最佳实践

有效利用 Jenkins CLI 需要采用特定的最佳实践以确保稳定性和安全性：

1. 脚本编写与自动化

CLI 的真正力量在于 Shell 脚本。使用像 get-job 这样的命令，使用 sed 或 awk 等工具修改生成的 XML，然后使用 create-job 或 reload-job 将修改后的配置反馈回去。

**示例工作流程（复制、修改和创建）：
**
1. 获取模板：get-job template-job > tmp.xml
2. 使用 sed 替换 tmp.xml 中的占位符（例如，项目名称、存储库 URL）。
3. 创建新作业：create-job new-job < tmp.xml

2. 处理配置更新

要使用 XML 文件更新现有作业的配置，请使用 reload-job 命令。这比删除并重新创建作业更安全，因为它保留了构建历史记录。

# 使用本地修改的配置文件更新 'project-a'
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH reload-job project-a < updated-config.xml

3. 错误处理

在脚本中执行 CLI 命令后，始终检查退出代码（$?）。返回代码 0 表示成功；任何非零代码都表示错误。这对于健壮的自动化和调试至关重要。

总结

Jenkins CLI 提供了一个强大且可脚本化的接口来管理作业，使管理员能够自动化重复性任务、管理配置迁移，并将 Jenkins 管理集成到更大的 CI/CD 部署脚本中。通过利用 copy-job、create-job、delete-job 和 build 等命令，您可以显著提高效率并维护 Jenkins 环境的一致性。