从连接到第一次归档

连上你的打包机

交付即附 SSH 与 VNC 凭据。用命令行跑构建,用远程桌面核对签名;整台独享物理 Mac 归你使用,非虚拟机。

已有节点?先记录地址、SSH 端口、用户名与桌面连接方式,再执行下方步骤。

先打通 SSH,再交给自动化

在本地终端生成密钥,把公钥授权给云端用户,然后给节点起一个固定别名。后续 rsync、Fastlane 与 runner 都沿用这条连接。

以下 192.0.2.10 是文档示例地址,macbuild 是示例用户名,22 是示例 SSH 端口。全部替换为控制台交付值;不要把私钥、密码或完整连接凭据贴进工单。

  1. 01

    生成一把构建专用密钥

    在本地执行。单独的文件名便于撤销授权,不会覆盖已有默认密钥。交互提示中设置口令;自动化环境应由受控的密钥管理方式提供访问权限,而不是把私钥写进仓库。

    ssh-keygen -t ed25519 -f ~/.ssh/xcr_build -C "xcr-build"
    ssh-add ~/.ssh/xcr_build
    ls -l ~/.ssh/xcr_build.pub

    带 .pub 后缀的是公钥,可以安装到节点。没有后缀的是私钥,只留在本地或受控的 CI 密钥存储中。

  2. 02

    安装公钥并确认主机身份

    本地已安装 ssh-copy-id 时,用交付的用户名与端口安装公钥。首次连接会显示主机指纹,先与交付信息核对;没有可信指纹时,通过控制台工单确认,不要直接跳过验证。

    ssh-copy-id -i ~/.ssh/xcr_build.pub -p 22 macbuild@192.0.2.10
    ssh -i ~/.ssh/xcr_build -p 22 macbuild@192.0.2.10

    macOS 本地环境未必自带 ssh-copy-id。如果交付允许密码登录,可以改用下面的标准 SSH 命令;如果只允许密钥认证,应通过交付流程授权公钥,不要反复尝试密码。

    cat ~/.ssh/xcr_build.pub | ssh -p 22 macbuild@192.0.2.10 \
    'umask 077; mkdir -p ~/.ssh; cat >> ~/.ssh/authorized_keys'

    重装节点后若出现主机密钥变化提示,先确认重装记录与新指纹,再更新本地记录。不要用关闭主机校验的参数掩盖异常。

  3. 03

    写入连接别名并验收

    把下面配置加入本地 ~/.ssh/config。别名不依赖节点地址的记忆;地址变更时,只改这一处,脚本仍使用 xcr-build。

    Host xcr-build
        HostName 192.0.2.10
        User macbuild
        Port 22
        IdentityFile ~/.ssh/xcr_build
        IdentitiesOnly yes
        ServerAliveInterval 30
        ServerAliveCountMax 3

    执行一次只读验收,核对实际系统版本、选中的 Xcode 与磁盘空间。先确认环境,再安装依赖或注册 runner,避免把错误版本带进流水线。

    ssh xcr-build
    sw_vers
    xcode-select -p
    xcodebuild -version
    df -h "$HOME"

打开 VNC,核对图形界面里的最后几项

首次配置签名证书、检查 Keychain 权限或查看 Xcode 设置时,远程桌面比反复猜命令更直接。完成检查后,把稳定步骤交回命令行。

用 macOS 屏幕共享连接

在本地 macOS 打开“屏幕共享”,按交付说明填写桌面地址与端口。也可在 Finder 的“前往 → 连接服务器”中输入交付的 VNC 地址。

桌面凭据与 SSH 凭据不一定相同。使用控制台给出的对应字段,不要把 SSH 密钥文件当作 VNC 密码。

用兼容客户端,或通过 SSH 隧道

其他系统可使用兼容交付认证方式的 VNC 客户端。填写主机、端口和认证信息,不要在公开网络上自行开放桌面服务。

若交付说明允许经 SSH 访问节点的本地 VNC 服务,可以建立隧道。下例仅适用于远端服务监听 127.0.0.1:5900 的情况;实际端口以交付值为准。

ssh -N -o ExitOnForwardFailure=yes \
-L 127.0.0.1:5901:127.0.0.1:5900 xcr-build

保持这个终端会话开启,然后让本地 VNC 客户端连接 127.0.0.1:5901。本地端口仅绑定回环地址;结束桌面会话后,按 Control-C 关闭隧道。

桌面验收只做三件事

确认 Xcode 可以启动并选中预期版本;确认构建用户能访问签名证书及其私钥;确认描述文件与工程的 Bundle Identifier、Team 和导出方式一致。不要把证书密码放在截图中。

保留可复现的构建链

从本地 Mac,迁到云端 Mac

按数据、工具链、CI 接入的顺序迁移。先在同一个源码提交上完成一次手动归档,再让 runner 接管;不要同时更换 Xcode、依赖版本和签名策略。

01 / 数据

同步源码,缓存按需带走

把源码与锁文件放进独立工作目录。先执行 rsync 预演,核对目标路径;不要直接同步整个用户目录,也不要默认把证书、私钥和本地环境文件一起上传。

DerivedData 是可重建缓存。仅在 Xcode 版本、依赖与源码环境兼容时复用;出现路径或模块缓存异常,优先清理并冷构建。

02 / 工具链

对齐 Xcode、依赖与签名

用 xcode-select -p 与 xcodebuild -version 核对版本。切换时使用节点上实际存在的 Xcode 路径,再检查工程要求的 SDK。

保留 Podfile.lock、Package.resolved 与 Gemfile.lock。按项目锁定的环境运行 CocoaPods、SPM 和 Fastlane;单独导入证书与描述文件,验证私钥访问权限。

03 / CI 接入

注册 runner,约束调度

在 GitHub 或 GitLab 项目中创建 self-hosted runner 注册信息,然后按平台提供的 macOS 步骤安装。注册令牌只用于受控配置,不写进仓库或构建日志。

给 runner 标注用途与工具链,例如 macos、ios-build。先只允许可信分支执行签名任务,限制首轮并发,再依据内存、磁盘和任务日志调整。

先预演目录同步,再执行传输

rsync -avzn --exclude '.env' --exclude '.env.*' \
--exclude 'DerivedData/' ./MyApp/ xcr-build:~/builds/MyApp/

rsync -avz --exclude '.env' --exclude '.env.*' \
--exclude 'DerivedData/' ./MyApp/ xcr-build:~/builds/MyApp/

第一条带 -n,只显示计划变更;确认后再执行第二条。示例不使用 --delete,避免初次迁移误删远端文件。项目若有额外密钥目录,应先补充排除规则。

用一份交接记录结束迁移

记录源码提交、Xcode 版本、依赖锁文件、Scheme、导出配置、runner 标签与产物路径。先分别验证冷构建和增量构建,再决定是否复制缓存;本页不把示例命令当成性能测试,也不承诺固定打包耗时。

六个术语,连接时一次说清

遇到问题时,区分连接协议、执行环境与构建缓存。准确描述失败发生在哪一层,比只说“机器连不上”更容易排查。

物理节点
实际运行 macOS 的独享物理 Mac。它不是虚拟机;节点的芯片、内存与磁盘规格对应所选方案,整台机器只分配给一个租户。
VNC
远程查看和操作图形桌面的协议。适合处理可视化设置与签名检查;它的认证方式、端口和入口应按交付信息填写。
SSH 隧道
把本地端口通过 SSH 会话转发到远端服务。上面的示例让 VNC 流量走已认证的 SSH 连接;关闭隧道会同时中断这条桌面连接路径。
self-hosted runner
由团队自己管理的 CI 任务执行器。注册到项目后,流水线按标签或运行器条件调度到这台 Mac;独享节点仍需自行规划任务并发与权限。
Keychain
macOS 保存证书、私钥及访问授权的机制。图形界面下签名成功,不等于非交互 runner 一定能访问私钥;应在实际构建用户下验收。
DerivedData
Xcode 保存中间产物、索引与模块缓存的目录。它可以重建,不是源码备份;版本或路径变化后,旧缓存可能需要清理。

选节点,先看谁在操作桌面

三档机型覆盖全部六个节点。交互式远程桌面优先靠近主要操作者,再检查代码仓库、依赖下载与产物上传路径;团队时区只能作为初筛,不能替代真实网络验证。

新加坡

SG · UTC+8

适合主要协作时间落在东南亚工作日的团队。先测试本地到节点的桌面交互,再检查依赖下载和产物上传。

日本 · 东京

JP · UTC+9

适合以日本工作时间为主的协作。让需要调试图形界面的成员先验证连接,再安排自动化任务的触发时段。

韩国 · 首尔

KR · UTC+9

适合以韩国工作时间为主的开发团队。检查公司网络能否访问交付端口,并验证长时间 SSH 会话的稳定性。

香港

HK · UTC+8

适合以华南及周边协作时段为主的团队。分别验证桌面响应、代码拉取和缓存传输,不把单次 ping 当作完整结论。

美国东部

US-E · UTC−5 / UTC−4

适合北美东部工作时段,并可作为跨时区协作的候选。当地采用夏令时,交接任务应写明时区而不是只写钟点。

美国西部

US-W · UTC−8 / UTC−7

适合北美西岸工作时段。跨时区团队可让夜间归档接续另一侧白天的代码提交,但仍需约束签名任务的并发。

节点全年 365 天正常运行。实际可用状态以控制台实时返回为准。连接排查时,在控制台工单中提供节点、机型、所用协议、错误原文和复现步骤;仅隐藏凭据,不要删掉有助于定位的错误信息。

拿到凭据,五分钟连上

把五分钟作为首次连接的操作目标:核对主机、验证 SSH、打开桌面。网络与认证配置确认后,再迁移构建环境;完整流水线验收需要按项目单独安排。

从 $21.7/天起租。支付仅支持 USDT-TRC20 与 Visa / Mastercard / Amex(经 Stripe),美元结算;实际可用网关以后端接口返回为准。