这是一份按执行顺序编排的工程指南。先核对设备与网络，再检查 Xcode、签名和 CI 环境，最后处理存储、升级与恢复，避免在多个变量之间反复试错。
连接 → 环境 → 构建 → 数据
六类入口分别处理身份确认、系统变更、开发工具、自动化任务、网络路径和订单信息。每类都给出先查什么、保留什么，以及何时提交工单。
获取连接资料、核对主机指纹、建立 SSH 会话，并在启用图形界面前排除基础网络问题。
进入连接顺序 02 / SYSTEM在系统变更前保存数据、版本与恢复材料，验证工具链后再推进长期任务所用设备。
查看升级与恢复 03 / TOOLCHAIN按证书、描述文件、Keychain 权限、DerivedData 与构建日志的顺序定位 Xcode 失败。
进入 Xcode 排障 04 / RUNNER核对执行器身份、工作目录、缓存边界、密钥注入方式和失败后的可重复回滚路径。
查看执行器清单 05 / NETWORK用有线网络、固定样本量和相同时间段比较五个节点，先区分本地接入与跨境路由影响。
查看延迟测量 06 / ORDER使用订单号和设备标识关联问题，不在日志或工单中提交完整卡号、私钥或账户密码。
准备工单材料不要在主机地址、端口和凭据尚未核对时反复切换客户端。下面四步应按顺序完成，每一步都为下一步提供可验证的输入。
登录控制台，在对应订单中核对设备标识、所选节点、主机地址、SSH 端口和当前凭据。多台设备并行使用时，先把订单号与设备标识一一对应。
首次连接应把客户端显示的指纹与控制台记录比对。设备重装后若指纹发生变化，先确认变更记录，再清理本地旧条目，不能直接忽略警告。
ssh-keygen -R example-host
ssh -p 22 user@example-host先从有线网络测试 DNS、端口与 SSH。成功后记录登录时间、出口网络和命令行响应；失败时保留完整错误信息，不要只截取“连接失败”一行。
只有 SSH 基线稳定后，才继续核对图形界面所需的地址、端口、客户端版本和本地防火墙。画面卡顿时同步记录分辨率、编码设置与网络时延。
下表用于展示从主要城市到新加坡、日本（东京）、韩国（首尔）、香港、美国西部的路由差异。数据是选点参考，不是应用吞吐、图形界面帧率或任务完成时间承诺。
| 测试源 | 运营商 | 新加坡 | 日本（东京） | 韩国（首尔） | 香港 | 美国西部 |
|---|---|---|---|---|---|---|
| 上海 | 中国电信 | 71 ms | 42 ms | 46 ms | 34 ms | 141 ms |
| 深圳 | 中国联通 | 44 ms | 55 ms | 59 ms | 18 ms | 157 ms |
| 北京 | 中国移动 | 91 ms | 48 ms | 39 ms | 63 ms | 138 ms |
使用网线直连，暂停大文件同步、视频会议和系统更新。连续测试本地网关与节点地址，如果两者同时抖动，应先处理本地接入。
远程交互还受丢包、抖动、上行带宽和客户端编码影响。提交网络问题时，应同时提供运营商、城市、测试时段、样本量与路由追踪结果。
同一个错误可能来自证书不可用、描述文件不匹配、Keychain 无访问权限、缓存污染或构建参数差异。先保存原始日志，再按下面顺序检查。
确认目标证书存在、未过期，证书与私钥能够配对，并且当前构建用户可以读取。先列出签名身份，不要直接重新导入全部材料。
security find-identity -v -p codesigning
核对 Bundle Identifier、团队标识、证书类型、设备范围与能力声明。手动签名项目应确认配置实际指向目标文件，而不是旧缓存。
CODE_SIGN_STYLE / PROVISIONING_PROFILE_SPECIFIER
CI 用户与交互登录用户可能使用不同的 Keychain 搜索列表。确认目标 Keychain 已解锁、加入搜索路径，并允许构建进程读取私钥。
security list-keychains
先记录当前路径与失败任务，再只清理对应项目的派生数据。不要把删除全部缓存当成第一步，否则会丢失可比较的构建证据。
xcodebuild -showBuildSettings
保存完整命令、Scheme、Configuration、SDK、Xcode 版本、退出码和首次失败位置。优先查看第一条根因错误，而不是最后一行汇总。
xcodebuild -version
独享物理 Mac 可以持续运行构建任务，但稳定性仍取决于身份、目录、缓存、密钥和回滚边界。每次变更应能回答“改了什么、如何验证、如何撤回”。
为每台设备使用可识别的执行器名称和标签，记录注册范围、服务用户与启动方式。避免多个执行器共用无法区分的名称。
按仓库、分支或任务建立独立目录，禁止并发任务写入同一 DerivedData、归档目录或依赖输出位置。
区分可重建缓存与必须保留的产物。清理前记录目录大小、最近使用时间和任务归属，避免全盘删除造成冷启动。
密钥只在任务需要时进入进程环境或临时 Keychain，日志中关闭回显，任务结束后删除临时材料并锁定访问。
更新执行器、Xcode 或依赖前保留版本记录。验证失败时恢复配置文件、工具链选择和缓存索引，而不是继续叠加修改。
路径至少包含项目标识、任务标识与尝试次数。清理动作只允许命中本次任务目录，避免误删并发构建。
WORK_ROOT="$HOME/ci-work"
JOB_DIR="$WORK_ROOT/$PROJECT/$RUN_ID"
mkdir -p "$JOB_DIR"保存执行器版本、工具链版本、完整退出码和首个根因日志。缓存命中率与磁盘余量也应写入任务摘要，便于比较前后差异。
附加存储和 Thunderbolt 5 并联会改变数据路径与权限边界。任何格式化、挂载点调整或设备断开动作，都应先确认数据副本和任务停止状态。
重要代码、素材、构建产物和配置至少保留一份独立副本。尚未验证的挂载卷不能作为唯一存储位置。
记录卷名、文件系统、容量、设备标识与预期挂载点，避免仅凭显示顺序判断目标磁盘。
确认运行构建或媒体任务的用户拥有所需目录权限，不要通过全局放宽权限绕过归属问题。
先用可删除的测试文件验证创建、读取、重命名和删除，再迁移真实工作目录。
标明每台 Mac、线缆方向、共享存储与任务角色。不要在无法识别上下游设备时调整连接。
确定由哪台设备写入、哪些设备只读，并为自动化任务设置独立目录，避免并发覆盖。
每增加一台设备就完成一次连接、权限和读写测试，不要完成全部接线后再集中排查。
先停止写入和构建任务，确认缓存已落盘，再卸载卷并从链路末端开始断开设备。
所有节点全年 365 天正常运行，平台不安排周期性停机。macOS 与工具链升级由用户根据任务节奏安排变更时段，先在非关键任务上验证，再推进长期执行器。
导出代码状态、依赖锁文件、Homebrew 清单、Xcode 路径、证书名称、Keychain 列表、执行器配置与磁盘余量。
把私有配置、签名材料、构建产物和项目数据迁出到独立位置，并实际验证至少一个文件可以恢复。
核对目标 macOS、Xcode、命令行工具、包管理器、执行器和项目依赖的兼容范围，记录必须保留的旧版本。
停止 CI 队列、素材处理与数据同步，确认没有进程继续写入工作目录、缓存或附加存储。
升级后依次验证 SSH、磁盘、Xcode 版本、证书读取、依赖恢复、测试、归档和产物下载。
保存首个成功任务的耗时、日志、缓存状态与磁盘余量，再逐步恢复并发任务，不要一次放开全部队列。
不要在根因未明确时连续升级多个组件，否则日志无法区分系统、工具链与项目配置的影响。
现有订单问题请在控制台提交工单并附上设备标识、复现步骤和完整错误上下文。尚未下单的配置问题，可通过唯一支持邮箱联系。
support@vmdebug.com