Concourse 8.3.1 常用 CLI 命令详解

逐命令实测 Concourse 8.3.1 官方 fly CLI：覆盖目标与认证、流水线管理、作业与构建、一次性构建与交互、集群资源与运维五大类，全部输出在真实服务器环境逐行照抄。

Concourse2026/10/20

Concourse 8.3.1 常用 CLI 命令详解

本文以真实服务器视角逐命令实测 Concourse 8.3.1 官方命令行工具 fly：覆盖目标与认证、流水线管理、作业与构建、一次性构建与交互、集群资源与运维五大类，全部命令与输出均在 Ubuntu 22.04 实测环境逐行照抄，未做任何加工。部署环境与流水线搭建过程见《Concourse 8.3.1 Docker Compose 部署指南》。

一、环境信息

  • 操作系统：Ubuntu 22.04.4 LTS（内核 6.8.0-138-generic）
  • Concourse 服务端版本：8.3.1（web + worker + PostgreSQL 三服务栈，项目名 concourse-831-stack）
  • fly 版本：8.3.1（fly -v 实测输出，与服务端一致；fly 从 web 节点 /api/v1/cli?arch=amd64&platform=linux 下载）
  • fly 登录目标：main → http://127.0.0.1:8148（web 对外端口 8148）
  • 测试账号：root / q1w2e3r4（main 团队 owner）
  • 已配置流水线：hello-world（含一个 hello-world 作业）
  • 一次性构建素材：pipelines/task-oneoff.yml（输出架构与时间）、pipelines/task-sleep.yml（休眠 25 秒，用于观察运行中的实例）
  • 实测日期：2026-10-20

二、fly 命令总览

2.1 版本与全局选项

fly -v 实测输出：

8.3.1

fly --help 显示的用法与全局选项（原文照抄）：

Usage:
  fly [OPTIONS] <command>

Application Options:
  -t, --target=              Concourse target name
  -v, --version              Print the version of Fly and exit
      --verbose              Print API requests and responses
      --print-table-headers  Print table headers even for redirected output

Help Options:
  -h, --help                 Show this help message

四个全局选项的实测要点：

选项作用实测说明
-t指定目标名目标保存在 ~/.flyrc，登录成功后自动写入
-v打印 fly 版本输出 8.3.1
--verbose打印 API 请求与响应排查认证与接口问题时使用
--print-table-headers重定向输出时也打印表头本文所有表格类输出均加此选项截取；不加时表格只有数据行

2.2 子命令清单

fly --help 的 Available commands 区块（原文照抄，共 55 个子命令，按字母排序）：

  abort-build                Abort a build (aliases: ab)
  active-users               List the active users since a date or for the past 2 months (aliases: au)
  archive-pipeline           Archive a pipeline (aliases: ap)
  builds                     List builds data (aliases: bs)
  check-resource             Check a resource (aliases: cr)
  check-resource-type        Check a resource-type (aliases: crt)
  checklist                  Print a Checkfile of the given pipeline (aliases: cl)
  clear-resource-cache       Clear cache of a resource (aliases: crc)
  clear-task-cache           Clears cache from a task container (aliases: ctc)
  clear-versions             Clear versions of a resource or resource type (aliases: cv)
  clear-wall                 Clear the wall message (aliases: cw)
  completion                 generate shell completion code
  containers                 Print the active containers (aliases: cs)
  curl                       curl the api (aliases: c)
  delete-target              Delete target (aliases: dtg)
  destroy-pipeline           Destroy a pipeline (aliases: dp)
  destroy-team               Destroy a team and delete all of its data (aliases: dt)
  disable-resource-version   Disable a version of a resource (aliases: drv)
  edit-target                Edit a target (aliases: etg)
  enable-resource-version    Enable a version of a resource (aliases: erv)
  execute                    Execute a one-off build using local bits (aliases: e)
  expose-pipeline            Make a pipeline publicly viewable (aliases: ep)
  format-pipeline            Format a pipeline config (aliases: fp)
  get-components             Get details about all web components (aliases: gc)
  get-pipeline               Get a pipeline's current configuration (aliases: gp)
  get-team                   Show team configuration (aliases: gt)
  get-wall                   Get the current wall message (aliases: gw)
  health                     Check cluster health
  help                       Print this help message
  hide-pipeline              Hide a pipeline from the public (aliases: hp)
  hijack                     Execute a command in a container (aliases: intercept, i)
  jobs                       List the jobs in the pipelines (aliases: js)
  land-worker                Land a worker (aliases: lw)
  login                      Authenticate with the target (aliases: l)
  logout                     Release authentication with the target (aliases: o)
  order-instanced-pipelines  Orders instanced pipelines within an instance group (aliases: oip)
  order-pipelines            Orders pipelines (aliases: op)
  pause-component            Pause one or more web components (aliases: pc)
  pause-job                  Pause a job (aliases: pj)
  pause-pipeline             Pause a pipeline (aliases: pp)
  paused-jobs                List the paused jobs in the pipelines (aliases: pjs)
  paused-pipelines           List the configured paused pipelines (aliases: pps)
  pin-resource               Pin a version to a resource (aliases: pr)
  pipelines                  List the configured pipelines (aliases: ps)
  prune-worker               Prune a stalled, landing, landed, or retiring worker (aliases: pw)
  rename-pipeline            Rename a pipeline (aliases: rp)
  rename-team                Rename a team (aliases: rt)
  rerun-build                Rerun a build (aliases: rb)
  resource-versions          List the versions of a resource (aliases: rvs)
  resources                  List the resources in the pipeline (aliases: rs)
  schedule-job               Request the scheduler to run for a job. Introduced as a recovery command for the v6.0 scheduler. (aliases: sj)
  set-pipeline               Create or update a pipeline's configuration (aliases: sp)
  set-team                   Create or modify a team to have the given credentials (aliases: st)
  set-wall                   Set a wall message (aliases: sw)
  status                     Login status
  sync                       Download and replace the current fly from the target (aliases: s)
  targets                    List saved targets (aliases: ts)
  teams                      List the configured teams (aliases: t)
  trigger-job                Start a job in a pipeline (aliases: tj)
  unpause-component          Unpause one or more web components (aliases: uc)
  unpause-job                Unpause a job (aliases: uj)
  unpause-pipeline           Un-pause a pipeline (aliases: up)
  unpin-resource             Unpin a version to a resource (aliases: ur)
  userinfo                   User information
  validate-pipeline          Validate a pipeline config (aliases: vp)
  volumes                    List the active volumes (aliases: vs)
  watch                      Stream a build's output (aliases: w)
  workers                    List the registered workers (aliases: ws)

说明：每个子命令都支持别名，例如 fly sp -p demo -c demo.yml 等价于 fly set-pipeline -p demo -c demo.yml；本文统一使用全称。未在本文展开的低频子命令（资源版本管控、团队重命名、组件暂停等）含义以帮助原文为准，不在此虚构输出。

三、目标与认证命令

3.1 login — 登录目标

实测命令：

$ ./fly -t main login -c http://127.0.0.1:8148 -u root -p q1w2e3r4

实测输出：

logging in to team 'main'


target saved

要点：

  • -t main 是目标名，首次登录后写入 ~/.flyrc；-c 指定 web 节点地址，-u/-p 为本地账号口令。
  • 也可以不带 -u/-p 执行，fly 会提示在浏览器中完成认证，服务器无浏览器环境时直接带账号口令最稳妥。
  • 登录后再次执行 fly -t main status 即可核验。

3.2 status — 登录状态

实测输出（已登录时）：

logged in successfully

执行 logout 后再查（见 3.3），输出为：

logged out

3.3 logout — 退出登录

实测命令与输出：

$ ./fly -t main logout
logged out of target: main

要点：logout 只清除本地 ~/.flyrc 中该目标的令牌，不影响服务端会话。

3.4 targets — 目标清单

实测输出：

main  http://127.0.0.1:8148  main  Wed, 21 Oct 2026 07:45:40 UTC

四列依次为：目标名、地址、团队、保存时间。该命令不需要 -t。

3.5 userinfo — 当前用户

实测输出：

root  main/owner

输出为「用户名 团队/角色」，owner 是团队最高权限角色。

3.6 teams — 团队清单

实测输出：

main

默认安装只有一个 main 团队。

四、流水线管理命令

4.1 set-pipeline — 创建/更新流水线

实测命令（-n 非交互模式，跳过确认提问）：

$ ./fly -t main set-pipeline -n -p tmp-d1 -c pipelines/tmp-d1.yml

实测输出：

jobs:
  job tmp-job has been added:
+ name: tmp-job
+ plan:
+ - config:
+     image_resource:
+       name: ""
+       source:
+         repository: docker.1ms.run/library/busybox
+         tag: latest
+       type: registry-image
+     platform: linux
+     run:
+       args:
+       - tmp pipeline for CLI demo
+       path: echo
+   task: noop

pipeline name: tmp-d1

pipeline created!
you can view your pipeline here: http://127.0.0.1:8148/teams/main/pipelines/tmp-d1

the pipeline is currently paused. to unpause, either:
  - run the unpause-pipeline command:
    ./fly -t main unpause-pipeline -p tmp-d1
  - click play next to the pipeline in the web ui

要点：

  • 不加 -n 时，fly 会先打印配置差异，再进入交互确认；脚本化场景务必加 -n。
  • 输出中的 + 行是本次新增的配置，更新已有流水线时还会出现 - 行（删除项）与空格行（保留项）。
  • 新流水线默认处于 paused 状态，必须 unpause 后才会被调度。
  • set-pipeline 支持的完整选项（-d 干跑、--check-creds 校验凭据、-v/-y/-i 变量注入、-l 变量文件、--team 跨团队配置）可用 fly set-pipeline --help 查看，本例仅覆盖最常用路径。

4.2 get-pipeline — 导出流水线配置

实测命令与输出：

$ ./fly -t main get-pipeline -p hello-world
jobs:
- name: hello-world
  plan:
  - config:
      image_resource:
        name: ""
        source:
          repository: docker.1ms.run/library/busybox
          tag: latest
        type: registry-image
      platform: linux
      run:
        args:
        - hello world
        path: echo
    task: say-hello

要点：输出即服务端当前生效的配置（YAML），可直接保存为文件再配合 set-pipeline 回写，形成「导出—修改—回写」的运维闭环。

4.3 pipelines — 流水线清单

实测输出（--print-table-headers，此时 tmp-d1 已创建）：

id  name         paused  public  last updated
2   hello-world  no      no      2026-10-20 15:13:29 +0800 CST
3   tmp-d1       yes     no      2026-10-20 15:45:40 +0800 CST

五列依次为：内部 id、名称、是否暂停、是否公开可见、最后更新时间。

4.4 pause-pipeline / unpause-pipeline — 暂停与恢复

实测命令与输出：

$ ./fly -t main pause-pipeline -p hello-world
paused 'hello-world'
$ ./fly -t main pipelines
2  hello-world  yes  no  2026-10-20 15:13:29 +0800 CST
$ ./fly -t main unpause-pipeline -p hello-world
unpaused 'hello-world'

要点：暂停后调度器不再检查该流水线的资源版本，也不会触发新构建；恢复后立即回到正常调度。注意与 pause-job 的粒度差异（见 5.2）。

4.5 expose-pipeline / hide-pipeline — 公开与隐藏

实测命令与输出：

$ ./fly -t main expose-pipeline -p hello-world
exposed 'hello-world'
$ ./fly -t main pipelines
2  hello-world  no  yes  2026-10-20 15:13:29 +0800 CST
$ ./fly -t main hide-pipeline -p hello-world
hid 'hello-world'

要点：expose 后未认证的访问者也能只读查看该流水线（public 列变 yes），适合对外展示构建状态；hide 恢复为仅团队可见。

4.6 destroy-pipeline — 删除流水线

实测命令（-n 跳过确认）与输出：

$ ./fly -t main destroy-pipeline -p tmp-d1 -n
!!! this will remove all data for pipeline `tmp-d1`

`tmp-d1` deleted

删除后再查清单，只剩 hello-world：

id  name         paused  public  last updated
2   hello-world  no      no      2026-10-20 15:13:29 +0800 CST

要点：destroy 会连同构建历史、资源版本一起清除，不可恢复；交互模式（不加 -n）会先显示上述警告行再等待确认。

五、作业与构建命令

5.1 jobs — 作业清单

实测命令（-p 必填）与输出：

$ ./fly -t main jobs -p hello-world --print-table-headers
name         paused  status     next
hello-world  no      succeeded  n/a

不指定 -p 时 fly 直接报错（实测原文）：

error: the required flag `-p, --pipeline' was not specified

要点：status 列取值为作业最近一次构建的结果；next 列显示下一次待执行构建（本例为 n/a）。

5.2 pause-job / unpause-job — 暂停与恢复单个作业

实测命令与输出：

$ ./fly -t main pause-job -j hello-world/hello-world
paused 'hello-world'
$ ./fly -t main jobs -p hello-world
hello-world  yes  succeeded  n/a
$ ./fly -t main unpause-job -j hello-world/hello-world
unpaused 'hello-world'
$ ./fly -t main jobs -p hello-world
hello-world  no  succeeded  n/a

要点：作业粒度的暂停比流水线粒度更细，适合「流水线其余作业照常跑、只冻结某一个作业」的场景。

5.3 builds — 构建历史

实测命令与输出（-j 过滤指定作业，表头来自 --print-table-headers）：

$ ./fly -t main builds -j hello-world/hello-world --print-table-headers
id  name                       status     start                     end                       duration  team  created by
13  hello-world/hello-world/8  succeeded  2026-10-20@15:43:37+0800  2026-10-20@15:43:39+0800  2s        main  root
11  hello-world/hello-world/7  succeeded  2026-10-20@15:33:07+0800  2026-10-20@15:33:15+0800  8s        main  root
6   hello-world/hello-world/6  succeeded  2026-10-20@15:21:23+0800  2026-10-20@15:21:36+0800  13s       main  root
5   hello-world/hello-world/5  errored    2026-10-20@15:20:03+0800  2026-10-20@15:20:03+0800  0s        main  root

不带 -j 时列出全部构建，包括一次性构建（摘录）：

id  name                       status     start                     end                       duration  team  created by
11  hello-world/hello-world/7  succeeded  2026-10-20@15:33:07+0800  2026-10-20@15:33:15+0800  8s   main  root
10  4                          succeeded  2026-10-20@15:24:18+0800  2026-10-20@15:24:45+0800  27s  main  system
9   3                          succeeded  2026-10-20@15:23:53+0800  2026-10-20@15:24:19+0800  26s  main  system
8   2                          succeeded  2026-10-20@15:23:18+0800  2026-10-20@15:23:43+0800  25s  main  system
7   1                          succeeded  2026-10-20@15:23:04+0800  2026-10-20@15:23:06+0800  2s   main  system
6   hello-world/hello-world/6  succeeded  2026-10-20@15:21:23+0800  2026-10-20@15:21:36+0800  13s  main  root
5   hello-world/hello-world/5  errored    2026-10-20@15:20:03+0800  2026-10-20@15:20:03+0800  0s   main  root

要点：

  • name 列为 流水线/作业/构建号；一次性构建没有归属流水线，name 列只显示序号（1、2、3……），created by 显示 system。
  • id 是集群全局自增号，触发新构建后该号持续增长（本例 id 12、13 为后续实测新增）。
  • status 取值：succeeded / errored / failed / aborted / pending 等。

5.4 trigger-job — 手动触发构建

实测命令与输出：

$ ./fly -t main trigger-job -j hello-world/hello-world
started hello-world/hello-world #8

要点：触发后立即返回构建号，不等待构建结束；需要同步等待时配合下一节的 watch。

5.5 watch — 跟踪构建输出

实测命令与输出（回放已完成构建的完整日志，此处摘录后半段）：

$ ./fly -t main watch --build 7 -j hello-world/hello-world
37bb94b0940b [============================================] 2.1MiB/2.1MiB
selected worker: worker-01
running echo hello world
hello world
succeeded

一个典型的错误用法（把作业串当位置参数，实测原文）：

error: strconv.Atoi: parsing "hello-world/hello-world#6": invalid syntax

要点：

  • 正确姿势是 -j 流水线/作业 加 -b 构建号，或直接传构建页 URL；把 hello-world/hello-world 当作位置参数会被当作全局构建号解析而报错。
  • 对正在运行的构建执行 watch 即实时跟踪；构建结束后 watch 变为回放。

六、一次性构建与交互命令

6.1 execute — 本地任务一次性执行

实测命令：

$ ./fly -t main execute -c pipelines/task-sleep.yml

实测输出（进度条行已省略，其余逐行照抄）：

executing build 14 at http://127.0.0.1:8148/builds/14
initializing
initializing check: image
selected worker: worker-01
selected worker: worker-01
INFO: found existing resource cache

selected worker: worker-01
running sleep 25
succeeded

要点：

  • execute 不需要预先配置流水线，把任务文件直接提交执行，适合排查任务配置、临时跑脚本；本例输出中的 INFO: found existing resource cache 表示 busybox 基础文件系统已被缓存、无需重新下载。
  • executing build N at http://…/builds/N 给出该次构建的页面地址，可用 fly watch -b N 跟踪。
  • 一次性构建同样占用 worker 资源并出现在 builds 清单中（见 5.3 的 name 列纯数字条目）。

6.2 hijack — 进入指定步骤执行命令

实测命令与输出：

$ ./fly -t main hijack -b 14 -s one-off --step-type task -- sh -c 'uname -m && hostname'
x86_64
6a9c6ac5-f8c4-43c8-b1bb-86994d55b72b

要点：

  • -b 指定全局构建号，-s one-off --step-type task 把定位范围收窄到该构建的 task 类步骤（名为 one-off）；不收窄时同一次构建往往同时存在 check/get/task 多个实例，fly 无法唯一定位。
  • -- 之后是目标实例内执行的命令，输出即命令回显（本例第一行是 uname -m 结果，第二行是实例 hostname，恰好等于 handle）。
  • 不带尾部命令时进入交互式登录环境，需要终端 TTY 支持；无 TTY 的自动化场景用 -- 命令 形式。
  • 该命令是调试任务环境（查文件、看进程、试命令）的第一入口，等价于其他系统的 exec into 能力。

七、集群资源与运维命令

7.1 containers — 查看活动运行实例

实测输出（一次性构建运行中抓取，--print-table-headers）：

handle                                worker     pipeline  job   build #  build id  type   name     attempt
6a9c6ac5-f8c4-43c8-b1bb-86994d55b72b  worker-01  none      none  6        14        task   one-off  n/a
81b6f81e-56bc-4cd6-9bfd-3e83c18b59d3  worker-01  none      none  6        14        check  image    n/a
8d86fffc-9a65-46ff-b6cf-f7dbdf2f4bb3  worker-01  none      none  5        12        check  image    n/a
ce363b59-bed1-4e45-90b6-e3f9df3f7e11  worker-01  none      none  5        12        get    image    n/a
deefbc17-faa6-4080-afbe-f8308b2530f0  worker-01  none      none  5        12        task   one-off  n/a

要点：一次构建在 worker 上会分解为 check（版本检查）、get（取基础文件系统）、task（执行任务）多类实例；handle 即 6.2 hijack 时的定位依据；pipeline/job 列为 none 说明是一次性构建。

7.2 volumes — 查看活动卷

实测输出（--print-table-headers，摘录前 5 行）：

handle                                worker     type           identifier
3d76d998-72a3-42d3-b546-22a1263b5c30  worker-01  container      deefbc17-faa6-4080-afbe-f8308b2530f0
555c6091-e79e-48d9-86e4-e95136c2d075  worker-01  container      deefbc17-faa6-4080-afbe-f8308b2530f0
69b79c12-57c0-4fa1-8754-094c8663a5ae  worker-01  resource       digest:sha256:fd7dc98638c8e305f4dc34e979f1c0fdfdcaeb0fbf8fcff77ae834b6da3d7e6e,tag:latest
726c2654-cb81-4f79-ab50-9d0f4a80d69b  worker-01  container      deefbc17-faa6-4080-afbe-f8308b2530f0
76105c9a-be22-48e4-9664-68a0c7fde37f  worker-01  container      8d86fffc-9a65-46ff-b6cf-f7dbdf2f4bb3

要点：type 为 resource 的卷对应基础文件系统缓存（identifier 是其摘要与标签），type 为 container 的卷挂在各步骤实例上；磁盘紧张时可用该命令评估占用，并配合 clear-resource-cache、clear-task-cache 清理。

7.3 workers — worker 清单

实测输出（--print-table-headers）：

name       containers  platform  tags  team  state    version  age
worker-01  0           linux     none  none  running  3.0      7m54s

八列依次为：名称、承载实例数、平台、标签、所属团队、状态、协议版本、存活时长。state 取值包括 running / landing / landed / retiring / stalled / stopped，运维时重点关注 stalled（心跳丢失）。配套的管理命令有 land-worker、prune-worker（帮助原文：Prune a stalled, landing, landed, or retiring worker）。

7.4 health — 集群健康检查

实测输出：

overall                        ok       2026-10-20T07:44:25Z
database                       healthy
workers                        healthy  1/1 running
being_watched_build_marker     healthy  last ran: 2026-10-20T07:41:17Z
signing_key_lifecycler         healthy  last ran: 2026-10-20T07:41:27Z
pipeline_pauser                healthy  last ran: 2026-10-20T06:40:52Z
collector_task_caches          healthy  last ran: 2026-10-20T07:43:47Z
collector_pipelines            healthy  last ran: 2026-10-20T07:43:47Z
collector_builds               healthy  last ran: 2026-10-20T07:43:57Z
reaper                         healthy  last ran: 2026-10-20T07:44:07Z
collector_artifacts            healthy  last ran: 2026-10-20T07:44:07Z
collector_resource_configs     healthy  last ran: 2026-10-20T07:44:07Z
collector_resource_cache_uses  healthy  last ran: 2026-10-20T07:44:07Z
collector_access_tokens        healthy  last ran: 2026-10-20T07:44:07Z
collector_check_sessions       healthy  last ran: 2026-10-20T07:44:07Z
scheduler                      healthy  last ran: 2026-10-20T07:44:07Z
collector_workers              healthy  last ran: 2026-10-20T07:44:07Z
collector_volumes              healthy  last ran: 2026-10-20T07:44:07Z
collector_containers           healthy  last ran: 2026-10-20T07:44:17Z
collector_checks               healthy  last ran: 2026-10-20T07:44:17Z
collector_resource_caches      healthy  last ran: 2026-10-20T07:44:17Z
tracker                        healthy  last ran: 2026-10-20T07:44:17Z
scanner                        healthy  last ran: 2026-10-20T07:44:17Z

要点：首行 overall 是汇总，database 与 workers 是两大关键依赖；各 collector 组件的 last ran 时间可作为「后台任务是否卡死」的判断依据。巡检脚本可直接以 overall ok 作为断言。

7.5 curl — 直连 API

实测命令与输出：

$ ./fly -t main curl /api/v1/info
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   236  100   236    0     0   269k      0 --:--:-- --:--:-- --:--:--  230k
{"version":"8.3.1","worker_version":"3.0","feature_flags":{"build_rerun":false,"cache_streamed_volumes":false,"global_resources":false,"resource_causality":false},"external_url":"http://192.168.146.128:8148","cluster_name":"quzuo-lab"}

要点：curl 子命令自动携带当前目标的认证令牌（token 来自 ~/.flyrc），是验证权限与探索 REST API 的便捷入口；本例返回值同时确认了版本 8.3.1、集群名 quzuo-lab 与对外地址。

7.6 validate-pipeline — 校验流水线文件

实测命令与输出：

$ ./fly -t main validate-pipeline -c pipelines/hello-world.yml
looks good

要点：只做语法与结构校验、不触碰服务端，可并入提交前检查；校验失败时会给出具体字段错误。

7.7 checklist — 输出监控检查项

实测命令与输出：

$ ./fly -t main checklist -p hello-world
#- hello-world
hello-world: concourse.check http://127.0.0.1:8148 main hello-world hello-world

要点：输出遵循 Checkfile 约定，可直接交给监控探针程序解析，实现「流水线 → 监控项」的自动生成。

八、本系列篇目