当前位置：首页 > news >正文

Jenkins CLI 使用方法介绍

news 2025/6/26 10:13:15

Jenkins CLI 使用方法介绍

Jenkins 内置了命令行界面（CLI），允许用户从脚本或 shell 环境访问 Jenkins，从而方便地执行日常任务、批量操作和故障排除。运维人员可以通过 SSH 方式 或 HTTP 方式（下载 jenkins-cli.jar 客户端）调用 CLI。SSH 模式使用标准 SSH 登录，例如：ssh -l USER -p PORT JENKINS_HOST command；而 HTTP 模式则通过下载 Jenkins 主机上的 jenkins-cli.jar 实现，无需打开额外端口，更适合跨网络环境使用。使用 HTTP 模式时，推荐通过 -auth 用户:API令牌 进行认证（可在个人设置页面获取 API 令牌）。

基本用法

最常见的 Jenkins CLI 命令之一是 build，用于触发有权限的任何任务或流水线构建。最简单的形式是直接调用它触发构建并立即返回，但通过附加选项可以等待构建完成、实时输出日志等。例如：

# SSH 模式触发构建，不带参数
ssh -l admin -p 22 jenkins.example.com build my-job

或者使用 HTTP 模式的 jenkins-cli.jar：

# HTTP 模式触发构建（需替换 JENKINS_URL、用户名和API令牌）
java -jar jenkins-cli.jar -s https://jenkins.example.com -auth admin:abcdef123456 build my-job

执行 build 命令时常用选项包括：-s 等待构建完成、-v 实时输出构建日志、-p KEY=VALUE 传递参数等。例如：

# 等待构建完成并显示日志
ssh -l admin -p 22 jenkins.example.com build my-job -s -v

如果构建需要参数，可以使用 -p 选项依次传递：

# HTTP 模式：触发带参数的构建
java -jar jenkins-cli.jar -s https://jenkins.example.com -auth user:token build deploy-job -s -p ENV=prod -p VERSION=1.2.3

如果对当前 CLI 登录用户和权限有疑问，可使用 who-am-i 命令列出认证信息和授权角色：

ssh -l admin -p 22 jenkins.example.com who-am-i

常见使用场景

远程批量触发构建：运维人员可以在远程服务器上编写脚本，循环调用 jenkins-cli.jar 或 ssh 命令，批量触发多个 Jenkins 任务，无需手动点击网页界面。这种方式适用于同时启动一组构建，或者在升级、维护时对多个项目进行并行构建调度。
自动化部署流水线：在自动化部署流程中，可在脚本或其他 CI 系统中调用 Jenkins CLI，将构建过程与后续部署步骤串联起来。例如，一个主流水线完成后使用 CLI 触发下游部署任务，实现跨系统的流水线联动。
定时任务脚本调用：可在操作系统的计划任务（如 cron）中定时执行 Jenkins CLI 命令，在指定时间点自动触发 Jenkins 构建，无需手动干预。如每天凌晨执行一键构建脚本，或者对特定任务做定期健康检查构建。

Jenkins 官方文档指出，CLI 非常适合 日常任务 和 批量更新 等场景，上述用法正是其典型运维应用之一。

案例示范

1. 基本构建触发示例

通过 SSH 模式 触发名为 build-all-software 的任务，并实时输出日志：

ssh -l kohsuke -p 53801 jenkins.example.com build build-all-software -s -v

解释：-l kohsuke 指定 Jenkins 用户，-p 53801 为 Jenkins SSH 端口。选项 -s 等待构建完成、-v 实时跟踪日志。运行后会在终端看到如下输出：

Started build-all-software #1
Started from command line by kohsuke
Building in workspace /tmp/jenkins/workspace/build-all-software
...
Completed build-all-software #1 : SUCCESS

2. HTTP 模式带参数构建示例

下载好 jenkins-cli.jar 后，可在任意机器执行 HTTP 模式命令：

java -jar jenkins-cli.jar -s http://jenkins.example.com -auth deployer:abcd1234 build deploy-pipeline -s -p ENV=staging -p VERSION=2025.06.25

解释：-auth deployer:abcd1234 使用用户名和 API 令牌认证，-p 后面传递了两个构建参数 ENV 和 VERSION。Jenkins 将使用这些参数启动名为 deploy-pipeline 的流水线。

3. 验证当前用户

使用 who-am-i 命令可以检查当前 CLI 连接的用户身份和权限：

java -jar jenkins-cli.jar -s http://jenkins.example.com -auth admin:token who-am-i

执行后会看到类似：

Authenticated as: admin
Authorities:authenticated

这有助于确认认证是否正确，避免因权限不足导致构建命令失败。

以上示例演示了常见的 Jenkins CLI 构建调用格式和参数用法。CLI 工具使用简便灵活，可有效融入自动化脚本和流程中，大幅提高运维效率。

参考文献： Jenkins 官方文档。

示例脚本

#!/bin/bash# Jenkins 配置
JENKINS_URL="http://jenkins.example.com"
CLI_JAR="./jenkins-cli.jar"
AUTH="admin:your-api-token"
ENV="prod"# 定义每个 Job 和其对应版本（格式：job_name:version）
JOBS=("deploy-service-a:1.0.0""deploy-service-b:2.3.1""deploy-service-c:0.9.8"
)# 循环解析 job 和版本，逐个触发构建
for entry in "${JOBS[@]}"; doJOB_NAME="${entry%%:*}"VERSION="${entry##*:}"echo "=== Triggering $JOB_NAME with VERSION=$VERSION ==="java -jar "$CLI_JAR" -s "$JENKINS_URL" -auth "$AUTH" build "$JOB_NAME" -s \-p ENV="$ENV" -p VERSION="$VERSION"
done