Mac 重启后 Runner 显示离线，先分别确认主机可达、Runner 服务状态和 GitHub 连通，再核对任务标签与 Runner group；不要一上来就删除并重新注册。只有代表性流水线成功接单、构建并回传结果后，才恢复生产派发。本周建议动作：将下面的分层检查加入值班 Runbook，并在下一次维护窗口演练。
负责 GitHub Actions self-hosted runner 的平台工程师：用这套步骤区分服务未启动与网络故障。
负责企业 Mac CI 的 IT 负责人：建立可复用的故障分层和恢复验收流程。
维护 iOS/macOS 发布流水线的技术负责人：确认 Runner 在线不等于构建或发布已恢复。
先分清主机离线，还是 Runner 应用离线
GitHub 页面上的 Offline 表示 Runner 未连接到 GitHub；原因可能是主机离线、Runner 应用未运行，或应用无法与 GitHub 通信。这个状态本身不能证明 Mac 已关机，也不能证明 Runner 注册记录损坏。GitHub 的状态说明与排障指引将这些情况列为不同可能原因。
Mac 重启后为什么会显示 Offline？先把现场信号交叉核对：GitHub Runner 页面状态、远程管理通道是否能连到 Mac，以及运维记录中的重启结果。远程连接失败时，先查供电、启动过程、网络和远程访问通道；远程连接正常但 Runner Offline，则继续检查服务与出站通信。
| 观察结果 | 更可能的故障域 | 下一步 |
|---|---|---|
| 远程管理也不可达，GitHub 显示 Offline | 主机未启动、网络或远程访问异常 | 查设备和网络侧记录；先恢复主机可达 |
| Mac 可登录，Runner 服务未运行 | 服务未安装、未启动或启动上下文不匹配 | 检查 svc.sh 状态和 launchd 配置 |
| 服务显示运行，GitHub 仍 Offline | DNS、代理、TLS 或目标域名访问问题 | 做 Runner 专用连通性检查并查看诊断日志 |
| Runner 在线，但任务排队 | 标签、Runner group 或仓库访问权限不匹配 | 对照工作流路由条件逐项核验 |
评估远程 Mac 节点的接入方式时，可以先查看 MESHLAUNCH 的远程 Mac 服务概览，再将实际交付和运维信息与团队现有节点的管理要求逐项对照。
用户登录后运行，还是无人值守服务运行
Mac 已经启动，不代表 Runner 会随系统自动恢复。先在 Runner 安装目录检查服务：
./svc.sh status
GitHub 的 macOS 服务排障文档说明，svc.sh status 会通过 launchctl 检查服务，并可从 .service 文件确认相应的 plist 路径。按文档配置服务时，可使用 ./svc.sh install 安装、./svc.sh start 启动；先确认当前状态和安装方式，再执行操作，不要同时手动启动 Runner 进程造成重复实例。GitHub Runner 服务配置说明和服务状态检查示例列出了这些检查方式。
macOS 上怎样确认 Runner 服务已经启动？以服务管理器的状态、.service 指向的配置文件，以及 GitHub 页面状态三方互证。仅在用户桌面打开终端后运行 Runner，不足以证明重启后可以无人值守接单。
| 启动上下文 | 生命周期与适用边界 | 排查重点 |
|---|---|---|
| 用户会话中的进程 | 依赖相应用户会话；退出登录后不能假定进程仍可用 | 登录状态、进程归属、是否手动启动 |
| LaunchAgent | 代表当前登录用户运行 | plist 所在目录、用户会话和授权状态 |
| LaunchDaemon | 系统级后台服务，可在用户登录前运行 | 服务安装、系统级权限和启动日志 |
Apple 对LaunchAgent 与 LaunchDaemon 的运行上下文说明表明，前者代表当前登录用户运行，后者由系统管理并可在用户登录前运行。不要把“用户登录后能跑”当成“重启后无人登录也能接单”。改服务配置前，先确认 Runner 实际采用哪种上下文；如使用自定义服务，也应按 GitHub 文档核实其启动入口。
服务在运行，但 GitHub 仍显示离线
本机浏览网页成功，只能说明部分网络请求可用，不能证明 Runner 能访问执行任务所需的 GitHub 服务。先用 Runner 自带的连通性检查，再检查 DNS 解析、出站 HTTPS、代理变量、TLS 证书链和防火墙规则。GitHub 提供 config.sh --check 检查所需网络服务；具体执行时应结合 Runner 配置中的 URL 与令牌参数，并按官方说明处理凭据。Runner 网络排障说明还列出了所需访问域名。
| 现象 | 优先核查 | 不要这样处理 |
|---|---|---|
| 域名无法解析或请求超时 | DNS、出站规则、所需域名及代理连通 | 只用浏览器能打开网页就判定网络正常 |
| 终端直连正常，服务启动后失败 | 服务进程继承的代理环境变量与配置 | 假设交互式 Shell 的环境变量自动应用到服务 |
| TLS 握手或证书报错 | 系统时间、证书链、TLS 检查设备与代理配置 | 关闭 TLS 证书验证作为正式修复 |
如果组织使用代理，Runner 应用启动时读取代理配置；变更代理后，需要按 GitHub 的自托管 Runner 代理配置文档重启 Runner 服务使配置生效。不要以关闭 TLS 验证代替修复证书链或代理问题。
Runner 进程在运行但仍显示离线，先查什么？先确认该服务进程是否能解析并访问所需域名，再检查代理与 TLS；随后查看 Runner 安装目录 _diag 中对应启动时生成的 Runner_ 日志。若问题发生在具体任务运行期间，再对照 Worker_ 日志；需要更详细的工作流诊断时，可按 GitHub 的Runner 诊断日志说明启用并下载诊断日志。
在线但没有任务：检查路由条件，不要重注册
Runner 在线只表示它连上了 GitHub，不代表它符合某个工作流的派发条件。检查 runs-on 中要求的标签是否全部存在，再确认 Runner 所属组以及该组是否允许目标仓库访问。GitHub 会依据标签和组匹配 Runner；组合指定时，Runner 必须满足相应条件。工作流 Runner 选择文档说明了标签与组的匹配方式，Runner 标签管理说明和Runner group 访问控制说明可用于核对配置与仓库权限。
按下面的决策条件处理：
- 若主机不可达，先修复主机启动或网络路径；不要修改 Runner 注册。
- 若主机可达、服务未运行，先确认服务是否已安装、启动上下文是否正确，再依当前状态启动服务。
- 若服务运行但 Runner Offline，先做网络检查并查
_diag日志；有证据指向注册异常后，才评估重新配置。 - 若 Runner 在线但任务排队，先对照
runs-on、Runner 标签、组和仓库访问权限；不匹配时修正路由或访问策略。 - 若 Runner 已接单但构建失败，转查工作区、工具链、凭据和流水线日志；不要把构建失败归为 Runner 离线。
重新注册会改变注册关系，也可能留下旧记录或造成重复服务。先比对 GitHub 上的 Runner 名称与状态、Mac 上的 .service 文件、服务状态和当前 Runner 进程。只有这些证据表明注册配置本身异常，才按官方配置流程移除并重新配置；单纯 Offline 并非重新注册的充分理由。
恢复在线后，用代表性任务验收再恢复派发
把恢复判断拆成不同门槛，逐项勾选。测试任务应避免使用生产签名资产，也不要在验证时扩大凭据权限。
- [ ] 主机可达：远程管理通道可用，重启和登录状态有运维记录。
- [ ] 服务已恢复：
./svc.sh status显示预期状态，Runner 页面不再显示 Offline。 - [ ] 网络可用：Runner 专用连通性检查通过；代理和证书配置符合团队要求。
- [ ] 路由匹配：工作流所需标签、Runner group 和仓库访问权限均已核对。
- [ ] 任务可执行：代表性任务成功接单，能访问工作区并调用必要工具。
- [ ] 结果可追溯：检查构建结果、工作流日志与必要的 Runner 诊断日志。
- [ ] 生产准入：按团队发布门禁确认后，再恢复生产任务派发。
Runner 恢复在线后，怎样确认工作流能正常接单？发起一条范围受控的代表性工作流，确认它确实分配到目标 Runner，完成工作区访问、必要工具调用和结果回传。若任务停在队列，继续查路由；若已接单但失败，则查构建步骤。Runner 在线不是 iOS 构建或发布恢复的充分证据。
Mac CI 的故障恢复也不宜只靠重启后人工登录。自管节点需要团队承担主机可达性、服务配置、网络策略和日志留存；临时借用个人 Mac 则可能带来环境不一致、权限边界不清和交接困难。若团队缺少适合长期运维的节点、但需要临时扩展远程 Mac 环境，可以先核对 MESHLAUNCH 的远程 Mac 交付信息，再按自身的安全、访问和运维要求评估是否租赁。长期固定负载或依赖本地物理接口的任务，仍应优先评估自购与现场维护；不论选择哪种方式，都要把服务恢复和流水线验收纳入发布准入。