连接
SSH 或 VNC 无法建立会话
适用于连接超时、主机指纹变化、凭据被拒绝、图形会话中断或重连后显示异常。
查看连接诊断
问题分类
从现象对应到检查入口
六类问题同时展开，不需要逐个切换筛选。每张卡给出最常见的症状、优先检查项与对应的本页位置。
系统
工具链版本发生变化
适用于 Xcode 选择错误、命令行工具路径漂移、系统更新后依赖不兼容或环境变量失效。
查看维护方法
网络
拉取、上传或端口转发失败
适用于 Git 拉取中断、SFTP 传输失败、SSH 隧道不可达、DNS 解析异常或本地网络限制。
查看传输建议
存储
构建缓存占满本地磁盘
适用于 DerivedData、归档、依赖缓存或日志持续增长，导致构建失败、导出中断或写入速度下降。
查看空间检查
构建
签名、归档或自动化任务失败
适用于证书与签名文件不匹配、runner 环境不一致、依赖缓存污染或归档产物未生成。
查看构建维护
账户
订单或设备记录需要核对
适用于租期状态、设备标识、订单记录、通知邮箱或工单关联对象需要确认的情况。
进入控制台
连接诊断
按同一顺序缩小故障范围
不要同时重置凭据、切换网络和修改系统设置。先保留原始报错，一次完成一项检查，结果才可比较。
01
节点状态
在控制台核对设备标识、区域、租期与访问状态。确认正在操作的是目标设备，并记录状态变化出现的时间。
02
访问凭据
核对用户名、SSH 私钥路径和文件权限。不要把私钥、密码或完整连接凭据粘贴到邮件、聊天记录或普通日志中。
03
SSH 通道
先核验主机指纹，再使用详细输出定位失败阶段。区分 DNS、TCP 建连、密钥协商和用户认证，避免只凭“连接失败”判断原因。
04
图形会话
SSH 正常而 VNC 异常时，检查客户端地址、会话状态与分辨率设置。断线后先等待原会话释放，再使用同一设备记录重连。
05
系统防火墙
确认远程访问所需进程仍在运行，相关端口处于预期监听状态。修改规则前保存当前配置，便于问题扩大时回退。
06
本地网络
最后再更换本地网络进行对照。临时停用可能改写路由的代理或 VPN，并比较公司网络、家庭网络与移动热点下的结果。
远程桌面
让图形会话可恢复、可交接
VNC 适合需要 Xcode、预览器与图形工具的工作。连接前先保证 SSH 通道可用，图形会话异常时仍有命令行检查路径。
准备受控的 VNC 客户端
从可信来源安装客户端，保存设备名称而不是共享完整凭据。首次连接先核对目标区域和设备标识，再确认加密与键盘映射设置。
- 分别保存设备名称与访问地址
- 团队成员使用各自受控的访问方式
- 优先通过受控网络或 SSH 隧道连接
先调整分辨率，再判断流畅度
远程画面受分辨率、色彩深度和本地网络共同影响。先降低显示面积做对照，不要同时更换客户端、网络和系统显示设置。
- 从较低分辨率开始验证输入响应
- 避免在传输大文件时同步评估画面
- 记录异常出现前最后一次设置变化
锁定会话，不强制结束进程
短暂离开时锁定图形会话，避免直接关闭仍在执行构建的应用。断线重连后先确认原任务状态，再决定是否重新启动工具。
- 离开前保存工程与未提交改动
- 不要因画面冻结立即重复启动任务
- 成员离组后及时撤销其访问方式
构建环境
固定工具链，再清理可再生数据
持续构建最怕环境在任务之间无记录地变化。把版本选择、签名材料和缓存清理写进团队运行手册。
固定 Xcode 与命令行工具
在项目配置和 runner 初始化脚本中记录 Xcode 版本，执行任务前核对当前开发者目录。系统或 Xcode 发生变化后，先运行最小测试任务，再恢复完整流水线。
分离证书、签名文件与代码仓库
证书、签名文件、令牌和环境变量应由团队自己的秘密管理流程注入。不要将长期凭据提交到 Git，也不要把包含敏感字段的原始日志作为普通附件转发。
按来源清理缓存
先确认空间由 DerivedData、依赖缓存、归档、模拟器数据还是项目素材占用。优先删除可重新生成的数据，保留仍需回传的构建产物与问题现场。
环境核对单
执行任务前
- Xcode
- 版本与项目约束一致
- 开发者目录
- 指向目标工具链
- 签名材料
- 按任务临时注入
- 磁盘空间
- 覆盖缓存、归档与导出
- 最小测试
- 先验证拉取、编译与产物生成
变更一次一项
结果写入构建日志
网络与文件
把连接通道与文件通道分开验证
先用小文件验证路径和权限，再传输完整仓库、素材或构建产物。失败时记录方向、大小、时间和具体阶段。
只转发需要的端口
明确本地端口、目标地址与用途，避免开放宽泛监听。建立隧道后分别验证 SSH 本身与被转发服务，便于区分认证问题和应用问题。
先确认目录权限
使用专门的项目目录接收文件，先上传小样本并核对读写权限。大文件完成后检查大小或校验值，不以客户端进度条作为唯一结果。
限制仓库凭据范围
为自动化任务使用最小权限凭据，并限制到所需仓库。拉取失败时分别检查 DNS、远端可达性、主机指纹、凭据权限与仓库地址。
回传后再清理源文件
为产物附上任务标识、版本和校验信息。确认目标端已完整接收后，再清理节点上的中间文件，避免重复构建却无法还原原始结果。
知识文章
从操作步骤延伸到团队策略
以下文章按发布日期降序排列，覆盖系统升级、连接安全、服务选型、音视频、Unity iOS 构建和 M4 开发任务观察。
知识文章正在整理
完整文章发布前，可先使用本页的连接诊断、系统维护、网络传输与构建环境检查清单。
设备标识
控制台中显示的设备名称，不发送访问密码
区域
新加坡、日本（东京）、韩国（首尔）、香港或美国东部
问题时间
包含时区，并注明最后一次正常操作的时间范围
复现步骤
按执行顺序写出命令、操作和实际结果
脱敏日志
移除令牌、密钥、密码、仓库凭据和个人数据