排查 Actions Runner Controller 的错误

了解如何排查 Actions Runner Controller（ARC）的错误。

日志记录

ARC 的资源，包括控制器、侦听器和运行器，都会将日志写入标准输出（stdout）。GitHub 建议部署日志解决方案来收集和存储这些日志。保留日志有助于你或 GitHub 支持团队进行故障排查与调试。更多信息参见 Kubernetes 文档中的日志架构。

资源标签

ARC 会为创建的资源添加标签，包括控制器、侦听器和运行器 Pod。可以使用这些标签筛选资源，辅助故障排查。

控制器 Pod

以下标签适用于控制器 Pod。

app.kubernetes.io/component=controller-manager
app.kubernetes.io/instance=<controller installation name>
app.kubernetes.io/name=gha-runner-scale-set-controller
app.kubernetes.io/part-of=gha-runner-scale-set-controller
app.kubernetes.io/version=<chart version>

侦听器 Pod

以下标签适用于侦听器 Pod。

actions.github.com/enterprise= # Will be populated if githubConfigUrl is an enterprise URL
actions.github.com/organization= # Will be populated if githubConfigUrl is an organization URL
actions.github.com/repository= # Will be populated if githubConfigUrl is a repository URL
actions.github.com/scale-set-name= # Runners scale set name
actions.github.com/scale-set-namespace= # Runners namespace
app.kubernetes.io/component=runner-scale-set-listener
app.kubernetes.io/part-of=gha-runner-scale-set
app.kubernetes.io/version= # Chart version

运行器 Pod

以下标签适用于运行器 Pod。

actions-ephemeral-runner= # True | False
actions.github.com/organization= # Will be populated if githubConfigUrl is an organization URL
actions.github.com/scale-set-name= # Runners scale set name
actions.github.com/scale-set-namespace= # Runners namespace
app.kubernetes.io/component=runner
app.kubernetes.io/part-of=gha-runner-scale-set
app.kubernetes.io/version= # Chart version

查看控制器和运行器集侦听器的日志

使用以下命令查看控制器 Pod 的日志。

kubectl logs -n <CONTROLLER_NAMESPACE> -l app.kubernetes.io/name=gha-runner-scale-set-controller

使用以下命令查看运行器集侦听器的日志。

kubectl logs -n <CONTROLLER_NAMESPACE> -l auto-scaling-runner-set-namespace=arc-systems -l auto-scaling-runner-set-name=arc-runner-set

使用 `master` 分支中的 Helm chart

GitHub 建议使用最新发布版本，而不是 master 分支中的 Helm chart。master 分支高度不稳定，GitHub 无法保证其中的 chart 在任何时刻都能正常工作。

排查侦听器 Pod 的故障

如果控制器 Pod 正在运行，但侦听器 Pod 没有运行，请先检查控制器日志是否存在错误。如果没有错误，而运行器集侦听器 Pod 仍未运行，请确保控制器 Pod 能够访问集群中的 Kubernetes API 服务器。

如果配置了代理，或者使用自动注入的边车代理，例如 Istio，请确保其配置允许流量从控制器容器（manager）到达 Kubernetes API 服务器。

如果已经安装自动缩放运行器集，却没有创建侦听器 Pod，请检查所提供的 githubConfigSecret 是否正确，以及 githubConfigUrl 是否准确。更多信息参见将 ARC 认证到 GitHub API和使用 Actions Runner Controller 部署运行器规模集。

取消工作流运行后，运行器 Pod 被重新创建

取消工作流运行后，会发生以下事件：

取消信号直接发送给运行器。
运行器应用程序终止，同时导致运行器 Pod 终止。
侦听器在下一次轮询时收到取消信号。

运行器收到信号和侦听器收到信号之间可能存在短暂延迟。当运行器 Pod 开始终止时，侦听器会依据自己当时掌握的状态，尝试启动新的运行器，以达到期望的运行器数量。当侦听器收到取消信号后，它会减少运行器数量，并最终缩减至期望数量。在此期间，你可能会看到额外的运行器。

错误：`Name must have up to n characters`

ARC 会将某些资源生成的名称用作其他资源的标签，因此资源名称最多允许 63 个字符。

资源名称的一部分由用户定义，所以 ARC 对安装名称和命名空间可使用的字符数施加了限制。

Error: INSTALLATION FAILED: execution error at (gha-runner-scale-set/templates/autoscalingrunnerset.yaml:5:5): Name must have up to 45 characters

Error: INSTALLATION FAILED: execution error at (gha-runner-scale-set/templates/autoscalingrunnerset.yaml:8:5): Namespace must have up to 63 characters

错误：`Access to the path /home/runner/_work/_tool is denied`

在 Kubernetes 模式下使用持久卷时，可能会遇到此错误。其原因是运行器容器以非 root 用户运行，而该用户的权限与挂载卷的权限不匹配。

可以选择以下一种方法解决问题：

使用支持 securityContext.fsGroup 的卷类型。hostPath 卷不支持此属性，local 卷和其他某些类型的卷支持。将运行器 Pod 的 fsGroup 更新为运行器的 GID。可以在 gha-runner-scale-set Helm chart 的 values 中添加以下内容。将 VERSION 替换为所需的 actions-runner 容器镜像版本。

template:
  spec:
    securityContext:
      fsGroup: 123
    containers:
      - name: runner
        image: ghcr.io/actions/actions-runner:latest
        command: ["/home/runner/run.sh"]

如果无法通过更新运行器 Pod 的 securityContext 解决问题，可以使用 initContainers 修改已挂载卷的所有者，如下所示。

template:
  spec:
    initContainers:
      - name: kube-init
        image: ghcr.io/actions/actions-runner:latest
        command: ["sudo", "chown", "-R", "1001:123", "/home/runner/_work"]
    volumeMounts:
      - name: work
        mountPath: /home/runner/_work
    containers:
      - name: runner
        image: ghcr.io/actions/actions-runner:latest
        command: ["/home/runner/run.sh"]

错误：`failed to get access token for GitHub App auth: 401 Unauthorized`

尝试获取 GitHub App 访问令牌时出现 401 Unauthorized，可能由网络时间协议（NTP）时钟偏移引起。请确保 Kubernetes 系统与 NTP 服务器准确同步，没有明显的时间偏差。系统时间落后于 GitHub 时，容许的偏差较大；如果环境时间领先几秒以上，使用 GitHub App 时就会发生 401 错误。

运行器组限制

每个运行器组最多可以包含 10,000 个自托管运行器。达到此上限后，将无法添加新的运行器。

运行器更新

请检查运行器软件和／或自定义运行器镜像，确保其使用最新版本。

更多信息参见自托管运行器参考。

法律通告

本文部分内容改编自采用 Apache-2.0 许可证的 actions/actions-runner-controller 项目：

Copyright 2019 Moto Ishizawa

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Apache License 2.0 许可文本

来源与许可

原文：排查 Actions Runner Controller 的错误。原作者：GitHub Docs 及其贡献者；版权归 GitHub, Inc. 及相关权利人所有。中文校订整理：未完纪。依据 2026 年 10 月 3 日读取的官方中文页面整理。

本版统一了中文术语、标点和排版，并将文章链接整理为绝对 HTTPS 地址；命令、配置、占位符与原文法律声明保持原意及原有实现。官方中文页面注明部分内容可能经过机器或 AI 翻译，本版保留这一来源说明。

GitHub Docs 官方仓库声明：文档及 assets、content、data 目录内容采用 Creative Commons Attribution 4.0 International（CC BY 4.0），代码采用 MIT License。本中文整理版按 CC BY 4.0 提供。材料按许可证以现状提供，不附保证；此整理版不代表 GitHub 官方认可。

原文对改编自 Actions Runner Controller 的部分另有 Apache-2.0 通告，已在“法律通告”一节完整保留；该通告不被上述通用代码许可说明替代。

MIT 代码许可声明

MIT License

Copyright 2026 GitHub

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.