CI/CD / 系统课时
处理 Runner 离线与任务排队
处理 Runner 离线与任务排队
自托管作业长时间停在 Queued,并不一定是 GitHub Actions 故障。Runner 离线、标签不匹配、网络中断或所有执行槽都被占用,都会产生相似现象。本节建立从工作流匹配到 Runner 服务和容量的排查顺序。
学习目标
- 区分 Runner 离线、标签不匹配和容量不足导致的排队
- 使用服务状态与 Runner 诊断信息定位连接问题
- 通过标签和容量检查验证修复结果
先确认任务能否匹配 Runner
排查 Queued 时先查看作业的 runs-on。自托管 Runner 必须满足作业声明的全部标签;例如下面的任务要求 Runner 同时匹配 self-hosted、linux 和 build。
jobs:
build:
runs-on: [self-hosted, linux, build]
steps:
- uses: actions/checkout@v4
- run: echo "runner is available"预期输出
runner is available只有任务真正获得匹配 Runner 后才会出现这段输出。如果 Runner 在线但缺少 build 标签,作业仍会排队,因此“机器在线”不能证明路由配置正确。

检查 Runner 服务是否真正运行
如果仓库或组织的 Runner 页面显示目标 Runner 为 Offline,应进入 Runner 主机检查服务。通过官方 Runner 脚本安装为 Linux 服务时,可以先在 Runner 安装目录执行状态检查。
cd <RUNNER_DIR>
sudo ./svc.sh status预期结果
<service status showing the runner service is running>不同 Linux 发行版和 Runner 版本的服务名称、状态文本可能不同,因此不要依赖固定的一行输出。若服务未运行,可执行 sudo ./svc.sh start,随后再次检查状态,并观察 GitHub 中 Runner 是否恢复 Online。
如果 Runner 不是通过 svc.sh 安装为服务,而是手动运行 ./run.sh,则应检查启动该进程的实际进程管理方式,不能假定系统中一定存在对应服务。
在线仍排队时检查容量
Runner 显示 Online 只说明它保持着与 GitHub 的连接,不代表当前有能力立即接收新作业。单个 Runner 同一时间只执行一个作业;当所有匹配 Runner 都处于 Busy 状态时,新作业只能等待空闲容量。
可以先把排队任务分成两类:如果始终没有任何匹配 Runner,重点检查标签和 Runner 组访问范围;如果任务最终会启动但高峰期等待明显增长,重点检查并发容量。后者通常需要增加独立 Runner,而不是在同一个 Runner 进程上反复重启服务。
检查到 GitHub 的网络路径
服务正在运行却持续 Offline 时,应继续检查 DNS、代理、防火墙和出站连接。Runner 需要主动连接 GitHub 服务,因此只检查主机是否能被外部访问没有意义。
可先做一个基础 HTTPS 连通性检查:
curl -I https://github.com预期结果
HTTP/<VERSION> <STATUS><VERSION> 和 <STATUS> 会因协议协商、网络环境和响应行为而不同。这里的目标是确认 DNS 解析、TLS 建连和 HTTPS 出站链路能够工作;它不能单独证明 Runner 所需的所有 GitHub 服务端点都可访问。
如果环境通过企业代理访问互联网,还要确认 Runner 服务进程实际继承了正确的代理配置。交互式终端中的 curl 成功,而后台 Runner 服务仍无法联网,往往说明两者使用的环境变量或系统代理配置并不相同。
按顺序验证修复
完成修复后,不要只看服务命令返回成功。先确认目标 Runner 在 GitHub 中显示 Online,再确认它具有工作流要求的全部标签,并确保至少一个匹配 Runner 处于空闲状态。最后重新运行一个最小作业,观察它是否从 Queued 进入执行并产生预期输出。
如果 Runner 能稳定上线但高峰期仍大量排队,问题已经从“故障”转为“容量规划”:统计同时处于运行状态的匹配作业数量,再决定增加固定 Runner 还是采用按任务创建的一次性 Runner。这样可以避免把标签错误、网络故障和容量不足混成同一个问题处理。