SSH 登录
适合运行构建命令、传输文件和检查日志。SSH 默认端口为 22；实例若返回其他端口，请使用实际值。
从实例详情读取主机地址与用户名。首次连接先核对主机指纹，再配置自己的公钥；私钥留在本地，不放进工单。
看首次构建示例
先确认实例状态
选一条连接路径
进入控制台的实例详情，核对实例编号、节点和就绪状态。公网地址、用户名、端口与初始凭据均以该实例实际返回为准，不要套用另一台机器的参数。
VNC 图形桌面
适合打开 Xcode、检查 Simulator 和处理图形界面设置。VNC 默认端口为 5900；连接地址、密码与实际端口从实例详情获取。
连入后先确认桌面可操作。不要把 VNC 密码用于代码仓库；网络允许时，优先通过受控连接或 SSH 隧道访问。
查图形桌面问题控制台网页终端
先登录控制台，再查看实例详情中返回的连接入口。网页终端如已提供，使用浏览器的 HTTPS 连接，通常走 443，无需另填终端端口。
凭据来自已登录的账户会话，不是独立公开链接。若实例未显示该入口，使用 SSH 或 VNC；不要自行猜测终端地址。
查看实例连接入口
跑通一次，再接流水线
把连接和构建分开验证
先确认能登录，再检查 Xcode 路径与版本。下面是输出格式示例，不是实例实时日志；会话名称、构建编号与耗时仅用于说明阅读位置。
merge@tokyo-m4pro-07
构建输出示例
$ ssh -p <SSH_PORT> <USER>@<HOST>
Welcome to MergeMac
$ xcode-select -p
/Applications/Xcode.app/Contents/Developer
$ xcodebuild -version
$ cd <PROJECT_DIRECTORY>
$ xcodebuild -scheme App archive
** ARCHIVE SUCCEEDED **
$ fastlane pilot upload
Successfully uploaded Build 214替换参数，再执行
将尖括号参数替换为实例详情中的值。App 是示例 scheme；workspace 工程还需传入自己的 -workspace，并确认 scheme 已共享。
Archive 成功不代表上传完成
上传还需要有效的签名、导出配置及上传凭据。示例假定项目已配置 fastlane；Build 214 不是你的交付回执，以上传工具实际输出为准。
把机器交给明确的任务
接入 self-hosted runner
MergeMac 提供独享物理节点，CI 的仓库权限、任务配置与凭据由你管理。先用同一个执行用户在终端跑通 archive，再注册 runner，避免把环境问题误判成调度问题。
GitHub Actions
- 进入目标仓库或组织的 Actions runner 设置，选择 macOS 与匹配的 Apple Silicon 架构。
- 在租用节点上按当前页面给出的命令下载、校验并注册 runner。注册 token 属于敏感信息，不写入仓库或截图。
- 增加标签，例如
mergemac、macos、m4。用 workflow 的runs-on匹配这些标签。 - 提交只检查 Xcode 版本的任务，确认被正确节点接收，再加入依赖安装、archive 与上传步骤。
不要让不可信的外部合并请求直接使用持有签名材料的 runner；将发布任务与普通验证任务分开授权。
GitLab Runner
- 在项目或组中创建 runner，取得当前注册流程要求的服务地址与认证 token。
- 在节点安装匹配架构的 GitLab Runner，按生成的指引完成注册；需要本机 Xcode 工具链时选择合适的 Shell 执行方式。
- 设置
macos、xcode等标签，并在任务中显式声明。发布 runner 只允许受保护的分支或标签使用。 - 先跑环境检测任务，核对工作目录、执行用户与钥匙串访问，再启用正式构建。
token 更新或租期结束前，在 CI 平台撤销该 runner 的授权；只删除节点文件不会自动撤销平台授权。
读懂控制台里的词
八个术语，一次说明白
这些词描述资源与连接方式，不代表额外的软件授权，也不把多台机器自动合成一台更大的 Mac。
- 物理节点
- 机房中可独立分配的一台 Mac mini，运行真实的 macOS 开发环境。
- 独享
- 租期内整机 CPU、GPU、统一内存与本机磁盘资源只分配给一个租户。
- 非虚拟机
- 直接使用物理 Mac 上的系统，不是共享宿主机内划分出的虚拟实例。
- VNC
- 用于远程查看和操作 macOS 图形桌面的连接协议。
- SSH
- 用于加密命令行登录、执行命令与传输文件的连接协议。
- self-hosted runner
- 安装在你租用节点上的 CI 执行器，由你的流水线配置分派构建任务。
- 统一内存
- Apple 芯片 CPU 与 GPU 共同使用的内存，实际可用空间还需扣除系统和其他进程占用。
- Thunderbolt 5 并联
- 通过 Thunderbolt 5 直连多台设备开展多机实验，仍需应用自身支持任务分发。
先保存证据，再改环境
按症状缩小范围
记录失败时间与时区、实例编号、完整报错和最近一次改动。每次只改一项，再执行同一个验证动作；重装不是第一步。
-
01
VNC 黑屏或无响应
先看控制台实例是否就绪，再测试 SSH 能否连接。SSH 可用而图形桌面异常时，检查是否正在登录、注销或切换图形会话，退出客户端后重新建立连接。
仍然黑屏时保留客户端版本与截图，提交工单。不要为了试错直接关闭防火墙或反复强制重启，正在运行的构建可能因此中断。
-
02
Xcode 版本不一致
分别运行
xcode-select -p与xcodebuild -version。交互会话和 runner 都要检查；安装多个版本不代表命令行已切换。单个任务可用
DEVELOPER_DIR指向目标 Xcode 的 Developer 目录，避免更改全机默认版本影响其他任务。目录不存在时先确认安装路径，不要照抄示例名称。 -
03
Simulator 占满磁盘
用
df -h看剩余空间，再检查 DerivedData、archive、设备数据与模拟器 runtime。先导出需要保留的构建产物，停止正在使用模拟器的任务。xcrun simctl delete unavailable可删除不可用的模拟器设备记录；它不等于删除全部 runtime。清理前确认对象，不要对项目目录或钥匙串执行递归删除。 -
04
签名证书失效
区分证书过期、描述文件失效、私钥缺失和钥匙串未解锁。检查证书有效期、团队与 bundle identifier 是否匹配，再核对 CI 执行用户是否能读取对应私钥。
更新证书后同步更新描述文件与受保护变量，用同一 scheme 重新验证。工单只附错误代码与脱敏日志，不发送私钥、证书导出密码或完整签名材料。
先备份，再确认重装
重装会改变环境，不会保留工作区
系统重装与租期结束后的数据清除是两个不同环节。不要把租用节点当作源码、签名材料或构建产物的唯一存储位置。
租期内自助重装
进入控制台实例详情，使用系统重装操作前，先停止 CI 调度，导出项目、产物和必要配置，并确认备份能在其他位置打开。
初始化通常需要数分钟，实际耗时与完成状态以控制台返回为准。任务进行中不要反复提交；完成后重新读取连接凭据，核对主机指纹并重建开发环境。
重装后重新验证 SSH、Xcode、依赖与 runner；不要假定旧的服务配置仍然存在。
到期后的磁盘清除
租期结束后，节点进入数据清除与系统重置流程，再用于后续交付。需要保留的数据应在到期前主动导出，不以到期后仍能连接作为备份方案。
同时撤销代码仓库部署密钥、CI runner token 和上传凭据。磁盘擦除处理节点内的数据，不会替你撤销外部系统的访问授权。
有数据处理或安全边界问题，先查看安全说明，再通过控制台工单确认具体实例情况。
让下一次回复直接进入排查
把问题交给支持人员
已租用实例的问题优先提交控制台工单，方便关联订单与节点；无法登录、售前咨询或安全报告，统一发送到支持邮箱。请勿在多个渠道反复创建同一问题。
控制台工单
登录后进入工单区，填写实例编号、影响范围和复现步骤。已有工单的故障升级直接补充原工单，保留同一条排查记录。
建议格式：发生时间与时区 → 预期结果 → 实际报错 → 已尝试操作。附上脱敏后的最短日志片段，不要整包上传源码。
登录并提交工单支持邮箱
无法进入账户时，在邮件主题中说明问题类别，并提供注册邮箱及可用于核对的订单编号；不要发送账户密码或付款卡号。
支持按亚太与美国东部时区协作处理。首响取决于问题级别与当前队列，具体进展以工单或邮件回复为准，不在此承诺未经公布的平均时长。
support@mergemac.com接好环境，再把构建交给它
已有机器，先从控制台确认状态；准备新增构建节点，直接选择租用配置。每台都是独享物理 Mac mini，非虚拟机。