2026 年在云 Mac 上部署 GitHub Actions 自建 macOS runner：注册、钥匙串、并发与成本对照

当 iOS 管线每周触发十几次 xcodebuild archive，GitHub Actions macOS 托管 runner 的分钟账单会先刺痛财务——而平台工程真正需要的是：一台角色清晰的 云 Mac 构建机，上面只跑 自建 macOS runner，钥匙串与 Derived Data 路径固定、出口 IP 可审计。 本文只回答「如何在租用 Mac 上落地 GHA self-hosted」，不重复 Windows 上搜 Xcode 的选型（见 虚拟机、云 Mac 与 CI 怎么选），也不展开 TestFlight 上传专机（见 加拿大节点 TestFlight 席位）。

1. 何时该从托管 macOS runner 切到自建

托管 GitHub Actions macOS runner 的优势是零运维、队列由 GitHub 调度；隐性成本是：高峰月分钟数、artifact 保留策略、以及跨洋排障时「只能看摘要日志」的人力折算。下列信号说明该评估 自建 macOS runner + 云 Mac 构建机：

• 同一仓库每月 macOS 作业 > 3,000 分钟，且大量时间花在 derived data 冷启动而非编译。
• 需要固定 hostname / 独享 IPv4 做 ASC API、Webhook 或企业代理白名单。
• Distribution 证书与 match 必须落在单写节点，禁止在共享托管池轮换钥匙串。
• 亚太白天提交、北美夜间批跑——与 公证与 Release 自建流水线 同一台加拿大席位的衔接需求。

2. 托管分钟 vs 云 Mac 专机：成本与可控性对照

粗算：若月均 5,000 macOS 分钟、单价约 $0.08，则托管侧约 $400/月 量级（未计私有仓库加成）。一台 M4 24GB/512 云 Mac 专机在不少供应商处接近或低于该数，且同一台机还可兼 VNC 验收与 Fastlane 上传——这是「云 Mac 构建机」相对纯 CI SaaS 的结构性优势。

3. 推荐架构：labels、并发与「单写」边界

不要把「编译」「签名」「上传 ASC」混在同一 workflow 的同一 job 里抢钥匙串。2026 年更稳的分工：

• runner 标签：macos-m4-canada（地理）、signing（仅 match）、build（允许并行 2 若 24GB+）。
• 并发：签名 job concurrency: signing 全局 1；编译 job 可按分支并发 2，避免 Derived Data 锁死。
• 跨区：亚太 runner 只做 lint/unit；加拿大 云 Mac 构建机 承接 archive + exportArchive。

4. 在云 Mac 上注册 runner（首台）

在 GitHub → Settings → Actions → Runners → New self-hosted runner → macOS，复制注册命令。SSH 登录云 Mac 后建议用专用系统用户（如 runner），与交互式 VNC 管理员分离。

# 以 runner 用户登录云 Mac
mkdir -p ~/actions-runner && cd ~/actions-runner
curl -o actions-runner-osx-arm64.tar.gz -L \
  https://github.com/actions/runner/releases/download/v2.319.1/actions-runner-osx-arm64-2.319.1.tar.gz
tar xzf actions-runner-osx-arm64.tar.gz
./config.sh --url https://github.com/YOUR_ORG/YOUR_REPO \
  --token YOUR_TOKEN --labels macos-m4-canada,arm64 --unattended
sudo ./svc.sh install
sudo ./svc.sh start
./run.sh --check

验证：在仓库放一个仅跑 sw_vers && xcodebuild -version 的 workflow，runs-on: [self-hosted, macos-m4-canada]。通过后 pin Xcode：sudo xcode-select -s /Applications/Xcode_16.3.app 并写入仓库 README。

5. 钥匙串、match 与无人值守解锁

自建 runner 失败 Top3 之一是「codesign 找不到 identity」。在云 Mac 上：

1. 导入 Distribution 证书到 login 钥匙串，设置 ACL 允许 codesign / security。
2. match 仓库单独 job，concurrency: signing；其他 job 只读 ~/Library/MobileDevice/Provisioning Profiles。
3. 用 security set-key-partition-list 处理 CI 解锁（仅限受控构建机，禁止复制到开发者笔电）。
4. 在 workflow 里显式 KEYCHAIN_PATH，避免 GHA 默认临时钥匙串覆盖 match 结果。

jobs:
  archive:
    runs-on: [self-hosted, macos-m4-canada, build]
    steps:
      - uses: actions/checkout@v4
      - name: Build archive
        run: |
          xcodebuild -scheme MyApp -configuration Release \
            -archivePath $RUNNER_TEMP/MyApp.xcarchive archive

6. 云 Mac runner 安全加固

自建 runner 会执行仓库（及配置不当时的 fork）任意脚本。请把云 Mac 构建机当作生产签名堡垒，而非实验 VM。

• 仓库范围：优先组织级 runner + 显式仓库白名单；不信任的分支保护下禁止 fork PR 触发自建机。
• 用户隔离：服务账户用 runner，禁止其 VNC 登录。
• Secrets：match 密码与 ASC API Key 放 GitHub Environments 并设审批；季度轮换。
• 网络：出站放行 GitHub + Apple CDN；入站仅办公室 IP 或 Tailscale SSH。
• 磁盘加密：云 Mac 开启 FileVault；快照导出排除明文 *.p12。

7. 运维：磁盘水位、Xcode 升级与 runner 轮换

Xcode 小版本升级：先 ./svc.sh stop，升级后跑 smoke workflow，再 svc.sh start。runner 软件大版本（actions-runner 包）建议每月第一个维护窗替换，保留旧目录回滚。

8. 组织级 runner 与多仓库策略

平台团队很快会从「单仓库注册」升级到组织级 runner 分组：

• Runner groups 对应环境（如仅 ios-release 可用 signing 标签）。
• Ephemeral（若许可）每 job 清盘——适合不可信构建，不适合 match 缓存；签名机勿开。
• 在 CODEOWNERS 规定哪些仓库可写 runs-on: [self-hosted]，防 rogue workflow 成为主要外泄面。

两条产品线共用一台云 Mac 构建机时，用 labels 分流而非急着买第二台——直到磁盘黄色告警周周出现。若 Xcode 大版本不兼容，应加席位，勿在同一卷做双 xcode-select 切换。

9. 可观测性：失败 job 要留什么日志

托管 runner 隐藏基础设施；自建必须自建信号。最低配：

1. 红构建时同步 ~/actions-runner/_diag/Runner_*.log 到日志栈。
2. 每 5 分钟 cron：df -h + ./run.sh --check，离线超 10 分钟告警。
3. Fastlane 输出标注 run-id，便于对照 ASC 上传错误。
4. 队列深度 > 3 时先告警平台频道，避免开发误判「GitHub 变慢」。

10. 首周 Runbook 检查清单

1. 选定一台 云 Mac 构建机（建议 24GB/512 起，周更 > 3 次考虑 1TB）。
2. 注册 runner + labels；仓库默认 runs-on 仍用托管，仅 Release workflow 切 self-hosted。
3. 跑通 smoke → 空 archive → 带签名的 TestFlight 内测分支（可先不上传）。
4. 记录月均分钟：若托管仍 < 1,500 分钟，可暂不迁移次要仓库。
5. 文档化 ASC API Key 与 match 写权限只在该机。
6. 配置磁盘告警与日志 ~/actions-runner/_diag 保留 7 天。

14. FAQ

自建 macOS runner 是否违反 GitHub 条款？

官方支持 self-hosted；需自行承担安全补丁与密钥保管。不要把 runner 装在不可信的共享池。

一台云 Mac 能挂几个 runner？

技术上可注册多个目录，但 iOS 签名与磁盘 I/O 建议一台物理机一个队列，用 labels 区分 job 类型即可。

ARM64 runner 能编译 x86_模拟器吗？

Apple Silicon 原生构建为主；若必须 x86 模拟器矩阵，单独加 Intel 云 Mac 或托管 runner 补矩阵。

和 GitLab macOS runner 比呢？

原理相同：固定 macOS 主机 + agent。本文聚焦 GitHub Actions 生态与 workflow 语法。

私有仓库 minutes 更贵，自建是否更划算？

当 macOS 作业 > 3,000 分钟/月或需要固定 IP/钥匙串时，通常 2–3 个月内专机更可控。

runner 离线怎么告警？

用 GitHub Enterprise 的 runner 状态 API，或 cron 跑 ./run.sh --check 配合外部 uptime 探针。

Hashvps 节点适合吗？

适合需要独享 IPv4、M4 裸金属与加拿大/亚太多区选择的团队；选型前对照节点延迟文与套餐磁盘档位。

Derived Data 要不要在自建机上缓存？

要。固定路径如 /Users/runner/DerivedDataCache，按 Swift 版本 + Package.resolved 哈希分桶；依赖升级时主动失效，可节省 30–50% 增量编译时间。

12. 三阶段从托管分钟迁到自建

阶段 A（第 1 周）：注册云 Mac runner，仅 workflow_dispatch 影子跑，对照同 commit 托管 job 耗时，不动签名。

阶段 B（第 2 周）：archive 切 self-hosted；TestFlight 上传暂留托管或手工，直至钥匙串连续 5 夜稳定。

阶段 C（第 3 周起）：match/签名迁至 signing 标签；默认分支关托管 macOS；保留一条 workflow_dispatch 托管灾备 job。

13. 12 个月 TCO 试算表（可复制给财务）