监视自托管运行器并排查故障

0380

可以监控自托管运行器，查看其活动并诊断常见问题。

检查访问级别

你可能无法为组织拥有的仓库创建自托管运行器。组织所有者可以选择允许哪些仓库创建仓库级自托管运行器，参见禁用或限制组织的 GitHub Actions。

检查运行器状态

自托管运行器位于仓库、组织或企业账户的设置中。管理它们所需权限取决于添加位置：用户仓库要求仓库所有者；组织要求组织所有者；组织仓库要求组织所有者或该仓库的管理员权限。

在组织或仓库主页进入 Settings → Actions → Runners，即可查看注册运行器的名称、标签与状态。

  • Idle（空闲）：已连接 GitHub，准备好执行作业。
  • Active（活动）：正在执行作业。
  • Offline（离线）：未连接 GitHub。可能是计算机离线、运行器应用未运行，或应用无法与 GitHub 通信。

排查网络连接

检查运行器的网络连接

使用运行器应用的 config 脚本和 --check 参数，检查它是否可访问所有必需的 GitHub 网络服务。除 --check 外，还必须提供：

  • --url：仓库、组织或企业的 URL，例如 https://github.com/octo-org/octo-repo。
  • --pat：具有 workflow 范围的 personal access token (classic)，或者具有工作流读写权限的 fine-grained personal access token。原文使用 ghp_abcd1234 作为示例占位值。参见管理个人访问令牌。

macOS／Linux：

./config.sh --check --url URL --pat ghp_abcd1234

Windows：

config.cmd --check --url https://github.com/YOUR-ORG/YOUR-REPO --pat GHP_ABCD1234

脚本逐项测试服务并输出 PASS 或 FAIL。失败检查的详细日志位于安装目录的 _diag 中，控制台会显示每个检查的日志路径。还应核实计算机满足全部运行器通信要求。

禁用 TLS 证书验证

运行器应用默认验证 GitHub 的 TLS 证书。遇到网络问题时，可为了测试而暂时禁用验证。GitHub Enterprise Server 使用自签名或内部签发证书时，也可能需要这种测试。

配置并运行应用前，将 GITHUB_ACTIONS_RUNNER_TLS_NO_VERIFY 设为 1。

Linux／macOS：

export GITHUB_ACTIONS_RUNNER_TLS_NO_VERIFY=1
./config.sh --url https://github.com/YOUR-ORG/YOUR-REPO --token
./run.sh

Windows：

[Environment]::SetEnvironmentVariable('GITHUB_ACTIONS_RUNNER_TLS_NO_VERIFY', '1')
./config.cmd --url https://github.com/YOUR-ORG/YOUR-REPO --token
./run.cmd

原文警告：不建议禁用 TLS 验证。 TLS 保障运行器与 GitHub 之间的隐私和数据完整性。建议把 GitHub 证书安装到运行器操作系统的证书存储中；安装方法请咨询操作系统厂商。采用 Azure 私有网络的大型 GitHub 托管运行器应参阅私有网络前提条件中的 TLS 拦截要求。

查阅运行器应用日志

应用状态和活动的日志保存在安装目录的 _diag 下。每次应用启动都会生成新日志，文件名以 Runner_ 开头，后接启动时的 UTC 时间戳。

临时运行器的应用日志必须转发到外部并保留，供故障排查和诊断使用。 参见用于自动扩缩容的临时运行器。

工作流作业的详细执行日志见下面的 Worker_ 文件。

查阅作业日志

运行器为每个处理过的作业生成详细日志，同样保存在 _diag，文件名以 Worker_ 开头。

Linux：使用 journalctl 检查服务

应用以服务运行时，可用 journalctl 监控实时活动。默认 systemd 服务名为 actions.runner.<org>-<repo>.<runnerName>.service；超过 80 个字符会被截断，因此最好查看 .service 文件确定名称：

$ cat ~/actions-runner/.service
actions.runner.octo-org-octo-repo.runner01.service

如果服务安装在其他位置而读取失败，可以从运行中的服务列表查找。大多数 Linux 系统可运行：

$ systemctl --type=service | grep actions.runner
actions.runner.octo-org-octo-repo.hostname.service loaded active running GitHub Actions Runner (octo-org-octo-repo.hostname)

实时监控：

sudo journalctl -u actions.runner.octo-org-octo-repo.runner01.service -f

原文示例输出依次显示 runner01 启动、接收 testAction 作业及最终状态：

Feb 11 14:57:07 runner01 runsvc.sh[962]: Starting Runner listener with startup type: service
Feb 11 14:57:07 runner01 runsvc.sh[962]: Started listener process
Feb 11 14:57:07 runner01 runsvc.sh[962]: Started running service
Feb 11 14:57:16 runner01 runsvc.sh[962]: √ Connected to GitHub
Feb 11 14:57:17 runner01 runsvc.sh[962]: 2020-02-11 14:57:17Z: Listening for Jobs
Feb 11 16:06:54 runner01 runsvc.sh[962]: 2020-02-11 16:06:54Z: Running job: testAction
Feb 11 16:07:10 runner01 runsvc.sh[962]: 2020-02-11 16:07:10Z: Job testAction completed with result: Succeeded

systemd 配置文件位于 /etc/systemd/system/actions.runner.<org>-<repo>.<runnerName>.service。不要直接修改该文件来定制服务，应遵循定制自托管运行器服务的说明。

macOS：使用 launchd 检查服务

应用以服务运行时，可用 launchctl 监控实时活动。默认 launchd 服务名为 actions.runner.<org>-<repo>.<runnerName>；超过 80 个字符会被截断，最好查看运行器目录的 .service 文件：

% cat ~/actions-runner/.service
/Users/exampleUsername/Library/LaunchAgents/actions.runner.octo-org-octo-repo.runner01.plist

svc.sh 脚本使用 launchctl 检查应用是否运行：

$ ./svc.sh status
status actions.runner.example.runner01:
/Users/exampleUsername/Library/LaunchAgents/actions.runner.example.runner01.plist
Started:
379 0 actions.runner.example.runner01

输出包含进程 ID 和应用的 launchd 服务名。launchd 配置路径应以 .service 文件中的实际值为准；上面的示例指向 ~/Library/LaunchAgents/ 下的 .plist 文件。若要定制服务，不应直接修改该文件，应遵循上述定制服务文档。

Windows：使用 PowerShell 检查服务

以服务运行时，可用 PowerShell 监控实时活动。服务名称遵循 GitHub Actions Runner (<org>-<repo>.<runnerName>) 形式，也可以查看运行器目录的 .service：

PS C:\actions-runner> Get-Content .service
actions.runner.octo-org-octo-repo.runner01.service

可在 Windows 服务应用（services.msc）查看状态，或运行：

PS C:\actions-runner> Get-Service "actions.runner.octo-org-octo-repo.runner01.service" | Select-Object Name, Status
Name                                                  Status
----                                                  ------
actions.runner.octo-org-octo-repo.runner01.service    Running

以下原文示例使用事件日志显示启动、接收 testAction 和最终状态：

PS C:\actions-runner> Get-EventLog -LogName Application -Source ActionsRunnerService
   Index Time          EntryType   Source                 InstanceID Message
   ----- ----          ---------   ------                 ---------- -------
     136 Mar 17 13:45  Information ActionsRunnerService          100 2020-03-17 13:45:48Z: Job Greeting completed with result: Succeeded
     135 Mar 17 13:45  Information ActionsRunnerService          100 2020-03-17 13:45:34Z: Running job: testAction
     134 Mar 17 13:41  Information ActionsRunnerService          100 2020-03-17 13:41:54Z: Listening for Jobs
     133 Mar 17 13:41  Information ActionsRunnerService          100 û Connected to GitHub
     132 Mar 17 13:41  Information ActionsRunnerService            0 Service started successfully.
     131 Mar 17 13:41  Information ActionsRunnerService          100 Starting Actions Runner listener
     130 Mar 17 13:41  Information ActionsRunnerService          100 Starting Actions Runner Service
     129 Mar 17 13:41  Information ActionsRunnerService          100 create event log trace source for actions-runner service

监控自动更新

建议定期检查自动更新过程。运行器版本低于某个阈值后，可能无法处理作业。应用会自动更新自身，但不会更新操作系统或其他软件，这些需分别管理。

在 Runner_ 日志里可查看更新活动：

[Feb 12 12:37:07 INFO SelfUpdater] An update is available.

安装目录 _diag 中的 SelfUpdate 日志包含更多信息。

排查运行器中的容器问题

检查 Docker 是否已安装

需要容器的作业要求运行器基于 Linux 并安装 Docker。检查 Docker 是否安装以及服务是否运行：

$ sudo systemctl is-active docker.service
active

未安装 Docker 时，依赖它的操作会报错：

[2020-02-13 16:56:10Z INFO DockerCommandManager] Which: 'docker'
[2020-02-13 16:56:10Z INFO DockerCommandManager] Not found.
[2020-02-13 16:56:10Z ERR  StepsRunner] Caught exception from step: System.IO.FileNotFoundException: File not found: 'docker'

检查 Docker 权限

若作业失败并出现：

dial unix /var/run/docker.sock: connect: permission denied

检查运行器的服务账户是否有权限使用 Docker。可从 systemd 配置确认账户：

$ sudo systemctl show -p User actions.runner.octo-org-octo-repo.runner01.service
User=runner-user

检查已安装的 Docker 引擎

若构建失败并出现：

Error: Input required and not supplied: java-version

检查运行器上的 Docker 引擎。为把操作输入传给容器，环境变量名可能包含短划线。如果 Docker 引擎是 shell 包装器或链接，而非二进制可执行文件（例如 Linux 上通过 snap 安装），操作可能读不到输入。应将运行器配置为使用其他 Docker 引擎。

用 which 检查是否由 snap 安装：

$ which docker
/snap/bin/docker

原文：GitHub 文档：对自托管运行程序进行监视和故障排除。Copyright © GitHub, Inc. 与文档贡献者。本文整理了官方中文措辞与跨平台示例，代码和示例输出保持原文；launchd 配置路径的说明已按页面中的实际示例订正。文档采用 CC BY 4.0，参见仓库许可。

© 版权声明
文章版权归作者所有，未经允许请勿转载。
THE END
技术译文
喜欢就支持一下吧
点赞0 分享
彩雨伞的头像-未完纪钻石会员
Self-introduction-未完纪
Self-introduction
Self-introduction
7天前 72
使用宝塔为 AList 配置反向代理与 HTTPS-未完纪
使用宝塔为 AList 配置反向代理与 HTTPS
使用宝塔为 AList 配置反向代理与 HTTPS
昨天 59
WordPress 接入 Microsoft Clarity Cookie 同意与偏好设置-未完纪
WordPress 接入 Microsoft Clarity Cookie 同意与偏好设置
WordPress 接入 Microsoft Clarity Cookie 同意与偏好设置
昨天 56
注册区块变体，同时在插入器中隐藏它-未完纪
注册区块变体，同时在插入器中隐藏它
注册区块变体，同时在插入器中隐藏它
23小时前 56
从用户序列到扩展规律：Meta 广告排序的多阶段架构-未完纪
从用户序列到扩展规律：Meta 广告排序的多阶段架构
从用户序列到扩展规律：Meta 广告排序的多阶段架构
14小时前 55
Windows快速部署OpenClaw + Qwen3.5 Plus完整教程-未完纪
Windows快速部署OpenClaw + Qwen3.5 Plus完整教程
Windows快速部署OpenClaw + Qwen3.5 Plus完整教程
前天 55
相关推荐
注册区块变体，同时在插入器中隐藏它-未完纪
注册区块变体，同时在插入器中隐藏它
注册区块变体，同时在插入器中隐藏它
23小时前 56
从用户序列到扩展规律：Meta 广告排序的多阶段架构-未完纪
从用户序列到扩展规律：Meta 广告排序的多阶段架构
从用户序列到扩展规律：Meta 广告排序的多阶段架构
14小时前 55
用 Ansible 定制 Loki 部署-未完纪
用 Ansible 定制 Loki 部署
用 Ansible 定制 Loki 部署
19小时前 54
用维度表加速字符串聚合-未完纪
用维度表加速字符串聚合
用维度表加速字符串聚合
昨天 54
用内部审计器测试数百个网页的 Cookie 行为-未完纪
用内部审计器测试数百个网页的 Cookie 行为
用内部审计器测试数百个网页的 Cookie 行为
22小时前 54
Loki 简明指南：处理乱序日志与旧日志-未完纪
Loki 简明指南：处理乱序日志与旧日志
Loki 简明指南：处理乱序日志与旧日志
昨天 53
评论 抢沙发

请登录后发表评论

    暂无评论内容