用 macOS 屏幕共享连接
在本地 macOS 打开“屏幕共享”,按交付说明填写桌面地址与端口。也可在 Finder 的“前往 → 连接服务器”中输入交付的 VNC 地址。
桌面凭据与 SSH 凭据不一定相同。使用控制台给出的对应字段,不要把 SSH 密钥文件当作 VNC 密码。
交付即附 SSH 与 VNC 凭据。用命令行跑构建,用远程桌面核对签名;整台独享物理 Mac 归你使用,非虚拟机。
已有节点?先记录地址、SSH 端口、用户名与桌面连接方式,再执行下方步骤。
在本地终端生成密钥,把公钥授权给云端用户,然后给节点起一个固定别名。后续 rsync、Fastlane 与 runner 都沿用这条连接。
以下 192.0.2.10 是文档示例地址,macbuild 是示例用户名,22 是示例 SSH 端口。全部替换为控制台交付值;不要把私钥、密码或完整连接凭据贴进工单。
在本地执行。单独的文件名便于撤销授权,不会覆盖已有默认密钥。交互提示中设置口令;自动化环境应由受控的密钥管理方式提供访问权限,而不是把私钥写进仓库。
ssh-keygen -t ed25519 -f ~/.ssh/xcr_build -C "xcr-build"
ssh-add ~/.ssh/xcr_build
ls -l ~/.ssh/xcr_build.pub
带 .pub 后缀的是公钥,可以安装到节点。没有后缀的是私钥,只留在本地或受控的 CI 密钥存储中。
本地已安装 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'
重装节点后若出现主机密钥变化提示,先确认重装记录与新指纹,再更新本地记录。不要用关闭主机校验的参数掩盖异常。
把下面配置加入本地 ~/.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"
首次配置签名证书、检查 Keychain 权限或查看 Xcode 设置时,远程桌面比反复猜命令更直接。完成检查后,把稳定步骤交回命令行。
在本地 macOS 打开“屏幕共享”,按交付说明填写桌面地址与端口。也可在 Finder 的“前往 → 连接服务器”中输入交付的 VNC 地址。
桌面凭据与 SSH 凭据不一定相同。使用控制台给出的对应字段,不要把 SSH 密钥文件当作 VNC 密码。
其他系统可使用兼容交付认证方式的 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 和导出方式一致。不要把证书密码放在截图中。
按数据、工具链、CI 接入的顺序迁移。先在同一个源码提交上完成一次手动归档,再让 runner 接管;不要同时更换 Xcode、依赖版本和签名策略。
把源码与锁文件放进独立工作目录。先执行 rsync 预演,核对目标路径;不要直接同步整个用户目录,也不要默认把证书、私钥和本地环境文件一起上传。
DerivedData 是可重建缓存。仅在 Xcode 版本、依赖与源码环境兼容时复用;出现路径或模块缓存异常,优先清理并冷构建。
用 xcode-select -p 与 xcodebuild -version 核对版本。切换时使用节点上实际存在的 Xcode 路径,再检查工程要求的 SDK。
保留 Podfile.lock、Package.resolved 与 Gemfile.lock。按项目锁定的环境运行 CocoaPods、SPM 和 Fastlane;单独导入证书与描述文件,验证私钥访问权限。
在 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 标签与产物路径。先分别验证冷构建和增量构建,再决定是否复制缓存;本页不把示例命令当成性能测试,也不承诺固定打包耗时。
遇到问题时,区分连接协议、执行环境与构建缓存。准确描述失败发生在哪一层,比只说“机器连不上”更容易排查。
三档机型覆盖全部六个节点。交互式远程桌面优先靠近主要操作者,再检查代码仓库、依赖下载与产物上传路径;团队时区只能作为初筛,不能替代真实网络验证。
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 天正常运行。实际可用状态以控制台实时返回为准。连接排查时,在控制台工单中提供节点、机型、所用协议、错误原文和复现步骤;仅隐藏凭据,不要删掉有助于定位的错误信息。