Jenkins 控制器负责管理节点、调度任务和协调流水线；Agent 执行被分配的 Pipeline 步骤。Jenkins 建议将控制器内置节点的执行器设为 0，避免构建任务与调度工作争用资源。Agent 标签可表达节点能力，让作业按条件选择执行环境。Jenkins Agent 文档。

这不是要求所有企业采用完全相同的节点布局，而是一个便于审计和排错的起点。不要只用一个含义模糊的 mac 标签。可根据实际边界设为 macos-build、ios-simulator、ios-signing，并记录每个标签允许执行的作业类型。

Jenkins Pipeline 的 agent 指令可以在整个流水线或单个 stage 上选择标签；使用 agent none 后，可以为每个 stage 单独指定执行节点。Pipeline 语法文档。

不要因为项目最终面向 iOS，就把每个检查都放到 Mac 上。格式校验、部分静态检查或与平台无关的脚本，在工具兼容且结果一致时可以留在通用节点；需要 Xcode、Apple SDK 或项目专属构建环境的步骤，再派给 Mac Agent。这样能避免不必要的 Mac 队列，也减少通用节点缺少 Apple 工具链导致的失败。

下面的写法展示按 stage 路由。general-check 和 macos-build 是示例标签，需替换成你在 Jenkins 中真实配置的标签：

pipeline {
    agent none

    stages {
        stage('通用检查') {
            agent { label 'general-check' }
            steps {
                sh './ci/check.sh'
            }
        }

        stage('Xcode 构建') {
            agent { label 'macos-build' }
            steps {
                sh 'xcodebuild -scheme App -configuration Release build'
            }
        }
    }
}

示例中的 scheme、配置和构建目标必须换成仓库实际值。提交后检查日志，确认任务落到了预期 Mac Agent，并核对检出的提交、工作区位置、依赖解析结果和构建产物。Agent 在线不能证明这些项目级条件已经成立。

xcodebuild 等命令随 Xcode 提供。Apple 明确说明，xcodebuild 不包含在独立的 Xcode Command Line Tools 安装包中；运行该命令前，必须安装 Xcode 并将其设为活动开发者目录。Apple 命令行工具安装文档。

在目标 Mac Agent 上，以 Jenkins 服务账号检查当前开发者目录和工具版本：

xcode-select -p
xcodebuild -version

Apple 提供了用于构建 Xcode 项目和工作区的 xcodebuild 工具说明。Apple Xcode 命令行工具参考。需要切换活动开发者目录时，由环境管理员按实际安装位置配置，再用 Jenkins 任务复验；不要只在管理员的交互终端里测试。

对模拟器测试，使用项目真实的 scheme、测试计划和目标设备配置执行流水线任务。验收时分别记录模拟器能否启动、测试是否实际结束、测试结果是否被流水线识别。模拟器进程启动，不等于测试通过，更不等于整条流水线成功。

签名发布与普通提交构建应分别评估。对可信发布节点设置专用标签，并限制哪些作业有权请求该节点；同时把凭证访问范围收窄到确实需要的项目或目录。Jenkins 凭证遮蔽的作用是降低日志意外泄露风险，不是阻止恶意或不可信流水线读取凭证。Jenkins 凭证安全文档。

⚠️ 节点标签只参与任务调度，不能单独形成完整的安全隔离。若不可信分支能修改 Jenkinsfile，或能在同一节点上运行并接触签名凭证，就不能仅凭“发布节点有专用标签”认定风险已解决。Jenkins 对多分支流水线凭证的安全说明也提醒，来自分叉仓库的拉取请求可能修改测试代码以访问流水线绑定的凭证。Jenkins 多分支流水线凭证安全说明。

先判断你的发布链路是否需要独立节点：

• ✅ 若构建和发布任务都来自可信代码，凭证权限已限制到必要的作业，且节点任务彼此可信，可以先用受限发布标签并审计授权。
• ✅ 若测试任务会处理不可信分支，或不同团队需要不同的信任边界，应把发布节点与普通测试工作负载分开评估，并限制谁能配置发布流水线。
• ⚠️ 若发布凭证对多个项目全局可用，或团队无法确认哪些作业能修改 Jenkinsfile，先收紧凭证作用域和作业权限，再开放生产签名。
• ❌ 若组织要求签名密钥不能接触共享执行环境，而当前架构无法满足这一条件，就不要仅靠标签放行生产发布。

私有仓库、依赖源和 Apple 服务的访问条件，必须由企业网络与安全团队结合自身策略确认。不要从示例文章猜测域名或端口，再直接写进防火墙规则；这里没有可适用于所有企业网络的固定清单。

你应使用 Jenkins Agent 的真实服务账号进行验证，而不是只用管理员登录 Mac 后测试。逐项检查仓库身份认证、依赖源访问、代理配置和证书信任，再在真实流水线中执行检出与依赖解析。若交互终端成功而 Agent 失败，优先比对账号、环境变量、钥匙串访问上下文、代理和证书链；这些差异会让同一台 Mac 呈现出两种连接结果。

把验收记录绑到可重跑的流水线，而不是只留一张节点在线截图。每项任务应记录使用的标签、实际节点、工具链选择、输入提交、测试或构建结果，以及凭证是否在预期范围内可用。

• ✅ 若通用检查、Xcode 构建、目标模拟器测试、签名发布和私有依赖访问都已用真实 Jenkins 作业验证，可按企业变更流程评估上线。
• ⚠️ 若只有 Agent 连接通过，或工具链检查只在管理员终端成功，继续视为试运行，不要把它登记为已验收的生产打包机。
• ❌ 若不可信流水线仍能接触生产签名凭证，暂停发布任务，先完成权限和信任边界整改。

若你计划把 Mac Agent 接入 Jenkins，先把所需环境、账号权限、网络条件和验收项整理成清单，再核对 KVMNODE 的 Mac 租赁页面中实际可查的方案信息。这样做不预设特定配置或接入能力，也不替代你对企业网络和安全要求的审核。

FAQ

Jenkins 流水线怎样把 iOS 构建派到 Mac Agent？
为 Mac Agent 设置表达节点能力的标签，并在 Jenkinsfile 的 Pipeline 或对应 stage 中使用该标签。提交后检查日志确认实际节点、工作目录和工具链；若任务跑错节点，先核对标签表达式和节点使用限制。

Mac Agent 显示在线，但 xcodebuild 仍然失败，先查哪些地方？
以 Agent 服务账号检查 xcodebuild 是否可用、当前开发者目录是否指向预期 Xcode，以及项目指定的 scheme、目标和依赖能否解析。再检查工作目录、证书权限和网络代理。在线状态本身不验证这些条件。

模拟器测试和签名发布必须拆到不同 Mac 节点吗？
不一定。若流水线和参与者可信、发布凭证授权受到限制，可以先评估受限标签方案；若测试包含不可信分支或团队信任边界不同，就应评估拆分发布节点。节点标签不是完整的凭证或主机隔离。

企业启用 Jenkins Mac 打包机前，怎样判断它已经能用于生产？
在真实仓库中分别执行构建、目标模拟器测试和签名发布，并验证 Agent 服务账号能访问私有仓库与依赖源。记录实际节点、工具链、测试结果、产物和凭证边界；只在管理员终端成功，不算流水线验收通过。

如果你现在用的是个人工作站或临时自建 Mac，常见代价是设备采购与折旧由团队承担、节点维护需要内部人员跟进、远程团队还要处理持续在线和访问管理；但自购设备仍可能更适合长期稳定负载或必须连接物理接口的场景。若你只需为 Jenkins 试点或阶段性构建准备 Mac 环境，可先查看 KVMNODE 服务入口，再按真实可用配置、接入方式和验收条件评估是否租用，不应在未核实前假定性能、成本或交付能力。