GoCD 26.1.0 常用 CLI 命令详解

目标：系统整理 GoCD 26.1.0 的命令行管理方式。GoCD 官方未提供单机管理 CLI 工具（区别于 Jenkins CLI jar），命令行管理以 REST API + curl 为主——本文逐条实测 version、dashboard、agents、pipeline_groups、pipelines（调度/暂停/历史）与制品日志下载等常用接口，含认证、版本头与确认头等通用约定，全部回显照抄。实测日期 2026-10-20；部署与环境见《GoCD Docker Compose 部署指南》，配置参数见《GoCD 26.1.0 配置参数详解》。

一、环境信息

项目	值	说明
操作系统	Ubuntu 22.04.4 LTS（内核 6.8.0-138-generic）	实测
GoCD 版本	26.1.0（build 22803）	version API 实测返回
API 入口	`http://localhost:8146/go/api/...`（映射到服务 8153）	compose 实测
认证	basic auth `admin:q1w2e3r4`（密码文件插件）	部署篇 4.5 节实测
测试流水线	hello-cd（defaultGroup，build-stage/run-echo，已跑 4 次）	部署篇 4.7 节实测
curl 版本	系统自带 curl 7/8.x 均可	无特殊依赖

二、工具概览

GoCD 的命令行管理面 = REST API。官方没有提供类似 gocd-cli 的单机管理工具，Web UI 之外的自动化全部走 /go/api/ 下的版本化 HTTP 接口（官方 API 文档 https://api.gocd.org/26.1.0/ 与 server 版本一一对应）。本文以 curl 为客户端逐条实测；任何支持 basic auth 的 HTTP 客户端（Python requests、Go net/http 等）等价可用。

三条通用约定（每条接口都受其约束，实测总结）：

认证：basic auth（用户名:密码）或 Personal Access Token（Authorization: Bearer <token>）；未认证或错密码返回 401；
版本头：除少数接口外，必须带 Accept: application/vnd.go.cd.v<N>+json，N 为该接口支持的 API 版本（各接口不同，用错版本返回 404）；
确认头：所有写操作（调度、暂停、启用 agent 等）必须带 X-GoCD-Confirm: true，否则返回 400。

三、前置条件

# 服务可达且认证有效（200 即就绪）
curl -s -o /dev/null -w '%{http_code}\n' -u admin:q1w2e3r4 http://localhost:8146/go/api/version -H 'Accept: application/vnd.go.cd.v1+json'

认证失败的对照实测（错误密码）：

curl -s -w '\nhttp=%{http_code}\n' -u admin:wrongpass http://localhost:8146/go/api/agents -H 'Accept: application/vnd.go.cd.v7+json'

{
  "message": "Invalid credentials. Either your username and password are incorrect, or there is a problem with your browser cookies. Please check with your administrator."
}
http=401

四、各 API 域详解

4.1 版本信息（GET /go/api/version，v1）

用途：确认 server 版本与构建号，升级后核对的第一入口。

curl -s -u admin:q1w2e3r4 http://localhost:8146/go/api/version -H 'Accept: application/vnd.go.cd.v1+json'

{
  "_links" : {
    "self" : {
      "href" : "http://localhost:8146/go/api/version"
    },
    "doc" : {
      "href" : "https://api.gocd.org/26.1.0/#version"
    }
  },
  "version" : "26.1.0",
  "build_number" : "22803",
  "git_sha" : "55b7b460510bb739c1ae6d226ff7fb650596dca2",
  "full_version" : "26.1.0 (22803-55b7b460510bb739c1ae6d226ff7fb650596dca2)",
  "commit_url" : "https://github.com/gocd/gocd/commit/55b7b460510bb739c1ae6d226ff7fb650596dca2"
}

4.2 仪表盘（GET /go/api/dashboard，v4）

用途：一条命令取回全部流水线的运行态概览（最近实例状态、暂停信息、权限），适合巡检脚本。

curl -s -u admin:q1w2e3r4 http://localhost:8146/go/api/dashboard -H 'Accept: application/vnd.go.cd.v4+json' | python3 -m json.tool | head -40

输出节选（实测首部）：

{
    "_links": {
        "self": {
            "href": "http://localhost:8146/go/api/dashboard"
        },
        "doc": {
            "href": "https://api.gocd.org/current/#dashboard"
        }
    },
    "_embedded": {
        "pipeline_groups": [
            {
                "name": "defaultGroup",
                "pipelines": [
                    "hello-cd"
                ],
                "can_administer": true,
                "defines_pipelines": true
            }
        ],
        "environments": [],
        "pipelines": [
            {
                "name": "hello-cd",
                "locked": false,
                "pause_info": {
                    "paused": false,
                    ...
                },
                "can_operate": true,
                "can_administer": true,
                ...

4.3 agent 管理域

4.3.1 列出 agent（GET /go/api/agents，v7）

curl -s -u admin:q1w2e3r4 http://localhost:8146/go/api/agents -H 'Accept: application/vnd.go.cd.v7+json' | python3 -c "import json,sys; d=json.load(sys.stdin); print(json.dumps([{'uuid':a['uuid'],'hostname':a['hostname'],'agent_state':a['agent_state'],'config_state':a['agent_config_state'],'sandbox':a['sandbox'],'ip':a['ip_address']} for a in d['_embedded']['agents']], indent=1))"

[
 {
  "uuid": "701e7549-18d9-49b1-bf9f-5778fadea2c1",
  "hostname": "gocd-agent",
  "agent_state": "Idle",
  "config_state": "Enabled",
  "sandbox": "/go-working-dir",
  "ip": "10.89.63.11"
 }
]

字段解读：agent_state 是运行态（Idle/Building/Canceled/LostContact），agent_config_state 是管理态（Enabled/Disabled/Pending）。uuid 是后续操作的路由键。

4.3.2 启用 agent（PATCH /go/api/agents/:uuid，v7）

新 agent 注册后为 Pending，需 enable 授权（等价于 UI 上 Admin → Agents 点 Enable）：

curl -s -w '\nhttp=%{http_code}\n' -X PATCH -u admin:q1w2e3r4 \
  http://localhost:8146/go/api/agents/701e7549-18d9-49b1-bf9f-5778fadea2c1 \
  -H 'Accept: application/vnd.go.cd.v7+json' -H 'If-Match: *' \
  -H 'Content-Type: application/json' \
  -d '{"agent_config_state": "Enabled"}' | tail -3

  "uuid" : "701e7549-18d9-49b1-bf9f-5778fadea2c1",
  "hostname" : "gocd-agent",
  ...
http=200

要点：方法是 PATCH（不是 POST），需 If-Match: * 头；body 只传 {"agent_config_state": "Enabled"}（停用传 Disabled）。

⚠️ 旧文档写法 POST /go/api/agents/:uuid/enable 在 26.1.0 实测返回 404——正确端点即上例 PATCH。

4.4 流水线组（GET /go/api/admin/pipeline_groups/:group，v1）

用途：确认某配置组下已加载的流水线（改完配置验证加载结果的快捷手段）。

curl -s -u admin:q1w2e3r4 http://localhost:8146/go/api/admin/pipeline_groups/defaultGroup -H 'Accept: application/vnd.go.cd.v1+json' | python3 -m json.tool | head -20

输出节选（实测）：

{
    "_links": {
        "self": {
            "href": "http://localhost:8146/go/api/admin/pipeline_groups/defaultGroup"
        },
        "doc": {
            "href": "https://api.gocd.org/26.1.0/#pipeline-groups"
        }
    },
    "name": "defaultGroup",
    "pipelines": [
        "hello-cd"
    ],
    ...

4.5 流水线运行域

4.5.1 触发运行（POST /go/api/pipelines/:name/schedule，v1）

# 缺确认头 → 400
curl -s -w '\nhttp=%{http_code}\n' -X POST -u admin:q1w2e3r4 \
  http://localhost:8146/go/api/pipelines/hello-cd/schedule \
  -H 'Accept: application/vnd.go.cd.v1+json'

{
  "message" : "Missing required header 'X-GoCD-Confirm' with value 'true'"
}
http=400

# 带确认头 → 202 受理
curl -s -w '\nhttp=%{http_code}\n' -X POST -u admin:q1w2e3r4 \
  http://localhost:8146/go/api/pipelines/hello-cd/schedule \
  -H 'Accept: application/vnd.go.cd.v1+json' -H 'X-GoCD-Confirm: true'

{
  "message" : "Request to schedule pipeline hello-cd accepted"
}
http=202

⚠️ 202 表示请求受理（进入调度队列），不代表运行完成；结果需查 4.5.2 的 history。可选 body 可指定物料修订与变量（{"materials": [...], "variables": {...}}，按官方 API 文档格式）。

4.5.2 运行历史（GET /go/api/pipelines/:name/history，v1）

curl -s -u admin:q1w2e3r4 http://localhost:8146/go/api/pipelines/hello-cd/history -H 'Accept: application/vnd.go.cd.v1+json' | python3 -m json.tool | grep -E '"counter"|"result"|"state"|"trigger_message"'

输出节选（实测，最新两条）：

"counter": 4,
"trigger_message": "Forced by admin",
"result": "Passed",
"state": "Completed",
...
"counter": 3,
"trigger_message": "Forced by admin",
"result": "Passed",
"state": "Completed",

pipelines[0] 为最新一次运行；stages[].jobs[].result 可下钻到 job 级结果。触发来源由 trigger_message 区分（手动 Forced by admin、物料变更 modified by ...、定时 scheduled by timer）。

4.5.3 暂停与恢复（POST pause/unpause，v1）

curl -s -w '\nhttp=%{http_code}\n' -X POST -u admin:q1w2e3r4 \
  http://localhost:8146/go/api/pipelines/hello-cd/pause \
  -H 'Accept: application/vnd.go.cd.v1+json' -H 'X-GoCD-Confirm: true' \
  -H 'Content-Type: application/json' -d '{"pauseCause":"api-test"}'

{
  "message" : "Pipeline 'hello-cd' paused successfully."
}
http=200

curl -s -X POST -u admin:q1w2e3r4 http://localhost:8146/go/api/pipelines/hello-cd/unpause \
  -H 'Accept: application/vnd.go.cd.v1+json' -H 'X-GoCD-Confirm: true' -w '\nhttp=%{http_code}\n'

{
  "message" : "Pipeline 'hello-cd' unpaused successfully."
}
http=200

暂停期间手动与定时触发均不受理；pause 需要 body（pauseCause 必填），unpause 无需 body。

4.6 制品与控制台日志（GET /go/files/...）

job 的控制台日志本身是制品（cruise-output/console.log），直接按制品路径下载：

curl -s -u admin:q1w2e3r4 http://localhost:8146/go/files/hello-cd/4/build-stage/1/run-echo/cruise-output/console.log | tail -7

输出节选（实测尾部）：

##|07:22:38.732 [go] Start to build hello-cd/4/build-stage/1/run-echo on gocd-agent [/go-working-dir]
!!|07:22:38.741 [go] Task: echo hello-from-gocd
&1|07:22:38.743 hello-from-gocd
?0|07:22:38.791 [go] Task status: passed (49 ms)
j0|07:22:38.802 [go] Current job status: passed
ar|07:22:38.811 [go] Start to upload hello-cd/4/build-stage/1/run-echo on gocd-agent [/go-working-dir]
ex|07:22:38.811 [go] Job completed hello-cd/4/build-stage/1/run-echo on gocd-agent [/go-working-dir]

路径模板：/go/files/<pipeline>/<counter>/<stage>/<stage_counter>/<job>/cruise-output/console.log。job 自定义产物按 XML 中 <artifact dest> 声明的目录同法下载。

五、注意事项

版本头用错即 404：Accept: application/vnd.go.cd.v<N>+json 的 N 每个接口不同（本文实测：version=v1、dashboard=v4、agents=v7、pipeline_groups=v1、pipelines/history/schedule/pause=v1）。404 且响应体为空或纯 HTML 时，先检查版本头再怀疑端点。
写操作三件套：X-GoCD-Confirm: true + POST/PATCH + 认证，缺一不可（schedule 缺确认头实测 400）。
部分文档端点实测不可用：GET /go/api/pipelines/:name/instance/:counter（v1～v3）与 GET /go/api/admin/config/current（v1～v5）在 26.1.0 实测均返回 404；查单次运行详情用 history 接口替代，查配置用 pipeline_groups 或直接读 cruise-config.xml。
幂等与并发：PATCH agents 带 If-Match: * 跳过并发检查；生产脚本建议先 GET 记录 ETag 再条件更新，避免覆盖他人改动。
202 ≠ 成功：schedule 只表示受理，务必轮询 history 确认 stage 结果再进入后续自动化步骤。

六、常见问题（FAQ）

Q1：返回 401 Invalid credentials？

密码错或该用户不在密码文件/认证域内。先用 UI 登录验证账号，再检查 curl 的 -u 参数（密码含特殊字符时用 --user 或 URL 编码）。

Q2：返回 400 Missing required header 'X-GoCD-Confirm'？

写操作加 -H 'X-GoCD-Confirm: true'（4.5.1 实测对比）。

Q3：返回 404 但路径看起来没错？

三种可能按序排查：版本头不对（最常见）；端点在当前版本未开放（见第五章第 3 条）；资源不存在（pipeline 名/uuid 写错）。先用 pipeline_groups 或 agents 列表确认资源名。

Q4：能自动化巡检吗？

可以。最小巡检组合：dashboard（全量流水线状态）→ history（最近运行结果）→ agents（执行节点在线情况），配合 4.6 下载失败 job 的 console.log 做告警附件。全部接口本文均已实测可用。

参考链接

GoCD REST API 官方文档（26.1.0）：https://api.gocd.org/26.1.0/
API 概览与认证说明：https://docs.gocd.org/current/developers/authorize_api.html
制品 API 说明：https://docs.gocd.org/current/advanced_usage/artifacts.html
本文部署环境搭建：《GoCD Docker Compose 部署指南》
本文配置参数依据：《GoCD 26.1.0 配置参数详解》
选型与架构背景：《GoCD 26.1.0 介绍与选型指南》