无法连接
先区分设备不可达与凭据失效
记录控制台设备状态、SSH 或 VNC 的报错原文、本地网络环境、首次发生时间，以及是否只有单一访问方式失败。
准备：节点、来源网络、报错、时间
云端 Mac 技术支持
先定位故障层，再提交可复现的信息
连接问题从设备状态和凭据开始，构建问题从 Xcode、依赖与签名环境开始。CDNMac 提供独享物理机、非虚拟机；项目代码、开发者账户和签名资产仍由使用方管理。
已有订单时，请优先携带订单标识、所选节点、发生时间和脱敏日志。实际设备状态与可用操作以控制台实时返回为准。
6 类入口
按连接、构建、签名、网络、账单与节点分流
6 项材料
工单上下文一次准备完整
全年运行
节点全年 365 天正常运行
问题交接记录
从现象到可复现路径
信息完整后进入处理队列
01
确认故障范围
记录是单台设备、单个仓库、单次构建，还是所有连接方式均受影响。
- 设备状态
- 读取控制台当前结果
- 所选节点
- 记录订单对应区域
02
缩小问题层级
分别验证网络、系统访问、工具链、项目依赖与签名步骤，避免同时改动多项配置。
- 最小复现
- 保留稳定复现步骤
- 时间边界
- 标明首次与最近发生时间
03
交接必要证据
提交脱敏日志、期望结果和已尝试动作，不发送私钥、令牌、证书密码或完整支付凭据。
- 日志范围
- 包含命令、阶段与时间戳
- 期望结果
- 说明正常状态应是什么
先选择问题类型
六类入口，对应六组必要信息
先按主要现象归类，再准备对应材料。一个请求只保留一个主问题，有关联现象可在复现步骤中补充。
构建失败
定位失败发生在哪个构建阶段
说明 Xcode 与 Command Line Tools 版本、使用的锁文件、失败命令、目标 scheme、磁盘余量和日志中的首个有效错误。
准备：版本、命令、阶段、脱敏日志
签名问题
核对证书、描述文件与目标配置
提交脱敏后的签名报错、bundle identifier、目标环境和证书有效状态。不要提交证书密码、私钥或可直接使用的令牌。
准备：目标、标识符、有效状态、报错
网络异常
分开测试往返延迟与实际下载链路
记录来源运营商、网络类型、目标节点、连续样本的中位数，以及仓库拉取或依赖下载是否同样异常。
准备：运营商、网络类型、样本、目标
账单疑问
按订单项目核对基础配置与附加项
提供订单标识、租用周期、基础配置、SSD 或 Thunderbolt 5 并联项目名称。不要在工单中填写完整支付凭据。
准备：订单、周期、配置、附加项
节点迁移
先说明迁移动机与数据交接范围
记录当前节点、目标连接方向、需要保留的工作目录和产物，并说明是否允许重新部署环境。可选范围以控制台实时返回为准。
准备：当前节点、目标方向、数据范围
连接排查
按固定顺序检查，避免把网络问题误判为设备故障
每完成一步再进入下一步，并记录结果。不要在排查过程中同时替换密钥、修改防火墙和重启本地网络，否则难以判断真正原因。
01
读取设备状态
先在控制台确认订单与设备状态，核对当前节点和设备标识。若状态正在变化，等待控制台返回稳定结果后再测试连接。
02
核对访问凭据
确认使用的是当前设备对应的系统用户名、主机地址与最新凭据。不要把其他订单的连接资料混用到当前设备。
03
验证 SSH 连通性
从可信网络测试主机与端口是否可达，再检查密钥文件权限和认证错误。保存带时间戳的报错，不要提交私钥内容。
04
验证 VNC 会话
若 SSH 正常而图形会话异常，单独记录 VNC 客户端、连接阶段和画面状态，避免把图形会话问题归入基础网络故障。
05
检查本地防火墙
核对公司网络、VPN、出口策略和本机防火墙是否限制目标端口。可在另一条可信网络上复测，用于判断问题是否来自本地链路。
单次 ping 只能反映当时的网络往返时间，不能直接代表 VNC 流畅度、依赖下载速度或完整构建耗时。请结合持续样本与实际任务复测。
构建排查
从工具链版本走到首个有效错误
构建日志常包含后续连锁错误。优先找到第一个导致流程中断的有效错误，再核对它对应的工具、依赖、签名或磁盘条件。
Xcode 与目标 SDK
记录 Xcode 完整版本、目标平台、scheme、configuration 和实际调用的工具路径。图形界面与命令行使用的版本应保持一致。
Command Line Tools
确认当前选中的开发者目录与预期版本一致。升级 Xcode 后，重新验证命令行工具指向，避免脚本调用旧路径。
依赖与锁文件
保留项目使用的锁文件，记录依赖恢复命令和缓存策略。先在干净工作目录复测，再判断是否为缓存污染。
证书与描述文件
核对有效状态、bundle identifier、目标环境和签名配置是否匹配。只提交脱敏错误，不提交私钥或证书密码。
磁盘余量与临时目录
检查源码、依赖缓存、DerivedData、Archive 和导出产物共同占用的空间。空间不足时先清理可重建缓存。
日志时间戳与失败阶段
保留任务开始、首个错误、任务结束三个时间点，标明失败发生在依赖恢复、编译、Archive、签名还是导出阶段。
CI/CD 接入
把独享物理机注册为受控的 self-hosted runner
CDNMac M4 可承接仓库触发的 iOS 构建任务。接入 GitHub Actions、GitLab CI、Jenkins 或其他调度系统时，应把执行节点视为长期存在的构建主机，而不是一次性容器。
- 为每个仓库创建独立工作目录，不在多个项目间复用未清理的构建缓存。
- 令牌只授予执行任务所需的最小权限，并为不同仓库分别配置。
- 签名资料放在受控位置，流水线日志不得输出密钥、令牌或证书密码。
- 任务完成后清理临时文件、派生数据和不再需要的产物副本。
- 为 runner 设置明确标签，避免不兼容任务被错误调度到该设备。
构建任务交接单
RUNNER / M4
A1
队列
接收受信任务
按仓库、分支和 runner 标签决定是否接受任务。
B2
工作区
恢复依赖
使用锁文件与仓库专属缓存，记录缓存命中情况。
C3
归档
执行 Archive
固定 Xcode 路径、scheme、configuration 与导出参数。
D4
产物
交付与清理
复制必要产物后清理临时目录，保留脱敏诊断日志。
隔离单位：仓库
凭据策略：最小权限
清理时点：任务结束
术语小词典
八个常见词，先统一排查语境
工单中使用一致术语，可以更快区分物理设备、访问协议、自动化执行器和最终交付文件。
- 云端 Mac
- 通过网络远程使用的 Mac 设备。CDNMac 提供的是独享物理机，不与其他订单共享同一台设备。
- 物理节点
- 设备实际部署和接入网络的区域位置。选区会影响连接路径，但不能单独决定完整构建耗时。
- 独享
- 一个订单对应一台设备的资源与访问环境，不把计算资源拆分给多个租用方共同运行。
- 非虚拟机
- 工作负载运行在实际 Mac 硬件上，而不是把一个宿主机切分成多个虚拟实例。
- VNC
- 用于访问 macOS 图形界面的远程会话方式，适合需要查看界面状态或进行图形操作的任务。
- SSH
- 面向命令行、脚本和文件传输的加密连接方式，适合自动化任务与日常系统操作。
- self-hosted runner
- 注册到持续集成系统、由团队自行管理的任务执行器。它在指定云端 Mac 上接收并运行流水线任务。
- 构建产物
- 编译、Archive 或导出流程生成的文件及必要日志，应复制到团队控制的存储并设置保留策略。
提交工单前准备
六项材料齐全，再进入控制台提交
完整上下文比重复发送短消息更有助于复现。敏感字段只说明类型与状态，不提交可直接使用的明文内容。
01
订单标识
提供控制台中的订单标识或设备标识，用于确认对应的机型、租期和设备记录。
02
所选节点
写明当前设备所在节点，不要只写“亚洲”或“美国”。需要迁移时，再说明目标连接方向。
03
发生时间
记录首次发生、最近一次复现和任务结束时间，并注明时区，便于对应设备与网络记录。
04
复现步骤
按顺序写明输入、命令、目标和结果。若问题不是每次出现，请补充出现频率与触发条件。
05
脱敏日志
保留错误上下文与时间戳，移除私钥、令牌、证书密码、个人资料和完整支付凭据。
06
期望结果
说明正常情况下应该看到的状态、文件或返回值，并列出已经尝试过且无效的动作。
服务边界
哪些问题由我们协助，哪些内容由团队维护
先区分设备与网络、系统访问、工具链建议和项目自身责任，能减少在错误层级反复修改配置。
硬件与网络状态
协助核对设备状态、节点侧网络、订单对应关系和控制台可见的管理状态，并根据可复现信息继续处理。
CDNMac 协助范围系统访问协助
协助判断设备是否可达、凭据是否对应当前设备，以及 SSH 与 VNC 问题处于网络、认证还是会话层。
CDNMac 协助范围构建工具排查建议
可根据日志协助梳理 Xcode、Command Line Tools、磁盘和构建阶段，但项目依赖与脚本仍需由项目团队验证。
共同排查范围项目与开发者资料
项目代码、开发者账户、证书、描述文件、访问密钥、软件许可、依赖版本和工作负载合法性由使用方维护。
使用方维护范围
安全提醒
把凭据、签名资料和构建产物纳入同一套退出流程
独享设备减少了资源共享边界，但不会替代团队自身的权限管理。首次连接、持续运行和租期结束都应有明确操作清单。
使用最小权限
CI 令牌、仓库密钥和自动化账户只授予当前任务需要的权限，不让多个项目长期共用同一组高权限凭据。
定期轮换凭据
建立密钥与令牌轮换记录。成员、仓库或任务边界变化时，及时撤销不再需要的访问权限。
移除过期证书
定期检查证书和描述文件的有效状态，删除不再使用的副本，避免旧配置被流水线误选。
提前导出必要产物
在租期结束前复制源码变更、构建日志、Archive 和必要产物到团队控制的存储，并验证文件可读取。