连接问题
SSH 或图形桌面无法进入
从地址、端口、密钥权限、主机指纹和凭据有效性开始。能连 SSH 但图形会话异常时，再检查分辨率、锁定状态和会话恢复。
节点运行支持
先定位故障层，再执行下一条命令
这里集中整理独享 Apple Silicon 物理节点的连接、构建、运行器、网络与存储排查路径。每一步都给出检查对象、命令和可用于判断下一步的返回结果。
已有节点时，请先记录节点编号和问题发生的时间范围；尚未订购时，可先查看三档在售配置与四个可选节点。
RUNBOOK / NODE CHECK
L0—L4
L0
节点状态
核对节点编号、区域与控制台返回状态
先确认
L1
连接链路
地址、端口、密钥权限与主机指纹
SSH
L2
工具链
Xcode、签名材料、Keychain 与构建日志
BUILD
L3
任务运行
运行器进程、工作目录、缓存与并发任务
CI
L4
硬件路径
磁盘余量、外接 SSD、网络与 Thunderbolt 5
I/O
工单最小信息集
节点编号 + 时间范围 + 命令输出
选择排查入口
按故障发生的位置分流
不要在多个层面同时修改配置。先选择最接近现象的一类，完成其中的基础检查，再带着结果进入下一层。
SSH 快速诊断
从本地权限和握手过程开始
连接失败不一定意味着节点离线。先区分地址错误、端口不可达、本地密钥权限不合规、主机指纹变化和服务端拒绝认证。
连接检查命令
SSH / VERBOSE
$ chmod 600 ~/.ssh/orbvps_node
$ ssh-keygen -F node-address
$ nc -vz node-address 22
$ ssh -vvv -p 22 \
-i ~/.ssh/orbvps_node \
node-user@node-address
Permission denied
认证材料不匹配
确认用户名与私钥对应当前节点，并检查密钥是否被本地 SSH 配置中的其他 IdentityFile 覆盖。
Connection timed out
链路未建立
核对控制台显示的地址和端口，暂时停用本地代理规则后复测，并记录发生时间与所在网络。
Connection refused
目标可达但端口未接受连接
保留完整 verbose 输出，不要反复删除主机记录；先确认端口是否与节点交付信息一致。
REMOTE HOST IDENTIFICATION
主机指纹与本地记录不同
不要直接忽略警告。先将显示的指纹与控制台交付记录核对，确认节点信息后再更新本地记录。
核对连接参数
从控制台重新读取地址、端口和用户名，不使用旧终端历史中的地址猜测。
收紧密钥权限
私钥建议为当前用户可读写，SSH 配置与上级目录也不应允许无关用户修改。
保存握手输出
使用 verbose 模式重试一次，保留从连接开始到失败位置的完整输出并脱敏地址。
图形桌面连接
按凭据、显示、锁定、重连的顺序处理
图形会话与 SSH 是两条不同链路。SSH 正常并不代表图形会话配置一定正常，因此需要分别记录现象。
确认凭据归属
仅使用当前节点交付的图形会话凭据。凭据轮换后，清除客户端保存的旧密码，避免旧记录持续自动重试。
降低首次连接分辨率
黑屏或画面停滞时，先以较低分辨率和单显示器连接。进入桌面后再逐步提高尺寸，确认问题是否与显示参数相关。
检查会话锁定状态
若能看到锁定界面但无法继续，先验证键盘输入与焦点，再通过 SSH 检查系统负载和剩余磁盘空间。
断开后重新建立会话
先主动关闭客户端连接，等待会话释放后再重连。不要连续快速创建多个并行图形会话，以免混淆正在使用的桌面。
需要支持时记录两组结果
说明 SSH 是否正常、图形客户端停在哪一步、使用的分辨率、客户端错误原文与最近一次正常连接的时间范围。请勿提交完整访问密码。
Xcode 与签名
固定工具链，再缩小签名失败范围
先确认实际调用的 Xcode 路径和版本，再检查可用签名身份、描述文件、Keychain 访问与工程缓存。不要在同一次排查中同时升级依赖和更换签名材料。
确认 Xcode 与命令行工具
- 保存
xcodebuild -version的完整结果。 - 用
xcode-select -p核对当前 Developer 目录。 - 确认流水线与交互式终端使用相同的环境变量。
分开检查身份和描述文件
- 列出当前可用于代码签名的身份及其有效状态。
- 核对描述文件的应用标识、团队和有效期限。
- 确认构建进程能读取对应 Keychain，而不只是当前桌面用户可见。
建立可复现的干净基线
- 先保存失败日志，再清理目标工程对应的 DerivedData。
- 使用相同 scheme、configuration 和 destination 重跑。
- 归档原始
.xcresult，不要只提交终端最后几行。
签名与版本检查
XCODE / CODESIGN
$ xcode-select -p
$ xcodebuild -version
$ security find-identity \
-v -p codesigning
$ profiles show \
-type provisioning
$ xcodebuild \
-workspace App.xcworkspace \
-scheme App \
-configuration Release \
-resultBundlePath Build.xcresult \
build
日志边界
保留命令、scheme、configuration、失败目标、首个 error 及其上下文。提交前移除仓库凭据、令牌和业务数据。
CI/CD 运行器
确认任务究竟停在进程、目录还是资源层
self-hosted runner 显示在线不等于任务环境完整。检查运行器进程、工作目录权限、缓存占用、并发任务和重启后的自动恢复路径。
进程状态
确认运行器服务仍在预期用户下运行，启动参数指向正确配置。若进程反复退出，先保存退出码和最近日志。
ps aux | grep -i runner
工作目录
检查目录所有者、剩余空间和旧任务锁文件。不要直接删除仍被运行中任务占用的工作目录。
df -h && du -sh ./work
缓存策略
区分依赖缓存、DerivedData 和构建产物。先定位异常缓存键，再做单项目清理，避免一次清空所有可复用内容。
du -sh ~/Library/Developer/Xcode/DerivedData
并发与恢复
核对是否有多个任务竞争同一 Keychain、模拟器或工作目录。重启后先执行一条受控测试任务，再恢复正常队列。
uptime && sysctl -n hw.memsize
恢复顺序
暂停新任务 → 保存日志 → 结束异常进程 → 验证目录 → 启动运行器 → 执行单任务测试
如果测试任务成功而并发任务失败，请同时提供并发数量、任务标签和共享资源清单。
网络与存储
把链路质量、磁盘容量和设备识别分开验证
吞吐下降、构建变慢和外接卷消失可能表现相似。先采集系统内置诊断结果，再判断问题属于网络、文件系统还是外接设备路径。
网络
验证基础链路质量
使用系统内置网络质量工具记录上下行能力和响应性，同时记录测试所在时间范围。跨区域结果会受本地运营商与路径影响。
networkQuality -v
route -n get default
ifconfig
内部存储
检查容量与卷状态
先确认系统卷和数据卷的剩余空间，再定位占用最大的工作目录。构建失败时要特别检查临时目录和 DerivedData。
df -h
diskutil list
du -sh ~/Library/Developer/*
外接设备
确认 SSD 与 Thunderbolt 5 路径
分别检查磁盘列表和 Thunderbolt 设备树。设备可见但卷未挂载时，先采集状态，不要立即抹除或重新分区。
diskutil list external
system_profiler SPThunderboltDataType
diskutil info /Volumes/VolumeName升级与运行变更
先留回退基线，再安排重启验证
OrbVPS 节点全年 365 天正常运行，不设固定停机时段。涉及系统升级、工具链切换或需要重启的操作，由用户按工作负载自行安排；若基础设施出现必须处理的紧急变更，将通过控制台记录相关信息。
建立变更清单
记录当前 macOS、Xcode、运行器版本、关键依赖和可回退构建日志，不在无基线时直接覆盖工具链。
完成数据备份
备份仓库、签名材料、运行器配置、缓存策略和必要构建产物，并在独立位置验证备份能够读取。
安排用户侧重启时段
暂停新任务，等待运行中任务结束，保存日志后再重启。重启期间不要同时修改网络、签名和构建配置。
执行恢复验证
依次验证 SSH、图形桌面、磁盘挂载、Xcode 版本和一条受控构建任务，再恢复正常并发队列。