核对开通信息与凭据
从控制台复制当前实例的主机地址、端口和用户名，确认没有混用旧订单信息。检查输入法、大小写、首尾空格和密码管理器自动填充结果。不要把密码、私钥或完整连接串放进截图和工单正文。
问题分流
从出现症状的环节开始
不要一次改动多个变量。每轮只调整连接方式、客户端设置、构建参数或网络路径中的一项，并保留调整前后的结果。
远程连接排查
按凭据、链路、会话顺序检查
先确认连接目标没有写错，再检查端口和客户端。不要通过反复重置凭据掩盖网络或会话层问题。
验证端口连通
在本地终端使用 nc 检查指定端口。成功建立 TCP 连接只说明端口可达，不代表图形会话已经正常；超时则应继续记录本地网络、运营商和目标节点。
nc -vz "$TARGET_HOST" "$TARGET_PORT"检查屏幕共享状态
确认实例处于运行状态，图形会话服务可用，并且当前账户具备远程会话权限。如果命令行可连接但画面无法建立，应把问题限定在图形服务、客户端协商或会话残留，而不是继续改网络配置。
降低显示参数做对照
先用单显示器、较低分辨率和较低画质建立基线，再逐项恢复缩放、色彩质量与多屏设置。若低分辨率稳定而高分辨率出现卡顿，应同时采集延迟、丢包和客户端编码设置。
清理旧会话后重连
正常退出客户端，等待旧连接释放后重新建立会话。避免多个客户端同时连接同一图形会话。重现中断时，记录精确到分钟的时间、客户端版本、是否切换网络，以及命令行连接是否同时受影响。
系统层快速检查：若能够进入命令行，可依次确认系统时间、磁盘剩余空间、内存压力和高占用进程。时间偏差可能影响证书与构建签名，磁盘不足则常表现为依赖安装、缓存写入或归档阶段失败。
CI/CD 排查
把失败限定到 Runner、环境或任务
先运行一个不读取项目密钥、不执行依赖安装的最小任务。最小任务通过后，再逐层加入仓库、缓存、签名材料与归档步骤。
注册与在线状态
核对 Runner 是否注册到正确项目或组织、标签是否匹配、执行器是否处于在线状态。若任务一直排队，先检查标签和并发限制，再看 Runner 进程，而不是直接重跑完整流水线。
ps aux | grep -i runner
launchctl list | grep -i runner签名环境
确认构建进程使用的账户、钥匙串搜索路径、证书可见性和描述文件范围一致。日志只保留证书名称、失效阶段和错误文本；提交前移除密码、私钥内容和完整签名材料。
security list-keychains
security find-identity -v -p codesigning缓存目录
把依赖缓存、派生数据和最终产物放在不同目录。缓存命中异常时，先记录缓存键和目录占用，再对单个项目执行清理，避免一次删除所有工作目录而失去对照样本。
du -sh "$CACHE_PATH"
df -h
find "$CACHE_PATH" -maxdepth 1 -type d构建队列
记录排队开始、实际执行和结束时间，区分“任务未被领取”与“任务已启动但长时间无输出”。前者重点查标签、并发与 Runner 状态，后者重点查脚本等待、网络依赖和子进程。
日志采集
保留失败步骤前后至少各 50 行日志，同时附命令退出码、工具版本和项目中可公开的最小复现参数。不要只提交一张错误弹窗截图，也不要上传包含令牌、仓库凭据或业务数据的完整日志包。
xcodebuild -version
sw_vers
uname -m失败重试
首次失败后先保存原始日志，再用相同提交和相同参数重试一次。若重试成功，比较网络请求、缓存命中和执行耗时；若稳定失败，则缩小到单一命令，并记录其输入、退出码和持续时间。
网络诊断工作台
用同一目标连续采样
单次 ping 不能代表链路质量。请在问题发生期间和恢复后各采集一组结果，并保持本地网络、目标地址与命令参数一致。
延迟与丢包
连续发送 20 个数据包，保存最小值、平均值、最大值和丢包比例。
ping -c 20 "$TARGET_HOST"路由路径
路径结果用于定位延迟从哪一跳开始变化。部分路由器不回应探测并不等于链路中断。
traceroute "$TARGET_HOST"DNS 查询
记录解析结果、响应时间与当前使用的 DNS 服务器，区分解析问题和目标端口问题。
dig "$TARGET_HOST"
scutil --dns上下行与响应能力
使用 macOS 自带工具采集上下行容量、响应能力与空闲延迟。测试期间暂停大文件同步和其他高带宽任务。
networkQuality -v
跨境链路会随运营商路由和本地网络负载波动。节点选择不应只看直线距离；请分别对新加坡、日本（东京）、韩国（首尔）和香港的可用目标进行实际测试，再结合团队位置与主要工作时段判断。
存储与数据处理
把源码、缓存、产物和备份分开
存储问题通常不是单一容量数字。目录边界、写入权限、可恢复副本和迁移时间都应在首次构建前确定。
工作目录规划
- 源码目录只保存仓库内容和必要配置，避免混入大型构建产物。
- 依赖缓存与派生数据使用独立目录，便于按项目清理和统计占用。
- 归档、安装包和调试符号使用带任务标识的产物目录。
- 临时文件设置清理规则，清理前确认没有正在执行的构建。
应用级备份责任
- 对源码、数据库、签名材料和不可重新生成的产物建立独立副本。
- 定期验证备份能否读取，不以“任务已上传”代替恢复测试。
- 密钥与凭据使用受控存储，不写入仓库、构建日志或共享目录。
- 租期结束前完成导出并核对文件数量、校验值和目标端可读性。
扩展 SSD 识别
添加扩展存储后，先检查系统是否识别设备、卷是否已挂载、文件系统是否可写，再调整构建目录。不要在任务运行中切换缓存或产物路径。
diskutil list
df -h
mount迁移前检查
- 停止会继续写入数据的构建、同步和后台任务。
- 先复制小样本验证权限、文件名和符号链接处理方式。
- 完整迁移后比较目录大小、文件数量与关键文件校验值。
- 在目标环境完成一次读取或构建测试后，再清理原目录。
服务可用率
以连续监测记录核对影响
状态记录用于判断服务端影响范围。具体测量窗口、排除事项、申请条件、服务抵扣与适用范围以服务条款为准。
目标可用率
99.9%
节点全年 365 天正常运行。不可抗力、用户自身操作、用户侧网络和工作负载配置造成的影响不计入平台可用率。
近 90 天逐日状态
90 DAYS
正常
存在受影响记录
若认为订单受到平台侧服务事件影响，请保留订单标识、节点、首次发现时间、恢复时间和连续探测记录，并通过控制台工单提交。是否符合服务抵扣条件及抵扣方式以服务条款的具体规则为准。
查看服务条款提交支持请求
一次提供可以开始排查的上下文
技术支持请求应围绕一个问题组织。不同节点、不同订单或不同故障阶段请分开描述，避免时间线互相覆盖。
必须提供的六项信息
-
01
订单标识
提供控制台中的订单或实例标识，不要发送账户密码。
-
02
目标节点
明确写出新加坡、日本（东京）、韩国（首尔）或香港。
-
03
故障时间
包含日期、时区、开始时间、持续时间以及是否已经恢复。
-
04
预期与实际结果
分别说明希望发生什么、实际看到什么，不只写“无法使用”。
-
05
复现步骤
列出从正常状态到故障出现的最短步骤，以及重试是否稳定复现。
-
06
脱敏日志
附错误步骤前后的日志、命令退出码和必要截图，移除令牌、密码、私钥、支付凭据及业务数据。
日志应如何脱敏？
保留错误码、时间、命令名称、工具版本、路径结构和退出码；替换访问令牌、密码、私钥、仓库地址中的凭据、用户真实姓名与业务数据。脱敏后应再次搜索常见密钥前缀和邮箱地址。
网络问题至少附哪些结果？
至少附一组连续 ping、一次 traceroute、问题发生时间、目标节点、本地城市与运营商，并说明切换有线、Wi-Fi 或移动热点后结果是否变化。
构建失败是否需要上传完整项目？
通常不需要。先提供失败命令、退出码、前后日志、工具版本和最小复现步骤。若必须提供样本，应移除业务代码、密钥、签名材料与生产数据，只保留能够重现问题的最小结构。