GitHub Actions Runner 版本过期怎么办？2026 Mac 升级清单

📋 本文目录

症状：Runner 显示在线，但任务开始排队或不再领取。
最快解法：不要等任务彻底停摆；自动更新节点立即核验更新链路，固定版本节点先准备备用 Mac，再灰度升级。

这套处理方式适用于个人开发者、小型研发团队，以及维护企业级 Mac 构建节点的 DevOps 团队。若你在使用 GitHub Actions 自托管 Runner，判断标准不能只看控制台里的“在线”状态，还要核对版本、标签、服务进程、真实构建和重启恢复。

最后更新于 2026 年 8 月 26 日，日期与执行规则核实自 GitHub 官方最低版本执行公告、Self-hosted runners 官方文档、账户内实时下载指引与 actions/runner 官方发布页。

在线状态与可执行状态

GitHub 控制台显示 Runner 为 Idle，只说明它已经连接并处于等待任务状态；Offline 则可能代表主机断电、Runner 服务未运行，或无法与 GitHub 通信。更隐蔽的情况是节点仍显示在线，却因为版本不再满足执行要求而不接收新任务。相关状态、日志和诊断方式可参考 GitHub Runner 监控与排障文档。

截至 2026 年 8 月 26 日，GitHub 已确认两层规则：

注册或重新注册时，Runner 至少需要达到 2.329.0，但这个版本不是永久的任务执行最低版本。
Runner 必须在新版本发布后的 30 天内完成更新；否则 GitHub Actions 可能停止向该节点排队任务。
GitHub Enterprise Cloud with Data Residency 的正式执行日期是 2026 年 7 月 31 日；GitHub Enterprise Cloud 的正式执行日期是 2026 年 9 月 25 日。
GitHub Enterprise Cloud 在 2026 年 8 月 24 日已经进入分阶段 brownout；后续日期包括 8 月 31 日、9 月 2 日、9 月 7 日、9 月 9 日、9 月 11 日、9 月 14 日、9 月 16 日和 9 月 18 日，具体时段为美国东部时间 11:00—15:00。

这些规则带来三个实际限制。第一，关闭自动更新后，责任会转移到你自己的镜像、安装脚本和维护日历。第二，Runner 版本、Xcode、钥匙串、缓存和签名证书通常绑定在同一台 Mac 上，直接覆盖升级可能同时破坏多个依赖。第三，节点在线并不代表标签路由正确，工作流仍可能因 runs-on 标签不匹配而持续排队。

按节点规模选择升级方式

节点类型	主要风险	推荐策略	通过标准	停止条件
单台 Mac Runner	升级期间完全没有构建能力	先准备临时或隔离备用节点，再维护主节点	注册、标签、重启、真实构建均通过	备用节点无法领取任务或签名失败
小型团队共享节点	多仓库共用缓存、钥匙串和 Xcode	新增节点灰度，先迁移低风险仓库	测试、归档、签名和产物比对通过	发布流水线失败或产物不一致
固定版本、受限网络节点	无法自动下载更新包	先验证代理、证书、权限和安装包校验	更新日志完整，服务可恢复	出站 HTTPS 或服务账户权限异常
企业节点池	批量升级引发集中故障	按 Runner 组和标签分批放量	领取率、失败率、发布链路稳定	关键节点出现连续失败
短生命周期节点	每次启动都带入旧镜像	重建镜像或更新自动化模板	新节点版本来自实时下载指引	缓存镜像仍包含旧 Runner

表里的“真实构建”不能用一个简单的单元测试替代。对于移动开发团队，至少要验证 Xcode 编译、测试、签名、归档和产物上传中的实际路径。

个人开发者：保住唯一构建能力

如果你只有一台长期在线 Mac Runner，最危险的做法是直接在生产节点执行覆盖式升级。你的节点可能同时保存了注册信息、工作目录、证书、钥匙串、Ruby 或 Node 版本，以及项目所需的本地缓存；其中任何一项没有记录，回滚都可能变成重新配置。

版本核验与升级前备份

如何确认当前节点没有落后于执行要求？

最可靠的方式有两层。第一，在仓库、组织或企业的 Runner 管理页面查看节点信息；第二，通过 REST API 查询 version、status、os、labels 等字段。GitHub 的接口示例会返回 Runner 的版本和标签，因此比只看“在线”更适合做节点清单。

组织级查询可以使用以下占位符命令：

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  "https://api.github.com/orgs/<ORG>/actions/runners"

REST API 返回的 version、status、操作系统和标签，可与账户内下载指引及官方发布页交叉核对。实际执行要求可能随 GitHub 的分阶段策略变化，因此不要把旧脚本里写死的版本号当作长期标准。接口字段说明可参考 GitHub 自托管 Runner REST API 文档。

升级前至少保存以下信息：

cd <RUNNER_PATH>

./svc.sh status || true
./run.sh --version || true

find . -maxdepth 2 -type f \
  \( -name ".runner" -o -name ".credentials" -o -name ".service" \) \
  -print

du -sh _work _diag 2>/dev/null || true

不要把令牌、凭据文件或签名证书提交到代码仓库。你需要保存的是节点名称、标签、工作目录路径、服务安装方式、证书恢复方法和依赖版本，而不是把敏感文件复制到不受控的位置。

五步保底流程

冻结变更。 暂停非必要的发布任务，记录当前 Runner 版本、标签和最后一次成功构建的运行编号。
准备备用节点。 使用一台隔离的远程 Mac 或临时主机，复制最小 Xcode、依赖、签名和工作流链路。MacDate 提供真实 Mac 远程访问方案，适合先做短期隔离验证；你也可以先查看 Mac 节点租赁与配置说明。
从账户内下载指引取包。 不要把搜索结果、旧脚本或缓存镜像中的版本号当成当前要求。官方发布页明确提示，Runner 采用渐进式发布，账户、组织或仓库实际可下载的版本可能不同。
先验收备用节点。 检查注册、标签路由、依赖安装、签名、归档和产物上传。
再维护主节点。 停止服务、保留日志和恢复信息，完成升级后重启服务，并执行一次真实项目构建。

升级中断时，恢复路径应该怎样设计？

回滚不是简单把压缩包换回旧版本。你应先把节点从任务路由中移除或改用备用标签，再停止服务，保留升级失败时的 _diag 日志，恢复此前验证过的 Runner 目录和服务配置，最后重新注册或启动服务。若旧版本已经不再满足 GitHub 的执行要求，回滚只能作为短时故障隔离，不能作为长期方案。

停止条件很明确：备用节点没有成功领取任务、签名权限丢失、归档产物无法上传，或者服务重启后没有恢复监听，就不要切换回生产流量。

小型团队：拆分共享环境与灰度批次

多人共享一台 Mac 构建节点时，升级影响的不只是 Runner 本身。固定标签可能被多个仓库使用，钥匙串可能依赖登录用户，缓存可能改变依赖解析结果，Xcode 命令行工具和证书权限也可能让普通测试通过、发布任务失败。

建议先把工作流分成三组：

低风险任务： 单元测试、静态检查、非发布构建。
中风险任务： 测试包、内部分发、依赖缓存验证。
高风险任务： 签名、归档、生产发布和商店上传。

新增或隔离一台 Mac Runner 后，先复制标签，但不要立即承接所有仓库。先迁移低风险任务，比较升级前后的 Runner 版本、任务日志、构建产物哈希、归档结果和耗时变化，再处理发布流水线。

为什么节点仍显示在线，却可能不领取新任务？

常见原因不是“机器坏了”，而是服务端已经不再向过旧版本排队任务。GitHub 文档说明，自动更新默认开启；如果通过 --disableupdate 关闭自动更新，仍必须在新版本发布后的 30 天内完成手动更新。即使节点之前已经注册成功，满足注册最低版本也不等于永久满足任务执行要求。

团队应把以下证据放进升级记录：

升级前后 Runner 版本和标签；
同一提交的测试、归档与签名日志；
构建产物校验值；
节点重启后的服务状态；
失败时的 _diag/Runner_*.log 与 _diag/Worker_*.log；
备用节点切换和回退演练结果。

GitHub 官方说明，Runner 应用日志和每个任务的详细日志都保存在安装目录的 _diag 文件夹中。不要只截图网页状态，否则出现“在线但排队”时很难判断是版本、网络、标签还是服务问题。

固定版本与受限网络：明确更新责任

自动更新关闭后的处理

如果注册脚本或节点模板使用了 --disableupdate，你需要建立自己的更新责任链：

从账户内下载指引确认当前可用包；
更新安装脚本、镜像或节点模板；
校验下载文件来源和校验信息；
以非关键节点先做升级；
记录服务账户、目录权限和启动方式；
在 30 天窗口内完成剩余节点更新。

不能只修改正在运行的目录而不更新模板。GitHub 已明确要求同时检查安装脚本、虚拟机镜像、容器镜像和部署自动化；由旧缓存镜像创建的节点需要重建。

代理、证书与权限检查

受限网络环境至少要验证：

curl -I https://github.com
curl -I https://api.github.com

Runner 主机需要能够通过出站 HTTPS 的 443 端口访问 GitHub；官方文档还列出最低 70 kilobits per second 的上传和下载网络要求。

在 macOS 上，还要确认服务账户能够读取 Runner 目录、访问工作目录，并在发布任务中访问正确的钥匙串。不要把关闭 TLS 证书校验当作常规修复方案。若是证书问题，应安装正确证书或修复代理链路，而不是降低通信安全级别。

升级失败时，先看 _diag 中的 Runner_ 日志和 Worker_ 日志，再决定是恢复网络、修复权限，还是重建节点。若服务账户无法读取证书或工作目录，继续重复下载 Runner 包通常没有意义。

企业节点池：盘点、灰度与审计

企业平台团队不应把“所有 Runner 更新到最新”当成一个一次性脚本任务。先生成节点清单，至少包含：

Runner 组与管理层级；
操作系统和 CPU 架构；
自定义标签；
所属仓库或组织；
当前版本；
自动更新是否关闭；
是否承载签名与生产发布；
是否为短生命周期或自动扩缩节点。

组织级和仓库级 REST API 都能返回 Runner 版本、状态和标签；大型节点池还可以结合审计日志查看注册事件。需要注意的是，审计日志记录的是注册时版本，不等于所有当前在线节点的完整库存，所以不能单独作为最终盘点依据。

建议采用三阶段：

第一阶段：测试

选择非关键节点，更新 Runner 与依赖模板。验证注册、标签、任务领取、日志、重启恢复和一个真实 Mac 构建。

第二阶段：放量

先迁移低风险仓库，再迁移测试包和内部分发任务。观察任务领取率、排队时间、失败类型和构建产物，不要只看服务进程是否为 running。

第三阶段：回滚

提前定义回滚对象：旧模板、节点标签、服务配置、证书恢复方式和任务切换路径。任何关键发布任务失败，都应暂停下一批升级，而不是继续扩大范围。

短生命周期节点适合更新基础镜像并重建；长期节点需要保留工作目录、签名环境和日志；自动扩缩节点则要优先修改创建模板，否则新节点仍会不断带入过期版本。由旧缓存模板生成的 Runner，应在模板更新后重新创建。

发布验收：测试通过不等于迁移完成

发布负责人最终要验收的是交付链路，而不是单个测试命令。建议按以下顺序执行：

节点重新注册，状态为可用；
固定标签能够正确路由到目标 Mac；
服务重启后自动恢复监听；
拉取真实项目并恢复依赖；
执行 Xcode 编译和测试；
访问签名证书与钥匙串；
生成归档文件；
上传内部或生产分发渠道；
保存任务日志、Runner 版本和产物信息；
演练切换备用节点，再恢复主节点。

如果只有普通测试通过，但归档、签名或上传失败，不能把升级标记为完成。你还可以在工作流中设置 ACTIONS_RUNNER_DEBUG=true，获取 Runner 和 Worker 的诊断日志，以定位具体失败步骤。

在 2026 年 9 月 25 日 GitHub Enterprise Cloud 正式执行日期前，企业团队应至少完成一次备用节点切换演练。若你使用的是 GitHub Enterprise Server，本文引用的这项 GitHub.com 与 GitHub Enterprise Cloud 规则目前不直接适用，仍需按对应版本和账户文档核对。

当前 Mac 与隔离远程 Mac 的选择

如果现有 Mac 能够安排维护窗口、网络出站正常、签名环境可恢复，继续使用现有节点并建立定期版本复核即可。若它承担所有发布任务、无法停机、没有可验证备份，或受限网络让自动更新长期失败，直接覆盖生产节点的风险就高得多。

本地 Mac 方案的真实缺点是：维护窗口难安排，硬件故障会让整个流水线中断，备用机和证书环境需要你自己长期维护。临时购买 Mac 也会把成本锁定在设备、存储和保修上，而且不一定马上具备可用的 CI 环境。

更稳妥的做法是先在隔离的远程 Mac 上复制最小构建链路，完成 Runner 注册、标签路由、Xcode 签名、真实项目归档和重启恢复，再决定是否切换生产任务。MacDate 的远程 Mac 可以作为短期备用节点或升级灰度环境；如果你还在比较硬件采购与远程方案，可参考 Mac mini 配置与价格判断，先按任务持续时间和是否需要物理接口做选择。

今天就先完成一次 Runner 资产盘点，并把备用节点切换演练跑通。对于无法安全停机的生产 Mac，先增加隔离容量、验证真实发布链路，再安排主节点升级，通常比等到任务全面排队后被动重建更可控。