Mac mini 搭建 GitHub Actions 自托管 Runner 完整指南（生产级 CI 架构｜2026 最新）

什么是 GitHub Actions 自托管 Runner（Mac mini 版本）

Mac mini GitHub Actions 自托管 Runner 是一种由用户自托管的 CI 执行环境，在 Mac mini 本地或云端实例上运行 workflow Job，替代 GitHub 托管的 macOS Runner。

在 Mac mini 上运行 Runner 的五大核心优势：

• ✔ 构建缓存长期保留（DerivedData / CocoaPods / SPM）
• ✔ Xcode 版本完全可控（Golden Image 钉扎）
• ✔ CI 成本固定（不按分钟计费）
• ✔ iOS 构建速度显著提升（热构建可进 5–6 分钟）
• ✔ 可做企业级安全隔离（专用 ci 用户 + Keychain 隔离）

为什么 iOS CI 必须使用 Mac mini 自托管 Runner

GitHub 托管 Runner 的三大瓶颈

核心结论

GitHub 托管 Runner = 无状态机器
Mac mini Runner = 有记忆的 CI 系统

这正是 iOS CI 性能差异的本质原因。延伸阅读：Flutter iOS CI 构建优化：从 28 分钟到 9 分钟。

Mac mini CI Runner 生产级三层架构设计

整体架构模型

┌──────────────────────────────┐
│ 第 1 层：launchd 系统守护层   │  ← 可靠性（自动重启 / 崩溃恢复）
├──────────────────────────────┤
│ 第 2 层：ci 用户执行隔离层    │  ← 安全性（Keychain / 权限边界）
├──────────────────────────────┤
│ 第 3 层：标签路由调度层       │  ← 可维护性（workflow → Runner）
└──────────────────────────────┘

第 1 层 — launchd 守护机制（核心稳定性）

launchd = macOS 版 systemd。关键能力：自动重启 Runner、系统重启自动恢复、崩溃自动拉起、以守护进程级别运行。

关键配置三项（缺一不可）：

• RunAtLoad = true — 用户登录后自动启动
• KeepAlive = true — 崩溃后自动重拉
• WorkingDirectory — 必须设置（最常见的 Runner 离线根因）

Runner 应使用 LaunchAgents（非 LaunchDaemons），因为 iOS CI 需要访问用户 Keychain 进行代码签名。配合 macOS 自动登录，让 ci 用户重启后自动进入会话。

第 2 层 — CI 用户隔离（安全核心）

为什么不能用管理员账号？

• 可以 sudo → 攻击面无限扩大
• Keychain 可被读取 → 证书可能泄露
• fork PR 可执行恶意脚本 → 全机沦陷

推荐方案：专用 ci 用户

• ❌ 无 sudo 权限，不在管理员组
• ✅ 独立 Keychain（/Users/ci/Library/Keychains/）
• ✅ 加入 _developer 组（允许 xcodebuild / simctl）

sudo dscl . -create /Users/ci UserShell /bin/zsh
sudo dscl . -create /Users/ci RealName "CI Runner"
sudo dscl . -create /Users/ci UniqueID 505
sudo dscl . -create /Users/ci PrimaryGroupID 20
sudo dscl . -create /Users/ci NFSHomeDirectory /Users/ci
sudo createhomedir -c -u ci
sudo passwd ci
sudo dscl . -append /Groups/_developer GroupMembership ci

第 3 层 — Runner 标签路由系统（CI 调度核心）

标签体系 = CI 调度系统。推荐三层结构：

runs-on: [self-hosted, macOS, ARM64, flutter-ios, xcode-16, m4]
           ┌──────────────┐  ┌───────────────────┐  ┌──────────────┐
           │ 平台层        │  │ 工作负载层         │  │ 硬件层        │
           │ self-hosted  │  │ flutter-ios        │  │ m4, 16gb     │
           │ macOS, ARM64 │  │ xcode-16           │  │ region:tokyo │
           └──────────────┘  └───────────────────┘  └──────────────┘

关键规则：标签是「与」关系（AND）；workflow 必须完全匹配；多机同标签 = 自动负载均衡。

Mac mini Runner 安装完整流程（生产级）

步骤 1 — 安装 Runner

# 以 ci 用户身份执行
mkdir -p ~/actions-runner && cd ~/actions-runner
curl -fsSL -O https://github.com/actions/runner/releases/download/v2.316.1/actions-runner-osx-arm64-2.316.1.tar.gz
tar xzf actions-runner-osx-arm64-2.316.1.tar.gz

步骤 2 — 注册 Runner

./config.sh \
  --url https://github.com/your-org/your-repo \
  --token YOUR_REGISTRATION_TOKEN \
  --name "$(hostname -s)" \
  --labels "self-hosted,macOS,ARM64,flutter-ios,xcode-16,m4,16gb" \
  --work _work \
  --replace \
  --unattended

步骤 3 — launchd 守护配置（关键）

保存到 ~/Library/LaunchAgents/com.kvmboot.github-runner.plist：

<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0"><dict>
  <key>Label</key><string>com.kvmboot.github-runner</string>
  <key>ProgramArguments</key>
  <array><string>/Users/ci/actions-runner/run.sh</string></array>
  <key>WorkingDirectory</key><string>/Users/ci/actions-runner</string>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
  <key>EnvironmentVariables</key>
  <dict>
    <key>PATH</key>
    <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
  </dict>
  <key>StandardOutPath</key><string>/Users/ci/Library/Logs/github-runner.log</string>
  <key>StandardErrorPath</key><string>/Users/ci/Library/Logs/github-runner.err</string>
</dict></plist>

步骤 4 — 启动 Runner

launchctl load ~/Library/LaunchAgents/com.kvmboot.github-runner.plist
launchctl list | grep github-runner
tail -f ~/Library/Logs/github-runner.log   # 期望出现 Listening for Jobs

网络与代理（出站白名单）

Runner 必须出站访问：*.github.com、api.github.com、*.actions.githubusercontent.com、objects.githubusercontent.com。代理须在 plist EnvironmentVariables 中注入（不会继承 shell 的 export https_proxy）。完整 IP 段见 api.github.com/meta。

生产级安全加固

自托管 Runner 最大风险来自公开仓库的 fork PR。必须开启三道防线：

1. 仓库级 Runner（禁止组织级）

注册为仓库级 Runner，避免组织级横向权限扩散——一旦某个仓库被攻击，所有仓库的 Keychain 和 Secrets 全部暴露。

2. Fork PR 保护机制

GitHub 仓库 → 设置 → Actions → 常规，开启：

要求批准所有外部协作者的 fork 拉取请求工作流（Require approval for all outside collaborators）

确保 fork PR 不会自动在自托管 Runner 上执行。详见 云 Mac CI 安全隔离体系。

3. Secrets 隔离

• ❌ 不把 .p12、.env 放在 ci 用户主目录
• ❌ 不把 API Key 硬编码在 workflow 中
• ✅ GitHub Secrets + 运行时注入；证书走 Fastlane match + Keychain

concurrency:
  group: flutter-ios-${{ github.ref }}
  cancel-in-progress: true

CI 性能优化（iOS / Flutter 场景）

Mac mini 自托管 Runner 提升 iOS CI 优化 效果的关键在于本地缓存持久化：

缓存优化三层

• CocoaPods 缓存（~/.cocoapods + ios/Pods）
• DerivedData 缓存（-derivedDataPath 固定路径）
• SPM / Flutter pub 缓存

完整缓存策略见专题：iOS CI 缓存体系设计（DerivedData / CocoaPods / SPM）。

一键重建 Runner（灾难恢复）

macOS 大版本升级、Golden Image 漂移或安全事件后，用 rebuild_runner.sh 在 5 分钟内完成重建：

#!/usr/bin/env zsh
set -euo pipefail
CI_USER="ci"
PLIST_DEST="/Users/$CI_USER/Library/LaunchAgents/com.kvmboot.github-runner.plist"

sudo -u "$CI_USER" launchctl unload "$PLIST_DEST" 2>/dev/null || true
sudo -u "$CI_USER" bash -c "cd /Users/$CI_USER/actions-runner && ./config.sh remove --token \$(gh api -X POST /repos/your-org/your-repo/actions/runners/remove-token --jq '.token') 2>/dev/null || true"
sudo -u "$CI_USER" zsh /Users/$CI_USER/scripts/setup_runner.sh
sudo -u "$CI_USER" launchctl load "$PLIST_DEST"
echo "[OK] Runner rebuilt."

验证 Runner 是否生产就绪（检查清单）

验收前确认基础环境已就绪（云 Mac 开通验收清单）。

层级 1 — Runner 在线

• ✅ GitHub 界面显示 空闲（Idle）
• ✅ launchctl list | grep github-runner PID 正常
• ✅ 日志出现 Listening for Jobs

层级 2 — 空 Job

runs-on: [self-hosted, macOS, flutter-ios]

• ✅ Job 30 秒内被分配（不长时间排队）
• ✅ 输出 Runner 名称与 OS 版本

层级 3 — 工具链验证

xcodebuild -version    # 符合 Golden Image
flutter --version
pod --version

常见问题（长尾关键词覆盖）

Mac mini 可以运行 GitHub Actions Runner 吗？

可以，并且是 iOS CI 最常见的生产方案之一。通过 launchd 守护，Mac mini 可长期稳定运行 GitHub Actions 自托管 Runner（macOS） 环境。

自托管 Runner 比 GitHub 托管 Runner 快多少？

通常 iOS CI 可提升 30%–60% 构建速度，主要来自 CocoaPods 与 DerivedData 缓存持久化——GitHub 托管 Runner 每次 Job 都是全新环境，无法保留本地缓存。

launchd 和 brew services 有什么区别？

launchd 是 macOS 系统级守护框架（systemd 等价物）；brew services 只是 launchd 的封装层，不适合管理非 Homebrew 安装的 Runner。生产环境应直接编写 plist。

Runner 离线了怎么排查？

按优先级检查：

1. launchctl list | grep github-runner — 进程状态
2. plist 中 WorkingDirectory 是否设置
3. workflow runs-on 标签是否与 Runner 完全匹配

一台 Mac mini 能跑多少个 Runner？

16GB → 建议 1 个；24GB → 1–2 个（轻量任务）。跑 xcodebuild 时内存容易打满，多实例需配合 concurrency 限制。