从连接到产物校验

把云端 Mac 接入你的构建流程

这里不是概念说明，而是一套可逐项执行的操作路径。先完成独享物理节点的身份核验和安全设置，再准备 Xcode、签名材料与自动化任务；遇到异常时，按统一口径收集网络输出和构建日志。

5 类 支持主题
6 步 自动化打包链路
2 种 可追踪联系入口
立即租用云端 Mac 查看 Runner M4 配置
RUNNER SUPPORT ROUTE MAC-01
01
领取与核验 连接参数、主机指纹、首次密码
准备
02
准备构建环境 Xcode、工具链、签名材料、目录
配置
03
运行自动化任务 检出、缓存、归档、导出、校验
执行
04
收集诊断材料 节点、订单、时间、命令与完整输出
排查
所有诊断都从可复现的输入开始
首次连接

五步完成节点身份核验与安全设置

RunnerVM 交付的是独享物理 Mac mini，不是虚拟机。首次操作的重点不是尽快运行命令，而是确认你连接到订单对应的设备，并把初始访问方式替换为团队自己的安全设置。

  1. 01

    在控制台领取交付信息

    核对订单标识、节点区域、连接地址、SSH 端口、VNC 参数和初始用户名。不要通过聊天转发完整凭据；团队协作时，只把必要字段交给实际操作者。

  2. 02

    先记录主机指纹

    将控制台显示的主机指纹与首次 SSH 提示逐字符比较。若算法或摘要不一致，停止连接并提交工单，不要用删除本地 known_hosts 记录的方式绕过异常。

  3. 03

    建立 SSH 命令行连接

    使用订单给出的主机、端口和用户名连接。登录后先执行 sw_vers、uname -m 与 hostname，把系统版本、Apple Silicon 架构和设备名称写入交付记录。

  4. 04

    按需建立 VNC 远程桌面

    在本地 VNC 客户端中填写控制台给出的地址、端口和密码。首次只使用默认分辨率验证键盘、指针和窗口缩放，确认会话稳定后再调高画面尺寸。

  5. 05

    更新密码并限制权限

    立即更新初始密码，检查 SSH 公钥和管理员权限，仅保留任务需要的访问。完成后重新建立 SSH 与 VNC 会话，确认新凭据有效，再开始导入项目或签名材料。

命令执行样例

从连接验证到归档输出

下面按一次常见构建任务的顺序展示 SSH、xcodebuild 和 fastlane 输出。命令中的主机、工作区、Scheme、导出配置和 lane 都应替换为项目真实值，不能直接复制后假定适用于所有仓库。

  • 先确认连接目标，再切换到项目目录。
  • 归档路径使用任务唯一目录，避免并发覆盖。
  • 保存完整标准输出和退出码，不只保留最后一行。
runner-build-session zsh
连接节点 SSH 
$ ssh -p 22 runner@10.0.0.12
Host key fingerprint: SHA256:…
$ sw_vers
ProductName: macOS
$ uname -m
arm64
生成归档 XCODEBUILD 
$ xcodebuild archive \
-workspace RunnerApp.xcworkspace \
-scheme RunnerApp \
-archivePath build/RunnerApp.xcarchive
** ARCHIVE SUCCEEDED **
执行自动化流程 FASTLANE 
$ bundle exec fastlane ios build
[08:42:16]: Resolving signing settings
[08:43:02]: Archive completed
[08:43:11]: Export verified
[08:43:11]: fastlane finished successfully
示例命令需按项目的工作区、Scheme、签名方式和目录结构调整。
环境准备

让 Xcode、签名材料和目录各自可核验

环境问题通常不是“Xcode 能不能打开”，而是图形界面选择、命令行路径、项目声明与签名上下文是否一致。按下面顺序检查，能更快区分工具链问题和项目问题。

01

确认 Xcode 版本与路径

执行 xcodebuild -version 和 xcode-select -p。若节点安装了多个版本，先明确项目要求，再切换开发者目录，避免图形界面与自动化任务使用不同版本。

02

验证 Command Line Tools

执行 xcrun --find xcodebuild、xcrun simctl list 和一次无签名的项目解析。若工具不存在或 SDK 列表异常，先修复工具链，不要直接修改项目文件。

03

建立任务专用签名钥匙串

将自动化任务使用的证书放入独立钥匙串，设置明确的解锁步骤和最小访问范围。不要把密码写入仓库、脚本参数或构建日志。

04

导入证书与描述文件

记录证书名称、有效期、团队标识和描述文件 UUID，确认 Bundle Identifier 与目标配置匹配。导入后用 security find-identity -v -p codesigning 核验可用身份。

05

规划构建目录

将源码、依赖缓存、DerivedData、Archive、Export 和日志分开。每次任务使用唯一归档路径；共享缓存只存放可重建内容，避免把签名材料混入缓存。

自动化打包

把一次成功构建变成六个可重复阶段

自动化的目标不是把本地脚本搬到远端，而是让输入、环境、签名和输出都能复现。每个阶段都应产生明确记录，失败时可以知道问题发生在哪一步。

  1. 01

    检出固定代码版本

    使用提交哈希或受保护标签，不依赖会继续移动的分支头。记录子模块版本、Git LFS 状态和仓库清洁状态。

    git checkout --detach <commit>
  2. 02

    恢复并验证依赖缓存

    缓存键至少包含锁文件摘要、工具版本和架构。缓存未命中时正常安装，不把“必须命中缓存”当作构建成功条件。

    bundle check || bundle install
  3. 03

    装载签名配置

    解锁任务专用钥匙串，导入匹配的描述文件，验证可用签名身份。任何密钥和密码都不得写入标准输出。

    security find-identity -v -p codesigning
  4. 04

    执行 Archive

    显式指定工作区、Scheme、Configuration、Destination 和归档路径。保存完整日志与 xcodebuild 退出码。

    xcodebuild archive …
  5. 05

    导出交付产物

    将导出配置纳入版本管理，但不包含秘密。导出目录与归档目录分离，避免重跑时覆盖原始 xcarchive。

    xcodebuild -exportArchive …
  6. 06

    校验并登记结果

    检查文件存在、大小、摘要、签名信息和任务退出码，把产物标识与提交版本、Xcode 版本及日志路径关联。

    shasum -a 256 build-output
远程桌面

VNC 用于图形操作，长任务交给独立进程

远程桌面适合完成首次图形设置、检查 Xcode 界面状态和处理需要视觉确认的任务。构建是否持续运行，不应依赖本地 VNC 窗口是否保持连接。

连接参数

严格使用控制台显示的地址、端口、用户名与密码。若客户端支持连接配置文件，也不要把密码写入可同步的明文文件。

分辨率调整

首次连接使用默认尺寸。确认交互稳定后再逐级提高分辨率；出现输入延迟时，先降低色深和画面尺寸，再检查网络路径。

会话锁定

离开设备前锁定图形会话，不以关闭 VNC 客户端代替锁屏。团队换班时应撤销不再需要的访问权限。

断开后的任务

持续构建应运行在 CI runner、launchd、tmux 或其他可恢复会话中。先做一次主动断开测试，确认任务和日志继续写入。

远程会话交接单 VNC / SSH
开始前 核对节点与会话身份

确认订单区域、设备名称和当前登录用户。

运行中 任务写入独立日志

不要只依赖屏幕输出判断构建是否仍在执行。

离开时 锁定会话并验证后台任务

断开后通过 SSH 检查进程、日志增长和退出状态。

交接后 撤销临时权限

移除临时公钥、一次性文件和不再需要的凭据。

网络与延迟

一次排查同时记录连通性、路径、解析和端口

网络问题需要明确“从哪里、在什么时间、访问哪个目标、得到什么完整输出”。单张截图或一句“连接很慢”无法区分本地网络、跨境路径、DNS、端口策略和目标服务状态。

PING

检查基础往返与丢包

连续发送固定数量的数据包，保留最小、平均、最大延迟和丢包率。不要用一次响应代表整段连接质量。

ping -c 20 target-host
TRACEROUTE

检查路径变化位置

从出现问题的源网络执行，保留完整跳数。中间节点不响应不等于链路中断，应结合最终目标是否可达判断。

traceroute target-host
DNS

检查解析结果与耗时

记录当前 DNS 服务器、返回地址和查询耗时。若不同网络结果不一致，同时提交两侧输出，不要手工改写结果。

dig target-host
PORT

检查目标端口可达性

分别测试 SSH 或项目实际使用的端口。连接成功只说明 TCP 可达，不代表身份验证和上层协议已经完成。

nc -vz target-host 22
工单诊断包

提交时必须包含的五项信息

NET-CHECK
问题时间
写明本地日期、时间、时区和持续时长。
源端位置
说明源节点、办公网络或家庭网络及运营商。
目标信息
提供订单标识、节点区域、目标主机和端口。
完整输出
附上 ping、traceroute、DNS 和端口检查原始结果。
对照结果
若可行，补充另一网络或另一时间段的相同测试。

提交前移除密码、私钥、令牌和业务数据，但不要删掉时间戳、错误码、路径跳数或命令参数。

支持升级路径

先缩小问题范围，再提交可追踪工单

售前问题、一般咨询和不关联具体订单的说明可以发送邮件；涉及节点、构建失败、连接异常或账务记录的问题，应登录控制台提交工单，以便关联订单和持续查看处理状态。

  1. 01

    检索并执行对应指南

    按首次连接、环境准备、自动化或网络排查选择路径。记录已经执行的步骤、命令、结果和首次出现异常的位置。

  2. 02

    整理最小复现材料

    提供订单标识、节点区域、问题时间、复现步骤、预期结果、实际结果和脱敏后的完整日志。构建问题还应写明提交版本与 Xcode 版本。

  3. 03

    在控制台提交工单

    选择与问题最接近的分类，把日志作为附件或正文代码块提交。一个工单聚焦一个问题，避免把网络、构建和账务异常混在同一条记录里。

  4. 04

    在原工单补充进展

    复测后继续回复原工单，补充新的时间、命令和输出。紧急事件同样通过控制台查看处理状态，不重复创建多个相同工单。

关联具体订单

控制台工单

适合连接失败、节点异常、构建环境、账务核对和需要持续跟进的问题。工单可关联订单，并保留完整处理时间线。

  • 订单标识与节点区域
  • 带时区的问题发生时间
  • 复现步骤与完整错误输出
  • 已执行的排查命令和结果
登录控制台提交工单
一般咨询

发送支持邮件

适合售前选型、流程确认、安全报告和不需要关联节点的说明。邮件主题中写明问题类别，正文避免包含密码或密钥。

support@runnervm.com
需要整理模板

先生成结构化说明

联系页按售前、技术、账务和安全事项列出必填信息，适合在发送邮件前检查材料是否完整。

查看联系说明
常见判断

开始排查前先确认这些边界

以下答案用于区分设备交付、连接方式、构建任务和支持材料，减少在错误方向上反复尝试。

RunnerVM 提供的是虚拟实例吗？

不是。订单对应独享物理 Mac mini 节点，设备规格为 Runner M4：Mac Mini M4、16GB RAM、256GB SSD。远程连接只是访问方式，不会把服务变成共享虚拟资源。

断开 VNC 后，构建任务会继续吗？

是否继续取决于任务如何启动。CI runner、launchd、tmux 或独立后台进程通常不依赖 VNC 窗口；直接绑定图形会话的交互任务可能受会话状态影响。正式使用前应主动断开一次并检查进程、日志和退出状态。

首次连接前需要准备什么？

准备可用的 SSH 与 VNC 客户端、团队内部的凭据保管方式、项目要求的 Xcode 版本、签名材料清单和一个不会写入仓库的秘密管理流程。领取交付信息后，先核对主机指纹和设备身份。

排查问题会改变订单计费周期吗？

不会自动改变。Runner M4 按天、周、月或季下单，订单周期与处理状态以控制台记录为准。如需核对具体订单，请在控制台提交关联该订单的工单。

任务完成后应清理哪些内容？

先导出需要保留的归档、产物和脱敏日志，再清理源码工作区、临时签名钥匙串、描述文件、临时公钥、访问令牌和项目缓存中的敏感信息。不要把明文凭据保留在 shell 历史或脚本参数中。

如何判断应该选择哪个节点？

优先从实际办公网络或 CI 来源测试目标区域的延迟与路径，再结合团队时区和产物传输方向选择。Runner M4 可在新加坡、日本东京、韩国首尔、香港和美国东部五个节点订购，实际可用性以控制台实时返回为准。

下一次构建

从一台可核验的云端 Mac 开始

选择 Runner M4 和目标区域，完成订单后按本页步骤核验连接、准备工具链并运行第一条可重复的构建任务。

立即租用云端 Mac 联系 RunnerVM 支持