Jenkins macOS 构建代理

把 Mac 接入 Jenkins 的两种方式

	SSH 代理	入站代理
谁发起连接	控制器通过 SSH 连接 Mac	Mac 主动连接控制器
插件或工具	SSH Build Agents 插件	agent.jar，走 WebSocket 或 TCP 代理端口
网络要求	控制器能访问 Mac 的 SSH 端口	Mac 能访问控制器 URL
重启	控制器负责重新拉起代理	需用 launchd 保持进程运行
适合	控制器有稳定的出站网络	控制器在防火墙或 NAT 之后

两种方式的 Mac 端准备相同：专用的 ci 用户、Java、Xcode，以及类似 /Users/ci/jenkins 的工作目录。如果还在比较 CI 系统，可以先看 macOS CI/CD 运行器概览。

价格为每台机器起始配置的美元月费。需要更多内存、存储或多台机器？联系我们。

准备 Mac

1. 订购 Mac。付款后我们会完成配置并发邮件通知你，SSH 信息显示在“My Macs”中。
2. 为 Jenkins 创建一个标准用户，并以该用户登录。
3. 安装 Xcode，接受许可协议并完成首次启动。多版本 Xcode 的配置见 Xcode 构建服务器页面。
4. 安装控制器支持的 Java 运行时。对当前的 Jenkins 版本，Java 21 是稳妥的选择；如果控制器版本较旧，请查阅 jenkins.io。

brew install --cask temurin@21
java -version

方式一：SSH Build Agents 插件

1. 把控制器的公钥加入 Mac 上 ci 用户的 ~/.ssh/authorized_keys。
2. 在 Jenkins 中安装 SSH Build Agents 插件，然后进入 Manage Jenkins → Nodes → New Node。
3. 远程根目录设为 /Users/ci/jenkins，标签填写如 macos xcode m6。
4. 启动方式选择 Launch agents via SSH，填写“My Macs”中的主机和端口，选择 SSH 密钥凭据和主机密钥校验策略（known hosts 或手动信任）。
5. 保存后，控制器会把 remoting.jar 复制到 Mac 并启动。

常见问题：非交互式 SSH 会话不会读取 shell 配置文件，Homebrew 工具可能不在 PATH 中。可以在节点的环境变量里加入 /opt/homebrew/bin，或在启动方式的高级选项中设置 JavaPath。

方式二：使用 agent.jar 的入站代理

新建节点时启动方式选择 Launch agent by connecting it to the controller，节点页面会显示密钥和完整命令。在 Mac 上以 ci 用户执行：

mkdir -p ~/jenkins && cd ~/jenkins
curl -sO https://jenkins.example.com/jnlpJars/agent.jar
echo "SECRET_FROM_NODE_PAGE" > ~/jenkins/secret-file && chmod 600 ~/jenkins/secret-file
java -jar agent.jar -url https://jenkins.example.com/ \
  -name mac-m6 -secret @$HOME/jenkins/secret-file \
  -webSocket -workDir "$HOME/jenkins"

-webSocket 走常规 HTTPS 端口，无需暴露 TCP 代理端口。要让代理在注销和重启后继续运行，可以把命令写成 ~/Library/LaunchAgents 中的 launchd 代理。详见 Jenkins 节点文档。

标签与流水线

用标签描述代理的能力，再用标签表达式选择它。在 withCredentials 中解锁签名钥匙串，并在 post 中重新锁定：

pipeline {
  agent { label 'macos && xcode' }
  stages {
    stage('Archive') {
      steps {
        withCredentials([string(credentialsId: 'ci-keychain-password',
                                variable: 'KEYCHAIN_PASSWORD')]) {
          sh '''
            security unlock-keychain -p "$KEYCHAIN_PASSWORD" ~/Library/Keychains/ci.keychain-db
            xcodebuild archive -scheme MyApp -destination 'generic/platform=iOS' \
              -archivePath build/MyApp.xcarchive
          '''
        }
      }
    }
  }
  post {
    always { sh 'security lock-keychain ~/Library/Keychains/ci.keychain-db || true' }
  }
}

shell 代码块请使用单引号，避免 Groovy 把密码插值进构建日志。钥匙串本身只需配置一次，做法见 iOS 构建服务器页面。

规格与执行器数量

• 16GB 的 Mac mini 建议节点只设 1 个执行器，Xcode 和模拟器很占内存。
• Mac mini M6 24GB / 512GB 通常可以为较轻的任务设两个执行器，或者跑一个较重的 UI 测试任务。
• 需要更多并行任务时，增加带相同标签的 Mac，让 Jenkins 分摊负载。详见 Mac 构建农场，多机报价请告诉我们你的需求。

常见问题

Jenkins macOS 构建代理用 SSH 还是入站方式更好？

SSH 更省心，控制器会帮你重启代理。如果控制器无法访问 Mac，例如位于 NAT 之后，就使用入站代理。

Jenkins 控制器必须运行在 Mac 上吗？

不需要。控制器可以运行在 Linux、容器或其他任何地方，只有需要 Xcode 的任务必须在 macOS 代理上执行。

为什么 codesign 在代理上卡住或失败？

通常是钥匙串被锁定，或没有设置私钥分区列表。请在任务中解锁钥匙串，并在导入证书时执行一次 security set-key-partition-list。

代理可以按月租用吗？

可以。Mac mini M4 和 M6 支持按月租用，详见价格。