按命令与错误关键词定位

从连接节点到交付 iOS 构建产物。

面向首次使用者、发布工程师和 CI/CD 维护者。输入命令、错误片段或任务名称，先缩小问题范围，再按预期输出逐项核对。

当前显示 8 个操作入口。

立即租用 Mac 构建节点 联系技术团队
RUNBOOK / OAK-06 构建节点验收索引
01
连接入口SSH · VNC · 屏幕共享
核对
02
构建环境Xcode · 签名资产 · 缓存
核对
03
任务执行runner 标签 · 隔离目录
核对
04
交付结果archive · export · logs
归档
排查原则 一次只改变一个变量
操作入口

先按症状进入对应卷宗

每个入口都给出核对对象、命令或观察指标。筛选只改变下方入口，不会隐藏完整操作章节。

CONNECTION

首次连接与本机检查

从控制台取得连接信息，核对 SSH、图形界面、密码与时区。
BUILD

iOS 自动化归档与导出

确认 Xcode 工具链、签名输入、归档路径和构建产物保存规则。
AUTOMATION

CI/CD runner 接入

区分平台注册、节点标签、并发边界和每次任务的工作目录。
DISPLAY

远程画面调优

按分辨率、色彩、帧率和网络抖动逐层排除交互卡顿。
GLOSSARY

构建环境术语

统一节点、runner、缓存和签名资产的含义，减少协作歧义。
DIAGNOSTICS

命令式故障诊断

把网络、磁盘、Xcode 与签名问题整理成命令、预期和分支。
ESCALATION

整理工单材料

提交区域、时间、任务编号与脱敏日志，让支持人员复现路径。
STORAGE

缓存与产物空间检查

区分可重建缓存、归档结果和必须保留的发布产物。
首次连接

先确认入口，再改变节点设置

连接信息以控制台当前实例详情为准。不要从旧工单、聊天记录或历史脚本复制地址与凭据。

建议顺序 · 4 项

首次登录验收单

先建立一种稳定连接，再检查密码与时区。不要同时切换网络、分辨率和认证方式，否则难以判断哪个变量造成变化。

  1. 01

    从控制台读取当前连接信息

    核对节点区域、主机地址、端口、用户名和实例状态。凭据只保存在受控密码管理工具中，不放入代码仓库或构建日志。

  2. 02

    先用 SSH 验证基础链路

    执行 ssh -v user@host 查看解析、握手和认证阶段。若在建立连接前超时，先检查本地网络与端口；若认证失败，再核对用户名和当前凭据。

  3. 03

    按任务选择图形连接

    需要操作 Xcode 界面时使用 VNC 或屏幕共享。先保持默认分辨率和色彩设置，确认键盘、鼠标及剪贴板行为正常后再调画质。

  4. 04

    完成首次登录检查

    更换初始密码，运行 date 和 systemsetup -gettimezone 核对时间与时区，并确认项目目录归属当前任务用户。

自动化打包

把构建输入与产物路径写进卷宗

一次可复现的 iOS 构建，需要固定工具链、项目入口、签名资产、归档参数和导出位置。仅记录“构建失败”不足以复查。

01 / TOOLCHAIN

锁定 Xcode 命令行工具

先运行 xcode-select -p 与 xcodebuild -version，确认脚本实际调用的开发者目录和 Xcode 版本。切换版本后重新执行这两项，不依赖终端窗口标题判断。

02 / SIGNING

分离证书、私钥与描述文件

签名资产应按项目和环境控制访问范围。导入后使用 security find-identity -v -p codesigning 检查可用身份，不把证书密码输出到流水线日志。

03 / ARCHIVE

明确 workspace、scheme 与归档路径

脚本应显式指定 workspace 或 project、共享 scheme、configuration 和 -archivePath。构建机上不要依赖上一次 Xcode 图形界面的临时选择。

04 / EXPORT

导出结果与日志一并保存

通过 -exportArchive 和受版本控制的导出配置生成产物。保存归档、导出结果、构建日志及提交标识，失败时也保留可脱敏的诊断信息。

BUILD RECORD 归档命令骨架 
xcodebuild \
  -workspace App.xcworkspace \
  -scheme App \
  -configuration Release \
  -archivePath "$PWD/output/App.xcarchive" \
  clean archive
输入提交标识、依赖锁文件、Xcode 版本、scheme
输出归档目录、导出目录、原始日志、任务编号
失败保留退出码、首个错误段、环境版本，不保留敏感值
CI/CD 接入

runner 注册只是开始，隔离规则决定能否长期运行

OakVM 节点是独享物理机、非虚拟机。并发通过增加独享节点扩展；同一节点上的任务仍应明确队列、标签和工作目录边界。

GITHUB ACTIONS

用标签把项目路由到指定节点

  • 在仓库或组织范围创建 self-hosted runner，并记录注册归属。
  • 使用区域、芯片和用途标签，例如项目发布与日常测试分开。
  • 工作流通过 runs-on 精确匹配，不使用含义模糊的通用标签。
  • 任务结束后清理临时钥匙串、临时目录和仅本次运行需要的环境变量。
GITLAB CI

把 runner 范围和任务标签写清楚

  • 确认 runner 属于实例、群组还是项目，避免无关项目获得执行机会。
  • 在作业中声明 tags，并关闭不需要的未标记任务接收能力。
  • 为缓存设置项目级键，避免不同分支或不同应用共用不可兼容结果。
  • 保留作业编号、提交标识和 runner 名称，便于对应节点日志。
GENERIC RUNNER

通用 runner 先定义生命周期

  • 注册脚本、服务启动方式和日志位置应进入团队运行手册。
  • 每次任务建立独立工作目录，结束后按保留策略处理缓存与产物。
  • 为同一物理节点设置明确的并发上限，避免多个重型归档任务争用资源。
  • 节点全年 365 天正常运行，任务重试仍应设置上限并记录失败原因。

隔离基线：项目目录、构建缓存、签名资产和产物目录分别管理。不要用清空整台节点作为日常隔离手段，也不要让两个项目共享同一组可写签名目录。

远程画面

从画面负载向网络链路逐层排查

VNC 与屏幕共享的主观卡顿不一定来自节点计算负载。按固定顺序测试，可以区分编码压力、本地网络抖动和后台任务争用。

  1. 01

    降低分辨率

    先把显示分辨率降到当前操作所需的最低档，关闭不使用的额外显示区域。若响应明显改善，问题更可能与画面编码量有关。

    观察指针与窗口拖动
  2. 02

    减少色彩与动态内容

    暂停视频、动画预览和持续刷新的监控窗口。构建时关闭不必要的模拟器画面，观察静态编辑操作是否恢复稳定。

    比较静态与动态画面
  3. 03

    控制帧率预期

    代码编辑和发布操作通常不需要高帧率。先以输入响应和文字清晰度为目标，再逐步提升画面流畅度。

    记录输入延迟变化
  4. 04

    检查网络抖动

    对节点地址执行连续短时延迟测试，关注波动和丢包，而不只看单次最低值。切换本地网络后使用相同样本数量复测。

    保留样本摘要
  5. 05

    确认团队共享方式

    同一任务只保留一名主要操作者，其他成员通过构建日志和产物记录协作。多人同时操作图形界面会增加上下文冲突。

    明确当前操作者
术语小词典

先统一词义，再讨论配置与边界

以下术语用于 OakVM 页面、控制台与支持沟通。它们描述交付形态和工作流，不代表第三方平台对服务的背书。

物理节点
直接承载 macOS 与构建任务的 Apple Silicon 实体设备，是订单对应的计算单元。
独享
租期内节点计算资源由当前订单使用，不与其他客户的任务共享同一台物理机。
云端 Mac
部署在数据中心、通过网络访问的 Mac 环境，可用于图形操作、命令行构建和自动化任务。
非虚拟机
订单交付的是独享物理机，不是从共享宿主机切分出的虚拟计算实例。
VNC
远程查看和操作 macOS 图形界面的连接方式之一，体验受分辨率、画面变化和网络抖动影响。
self-hosted runner
注册到 CI/CD 平台、在自有或租用节点上领取并执行流水线任务的运行代理。
构建缓存
为减少重复下载或编译而保留的数据，例如依赖缓存和 DerivedData；它应可失效、可重建。
签名资产
完成应用签名所需的证书、私钥、描述文件及相关访问权限，应按最小权限管理。
故障诊断

每项检查都记录命令、预期输出和异常分支

先保存原始退出码和首个有效错误，再做修复。连续执行多种清理命令会丢失问题现场，也可能把依赖错误误判成节点故障。

云端 Mac 常见故障的命令式检查清单
检查对象 命令或动作 预期结果 异常分支
网络解析与可达性 ping -c 20 host
ssh -v user@host		 地址解析一致；样本无持续丢包；SSH 能进入握手和认证阶段。 解析错误时核对地址；连接前超时则更换本地链路复测；认证失败只检查当前用户名与凭据。
磁盘与构建空间 df -h
du -sh ~/Library/Developer/Xcode/DerivedData		 目标卷有足够空间保存源码、依赖、归档和导出结果；缓存体积在团队阈值内。 先转移必须保留的产物，再按项目删除可重建缓存；不要直接删除无法确认归属的归档目录。
Xcode 工具链 xcode-select -p
xcodebuild -version		 开发者目录和版本与流水线记录一致，命令可正常返回。 路径错误时显式切换工具链；版本不符时停止任务，避免生成不可比较的归档结果。
项目与 scheme xcodebuild -list -workspace App.xcworkspace 目标 scheme 可见，并且用于自动化的 scheme 已共享。 列表为空时检查工作目录和依赖生成步骤；scheme 不可见时检查项目共享设置与名称大小写。
签名身份 security find-identity -v -p codesigning 当前任务需要的签名身份可见，输出不包含失效或重复选择造成的歧义。 身份缺失时检查导入范围、钥匙串访问与描述文件匹配关系；不要把私钥或密码贴入公开页面。
归档与导出 保留 xcodebuild 退出码、归档路径和导出日志。 归档目录存在，导出结果与提交标识、任务编号建立对应关系。 从日志首个 error 开始排查；分别判断编译、签名、归档和导出阶段，不用最后一行概括整个失败。
RULE 01

一次改变一个变量

切换网络后保持画面设置不变；切换 Xcode 后保持源码提交不变。这样才能比较前后结果。

RULE 02

保留首个有效错误

后续报错往往是连锁结果。记录最早出现的错误段、退出码和对应命令。

RULE 03

日志先脱敏再共享

移除主机凭据、令牌、私钥内容和项目敏感路径，同时保留时间、任务编号和工具版本。

升级支持

无法自行定位时，提交一份可复查的任务记录

已有用户优先登录控制台提交工单；无法登录时发送邮件至 support@oakvm.com。两种渠道都不要求在公开页面粘贴连接凭据。

SUPPORT PACKET 建议附带 6 项信息
01节点区域

新加坡、日本（东京）、韩国（首尔）、香港、美国东部或美国西部。

02发生时间

写明日期、时间和时区，确保节点日志能对齐。

03任务编号

提供订单、实例或 CI 任务中的可识别编号。

04复现步骤

列出执行入口、命令和问题出现前的最后一个成功步骤。

05预期与实际

分别描述预期输出和实际输出，不只写“无法使用”。

06脱敏日志

保留错误上下文、退出码和版本，移除凭据、令牌与私钥内容。

独享物理机 · 非虚拟机 · USD 结算

需要一台可接入现有流水线的云端 Mac？

选择 OakVM M4 或 OakVM M4 Pro，在六个可选节点区域中配置租期。所有区域全年 365 天正常运行，实际可用性以控制台实时返回为准。

立即租用 Mac 构建节点 查看价格与配置