管理代理

构建代理是运行构建的机器。 teamcity agent 命令组可用于列出和检查代理、启用或禁用它们、管理授权、执行远程命令、打开交互式 shell 会话以及请求重启。

列出代理

视图所有已注册的构建代理：

teamcity agent list

筛选

# Only connected agents
teamcity agent list --connected

# Only enabled agents
teamcity agent list --enabled

# Only authorized agents
teamcity agent list --authorized

# Agents in a specific pool
teamcity agent list --pool Default

# Combine filters
teamcity agent list --connected --enabled --pool Default

   

限制结果并以 JSON 格式输出：

teamcity agent list --limit 20
teamcity agent list --json
teamcity agent list --json=id,name,connected,enabled,pool.name

   

agent list 标志

标志	描述
`--connected`	仅显示已连接的代理
`--enabled`	仅显示已启用的代理
`--authorized`	仅显示已授权的代理
`-p`， `--pool`	按代理池名称筛选器
`-n`， `--limit`	显示的代理最大数量
`--json`	输出为 JSON。使用 `--json=` 可列出可用字段， `--json=f1,f2` 可查看指定字段。

查看代理详细信息

通过 ID 或名称视图特定代理的详细信息：

teamcity agent view 1
teamcity agent view Agent-Linux-01
teamcity agent view Agent-Linux-01 --web
teamcity agent view 1 --json

  

启用和禁用代理

禁用代理以防其运行新的构建：

teamcity agent disable 1
teamcity agent disable Agent-Linux-01

启用代理以再次允许其运行构建：

teamcity agent enable 1
teamcity agent enable Agent-Linux-01

授权和取消授权代理

授权新连接的代理以允许其运行构建：

teamcity agent authorize 1
teamcity agent authorize Agent-Linux-01

取消授权代理以撤销其连接权限：

teamcity agent deauthorize 1
teamcity agent deauthorize Agent-Linux-01

在池之间移动代理

将代理移动到其他代理池：

teamcity agent move 1 0
teamcity agent move Agent-Linux-01 2

第 1 个实参是代理（通过 ID 或名称），第 2 个实参是目标池 ID。

查看兼容作业

列出代理可运行的构建配置：

teamcity agent jobs 1
teamcity agent jobs Agent-Linux-01

显示不兼容作业及其无法在代理上运行的原因：

teamcity agent jobs Agent-Linux-01 --incompatible
teamcity agent jobs 1 --json

执行远程命令

在构建代理上运行命令并返回输出：

teamcity agent exec 1 "ls -la"
teamcity agent exec Agent-Linux-01 "cat /etc/os-release"

为长时间运行的命令设置超时：

teamcity agent exec Agent-Linux-01 --timeout 10m -- long-running-script.sh

交互式 shell 会话

打开到构建代理的交互式终端会话：

teamcity agent term 1
teamcity agent term Agent-Linux-01

这将在代理上建立 WebSocket 连接，并提供 shell，可以直接在代理机器上运行命令。当输入 exit 或按下 Ctrl+D 时，会话结束。

重启代理

请求重启构建代理：

teamcity agent reboot 1
teamcity agent reboot Agent-Linux-01

重启前请等待当前构建完成：

teamcity agent reboot Agent-Linux-01 --graceful

跳过确认提示：

teamcity agent reboot Agent-Linux-01 --yes

2026年 8月 6日