确认设备状态
先登录控制台查看实例是否处于可用状态，并核对订单对应的设备名称与节点。若控制台显示设备可用但两种连接方式都失败，继续检查网络；不要先改系统配置。
- 核对订单号、设备标识和节点。
- 确认不是连接到旧记录中的地址。
- 记录控制台显示状态与检查时间。
从现象开始排查
先定位问题，再执行下一步
输入错误信息、工具名称或连接方式。页面不会只给概念解释，而会把设备状态、日志位置、验证命令和升级人工支持所需资料按顺序列清。
快速分流
按当前现象选择检查路径
先选最接近的现象，再沿页面中的顺序检查。不要在尚未确认网络与磁盘状态时直接重装 Xcode、依赖或 Runner。
首次连接
连不上设备时，按五个检查点缩小范围
连接问题通常发生在状态、凭据、网络或客户端配置中的一层。保持检查顺序，可以避免把网络故障误判成设备故障。
核对访问凭据
区分系统用户名、初始密码和 SSH 密钥。复制凭据时检查首尾空格；密钥认证失败时，先确认使用了正确私钥和用户名，不要连续尝试不同组合。
- 确认用户名大小写与输入法状态。
- 检查私钥文件权限是否过宽。
- 凭据异常时在控制台提交工单。
验证本地网络
切换到另一条可信网络复测，并暂时排除公司代理、VPN、出口防火墙和安全软件规则。记录目标地址、端口、发生时间与超时文本。
- 分别测试域名解析与目标端口。
- 比较家庭网络与公司网络结果。
- 不要只提交“连接失败”四个字。
检查远程桌面
确认客户端保存的地址、用户名和显示设置仍对应当前设备。若画面可打开但输入迟滞，先降低分辨率和颜色质量，再检查本地网络抖动。
- 删除客户端中的旧连接记录后重建。
- 截取错误文本，不提交敏感凭据。
- 对比 SSH 是否能独立连接。
检查 SSH 配置
使用详细输出确认失败发生在解析、握手还是认证阶段。若能握手但认证失败，重点检查用户名、私钥和授权文件；若连接直接超时，回到网络路径检查。
ssh -vvv user@host
chmod 600 ~/.ssh/id_ed25519
ssh-add -l
安全边界
支持请求中不要提交密码、私钥、恢复码、完整支付凭据或未脱敏证书。需要展示配置时，只保留与故障有关的字段。
Xcode 与签名
把版本问题、签名问题和归档问题分开验证
不要用一次完整发布任务同时验证所有环节。先确认工具链版本，再用测试项目验证签名，最后回到真实项目读取归档日志。
检查项
验证结果
XCODE
版本与命令行工具一致
确认图形界面所选版本、命令行路径和项目要求一致。切换版本后重新打开终端与构建进程。
xcode-select -p
CERT
证书可被当前用户读取
确认所需证书及其私钥完整导入，并能在当前登录会话中访问。不要只看到证书名称就判断导入成功。
security find-identity -v -p codesigning
PROFILE
描述文件与目标匹配
核对应用标识、团队、能力和有效范围。清理旧描述文件前先保存清单，避免无法回退。
~/Library/MobileDevice/Provisioning Profiles
KEYCHAIN
非交互任务具备访问权限
图形界面能归档而 CI 失败时，重点检查 Runner 会话使用的 Keychain、解锁流程和访问控制。
security list-keychains
ARCHIVE
保留第一条根因错误
从归档日志中定位最早出现的失败，不要只复制末尾汇总。记录目标、配置、SDK 与执行命令。
xcodebuild -showBuildSettings
CI/CD 故障手册
任务不执行时，先查 Runner，再查任务本身
持续集成故障需要按调度、执行环境、资源和脚本四层拆开。直接重复运行只会覆盖现场日志，并不能证明问题已经恢复。
| 现象 | 优先检查 | 处理顺序 | 恢复标准 |
|---|---|---|---|
| Runner 离线 | 进程、网络、注册信息、执行用户 | 确认设备可达，再读取服务日志；核对注册范围和启动用户，不要先重新注册。 | Runner 持续在线，并成功领取一个最小测试任务。 |
| 任务长期排队 | 标签、并发上限、已有任务 | 确认任务标签能匹配 Runner；检查是否存在未结束进程或被占用的执行槽。 | 新任务能在预期队列中被领取，旧任务退出状态明确。 |
| 缓存恢复失败 | 缓存键、目录权限、剩余磁盘 | 比较成功任务与失败任务的缓存键；验证目录所有者，再清理可重建缓存。 | 依赖恢复完成，且下一次任务能复用同一缓存规则。 |
| 脚本权限错误 | 执行位、解释器、工作目录 | 确认脚本已进入仓库并保留执行位；检查首行解释器与相对路径。 | 脚本在 Runner 用户的非交互会话中执行成功。 |
| 构建超时 | 最后活跃阶段、CPU、内存、磁盘 | 先找最后一条有效日志，再判断是进程阻塞、资源不足还是网络依赖等待。 | 相同提交连续完成，耗时与基线接近且没有遗留进程。 |
RUNNER BASELINE
保留一条最小健康检查任务
健康检查只验证工作目录、磁盘、工具链路径和一个短测试。它不应包含发布凭据，也不应依赖大型缓存。
whoami
pwd
df -h
xcodebuild -version
git --version性能与存储
用三组证据判断任务为什么变慢
一次任务变慢不足以判断需要更高配置。至少同时查看活动监视器、磁盘容量和构建日志，并与同一项目的正常基线比较。
CPU 与内存
观察整个任务周期，而不是只看某一秒。CPU 长时间满载且任务持续推进，属于计算负载；内存压力持续升高并伴随大量交换，才说明并发或项目规模可能超出当前配置。
- 记录
- 峰值、持续时间、并发任务数
- 排除
- 遗留模拟器、未退出编译进程
磁盘与缓存
先统计项目、依赖、模拟器、归档和可重建缓存的占用。磁盘接近容量边界时，依赖解压、归档和日志写入都可能异常。清理前应区分产物与可重建数据。
- 检查
- DerivedData、归档、模拟器、包缓存
- 验证
- 清理后重新运行同一提交
构建日志与工具链
若资源曲线正常但任务停在同一脚本、依赖下载或编译阶段，应检查版本变化、网络依赖和脚本等待条件。对比成功日志能比单看总耗时更快找到偏移点。
- 比较
- 同一提交、同一工具链、同一命令
- 定位
- 第一处明显偏离基线的阶段
A
资源持续饱和
降低并发复测；若耗时随并发稳定变化，再评估更高配置。
B
磁盘接近容量边界
清理可重建缓存、归档旧产物，并建立任务后清理规则。
C
资源正常但阶段卡住
检查脚本、依赖源、工具链版本和非交互权限。
节点与网络
四个在售节点，使用同一套网络记录格式
NUMACS 提供新加坡、日本（东京）、韩国（首尔）和香港节点。所有目录组合均可订，实际可用状态以控制台实时返回为准。
SG充足
新加坡
适合从东南亚及周边网络接入。诊断时记录本地运营商、目标地址、连接方式和发生时间。
选择新加坡节点JP充足
日本（东京）
连接异常时分别测试远程桌面与 SSH，并注明问题是否只出现在特定本地网络。
选择日本节点KR充足
韩国（首尔）
提交网络问题时附上超时或断连时间段，以及同一设备在另一条网络下的复测结果。
选择韩国节点HK充足
香港
若交互延迟突然变化，记录目标地址、使用协议、客户端版本和当时正在运行的任务。
选择香港节点
网络工单记录
一条可复核的网络报告应包含什么
请同时提供发生时间与时区、所在节点、目标地址、使用协议、本地网络类型、完整错误文本，以及更换网络后的复测结果。若执行诊断命令，请提交脱敏后的文本结果，不要只提交截图中的局部数字。
- 时间：精确到分钟并注明时区
- 路径：本地网络、目标地址与端口
- 结果：超时、拒绝、认证失败或断连
- 对照：另一网络或另一连接方式的结果
账单与周期
先核对订单周期，再核对支付记录
设备支持按天、周、月或季租用。订单金额统一以美元（USD）结算，周期和配置以订单记录为准。
按天
适合短期验证、临时构建或迁移演练。提交账单问题时注明订单开始时间与设备标识。
按周
适合一段连续冲刺或版本验收。核对时不要把自然周与订单实际周期混为一谈。
按月
适合稳定开发与持续集成工作流。升级配置前先导出必要数据并确认迁移安排。
按季
适合持续项目与固定 Runner。团队应提前记录凭据轮换、备份与任务交接流程。
提交前复核
避免让排查回到起点
以下问题决定支持人员能否直接进入复现与定位，而不是先来回补充基础信息。
远程桌面和 SSH 都失败，应该先提交什么？
先确认控制台中的设备状态，再提交订单号、节点、发生时间与时区、目标地址、两种连接方式的完整错误文本，以及更换本地网络后的复测结果。不要提交密码或私钥。
Xcode 构建失败后，是否应该立即重装工具链？
不建议。先保存第一条根因错误、Xcode 版本、命令行工具路径、项目配置与最近变更。重装会改变现场状态，也可能删除能够定位问题的版本差异和日志。
Runner 离线时，重新注册是不是最快办法？
先检查设备连接、Runner 进程、执行用户和服务日志。只有确认注册信息损坏或已失效后才重新注册。否则新旧 Runner 记录可能同时存在，让调度问题更难判断。
日志应该怎样脱敏？
保留时间、命令、错误码、工具版本和与故障有关的路径结构；替换用户名、仓库地址、访问令牌、证书内容、私钥和业务数据。脱敏后重新阅读一次，确认上下文仍足以复现。
怎样让紧急构建故障更快进入排查？
在主题中注明构建故障，并提供订单号、节点、发生时间、可复现步骤、期望结果、实际结果和脱敏日志。请求会按信息完整度排队处理；上下文越完整，越能减少补充确认。