Jenkins 2.580.1 常用 CLI 命令与工具详解

目标：详解 Jenkins 2.580.1 常用的命令行工具——jenkins-cli（jenkins-cli.jar）与 Web REST API（curl/wget），覆盖版本查看、认证、任务与插件管理、系统操作（shutdown/quiet）、健康探活等。每个工具给出完整命令、真实输出与参数说明。本文已在 Ubuntu 22.04 真实环境实测通过。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS
系统架构：x86_64
Jenkins 服务器：2.580.1（LTS），HTTP http://localhost:8080，HTTPS https://localhost:8443（自签）
数据目录：/opt/data/jenkins
管理账号：admin ／密码 q1w2e3r4
CLI 客户端：jenkins-cli.jar（11.7 MB，由服务器 /jnlpJars/jenkins-cli.jar 提供）
测试任务：demo-job（Shell 输出 hello from jenkins）

二、工具概览

工具	主要用途	来源/位置
`jenkins-cli.jar`	全功能命令行管理（任务/节点/插件/系统）	服务器 `/jnlpJars/jenkins-cli.jar` 下载
`curl` / `wget`	调用 Web REST API（JSON/XML）	系统自带
`jenkins.war --version`	离线查看 war 版本	`/usr/share/java/jenkins.war`

三、前置条件

已部署 Jenkins 2.580.1 且服务正常（HTTP 8080，可参考《Ubuntu 22.04 安装 Jenkins 2.580.1 指南》）
具备管理账号（admin / q1w2e3r4）或对应权限的 API Token
需要 JDK 21 运行 java -jar jenkins-cli.jar
服务器根地址已配置（jenkinsUrl），否则 CLI 握手会报错（见"六、6.1"）

四、jenkins-cli 命令行工具

4.1 下载与连接

CLI 客户端由 Jenkins 服务器自行提供，任意主机下载即可：

mkdir -p /opt/data/jenkins
curl -s -o /opt/data/jenkins/jenkins-cli.jar http://localhost:8080/jnlpJars/jenkins-cli.jar
ls -l /opt/data/jenkins/jenkins-cli.jar

执行结果：

-rw-r--r-- 1 root root 11722819 Oct  9 11:29 /opt/data/jenkins/jenkins-cli.jar

💡 说明：jenkins-cli.jar 本质是瘦客户端，运行需要本机有 Java（java -jar）。

4.2 认证方式

# 方式一：命令行带账号密码（演示环境）
java -jar /opt/data/jenkins/jenkins-cli.jar -s http://localhost:8080/ \
  -auth admin:q1w2e3r4 who-am-i

# 方式二：使用 API Token（推荐，避免明文口令落到 shell 历史）
java -jar /opt/data/jenkins/jenkins-cli.jar -s http://localhost:8080/ \
  -auth admin:$(cat /root/.jenkins-api-token) who-am-i

# HTTS + 自签时加 -noCertificateCheck
java -jar /opt/data/jenkins/jenkins-cli.jar -s https://localhost:8443/ -noCertificateCheck \
  -auth admin:q1w2e3r4 who-am-i

⚠️ 注意：HTTPS 走自签、且信任校验失败时需加 -noCertificateCheck。生产建议使用正式证书并改用 API Token 认证，避免明文口令出现在 shell 历史与 ps 输出中。

4.3 版本与身份确认

java -jar /opt/data/jenkins/jenkins-cli.jar -s http://localhost:8080/ -auth admin:q1w2e3r4 version
java -jar /opt/data/jenkins/jenkins-cli.jar -s http://localhost:8080/ -auth admin:q1w2e3r4 who-am-i

执行结果：

2.580.1
Authenticated as: admin
Authorities:
  authenticated
  FACTOR_PASSWORD

💡 说明：version 返回服务器版本 2.580.1；who-am-i 返回当前身份 admin 及其权限，可用于校验认证是否成功。

4.4 任务管理

创建任务（从 stdin 读取任务配置 XML）：

cat > /tmp/demo-job.xml <<'EOF'
<project>
  <description>demo job for CLI test</description>
  <scm class="hudson.scm.NullSCM"/>
  <builders>
    <hudson.tasks.Shell><command>echo hello from jenkins</command></hudson.tasks.Shell>
  </builders>
</project>
EOF
java -jar /opt/data/jenkins/jenkins-cli.jar -s http://localhost:8080/ \
  -auth admin:q1w2e3r4 create-job demo-job < /tmp/demo-job.xml
java -jar /opt/data/jenkins/jenkins-cli.jar -s http://localhost:8080/ \
  -auth admin:q1w2e3r4 list-jobs

执行结果：

demo-job

触发构建并查看控制台：

java -jar /opt/data/jenkins/jenkins-cli.jar -s http://localhost:8080/ -auth admin:q1w2e3r4 build demo-job
java -jar /opt/data/jenkins/jenkins-cli.jar -s http://localhost:8080/ -auth admin:q1w2e3r4 console demo-job

执行结果（console）：

Started from command line by admin
Running as SYSTEM
Building in workspace /opt/data/jenkins/workspace/demo-job
[demo-job] $ /bin/sh -xe /tmp/jenkins5980469956492043110.sh
+ echo hello from jenkins
hello from jenkins
Finished: SUCCESS

💡 说明：create-job <名称> 从 stdin 读取 XML 创建任务；list-jobs 列出任务；build <任务> 触发构建（可加 -f 等待完成）；console <任务> 输出最后一次构建的控制台日志，Finished: SUCCESS 表示构建成功。

查看任务定义 / 删除任务：

java -jar /opt/data/jenkins/jenkins-cli.jar -s http://localhost:8080/ -auth admin:q1w2e3r4 get-job demo-job
java -jar /opt/data/jenkins/jenkins-cli.jar -s http://localhost:8080/ -auth admin:q1w2e3r4 delete-job demo-job

💡 说明：get-job 导出任务 XML（便于版本化/迁移）；delete-job 删除任务（谨慎）。

4.5 插件管理

java -jar /opt/data/jenkins/jenkins-cli.jar -s http://localhost:8080/ -auth admin:q1w2e3r4 list-plugins
java -jar /opt/data/jenkins/jenkins-cli.jar -s http://localhost:8080/ -auth admin:q1w2e3r4 install-plugin git
java -jar /opt/data/jenkins/jenkins-cli.jar -s http://localhost:8080/ -auth admin:q1w2e3r4 enable-plugin git
java -jar /opt/data/jenkins/jenkins-cli.jar -s http://localhost:8080/ -auth admin:q1w2e3r4 disable-plugin git

💡 说明：全新安装未装任何插件时，list-plugins 输出为空属正常。install-plugin <id> 从更新中心安装，可加 --restart 装完自动重启。

4.6 系统操作

安全停机与排队控制：

java -jar /opt/data/jenkins/jenkins-cli.jar -s http://localhost:8080/ -auth admin:q1w2e3r4 quiet-down
java -jar /opt/data/jenkins/jenkins-cli.jar -s http://localhost:8080/ -auth admin:q1w2e3r4 cancel-quiet-down
java -jar /opt/data/jenkins/jenkins-cli.jar -s http://localhost:8080/ -auth admin:q1w2e3r4 clear-queue

💡 说明：quiet-down 进入静默（不再接受新构建，等待存量跑完）；cancel-quiet-down 取消静默；clear-queue 清空排队。shutdown/restart 用于停止/重启服务：
java -jar /opt/data/jenkins/jenkins-cli.jar -s http://localhost:8080/ -auth admin:q1w2e3r4 shutdown
实测执行 shutdown 后 systemctl is-active jenkins 变为 inactive，随后 systemctl start jenkins 即可恢复。

4.7 help 命令总览

用 help 查看全部可用命令：

java -jar /opt/data/jenkins/jenkins-cli.jar -s http://localhost:8080/ -auth admin:q1w2e3r4 help

执行结果（节选）：

  add-job-to-view
    Adds jobs to view.
  build
    Builds a job, and optionally waits until its completion.
  cancel-quiet-down
    Cancel the effect of the "quiet-down" command.
  clear-queue
    Clears the build queue.
  connect-node
    Reconnect to a node(s)
  console
    Retrieves console output of a build.
  copy-job
    Copies a job.
  create-job
    Creates a new job by reading stdin as a configuration XML file.
  create-node
    Creates a new node by reading stdin as a XML configuration.
  delete-job
    Deletes job(s).
  install-plugin
    Installs an installed plugin.
  list-jobs
    Lists all jobs in a specific view or item group.
  list-plugins
    Lists installed plugins.
  quiet-down
    Quiet down Jenkins, in preparation for a restart.
  restart
    Discard all builds and restart Jenkins.
  shutdown
    Shuts down Jenkins.

💡 说明：java -jar jenkins-cli.jar -s <url> -auth admin:q1w2e3r4 help <命令> 可查看单个命令的详细参数。

五、Web REST API（curl / wget）

除了 jenkins-cli，还可用 curl/wget 直接调用 Jenkins 的 REST API（返回 JSON/XML），适合脚本化、无 java 环境。

5.1 系统信息与执行器

curl -s -u admin:q1w2e3r4 "http://localhost:8080/api/json?depth=2"

执行结果（关键字段）：

"mode" : "NORMAL",
"nodeName" : "",
"numExecutors" : 2,

💡 说明：/api/json 返回系统级信息，含执行器数 numExecutors=2、模式 mode=NORMAL 等。

5.2 当前身份（WhoAmI）

curl -s -u admin:q1w2e3r4 "http://localhost:8080/whoAmI/api/json"

执行结果：

{"_class":"hudson.security.WhoAmI","anonymous":false,"authenticated":true,"authorities":["authenticated","FACTOR_PASSWORD"],"name":"admin"}

💡 说明：authenticated:true 与 name:"admin" 用于校验认证是否成功，等价于 CLI 的 who-am-i。

5.3 插件清单

curl -s -u admin:q1w2e3r4 "http://localhost:8080/pluginManager/api/json?depth=1"

💡 说明：返回插件列表；全新安装无插件时 plugins 数组为空。可配合 jq 做插件版本统计。

5.4 任务与构建 API

# 触发构建（POST）
curl -s -X POST -u admin:q1w2e3r4 "http://localhost:8080/job/demo-job/build"

# 查看任务配置
curl -s -u admin:q1w2e3r4 "http://localhost:8080/job/demo-job/config.xml" | head -5

# 查看构建结果（JSON）
curl -s -u admin:q1w2e3r4 "http://localhost:8080/job/demo-job/lastBuild/api/json" | head -30

💡 说明：REST API 支持对任务的增删改查：GET 取任务配置、POST 触发构建、DELETE 删除任务。

5.5 健康探活与资源下载

# 登录页/根地址连通性
curl -s -o /dev/null -w "%{http_code}\n" -u admin:q1w2e3r4 http://localhost:8080/api/json

# 下载 CLI 客户端（等价 wget）
wget -q -O /opt/data/jenkins/jenkins-cli.jar http://localhost:8080/jnlpJars/jenkins-cli.jar

# 自签 HTTPS 时加 -k
curl -sk -u admin:q1w2e3r4 https://localhost:8443/api/json

执行结果：

💡 说明：返回 200 表示服务正常；HTTPS 自签校验失败时 curl 需加 -k（安全上仅限内部/受信环境）。

六、注意事项

根地址（jenkinsUrl）必须配置：未设置时 CLI 握手会返回 403 Jenkins URL is not configured (set Jenkins URL in the configuration)。在「系统配置」设置或在 init.groovy.d/set-rooturl.groovy 写入后重启（见配置详解篇"3.3"）。
认证安全：演示环境用 admin:q1w2e3r4；生产建议改用 API Token 认证，并仅把 -auth 用于可控脚本，避免明文口令落地。
自签 HTTPS：curl 加 -k、jenkins-cli 加 -noCertificateCheck，生产替换为正式证书后应去掉。
毁灭性命令谨慎：delete-job、shutdown、restart、delete-builds 均有破坏性，脚本中务必加校验与二次确认。
任务配置 XML 的完整性：create-job 从 stdin 读 XML，字段格式要严格（可先用 get-job 导出现有任务作模板参考）。

七、常见问题

7.1 问题 1：CLI 握手报 `Jenkins URL is not configured`

原因： 根地址未设置（首次安装常见）。

解决： 在「系统管理 → 系统配置」填写 Jenkins URL，或在 init.groovy.d/set-rooturl.groovy 写入 jenkins.model.JenkinsLocationConfiguration.get().setUrl("http://localhost:8080/") 后重启服务。

7.2 问题 2：`curl`/`java` 提示认证失败（403/401）

原因： 账号密码错误，或开启了 SECURITY/CSRF 且未带 token。

解决： 确认账号口令；生产建议生成 API Token（可由 jenkins-cli token 或 Web 用户页生成）并使用 -auth admin:<token>。

7.3 问题 3：`list-plugins` 为空 / 装插件后不生效

原因： 全新安装未装插件，或插件需重启才生效。

解决： 用 install-plugin <id> --restart 安装并重启，或到「插件管理」手动安装。

7.4 问题 4：构建始终 `Waiting for next available executor`

原因： 并发构建数超过 numExecutors（内置节点默认 2）。

解决： 调高执行器数（config.xml 的 <numExecutors>）或清空构建队列（clear-queue）。

7.5 问题 5：下载 jenkins-cli.jar 失败

原因： 根地址配置为 localhost、外部主机无法访问，或 jnlp 端口被禁。

解决： 使用可被外部访问的服务器地址访问 /jnlpJars/jenkins-cli.jar。

八、参考链接

本文档由 www.quzuo.net 平台开发

Jenkins 2.580.1 常用 CLI 命令与工具详解

Jenkins 2.580.1 常用 CLI 命令与工具详解

一、环境信息

二、工具概览

三、前置条件

四、jenkins-cli 命令行工具

4.1 下载与连接

4.2 认证方式

4.3 版本与身份确认

4.4 任务管理

4.5 插件管理

4.6 系统操作

4.7 help 命令总览

五、Web REST API（curl / wget）

5.1 系统信息与执行器

5.2 当前身份（WhoAmI）

5.3 插件清单

5.4 任务与构建 API

5.5 健康探活与资源下载

六、注意事项

七、常见问题

7.1 问题 1：CLI 握手报 Jenkins URL is not configured

7.2 问题 2：curl/java 提示认证失败（403/401）

7.3 问题 3：list-plugins 为空 / 装插件后不生效

7.4 问题 4：构建始终 Waiting for next available executor

7.5 问题 5：下载 jenkins-cli.jar 失败

八、参考链接

7.1 问题 1：CLI 握手报 `Jenkins URL is not configured`

7.2 问题 2：`curl`/`java` 提示认证失败（403/401）

7.3 问题 3：`list-plugins` 为空 / 装插件后不生效

7.4 问题 4：构建始终 `Waiting for next available executor`