# 自托管运行程序参考 查找有关设置和使用自托管运行器的信息。 ## 自托管运行器机器的要求 只要符合以下要求，便可将计算机用作自托管运行程序： * 你可以在机器上安装和运行自托管运行器应用程序。 请参阅[支持的操作系统](#supported-operating-systems)和[支持的处理器体系结构](#supported-processor-architectures)。 * 机器可以与GitHub Actions通信。 * 机器有足够的硬件资源来执行你计划运行的工作流程类型。 自托管运行器应用程序本身只需要很少的资源。 * 如果你想运行使用 Docker 容器操作或服务容器的工作流程，你必须使用 Linux 机器并安装 Docker。 ### 受支持的操作系统 #### Linux * Red Hat Enterprise Linux 8 或更高版本 * CentOS 8 或更高版本 * Oracle Linux 8 或更高版本 * Fedora 29 或更高版本 * Debian 10 或更高版本 * Ubuntu 20.04 或更高版本 * Linux Mint 20 或更高版本 * openSUSE 15.2 或更高版本 * SUSE Enterprise Linux (SLES) 15 SP2 或更高版本 #### Windows * Windows 10 64 位 * Windows 11 64 位 * Windows Server 2016 64 位 * Windows Server 2019 64 位 * Windows Server 2022 64 位 #### macOS * macOS 11.0 (Big Sur) 或更高版本 ### 支持的处理器体系结构 * `x64` - Linux、macOS、Windows。 * `ARM64` - Linux、macOS。 * `ARM32` - Linux。 ## 自托管运行器的路由优先级 将作业路由到自托管运行器时，GitHub 会查找与作业的 `runs-on` 标签和组匹配的运行器： * 如果 GitHub 找到一个在线且空闲的运行器，且该运行器与作业的 `runs-on` 标签和组匹配，则该作业将被分配并发送至该运行器。 * 如果运行器在 60 秒内未接受分配的任务，任务将被重新排队，以便新的运行器能够接受任务。 * 如果 GitHub 找不到与该作业的 `runs-on` 标签和组匹配的在线且空闲的运行器，则该作业将保持排队状态，直到有运行器上线。 * 如果作业排队的时间超过 24 小时，则作业将失败。 ## 自动缩放 自动缩放允许你根据需求动态调整自托管运行器的数量。 这有助于优化资源利用率，并确保在高峰时段有足够的运行程序容量，同时在低活动期间降低成本。 有多种方法可实现自托管运行器的自动缩放，每种方法在复杂性、可靠性和响应性方面都有不同的权衡。 ### Actions Runner Controller Actions Runner Controller (ARC) 是 GitHub 规模集 API 的参考实现，也是用于对自托管运行器进行自动缩放的推荐 Kubernetes 解决方案。 ARC 为在 Kubernetes 环境中运行 GitHub Actions 的团队提供了一套完整的、可用于生产环境的自动缩放解决方案。 GitHub 建议拥有 Kubernetes 基础架构且团队具备 Kubernetes 专业知识的组织使用 ARC。 ARC 处理群集中运行器的整个生命周期，从预配到作业执行再到清理。 有关详细信息，请参阅 [操作运行器控制器](/zh/enterprise-server@3.22/actions/concepts/runners/actions-runner-controller) 和 [对 Actions Runner Controller 的支持](/zh/enterprise-server@3.22/actions/concepts/runners/support-for-arc)。 ### GitHub Actions 运行器规模集客户端 GitHub Actions 运行程序规模集客户端是基于 Go 的独立模块，它使平台团队、集成商和基础结构提供商能够跨 VM、容器、本地基础结构和云服务为 GitHub Actions 运行程序生成自定义自动缩放解决方案，并支持 Windows、Linux 和 macOS 平台。 客户端 GitHub 负责统筹处理与规模集相关的 API 交互，而基础结构预配则由你负责。 您定义运行器如何创建、扩展和销毁，并配置具有多个标签的运行器，以便灵活地路由和定向作业。 这使组织能够对运行器生命周期管理进行精细控制，并获得作业执行的实时遥测。 客户端设计为使用基本配置开箱即用，使团队能够快速实现自动缩放。 但是，其真正的能力在于其灵活性，客户端可以扩展和自定义，以满足每个组织的特定基础结构要求、合规性约束和操作工作流。 无论需要简单的缩放逻辑还是复杂的多环境预配策略，客户端都适应你的需求。 GitHub Actions 运行器扩展集客户端是一个开源项目。 [actions/scaleset 仓库](https://github.com/actions/scaleset) 包含完整的源代码、全面的文档和实用示例，帮助你快速上手。 你将找到实现指南、各种基础结构方案的示例配置，以及演示如何将客户端与不同的预配系统集成的参考体系结构。 存储库还包括为有兴趣扩展客户端或与社区共享其自动缩放模式的团队提供指南。 > **注意：** Runner Scale Set Client 并不是 Actions Runner Controller（ARC）的替代方案；ARC 仍然是规模集 API 的参考实现，也是用于运行器自动扩缩的推荐 Kubernetes 解决方案。 相反，客户端是一种补充工具，用于与相同的规模集 API 进行连接，以在 Kubernetes 外部生成自定义自动缩放解决方案。 ### 使用临时运行器进行自动缩放 GitHub 建议使用临时自托管运行器实现自动缩放；不建议使用持久性自托管运行器进行自动缩放。 在某些情况下，GitHub 无法保证任务不会在持久化运行器关闭期间被分配给它们。 使用临时运行程序可以保证这一点，因为 GitHub 只向运行程序分配一个作业。 这种方法允许您将运行器作为临时系统进行管理，因为您可以使用自动化为每个作业提供干净的环境。 这有助于限制以前工作中任何敏感资源的暴露，也有助于降低受损运行器获得新作业的风险。 > \[!WARNING]临时运行器的运行器应用程序日志文件必须转发到外部日志存储解决方案，以便进行故障排除和诊断。 虽然并不要求部署临时运行器，但 GitHub 建议在生产环境中部署临时运行器自动扩缩容解决方案之前，先将运行器日志转发到外部并妥善保存。 有关详细信息，请参阅“[对自托管运行程序进行监视和故障排除](/zh/enterprise-server@3.22/actions/how-tos/manage-runners/self-hosted-runners/monitor-and-troubleshoot#reviewing-the-self-hosted-runner-application-log-files)”。 要将临时运行器添加到环境，请在使用 `--ephemeral` 注册运行器时包含 `config.sh` 参数。 例如： ```shell ./config.sh --url https://github.com/octo-org --token example-token --ephemeral ``` 此时，GitHub Actions 服务将在运行器处理完一个任务后自动将其注销。 然后，您可以创建自己的自动化，在取消注册后擦除运行器。 > \[!NOTE] > 如果作业标记为某种类型的运行器，但没有匹配该类型的运行器可用，作业在排队时不会立即失败。 相反，作业将保持排队状态，直到 24 小时超时期限到期。 或者，可以使用 REST API 创建临时的实时运行器。 有关详细信息，请参阅“[自托管运行器的 REST API 终结点](/zh/enterprise-server@3.22/rest/actions/self-hosted-runners)”。 ### 自托管运行器上的运行器软件更新 默认情况下，每当有新版本的运行器软件可用时，自托管运行器将自动执行软件更新。 如果在容器中使用临时运行器，则当发布新的运行器版本时，这可能会导致重复的软件更新。 关闭自动更新允许你按照自己的计划直接更新容器映像上的运行器版本。 要关闭自动软件更新并自行安装软件更新，请在使用 `--disableupdate` 注册运行器时指定 `config.sh` 标志。 例如： ```shell ./config.sh --url https://github.com/YOUR-ORGANIZATION --token EXAMPLE-TOKEN --disableupdate ``` 如果禁用自动更新，您仍必须定期更新运行器版本。 GitHub Actions中的新功能需要对GitHub Actions服务\_和\_运行器软件都进行更改。 如果不进行软件更新，运行器可能无法正确处理利用 GitHub Actions 中新功能的作业。 如果禁用自动更新，则需要在新版本可用后的 30 天内更新运行器版本。 你可能想要订阅[`actions/runner`存储库](https://github.com/actions/runner/releases)中关于发布的通知。 有关详细信息，请参阅“[配置通知](/zh/enterprise-server@3.22/subscriptions-and-notifications/get-started/configuring-notifications#about-custom-notifications)”。 若要了解如何安装最新的运行器版本，请参阅[最新版本](https://github.com/actions/runner/releases)的安装说明。 > \[!WARNING] 针对软件发布的任何更新（包括主要版本、次要版本或修补程序版本）都被视为可用更新。 注意：如果未在 30 天内执行软件更新，GitHub Actions 服务将不会将工作排队到运行器。 此外，如果需要关键安全更新，GitHub Actions 服务在更新之前不会将作业排队到运行器。 ### 使用 Webhook 进行自动缩放 可使用从 [`workflow_job`](/zh/enterprise-server@3.22/webhooks/webhook-events-and-payloads#workflow_job) webhook 接收的负载自行创建自动缩放环境。 此 Webhook 在存储库、组织和企业级别可用，并且此事件的有效负载包含一个 `action` 键，该键对应于工作流作业生命周期的各个阶段；例如，当作业是 `queued`、`in_progress` 和 `completed` 时。 然后，您必须创建自己的缩放自动化以响应这些 web 挂钩有效负载。 * 有关 `workflow_job` webhook 的详细信息，请参阅 [Webhook 事件和有效负载](/zh/enterprise-server@3.22/webhooks/webhook-events-and-payloads#workflow_job)。 * 要了解如何使用 Webhook，请参阅“[Webhooks 文档](/zh/enterprise-server@3.22/webhooks)”。 > **注意：** 此方法依赖于 Webhook 交付的时间线来做出缩放决策，这可能会导致延迟和可靠性问题。 请考虑将 操作控制器 或 规模集客户端 用于更大规模的自动缩放方案。 ### 身份验证要求 可使用 [API](/zh/enterprise-server@3.22/rest/actions/self-hosted-runners) 注册和删除存储库和组织自托管运行器。 若要向 API 进行身份验证，自动缩放实现可以使用访问令牌或 GitHub 应用。 访问令牌将需要以下作用域： * 对于专用存储库，请使用设有[`repo`范围](/zh/enterprise-server@3.22/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps#available-scopes)的访问令牌。 * 对于公共存储库，请使用设有[`public_repo`范围](/zh/enterprise-server@3.22/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps#available-scopes)的访问令牌。 * 对于组织，请使用设有[`admin:org`范围](/zh/enterprise-server@3.22/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps#available-scopes)的访问令牌。 若要使用 GitHub 应用进行身份验证，必须为其分配以下权限： * 对于存储库，请分配 `administration` 权限。 * 对于组织，请分配 `organization_self_hosted_runners` 权限。 可使用 [API](/zh/enterprise-server@3.22/rest/actions/self-hosted-runners) 注册和删除企业自托管运行器。 要向 API 进行身份验证，自动缩放实现可以使用访问令牌。 访问令牌将需要 `manage_runners:enterprise` 权限范围。 ## 通信 自托管运行器连接到 你的 GitHub Enterprise Server 实例 以接收任务分配并下载运行器应用程序的新版本。 GitHub Actions 运行器应用程序是开源的。 可以参与 [runner](https://github.com/actions/runner) 存储库并在其中提交问题。 发布新版本后，运行程序应用程序将在 24 小时内自动更新。 ### 与 、你的 GitHub Enterprise Server 实例、 通信的要求 * 自托管运行器应用程序必须在主机上运行，才能接受并运行 GitHub Actions 任务。 * GitHub Enterprise Server 必须能够在 你的 GitHub Enterprise Server 实例 的主机名和 API 子域上接受来自您的运行器的 HTTP(S) 入站连接，并且您的运行器必须允许通过 HTTP(S) 出站连接到 你的 GitHub Enterprise Server 实例 的主机名和 API 子域。 * 若要使缓存正常工作，运行器必须能够与 blob 存储进行通信，并直接从其中下载内容。 ### 与 GitHub.com 的通信 除非您已为 GitHub.com 启用了对 GitHub.com 操作的自动访问，否则自托管运行器无需连接到 GitHub Enterprise Server。 有关详细信息，请参阅“[关于在企业中使用操作](/zh/enterprise-server@3.22/admin/managing-github-actions-for-your-enterprise/managing-access-to-actions-from-githubcom/about-using-actions-in-your-enterprise)”。 如果希望运行程序连接到 GitHub.com，则主机必须能够通过端口 80 建立出站 HTTP 连接，或者通过端口 443 建立 HTTPS 连接。 若要确保通过 HTTPS 建立连接，请为其 GitHub Enterprise Server配置 TLS。 请参阅“[配置 TLS](/zh/enterprise-server@3.22/admin/configuring-settings/hardening-security-for-your-enterprise/configuring-tls)”。 如果您已启用对 GitHub.com 操作的自动访问，则自托管运行器将直接连接到 GitHub.com 以下载操作。 必须确保计算机具有适当的网络访问权限，以便与 GitHub 下面列出的 URL 通信。 ```shell copy github.com api.github.com codeload.github.com ``` 您可以使用 REST API 获取有关 GitHub 的元信息，包括 GitHub 服务的 IP 地址和域名详细信息。 API 的 `actions_inbound` 部分支持完全限定的域和通配符域。 完全限定的域指定完整的域名（例如 `example.github.com`），而通配符域则使用 `*` 来表示多个可能的子域（例如 `*.github.com`）。 下面列出了使用通配符域的自托管运行器要求的示例。 有关详细信息，请参阅“[元数据的 REST API 端点](/zh/enterprise-server@3.22/rest/meta/meta)”。 ```shell copy github.com *.github.com *.githubusercontent.com ghcr.io ``` > \[!NOTE] > 列出的一些域名使用 `CNAME` 记录配置。 一些防火墙可能要求你为所有 `CNAME` 记录递归添加规则。 请注意，`CNAME` 记录将来可能会改变，只有列出的域名将保持不变。