CI/CD / 系统课时

处理 Runner 离线与任务排队

处理 Runner 离线与任务排队

自托管作业长时间停在 Queued,并不一定是 GitHub Actions 故障。Runner 离线、标签不匹配、网络中断或所有执行槽都被占用,都会产生相似现象。本节建立从工作流匹配到 Runner 服务和容量的排查顺序。

学习目标

  • 区分 Runner 离线、标签不匹配和容量不足导致的排队
  • 使用服务状态与 Runner 诊断信息定位连接问题
  • 通过标签和容量检查验证修复结果

先确认任务能否匹配 Runner

排查 Queued 时先查看作业的 runs-on。自托管 Runner 必须满足作业声明的全部标签;例如下面的任务要求 Runner 同时匹配 self-hosted、linux 和 build。

yaml
jobs:
  build:
    runs-on: [self-hosted, linux, build]
    steps:
      - uses: actions/checkout@v4
      - run: echo "runner is available"

预期输出

text
runner is available

只有任务真正获得匹配 Runner 后才会出现这段输出。如果 Runner 在线但缺少 build 标签,作业仍会排队,因此“机器在线”不能证明路由配置正确。

自托管 Runner 排队故障定位流程

检查 Runner 服务是否真正运行

如果仓库或组织的 Runner 页面显示目标 Runner 为 Offline,应进入 Runner 主机检查服务。通过官方 Runner 脚本安装为 Linux 服务时,可以先在 Runner 安装目录执行状态检查。

bash
cd <RUNNER_DIR>
sudo ./svc.sh status

预期结果

text
<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 连通性检查:

bash
curl -I https://github.com

预期结果

text
HTTP/<VERSION> <STATUS>

<VERSION> 和 <STATUS> 会因协议协商、网络环境和响应行为而不同。这里的目标是确认 DNS 解析、TLS 建连和 HTTPS 出站链路能够工作;它不能单独证明 Runner 所需的所有 GitHub 服务端点都可访问。

如果环境通过企业代理访问互联网,还要确认 Runner 服务进程实际继承了正确的代理配置。交互式终端中的 curl 成功,而后台 Runner 服务仍无法联网,往往说明两者使用的环境变量或系统代理配置并不相同。

按顺序验证修复

完成修复后,不要只看服务命令返回成功。先确认目标 Runner 在 GitHub 中显示 Online,再确认它具有工作流要求的全部标签,并确保至少一个匹配 Runner 处于空闲状态。最后重新运行一个最小作业,观察它是否从 Queued 进入执行并产生预期输出。

如果 Runner 能稳定上线但高峰期仍大量排队,问题已经从“故障”转为“容量规划”:统计同时处于运行状态的匹配作业数量,再决定增加固定 Runner 还是采用按任务创建的一次性 Runner。这样可以避免把标签错误、网络故障和容量不足混成同一个问题处理。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

处理 Runner 离线与任务排队

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通