工程师可执行的排查路径

先定位问题，再用最短步骤恢复云端 Mac。

从首次 SSH 连接、Xcode 工具链到 CI/CD 执行器和节点网络，本页先给检查命令，再说明判断条件。若仍无法恢复，可携带订单号、节点、时间与脱敏日志提交工单。

进入控制台提交工单 查看首次连接步骤
优先路径
4 步完成首次连接
问题范围
6 类常见任务
人工入口
邮箱与控制台工单
ONCEMAC SUPPORT BOARD 节点检查单
可开始排查
A1
确认连接资料 主机地址、用户名、密钥文件
连接
B2
确认工具链 Xcode、CLT 路径、构建日志
构建
C3
确认运行边界 磁盘、网络、进程与重启记录
节点
提交前请移除密钥、访问令牌与完整 IP
快速定位

按任务找答案，不必从头阅读。

选择连接、Xcode、CI/CD、存储、网络或续租，页面会保留相关入口。也可以输入命令、现象或工具名称检索。

当前显示全部 6 类帮助入口。

首次连接 核对地址、用户名、密钥权限与 SSH 命令。 Xcode 工具链 确认版本、Command Line Tools、签名环境和日志。 CI/CD 接入 检查执行用户、工作目录、并发、缓存与退出码。 文件与环境迁移 使用 rsync、Git 与 Brewfile 重建可重复环境。 故障诊断 按连接、构建、磁盘、网络和重启现象逐项缩小范围。 续租与订单 在控制台核对租期、续租记录、账单和节点状态。
首次使用优先

四步建立第一次 SSH 连接。

连接资料以控制台实例详情页显示为准。不要根据旧工单或历史命令猜测主机地址，节点重新交付后应重新复制当前信息。

  1. 01

    复制当前连接资料

    进入控制台的实例详情，复制主机地址、SSH 用户名、端口与密钥信息。先确认所选订单和节点一致，再把命令放入本地终端。

  2. 02

    把私钥保存到受控目录

    将密钥文件放在本地用户可控目录，不要提交到 Git 仓库、构建产物或团队聊天记录。文件名可自定义，但后续命令路径必须对应。

  3. 03

    收紧本地文件权限

    macOS 或 Linux 本地终端执行 chmod 600 ~/.ssh/oncemac_key。若 SSH 提示私钥权限过宽，应先修正权限，不要通过关闭安全检查绕过。

  4. 04

    连接并核对节点身份

    执行控制台给出的 SSH 命令。首次连接时核对主机指纹来源；进入节点后运行 hostname、sw_vers 与 whoami，确认主机、系统和当前用户。

命令执行顺序

先验证连接和版本，再启动完整构建。

一次排查只改变一个变量。先确认 SSH 会话稳定，再读取 Xcode 版本，最后执行带结果包和日志的构建命令。这样能区分连接问题、工具链问题和工程自身问题。

  • 连接层SSH 成功后记录节点名与当前用户。
  • 工具层确认当前生效的 Xcode 与开发者目录。
  • 工程层保留 scheme、destination、退出码和日志。
  • 自动化层只截取已脱敏的 fastlane 输出用于工单。
once-node / build-diagnostics
SSH 
$ ssh -i ~/.ssh/oncemac_key user@host
Last login: current session
connected: once-node

$ xcodebuild -version
Xcode 16.x
Build version 16x

$ xcode-select -p
/Applications/Xcode.app/Contents/Developer

$ set -o pipefail
$ xcodebuild \
  -workspace App.xcworkspace \
  -scheme App \
  -destination 'generic/platform=iOS' \
  -resultBundlePath ./BuildResults.xcresult \
  build | tee build.log

** BUILD SUCCEEDED **

$ bundle exec fastlane ios build
[fastlane] resolving dependencies
[fastlane] archive completed
[fastlane] lane finished successfully
工具链核对

把 Xcode 问题拆成版本、路径、签名与日志。

“本地能构建、节点不能构建”通常不足以定位原因。应对照同一提交、依赖锁文件、scheme、destination 与环境变量，再比较两端输出。

XC-01

确认 Xcode 版本

运行 xcodebuild -version，记录主版本和 Build version。若流水线依赖特定版本，应在任务开始处输出版本，而不是只在初次配置时检查。

xcodebuild -version
xcrun --find simctl
swift --version
XC-02

确认开发者目录

运行 xcode-select -p 检查 Command Line Tools 当前路径。若使用多个 Xcode 版本，应在执行器环境中明确 DEVELOPER_DIR，避免交互会话与自动化任务读取不同路径。

xcode-select -p
echo "$DEVELOPER_DIR"
xcrun --sdk iphoneos --show-sdk-path
XC-03

检查签名环境

先确认钥匙串可访问、证书名称与 provisioning profile 条件匹配，再检查工程的 Team、Bundle Identifier 和签名方式。工单只需提供脱敏后的错误段，不要附带证书、私钥或密码。

security list-keychains
security find-identity -v -p codesigning
xcodebuild -showBuildSettings
XC-04

导出可复查日志

通过 set -o pipefail 保留真实退出状态，同时用 tee 写入日志。复杂失败建议生成 .xcresult，并在分享前移除用户名、路径、令牌和业务数据。

set -o pipefail
xcodebuild build | tee build.log
echo "${PIPESTATUS[0]}"
自动化执行器

接入 CI/CD 前，先固定执行身份与工作目录。

OnceMac 提供独享物理节点和完整 macOS 命令行环境。具体平台功能、插件兼容性与任务定义应由团队在自己的仓库和版本条件下验证。

RUNNER / 01

GitHub Actions 自托管执行器

  • 确认执行器服务使用的 macOS 用户与手动 SSH 测试用户是否一致。
  • 检查仓库、组织或企业范围的注册位置，避免任务被分配到错误标签。
  • 为节点设置可识别标签，并在工作流中显式使用对应 runs-on 条件。
  • 验证非交互 shell 能读取所需 PATH、Ruby、Homebrew 与 Xcode 路径。
  • 并发任务开始前确认 DerivedData、包管理器缓存与磁盘余量。
RUNNER / 02

GitLab Runner

  • 核对 executor 类型、runner 标签、保护分支规则与任务匹配条件。
  • 确认 LaunchAgent 或服务进程的用户、HOME 和钥匙串上下文。
  • 在任务首段输出 whoami、pwd、Xcode 版本和可用磁盘。
  • 缓存键应包含依赖锁文件或工具链版本，避免复用不兼容缓存。
  • 失败时同时保留 job 日志、退出码与 runner 服务状态。
RUNNER / 03

Jenkins 节点

  • 确认 agent 启动方式、工作目录和节点标签符合 Pipeline 条件。
  • 检查 Jenkins 执行用户能否读取仓库、构建目录和必要钥匙串。
  • 将 Xcode 选择、依赖安装和构建命令写入可审查的 Pipeline。
  • 限制同一物理节点上的并发执行器数量，避免磁盘和内存争用。
  • 归档前记录 workspace 大小、构建结果路径和清理策略。
可重复迁移

迁移文件，不复制无法审计的旧环境。

优先从 Git、锁文件和 Brewfile 重建工具链，只迁移确实需要的工作目录与缓存。整目录复制旧用户环境会把过期配置、绝对路径和敏感凭据一起带入新节点。

MIGRATION MANIFEST 环境迁移清单
源代码 Git 克隆并核对提交哈希 不要复制包含未提交秘密的旧工作树
系统工具 Brewfile 声明式恢复 恢复后重新检查版本与 PATH
项目文件 rsync 增量传输 明确排除缓存、日志和凭据目录
构建缓存 按工具链版本选择性迁移 版本变化时优先重新生成

用 rsync 迁移工作目录

先用预演模式检查将要复制和删除的内容，再执行正式同步。目标路径中的删除行为必须由操作者确认。

rsync -avhn \
  --exclude '.git' \
  --exclude 'DerivedData' \
  ./Project/ user@host:~/Project/

用 Git 固定代码状态

在源节点记录分支、提交哈希与未提交变更。新节点完成克隆后核对哈希，再恢复依赖，不用压缩包代替版本记录。

git status --short
git rev-parse HEAD
git clone repository-url
git checkout commit-hash

用 Brewfile 重建工具

导出前审查列表，移除不再需要的软件。恢复后逐项验证命令版本，不能仅以安装命令退出成功作为环境可用依据。

brew bundle dump --file Brewfile
brew bundle check --file Brewfile
brew bundle install --file Brewfile
迁移前单独核对敏感凭据

SSH 私钥、仓库令牌、签名材料、环境变量文件和服务密钥不应随项目目录批量复制。确认新节点的最小权限后，通过团队认可的安全流程重新配置。

故障最短路径

先排除可验证条件，再提交完整上下文。

下面五类问题都按“确认现象、运行最小命令、记录结果、停止无效改动”的顺序处理。展开对应项目即可查看检查清单。

无法连接 SSH 超时、拒绝连接或密钥认证失败
  1. 从当前实例详情重新复制主机地址、端口与用户名，确认没有使用旧订单信息。
  2. 执行 chmod 600 检查本地私钥权限，并确认命令中的密钥路径存在。
  3. 使用 ssh -vvv 获取连接阶段，但提交工单前移除完整地址、用户名和密钥路径中的个人信息。
  4. 切换到另一条可信网络复测，用于区分本地出口限制与节点连接问题。
  5. 工单附订单号、节点、发生时间、错误类型和脱敏后的调试末段。
构建失败 xcodebuild、依赖解析或签名阶段退出
  1. 记录提交哈希、scheme、destination、Xcode 版本和开发者目录。
  2. 清晰区分依赖解析失败、编译失败、测试失败、签名失败和归档失败。
  3. 使用 set -o pipefail 保留真实退出码，并导出 .xcresult 或完整日志。
  4. 不要同时升级依赖、切换 Xcode 和清理全部缓存；一次只改变一个变量。
  5. 工单附首个关键错误前后日志，移除仓库令牌、签名材料和业务数据。
磁盘不足 构建中断、归档失败或工作目录持续增长
  1. 运行 df -h 查看卷余量，再用 du -sh 定位工作区、DerivedData、归档与依赖缓存。
  2. 确认日志、测试结果和历史产物是否有明确保留周期，而不是直接删除整个用户目录。
  3. 清理前保存仍需下载的构建产物，并确认没有正在运行的任务使用对应目录。
  4. 若长期容量需求超过基础 SSD，可在方案中评估 +1TB SSD 或 +2TB SSD 附加选项。
  5. 工单附磁盘占用摘要、增长目录和失败任务时间，不要上传项目源文件。
网络波动 SSH 卡顿、依赖下载失败或仓库连接不稳定
  1. 分别记录本地到节点、节点到目标仓库或依赖源的现象，不要把两段链路混为一个结论。
  2. 连续采样时记录测试地点、运营商、节点、命令和样本数量，单次 ping 不能代表持续体验。
  3. 检查 DNS 解析、代理环境变量、Git 远端和包管理器源是否符合团队配置。
  4. 用另一条可信本地网络进行对照，避免把本地 Wi-Fi 或出口策略误判为节点异常。
  5. 工单附发生时间范围、目标类型、失败比例和脱敏输出。
节点重启 会话中断、服务未恢复或执行器离线
  1. 先在控制台查看当前节点状态，不要连续重复发送电源操作。
  2. 恢复连接后运行 uptime，核对启动时间与问题发生时间是否一致。
  3. 检查自托管执行器、GitLab Runner 或 Jenkins agent 的启动方式与当前服务状态。
  4. 确认构建工作区是否完整，并重新验证未完成任务的产物，不沿用状态不明的归档。
  5. 工单附订单号、节点、发生时间、重启前后现象和需要恢复的服务名称。
人工支持

一次提交足够信息，减少往返确认。

现有订单、节点状态和续租问题优先通过控制台工单提交；尚未下单的配置与使用范围问题可发送邮件。对外联系邮箱仅为 support@oncemac.com。

SUPPORT PACKET 工单信息包
01

订单与节点

提供订单号、配置名称和节点区域，不要提供付款凭据或完整账单资料。

02

发生时间

写明时区、首次发生时间、最后一次复现时间，以及问题是否持续。

03

复现动作

列出执行命令、预期结果、实际结果和退出码，避免只写“不能使用”。

04

脱敏日志

保留错误上下文，移除密钥、令牌、密码、完整 IP、签名材料与业务数据。

05

已做检查

说明已验证的网络、版本、路径、磁盘和重试结果，避免重复执行无效步骤。

现有订单

通过控制台提交工单

适合节点连接、构建异常、账单、续租与订单状态问题。工单会关联登录账户，便于核对实例上下文。

进入控制台
售前与一般咨询

发送结构化邮件

请写明用途、目标节点、Xcode 版本、并发构建数、存储需求与期望启用时间。

support@oncemac.com
独享物理 Mac mini 节点

需要新节点，直接选择配置与租期。

OnceMac 提供 3 档在售配置与 6 个节点，全年 365 天正常运行。所有订单以美元结算，可在控制台统一管理订单、节点与工单。

立即租用云端 Mac 联系团队