这篇讲流水线 YAML 写好了、任务却没人执行时，怎么把运行器接到构建机上。看完你可以在控制台新增 Runner（装在构建机上、替 AngusGit 执行任务的程序），生成 1 小时有效的注册令牌，按 Docker 或 Zip 把接入命令复制到构建机上执行，并确认它心跳上线。
流水线和运行器在团队版和企业版中提供；社区版没有 CI/CD 菜单，本文的操作不适用。
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. 在控制台新增运行器
打开接入页
侧栏进入 CI/CD → 运行器，点右上角 新增 Runner，页面切到 接入新 Runner。
确认控制面地址
控制面地址 默认取当前浏览器打开的站点地址。页面提示「若 Runner 所在网络访问不到，请改为控制面对外可达的 URL」。例如你在办公网用域名访问 AngusGit，而构建机在机房只能用内网 IP 访问，这里就要改成构建机能访问的那个地址。
填名称和标签
Runner 名称（可选） 写清是哪台机器，例如
build-linux-01。标签（可选） 用逗号分隔，例如linux,docker。流水线里的任务会按标签挑运行器，这里的标签要和任务里写的对得上。不确定时先留空，用每种接入方式的默认标签。最大并发 Job 数 是这台机器同时最多跑几个任务（Job 就是流水线里的一组步骤），默认 4，可填 1 到 64，按机器的 CPU 和内存决定。生成注册令牌
点 注册令牌 旁的 生成令牌。页面提示「已签发短期注册令牌（明文仅显示一次）」，下方显示「令牌有效期至 …」，有效期 1 小时。令牌会自动填进下面的命令里。没有令牌时点 复制命令，会提示「请先生成或粘贴注册令牌后再复制命令」。
下面这张是还没点 生成令牌 时的页面。控制面地址是 https://git.anguskit.com，名称 build-linux-01，标签 linux,docker，最大并发 Job 数 4。黄色提示是「尚未填写令牌」，复制命令 是灰的。三个页签是 Zip 安装、Docker 一键拉起、一键安装脚本，默认停在 Docker 一键拉起。页签上没有「推荐」两个字，推荐用 Docker 是本文的建议。
3. 选一种接入方式，复制命令
三个页签生成的命令，都已经带上了你填的地址、名称、标签、并发数和令牌。
Docker 一键拉起（推荐）
页签提示「从 AngusRepo 公开仓库拉取 repo.anguskit.com/docker-public/angus-runner-agent」。命令形如：
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 运行器，领不到宿主机任务。
一键安装脚本
命令形如：
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 → 运行器 对照列表。当前实例已经有两台空闲的运行器：dev-1 运行模式 NATIVE，执行器 SHELL，标签 linux、native、dev，并发 0/2；priv-1 运行模式 DOCKER，执行器 SHELL，标签 linux、docker，并发 0/2。按上面命令接入的 build-linux-01 也会出现在这张表里，状态是 空闲，最近心跳是「刚刚」。
等了 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 填好构建机可达的 控制面地址、标签并点 生成令牌，复制命令到构建机执行后，列表出现 在线 / 空闲 状态即接入完成。
