这篇讲流水线 YAML 写好了、任务却没人执行时，怎么把运行器接到构建机上。看完你可以在控制台新增 Runner（装在构建机上、替 AngusGit 执行任务的程序），生成 1 小时有效的注册令牌，按 Docker 或 Zip 把接入命令复制到构建机上执行，并确认它心跳上线。

流水线和运行器在团队版和企业版中提供；社区版没有 **CI/CD** 菜单，本文的操作不适用。

![控制面 git.anguskit.com 和构建机上的运行器之间交换心跳、任务和日志](https://developer.qcloudimg.com/http-save/yehe-1099973/2ff721e28b778fe5f0dd5c951bedfb57.svg)

## 1. 准备一台构建机

接入之前，先确认网络、容器环境和宿主机环境这三件事。Docker 方式会在这台机器上为每个任务拉起容器（按镜像临时启动的隔离环境）；Zip 方式则让任务直接在宿主机（运行器进程所在的那台机器）上执行。

| 检查项 | 适用方式 | 要求 |
| --- | --- | --- |
| 网络连通 | 全部方式 | 构建机主动连 AngusGit（HTTPS / WebSocket 长连接），AngusGit 不需要反连构建机 |
| 容器环境 | Docker 方式 | 机器装好 Docker，当前用户有权限执行 `docker` 并挂载 `/var/run/docker.sock` |
| 宿主机环境 | Zip 方式 | 机器装好 JDK 21、`curl` 和 `unzip`，当前用户有 `sudo` 权限（安装到 `/opt/AngusRunnerAgent`） |

在构建机上用 `curl -I https://<你的 AngusGit 地址>` 试一下，能返回 HTTP 状态码，说明网络是通的。

## 2. 在控制台新增运行器

1. **打开接入页**

   侧栏进入 **CI/CD → 运行器**，点右上角 **新增 Runner**，页面切到 **接入新 Runner**。

2. **确认控制面地址**

   **控制面地址** 默认取当前浏览器打开的站点地址。页面提示「若 Runner 所在网络访问不到，请改为控制面对外可达的 URL」。例如你在办公网用域名访问 AngusGit，而构建机在机房只能用内网 IP 访问，这里就要改成构建机能访问的那个地址。

3. **填名称和标签**

   **Runner 名称（可选）** 写清是哪台机器，例如 `build-linux-01`。**标签（可选）** 用逗号分隔，例如 `linux,docker`。流水线里的任务会按标签挑运行器，这里的标签要和任务里写的对得上。不确定时先留空，用每种接入方式的默认标签。**最大并发 Job 数** 是这台机器同时最多跑几个任务（Job 就是流水线里的一组步骤），默认 4，可填 1 到 64，按机器的 CPU 和内存决定。

4. **生成注册令牌**

   点 **注册令牌** 旁的 **生成令牌**。页面提示「已签发短期注册令牌（明文仅显示一次）」，下方显示「令牌有效期至 …」，有效期 1 小时。令牌会自动填进下面的命令里。没有令牌时点 **复制命令**，会提示「请先生成或粘贴注册令牌后再复制命令」。

下面这张是还没点 **生成令牌** 时的页面。控制面地址是 `https://git.anguskit.com`，名称 `build-linux-01`，标签 `linux,docker`，最大并发 Job 数 4。黄色提示是「尚未填写令牌」，**复制命令** 是灰的。三个页签是 **Zip 安装**、**Docker 一键拉起**、**一键安装脚本**，默认停在 **Docker 一键拉起**。页签上没有「推荐」两个字，推荐用 Docker 是本文的建议。

![接入新 Runner：名称 build-linux-01，标签 linux,docker，Docker 一键拉起命令里令牌还是占位符](https://developer.qcloudimg.com/http-save/yehe-1099973/74ca5c95e910ba7a0a7717a1efd2836b.png)

## 3. 选一种接入方式，复制命令

三个页签生成的命令，都已经带上了你填的地址、名称、标签、并发数和令牌。

### Docker 一键拉起（推荐）

页签提示「从 AngusRepo 公开仓库拉取 repo.anguskit.com/docker-public/angus-runner-agent」。命令形如：

```bash
docker run -d --restart=always --name build-linux-01 \
  -v /opt/AngusRunnerAgent/logs:/opt/AngusRunnerAgent/logs \
  -v /opt/AngusRunnerAgent/data:/opt/AngusRunnerAgent/data \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e RUNNER_SERVER_URL=wss://git.anguskit.com/ws/runner \
  -e RUNNER_REGISTER_TOKEN=<注册令牌> \
  -e RUNNER_NAME=build-linux-01 \
  -e RUNNER_LABELS=linux,docker \
  -e RUNNER_MAX_CONCURRENCY=4 \
  repo.anguskit.com/docker-public/angus-runner-agent:1.0.0
```

几个要点：`--restart=always` 让运行器在机器重启后自动恢复；挂载 `/var/run/docker.sock` 是为了让运行器能在这台机器上为每个任务启动容器；标签留空时默认是 `linux,docker`。

### Zip 安装

页签提示「从 AngusRepo 下载 Zip，安装到 /opt/AngusRunnerAgent」。命令会依次下载并解压 `AngusRunnerAgent-1.0.0.zip`，复制到 `/opt/AngusRunnerAgent`，设置 `RUNNER_SERVER_URL`、`RUNNER_REGISTER_TOKEN` 等环境变量，然后执行 `./doctor-native.sh` 检查本机环境，最后执行 `./startup-agent.sh` 启动。

这种方式下，任务直接在宿主机上执行，用的是机器上装好的 JDK、Node.js 等工具。页签提示「NATIVE 流水线不要加 docker 标签」：带了 `docker` 标签的运行器会被当作 Docker 运行器，领不到宿主机任务。

### 一键安装脚本

命令形如：

```bash
curl -fsSL https://git.anguskit.com/runner/install.sh | bash -s -- \
  --url https://git.anguskit.com --token <注册令牌> \
  --name build-linux-01 --labels linux,docker --max-concurrency 4
```

页签提示「从控制面下载 /runner/install.sh，在目标机用 Docker 拉起公开镜像」。效果和 Docker 方式相同，适合不想手动拼 `docker run` 参数的情况。

两种 Docker 方式和 Zip 方式分别适合什么任务，见文末参考里的「Docker 还是宿主机」一文。

## 4. 在构建机上执行，等它上线

把复制的命令粘贴到构建机的终端里执行。然后回到控制台，点 **完成并等待上线**。

页面显示「正在等待 “build-linux-01” 心跳上线…」，每隔几秒检查一次。运行器连上之后，提示「Runner “build-linux-01” 已上线」，列表里出现这台机器，状态是 **在线** 或 **空闲**。

接入成功后，可以到 [CI/CD → 运行器](https://git.anguskit.com/cicd/compute) 对照列表。当前实例已经有两台空闲的运行器：`dev-1` 运行模式 NATIVE，执行器 SHELL，标签 `linux`、`native`、`dev`，并发 0/2；`priv-1` 运行模式 DOCKER，执行器 SHELL，标签 `linux`、`docker`，并发 0/2。按上面命令接入的 `build-linux-01` 也会出现在这张表里，状态是 **空闲**，最近心跳是「刚刚」。

![运行器列表：dev-1 与 priv-1 都是空闲，最近心跳为刚刚](https://developer.qcloudimg.com/http-save/yehe-1099973/8fe2559605e2dc72d9c1a55d28c81dc4.png)

等了 90 秒还没上线，页面会提示「等待心跳超时，请稍后刷新列表确认」。这不一定是失败，运行器可能还在拉镜像。过一两分钟刷新列表；仍然没有，按第 6 节排查。

## 5. 接好之后

上线之后，日常只要盯状态、改标签或暂时停用，一般不用重装。

- **运行器的状态。** 列表里有 **在线**、**空闲**、**忙碌**、**离线**、**已禁用** 几种。运行器每 15 秒发一次心跳；超过 90 秒没有心跳、连接也断了，就会变成 **离线**。
- **改名称、标签和并发。** 在列表里打开 **编辑运行器** 修改，不用重新安装。
- **重装或换机器。** 打开运行器详情的 **安装运行器** 页签，在 **安装 / 重装命令** 里重新生成命令。页面提示「重装到新主机时请重新生成或粘贴注册令牌」，因为原来那把注册令牌已经在第一次接入时用掉了。
- **暂时不用这台机器。** 点 **禁用**，它就不再领取新任务；要恢复时点 **启用**。

私有化部署时，运维也可以在服务端配置一把共享注册令牌（`CICD_RUNNER_REGISTER_TOKEN`），接入时直接粘贴。这把令牌的默认值是 `change-me-runner-register-token`，上线前一定要改掉；否则任何知道默认值、又能访问 AngusGit 的机器，都能把自己注册成运行器来领取任务。

## 6. 接入失败时

| 你看到的 | 原因 | 怎么处理 |
| --- | --- | --- |
| 「等待心跳超时，请稍后刷新列表确认」，刷新后仍没有 | 构建机访问不到 **控制面地址**；或者注册令牌已过期 | 在构建机上 `curl -I <控制面地址>` 检查网络；超过 1 小时的令牌重新生成，再复制一次命令 |
| Docker 方式执行后，容器很快退出 | 令牌不对，或者连不上控制面 | 执行 `docker logs build-linux-01` 看最后几行报错 |
| Docker 方式拉镜像失败 | 构建机访问不到 `repo.anguskit.com` | 让构建机能访问外网，或者把镜像提前导入到内网镜像仓库，再把命令里的镜像地址改成内网地址 |
| Zip 方式 `doctor-native.sh` 报错 | 缺 JDK 21 或其他依赖 | 按它打印的提示补装，再执行 `./startup-agent.sh` |
| 运行器上线了，但任务一直 **等待中** | 任务要求的执行方式或标签和这台运行器对不上 | 看运行详情里任务的等待原因，排查方法见文末参考里的「运行器不接任务」一文 |

运行器进程自己的日志，在运行器详情的 **运行日志** 页签里能看到，页面说明是「Runner 进程日志，包含注册、心跳、接单、拉镜像和步骤执行记录」。旧版本运行器不上报这部分日志时，显示「暂无进程日志（需 Runner 升级到支持上报的版本）」，这时到构建机上看 `/opt/AngusRunnerAgent/logs` 目录。

## 常见问题

**一台机器能装几个运行器？**

通常一个就够了，用 **最大并发 Job 数** 控制同时跑几个任务。需要在同一台机器上同时提供 Docker 和宿主机两种执行方式时，可以装两个：一个用 Docker 方式、带 `docker` 标签，一个用 Zip 方式、不带 `docker` 标签，名称要区分开。

**注册令牌过期了，已经接入的运行器会掉线吗？**

不会。控制台生成的注册令牌是一次性的，只在第一次接入时使用。接入成功后，AngusGit 会给这台运行器下发一把长期身份令牌，运行器把它保存在本机，以后重启、断线重连都用这把。要再接入一台新机器时，重新生成一把注册令牌即可。

**运行器要开放端口吗？**

不需要。是运行器主动连 AngusGit，构建机上不需要对外开放任何端口。

## 小结

运行器是装在构建机上、替 AngusGit 执行流水线任务的程序。在 **CI/CD → 运行器 → 新增 Runner** 里确认构建机能访问的 **控制面地址**，填名称、标签和并发数，点 **生成令牌**，选一种接入方式复制命令，到构建机上执行，再点 **完成并等待上线**。有 Docker 的机器优先用 Docker 方式，要在宿主机上直接构建就用 Zip 方式并装好 JDK 21。私有化部署时，共享注册令牌的默认值必须改掉。

> **结论：** 在 **CI/CD → 运行器 → 新增 Runner** 填好构建机可达的 **控制面地址**、标签并点 **生成令牌**，复制命令到构建机执行后，列表出现 **在线 / 空闲** 状态即接入完成。

## 参考文章

- [AngusGit 手册：运行器管理](https://www.anguskit.com/zh/docs/git/manual/12-runner-management)
- [AngusGit 手册：流水线基础](https://www.anguskit.com/zh/docs/git/manual/10-pipeline-basics)
- [流水线任务在哪跑：Docker 容器还是宿主机](https://www.anguskit.com/zh/blog/pipeline-runner-docker-vs-native)
- [运行器不接任务：标签、在线和并发对不上](https://www.anguskit.com/zh/blog/pipeline-runner-not-picking-up-jobs)

这篇讲流水线 YAML 写好了、任务却没人执行时，怎么把运行器接到构建机上。看完你可以在控制台新增 Runner（装在构建机上、替 AngusGit 执行任务的程序），生成 1 小时有效的注册令牌，按 Docker 或 Zip 把接入命令复制到构建机上执行，并确认它心跳上线。

流水线运行器怎么接到构建机：在那台机器上执行接入命令

流水线要靠运行器（Runner）在构建机上真正执行任务。在控制台新增 Runner、生成注册令牌、按 Docker 或 Zip 方式复制接入命令，到构建机上执行后等它上线；接入失败时，也可以按页面提示和运行器日志对照排查。

运维

开发工具

在CI/CD→运行器→新增Runner，填写构建机可访问的控制面地址并生成一次性注册令牌，选择Docker或Zip方式复制命令，在构建机上执行并等待心跳上线。Docker方式推荐，Zip需装JDK21。接入成功后任务将按标签分发，注意共享令牌默认值需修改。

代码解释

WebSocket

容器

Docker

Linux

Agent

让每一个 Agent，都跑在云上

热销域名限时优惠，新客首年免费！


domain

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

流水线运行器怎么接到构建机：在那台机器上执行接入命令-腾讯云开发者社区-腾讯云

流水线运行器怎么接到构建机：在那台机器上执行接入命令

流水线运行器怎么接到构建机：在那台机器上执行接入命令

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐