真实命令 · 少走弯路·已沉淀 95 篇排障/命令手册，25 份速查表，15 个配置工具进入排障台
LaoHand开发者排障手册
配置生成

cicd Troubleshooting

GitHub Actions Runner 离线排查方法

GitHub Actions 自托管 Runner 显示 offline、job 一直 waiting for runner 时，用 systemctl status actions.runner.* 确认服务状态，查看 ~/actions-runner/_diag 日志中的连接错误，排查 registration token 过期和到 github.com 的网络代理与证书。

先看 actions.runner 服务是否 running，再查 _diag 日志里的连接错误，多半是服务挂了、token 过期或网络连不到 GitHub。

适用环境Jenkins / GitLab CI / GitHub Actions
风险等级低
最后验证2026-07-04
建议权限普通用户 + sudo

2026-07-04 更新·约 3 分钟阅读

Scenario

这篇文章解决什么问题

适用于“GitHub Actions Runner 离线排查方法”对应的线上或本地排障场景。不要只根据最终报错下结论，应先把问题拆成入口、链路、目标服务和资源限制几层，再用命令逐层证实。先看 actions.runner 服务是否 running，再查 _diag 日志里的连接错误，多半是服务挂了、token 过期或网络连不到 GitHub。

Symptoms

典型现象

  • GitHub Actions 自托管 Runner 显示 offline、job 一直 waiting for runner 时，用 systemctl status actions.runner.* 确认服务状态，查看 ~/actions-runner/_diag 日志中的连接错误，排查 registration token 过期和到 github.com 的网络代理与证书。
  • 相关日志、命令或页面中反复出现 github-actions、runner、self-hosted 等关键词。
  • 同一服务在不同机器、不同入口或不同时间段表现不一致，需要通过证据链缩小范围。

Before Debugging

排查前先确认

  • 先确认是流水线配置问题，还是 Runner / 执行环境问题，避免在 YAML 和基础设施之间来回横跳。
  • 保留失败 job 的完整日志、触发上下文、分支和 commit，而不是只看最后几行报错。
  • 区分本地能复现但 CI 不行的问题，重点对比环境、密钥、缓存和网络差异。

Root Causes

常见根因分层

Runner 离线或标签不匹配

job 一直 pending 通常是可用 Runner 不足、标签没匹配上或 Runner 被并发占满，而不是流水线语法错误。

  • 查看 Runner 在线状态和标签
  • 确认 job 声明的 runs-on/tags
  • 看并发队列和 executor 资源

缓存失效或 key 计算错误

缓存 key 用了时间戳或分支变量、路径没覆盖真实依赖目录，会让命中率为零甚至复用错误产物。

  • 用 lockfile hash 做 key
  • 核对 cache path 与真实路径
  • 看 restore 日志是否命中

构建环境差异

Docker socket 没挂载、网络走不了内网、secrets 没注入、镜像架构不一致，都会让 CI 表现和本地不同。

  • 确认 secrets 作用域和变量
  • 检查 docker socket 与网络
  • 对比本地与 CI 镜像架构

Diagnosis Path

分步诊断流程

1. 固定现场，避免追着变化状态跑

先记录故障时间、影响入口、完整错误和最近一次变更。GitHub Actions Runner 离线排查方法 这类问题经常在重启、重试或缓存刷新后短暂消失，没有现场信息会很难复盘。

  • 截图或保存完整错误文本
  • 记录请求域名/IP/端口/namespace/服务名
  • 标出最近发布、配置、证书、镜像或依赖变更
1. 固定现场，避免追着变化状态跑
sudo systemctl status actions.runner.*
sudo journalctl -u actions.runner.<org>.<repo>.<runner> -n 200 --no-pager

2. 在故障发生的同一位置复现

很多误判来自测试位置不同：本机通不代表服务器通，容器内通不代表宿主机通，集群外通也不代表 Pod 内通。复现命令要尽量贴近真实流量路径。

  • 从报错服务所在机器执行测试
  • 必要时加 Host、SNI、namespace 或代理参数
  • 把成功路径和失败路径的输出并排比较
2. 在故障发生的同一位置复现
sudo journalctl -u actions.runner.<org>.<repo>.<runner> -n 200 --no-pager
ls -lh ~/actions-runner/_diag/
gh api repos/:owner/:repo/actions/runners

3. 读取服务端证据，而不是只看客户端提示

客户端报错通常是结果摘要。真正能区分根因的是服务端日志、内核日志、事件、进程状态或数据库状态。

  • 用 systemctl 确认 actions.runner 服务状态，挂掉则重启并看是否自动退出。
  • 查看 _diag 目录下的 Runner 日志，定位连接 GitHub 失败、代理或证书错误。
  • 通过 gh api 确认 Runner 在仓库或组织层面是否还被识别为 online。
3. 读取服务端证据，而不是只看客户端提示
ls -lh ~/actions-runner/_diag/
gh api repos/:owner/:repo/actions/runners
./config.sh --url https://github.com/<org> --token <TOKEN>

4. 做最小修复并立即回归验证

每次只改一个变量，修复后用同一条复现命令回测，并观察日志是否停止增长。这样可以避免多个临时改动互相掩盖。

  • 通过 gh api 确认 Runner 在仓库或组织层面是否还被识别为 online。
  • 检查注册 token 是否过期，过期则重新生成 token 并用 config.sh 重新注册。
  • 排查机器到 github.com 的网络连通性、代理配置和 HTTPS 证书，必要时配置 .env 中的代理。
4. 做最小修复并立即回归验证
gh api repos/:owner/:repo/actions/runners
./config.sh --url https://github.com/<org> --token <TOKEN>

Commands

排查命令与使用意图

命令 1

用于确认服务当前运行状态、退出码和最近日志。重点看 Active 行和 Main PID。

命令 1
sudo systemctl status actions.runner.*

命令 2

用于读取 systemd 或内核在故障时间附近记录的真实错误，比 status 摘要更完整。重点看时间、退出码、权限、路径和依赖失败。

命令 2
sudo journalctl -u actions.runner.<org>.<repo>.<runner> -n 200 --no-pager

命令 3

用于补充“GitHub Actions Runner 离线排查方法”的排查证据链。ls 的输出需要结合上下文其他命令交叉验证，不要单独依赖某一条结果下结论。

命令 3
ls -lh ~/actions-runner/_diag/

命令 4

用于补充“GitHub Actions Runner 离线排查方法”的排查证据链。gh 的输出需要结合上下文其他命令交叉验证，不要单独依赖某一条结果下结论。

命令 4
gh api repos/:owner/:repo/actions/runners

命令 5

用于确认 Git/SSH 的最终配置和认证链路。注意输出中可能包含仓库地址、用户名或代理信息，分享前应脱敏。

命令 5
./config.sh --url https://github.com/<org> --token <TOKEN>

Risk Notes

容易踩坑的地方

  • 不要在日志里打印 secrets 或 token，CI 日志常被长期留存，泄露后难以追溯。
  • 不要用 latest tag 做缓存 key，会导致产物不可复现甚至复用错误缓存。
  • 不要在流水线中执行不安全的 shell 命令或从不可信源下载脚本。

Verification

修复后怎么确认

  • 原始故障现象已经消失，且使用同一入口重新测试 GitHub Actions Runner 离线 能稳定成功。
  • 服务端日志不再出现同类错误，监控中的错误率、重启次数、连接数或延迟回到正常区间。
  • 如果做过临时绕过，已经记录恢复计划，例如还原宽松策略、补监控、补限制或提交正式配置。

Prevention

后续预防

  • 把 secrets 和环境变量在流水线里显式声明，避免依赖运行时隐式注入导致不一致。
  • 为关键 job 加超时上限，防止卡死占用 Runner 影响其他流水线执行。
  • 缓存 key 统一用 lockfile hash，不要用 latest tag 或时间变量，确保缓存可复现。
  • 在流水线中增加构建产物验证步骤，如类型检查、lint 和测试，尽早发现质量问题。

常见问题

Runner 注册后一直 offline 怎么办？

通常是服务没启动或网络不通，先 systemctl status 和 _diag 日志，再确认机器能访问 github.com 且没有代理拦截。

registration token 多久过期？

注册 token 有效期较短（约 1 小时），过期后需要在 GitHub 设置页重新生成再用 config.sh 注册。

Long-tail SEO

你可能正在搜索这些报错

下面这些错误原文、场景词和中英文搜索词，都是排查同类问题时常见的入口。

  • GitHub Actions runner offline
  • self-hosted runner 离线
  • GitHub Actions job waiting for runner
  • 自托管 runner 不在线
  • actions.runner 服务状态
  • runner 连不上 github
  • github runner token 过期
  • runner _diag 日志查看

Related

相关排障 / 命令 / 工具

按分类和标签关联的排障流程、命令模板和配置工具，方便顺着同一个问题继续往下查。

速查

CI/CD 常用命令速查表

GitHub Actions、GitLab CI 和 Jenkins 三大 CI/CD 流水线一页速查：gh run/rerun/cancel 调试、gitlab-runner list/verify 与 CI Lint、jenkins-cli 构建日志、Runner 在线状态与缓存磁盘排查，覆盖 job 卡顿和构建失败主路径。

cicd命令

CI/CD 常用排障命令

CI/CD 排障常用命令合集，Jenkins 用 jenkins-cli 与 queue/computer API 查队列和 executor，GitLab 用 gitlab-runner verify/list 检查 Runner，GitHub Actions 用 gh run list、gh run view --log-failed、gh cache 定位失败步骤和缓存。

cicd排障

CI 缓存失效排查方法

CI 缓存不命中、每次构建都从零安装依赖时，先对比 restore/save 步骤打印的 cache key 是否变化，再检查缓存路径配置、runner OS 前缀和 gh cache list 中的实际条目，常见根因是 key 把易变内容算入或 restore-keys 顺序不对。

cicd排障

GitLab CI 流水线失败排查方法

GitLab CI 流水线失败、job 报错或 pending 不执行时，用 gitlab-runner verify 测试 Runner 与 GitLab 连接，检查 Runner tags 是否匹配 job、executor 类型（shell/docker/kubernetes）配置和 registration token，再用 journalctl 看 gitlab-runner 服务日志定位脚本或镜像问题。

cicd排障

CI 中 Docker 构建失败排查方法

CI 流水线 docker build 报错、层缓存失效或 permission denied 时，用 --progress=plain --no-cache 输出完整构建日志，检查 docker.sock 权限、buildx builder 和 Dockerfile 指令顺序，常见根因是 socket 无权限、上下文频繁变化或缓存未持久化。

cicd排障

Jenkins 构建卡住排查方法

Jenkins 构建卡在队列不动或执行中挂起时，用 queue/api/json 查看队列 why 阻塞原因，computer/api/json 检查 executor 是否 offline，卡死用 jstack 抓 Jenkins 主线程转储，多数是节点掉线、标签不匹配或 Quiet Period 延迟。

cicd