凭据是否对应当前节点
确认用户名、密钥或连接密码来自当前订单，不复用已结束订单的连接资料。检查密钥文件权限与复制过程中是否增加空格或换行。
恢复工作路径
从连接检查到构建日志，按顺序定位问题
面向 iOS、macOS、CI/CD 与 Apple Silicon 实验负载的排查手册。先确认节点与网络，再检查工具链和任务日志，避免同时改动多个变量。
5
级连接检查
4
类构建故障
6
个在售节点
运行单
先保留现场，再逐项排除
READY
A01
确认节点信息
区域、主机地址、连接方式、订单状态
01
A02
验证本地路径
DNS、端口、防火墙、丢包与抖动
02
A03
缩小工具链范围
Xcode、SDK、依赖、签名与测试
03
A04
提交最小证据集
发生时间、复现步骤、日志与影响范围
04
不要发送密码、私钥或恢复码
SUPPORT / NODE
首次接入
四步完成第一次连接
控制台提供当前订单对应的节点信息。复制字段时保留原始格式，不要手动猜测地址、用户名或端口。
-
01
读取节点字段
登录控制台，核对订单、区域、主机地址、用户名与允许的连接方式。节点位于新加坡、日本（东京）、韩国（首尔）、香港、美国东部或美国西部之一。
-
02
检查本地网络
确认办公网络没有拦截目标端口，关闭会改写路由的临时代理，并分别记录有线、无线或其他网络下的连接结果。
-
03
选择连接方式
命令行、文件同步和自动化任务优先使用 SSH；需要 macOS 图形界面时使用 VNC。首次测试只建立一种连接，避免结果相互干扰。
-
04
完成基线验证
登录后记录系统版本、磁盘可用空间、Xcode 路径与当前网络时间。先执行一个最小项目，再迁入完整工程和构建缓存。
首次登录只验证基础链路
不要在尚未确认连接稳定时批量上传项目、修改系统设置或注册 CI runner。先保留一组可复现的基线结果。
连接诊断
按固定顺序排查 SSH 与 VNC
连接失败时从身份信息向网络外层推进。每一步只改变一个条件，并保留命令输出或错误提示。
端口是否能从本地到达
用控制台显示的端口执行连通性测试。超时通常指向网络路径，立即拒绝通常说明目标可达但服务或端口不匹配。
本地防火墙是否拦截
检查终端安全软件、企业出口策略与路由器规则。换用另一条已知可用网络复测，可快速区分本地限制与节点侧问题。
网络路径是否稳定
记录延迟、抖动与丢包，不只看一次 ping。VNC 对连续抖动更敏感，SSH 构建也可能因下载连接重置而中断。
节点状态是否正常
回到控制台核对实例与订单状态。若不同网络均无法连接且凭据无误，保留发生时间与错误原文后提交节点异常工单。
工具链核对
Xcode 问题先检查版本选择，再检查工程
同一提交在不同工具链下可能产生不同结果。把系统环境与项目依赖分开验证，才能判断故障属于节点、工具链还是仓库配置。
版本与路径
- 运行
xcodebuild -version，记录 Xcode 与构建版本。 - 运行
xcode-select -p，确认 Command Line Tools 指向预期目录。 - 检查脚本中是否写死旧版 Xcode 路径。
SDK 与依赖
- 确认 scheme、destination 与 SDK 名称存在。
- 重新解析 Swift Package、CocoaPods 或其他项目依赖。
- 比较锁文件、依赖源和下载失败的具体地址类型。
签名环境
- 核对构建配置读取的签名变量是否存在。
- 确认 CI 进程能访问所需材料且不会把内容写入日志。
- 将签名失败与编译失败分开重跑并记录退出码。
BASELINE
推荐的最小环境快照
sw_vers
xcodebuild -version
xcode-select -p
df -h
自动化接入
把 self-hosted runner 当作受控执行器
runner 注册成功不代表工作流已经安全可复现。执行范围、工作目录、凭据与并发策略需要同时落地。
注册并标注执行器
使用项目或组织提供的短期注册信息，设置能表达芯片、区域和用途的标签。注册完成后删除本地临时命令记录。
交付物：runner 名称与标签清单限制可执行范围
只允许可信仓库、受保护分支与明确工作流调用节点。外部贡献触发的任务应经过审核，不让未知脚本直接取得节点权限。
交付物：仓库与分支授权规则清理工作目录
在任务前后处理临时文件、派生数据和无效缓存。保留缓存时记录键名、来源与失效条件，避免旧产物污染新构建。
交付物：清理脚本与缓存策略轮换访问凭据
令牌、SSH 密钥与签名材料进入受控密钥流程。成员离开团队、仓库权限变化或出现异常日志后立即撤销并重新签发。
交付物：凭据负责人和轮换记录
日志分流
从第一条有效错误判断构建故障类型
不要只截取日志末尾的通用退出码。保存完整日志，在首次出现错误的位置向上读取目标、命令和依赖上下文。
| 故障类别 | 常见日志信号 | 先检查 | 工单应附内容 |
|---|---|---|---|
| 依赖解析 | 包版本冲突、仓库拉取失败、锁文件不一致 | 锁文件、依赖源、缓存键与网络下载结果 | 依赖管理方式、失败包名、首次错误段 |
| 签名配置 | 证书匹配失败、权限不可用、配置变量缺失 | scheme、构建配置与密钥注入流程 | 脱敏后的错误原文与构建目标 |
| 测试失败 | 断言失败、模拟环境差异、测试超时 | 失败用例、destination、并行参数与重试结果 | 用例名、退出码、可复现命令 |
| 网络下载 | 连接重置、解析失败、下载超时 | 同地址重复请求、DNS、代理与出口路径 | 发生时间、目标类型与网络测试结果 |
01
保留完整原始日志
02
定位第一条有效错误
03
用最小命令独立复现
04
删除凭据后提交节选
数据操作
项目、缓存与附加 SSD 分开管理
容量增加不能替代数据分类和备份。先定义哪些内容必须保留，再决定同步、缓存和迁出的方式。
项目同步
优先通过版本库同步源码，将大体积二进制和私有依赖放入受控存储流程。首次迁移后比较提交哈希、子模块与锁文件。
- 源码与配置分开核验
- 记录大文件同步方式
- 迁移后执行最小构建
缓存清理
DerivedData、包缓存和 runner 工作目录都可能影响复现。删除前记录目录大小与缓存键，清理后比较构建时间和错误变化。
- 先测磁盘可用空间
- 只清理能重新生成的内容
- 避免并发任务同时改缓存
附加 SSD 边界
附加 SSD 用于需要更多工作空间的工程、缓存或数据集。挂载点、读写路径与任务权限应在投入正式工作前确认。
- 明确数据落盘位置
- 监控增长速度与剩余容量
- 迁出前验证文件完整性
迁移前由用户保留必要副本
项目数据、签名材料、凭据和构建产物应按团队策略备份。租期结束前完成迁出并验证副本可读取，不把节点上的单一副本视为长期归档。
工单证据集
一次提交足够进入排查的信息
支持请求越具体，越容易直接进入复现与定位。先说明影响，再给时间线和最小日志，不发送任何秘密值。
请求模板
复制字段并填写事实
CASE
- 节点区域
- 新加坡、日本（东京）、韩国（首尔）、香港、美国东部或美国西部
- 发生时间
- 写明当地时间和时区，并说明问题持续或间歇出现
- 复现步骤
- 从登录、执行命令到出现错误，按实际顺序列出
- 日志节选
- 包含第一条有效错误、退出码和前后必要上下文
- 影响范围
- 单个任务、单个成员、全部构建或整个节点连接
- 已完成检查
- 列出更换网络、重试命令、清理缓存等已执行动作及结果
不要提交这些内容
密码、私钥、恢复码、完整令牌、签名材料以及完整付款凭据。日志中若包含秘密值，请先删除或替换为明确的脱敏标记。
关联现有订单
登录控制台创建工单并选择对应订单，有助于支持人员核对正确的节点与服务记录。
登录控制台创建工单
升级路径
按问题类型进入对应处理队列
连接中断、节点异常和计费疑问需要不同证据。选择正确分类并在同一会话中补充材料，避免上下文被拆散。
凭据正确但无法建立 SSH 或 VNC
附上本地网络类型、目标端口测试、错误原文与发生时间。若换用另一网络后恢复，也应写明两次测试的差异。
分类：连接与访问多个任务同时失败或节点状态异常
说明影响范围、最后一次正常时间、实例状态和最小复现命令。不要通过连续重启或批量改配置覆盖原始现场。
分类：节点运行订单周期、附加项或付款记录需要核对
提供订单标识、计费周期、相关附加项与问题描述。所有订单均以美元（USD）结算，不在工单中发送完整付款凭据。
分类：订单与账务
持续跟踪同一会话
进入控制台跟踪工单
处理进度、补充问题与最终结论均在控制台对应工单中更新。补充新日志时标明采集时间和本次改动，便于对照前后结果。
准备好节点信息，再开始一次可复现的排查
新订单可直接选择两档配置与六个节点；现有订单问题请登录控制台提交关联工单。