连接问题
地址可达但无法进入会话
先核对节点地址、端口、用户名和凭据，再检查本地网络限制、客户端加密选项与会话状态。不要反复尝试旧凭据。
打开连接检查步骤
支持入口总览
按症状进入对应检查路径
不要同时修改网络、系统版本和构建配置。一次只改变一个变量，保留原始错误文本与时间点，才能判断问题属于连接层、环境层还是项目层。
Xcode 构建
编译、归档或上传失败
记录失败阶段，随后检查磁盘空间、Xcode 与 SDK 版本、依赖锁文件、签名材料和完整构建日志。优先保留第一条实际错误。
查看构建诊断顺序
CI/CD
Runner 离线或任务不调度
检查 runner 服务进程、注册状态、标签匹配、工作目录权限与并发上限。平台显示在线，不代表当前任务标签一定能够命中。
核对 runner 配置
存储扩展
缓存与构建产物占满空间
区分源码、依赖缓存、DerivedData、归档和交付产物的占用。先导出必要文件，再按目录清理，不要直接删除无法确认用途的数据。
阅读存储常见问答
节点迁移
团队位置或仓库位置发生变化
先记录当前节点、仓库托管区域、主要操作者位置和大文件传输方向，再评估迁移。迁移前必须准备代码与构建产物的独立副本。
比较节点与网络
账单问题
订单、周期或支付状态需要核对
准备订单号、所选配置、计费周期、支付方式与控制台显示状态。仅提交交易标识，不要发送卡片完整信息或任何私钥。
在控制台提交账单工单
首次使用路径
先把节点基线固定，再安装项目工具
首次进入节点时，先完成连接与安全检查，再配置开发环境。这样可以把系统问题与项目依赖问题分开，后续复现更直接。
-
01
从控制台取得连接信息
核对订单对应节点、服务器地址、端口、用户名和临时凭据。连接信息只用于当前授权成员，不通过聊天记录或公共文档转发。
完成标志：能够稳定建立会话，并确认进入的是订单对应节点。 -
02
完成账户安全设置
首次进入后更新临时凭据，创建满足团队权限策略的系统账户，确认管理员操作仅交给需要安装工具或调整服务的成员。
完成标志：临时凭据不再使用，日常账户与管理账户的用途已区分。 -
03
记录系统与开发基线
记录 macOS 版本、芯片、可用磁盘、Xcode 版本、命令行工具路径与目标 SDK。团队应把这些信息写入自己的构建运行手册。
完成标志：能够用同一组版本信息解释本地与云端构建差异。 -
04
安装依赖与 runner
按项目锁文件安装依赖，设置独立缓存目录，再注册 self-hosted runner。首次任务先使用低并发验证签名、归档和上传路径。
完成标志：一条最小构建任务可以重复执行，并留下完整日志。
建议保留的环境清单
- macOS 与 Xcode 完整版本号
- 目标 SDK、命令行工具路径
- 依赖管理器与锁文件版本
- Runner 名称、标签和工作目录
- 缓存目录与最大并发任务数
用最小任务确认链路
先拉取一个确定可构建的提交，只运行依赖安装、编译和归档。确认成功后，再加入并行任务、缓存恢复和交付步骤。
检查连接前准备
构建故障诊断
按失败链路逐项排除，不同时改六个变量
构建问题通常沿着空间、签名、版本、依赖、日志和并发六层展开。每完成一层就重新运行同一提交，记录结果是否变化。
01
容量
磁盘空间
分别检查系统卷可用空间、DerivedData、依赖缓存、归档目录和导出产物。空间不足时先保存必要产物，再按目录清理。
02
签名
证书与描述文件
确认项目选择的团队、证书有效状态、描述文件目标与 Bundle Identifier 一致。不要在日志或工单中附带签名私钥。
03
版本
Xcode 与 SDK 版本
记录实际执行构建的 Xcode 路径，确认命令行工具没有指向另一版本，并核对项目要求的目标 SDK 是否存在。
04
依赖
依赖缓存
对照锁文件判断缓存是否过期。先尝试不恢复缓存的干净构建；若成功，再逐个恢复依赖缓存以定位不一致来源。
05
日志
完整构建日志
保留执行命令、退出码与第一条实际错误。只截取最后一屏常会漏掉前置失败，应附带从任务开始到退出的脱敏日志。
06
并发
并行任务数量
将并发降到单任务复现，观察内存、磁盘与网络占用。单任务成功而并行失败时，再逐级增加并发寻找稳定边界。
完成六层检查仍无法定位时，请提交失败提交标识、执行命令、环境版本、退出码和脱敏日志。
提交构建问题工单
CI/CD 支持
让 runner 可识别、可恢复、可审计
独享物理节点适合作为 self-hosted runner，但稳定运行依赖清晰的注册策略、标签、服务管理、缓存边界和权限控制。
注册
为每台节点使用唯一 runner 名称，记录所属仓库或组织、注册范围、工作目录与服务账户。迁移节点时先撤销旧注册。
标签
标签应表达稳定事实，例如芯片架构、Xcode 主版本、节点区域和用途。不要把临时项目名堆成难以维护的标签组合。
服务保活
把 runner 作为受管理服务运行，记录启动方式与日志位置。重启系统后验证服务是否自动恢复，并测试一条最小任务。
缓存目录
把依赖、DerivedData 与归档分目录管理，设置清理阈值。缓存用于加速，不应成为项目唯一副本或长期交付仓库。
最小权限
日常构建账户只获得任务需要的目录与命令权限。安装工具、修改系统配置和管理服务时再使用管理员权限。
Runner 离线时的检查顺序
提交 runner 工单
服务进程 → 注册有效性 → 标签匹配 → 工作目录权限 → 外部连接 → 平台任务队列。
术语小词典
先统一术语，再描述问题
工单中使用一致术语，可以避免把物理节点、远程会话、runner 与构建缓存混为同一个故障对象。
- 物理节点
- 实际运行 macOS、Xcode 与构建任务的 Apple Silicon Mac 设备。节点是硬件交付单位，不是共享虚拟资源。
- 独享
- 一个订单对应节点资源由该客户使用，CPU、内存和本地存储不会与其他客户的任务混合调度。
- 非虚拟机
- 系统直接运行在物理 Mac 上，不是把一台设备拆成多个虚拟实例。硬件规格与订单配置直接对应。
- VNC
- 用于远程查看和操作 macOS 图形界面的连接方式。地址、端口、账户与加密选项需要按连接信息填写。
- Self-hosted runner
- 由团队自行注册到 CI/CD 平台并在独享节点上执行任务的 runner，可控制工具版本、缓存和并发策略。
- 构建缓存
- 用于减少重复下载或编译的可再生成数据，包括依赖缓存和 DerivedData。缓存损坏时应能安全重建。
- 签名证书
- 构建与交付流程中的敏感签名材料。排查时仅描述证书名称、状态与错误，不向工单上传私钥。
- 节点区域
- 物理节点所在区域。选择时同时考虑开发者位置、代码仓库位置、交付目标与大文件传输方向。
节点与网络排查
选区看完整工作流，不只看一次延迟
VMArm 提供新加坡、日本（东京）、韩国（首尔）、香港、美国西部共 5 个节点区域。应同时比较远程操作、仓库拉取、依赖下载和产物上传方向。
新加坡
适合东南亚团队以及主要服务位于东南亚的仓库与交付链路。
日本（东京）
适合日本及东亚团队，便于兼顾远程桌面操作与区域内构建资源访问。
韩国（首尔）
适合韩国与东北亚方向的开发成员、依赖镜像和交付流程。
香港
适合华南与东南亚协作团队，选择前应同时测试仓库和远程会话链路。
美国西部
适合北美西岸团队，以及主要仓库、依赖源或交付系统位于北美的项目。
| 检查对象 | 怎么测 | 需要记录 | 判断重点 |
|---|---|---|---|
| 远程会话 | 分别测试工作时段与非高峰时段的连接和交互 | 本地网络、节点、客户端版本、发生时间 | 持续异常还是特定时段波动 |
| 代码仓库 | 用同一仓库和同一提交测试克隆、拉取与子模块 | 仓库所在区域、耗时、失败命令、退出码 | 连接建立慢还是大文件传输慢 |
| 依赖下载 | 关闭缓存后执行一次完整依赖解析 | 依赖源、包管理器版本、失败包与重试次数 | 单一依赖源异常还是整体带宽异常 |
| 产物上传 | 使用相同大小的脱敏测试文件比较传输 | 文件大小、目标区域、开始与结束时间 | 上行链路、目标服务或文件大小影响 |
提交工单所需信息
一次给齐诊断上下文
工单的目标不是证明问题存在，而是让支持人员能够定位同一订单、同一节点、同一时间和同一失败步骤。
诊断信息单
7 REQUIRED FIELDS
01
订单号
用于确认对应配置、计费周期与交付记录。
02
节点区域
写明新加坡、日本（东京）、韩国（首尔）、香港或美国西部。
03
发生时间
提供含时区的时间，并说明问题是否可以重复出现。
04
系统版本
写完整 macOS 版本，不只写主版本名称。
05
Xcode 版本
同时写实际命令行工具指向的版本与路径。
06
复现步骤
从正常状态开始，按实际点击或命令顺序逐步描述。
07
脱敏日志
保留错误上下文与退出码，移除令牌、私钥和其他敏感信息。
提交前移除访问令牌、签名私钥、支付完整信息和其他敏感内容。需要了解数据处理方式时，请阅读隐私政策。
服务边界与响应流程
从确认问题到关闭工单，每一步都有输出
响应顺序取决于影响范围和可复现程度。支持流程负责节点交付、连接、环境与订单问题；项目业务逻辑仍需由项目维护者确认。
-
01
问题分级
根据无法连接、构建完全阻断、部分任务异常或一般咨询判断影响范围，并确认是否存在可行替代路径。
-
02
确认回执
确认已收到订单号、节点、时间、环境与日志；缺少必要信息时，会明确列出需要补充的字段。
-
03
诊断更新
说明当前检查层、已排除项、下一步验证动作与需要用户执行的测试，避免重复运行没有信息增量的步骤。
-
04
关闭条件
问题已恢复、根因与规避方法已说明，或确认属于项目配置并给出可执行检查方向后，工单进入关闭流程。
支持范围内
- 订单与节点交付状态核对
- VNC 地址、端口与会话连接排查
- 节点系统、磁盘、网络与权限基础诊断
- Runner 服务状态与通用配置检查
- 计费周期和支付状态说明
需要项目团队共同确认
- 业务代码逻辑与第三方 SDK 行为
- 项目自定义脚本和内部依赖源
- 团队自行制定的签名与发布流程
- 仓库权限、分支策略和任务触发条件
- 构建产物的业务验收标准
下一步
把下一次构建放到独享物理 Mac 节点
选择 VMArm M4 Core 或 VMArm M4 Plus，在新加坡、日本（东京）、韩国（首尔）、香港、美国西部中选择节点。实际可用状态以控制台实时返回为准。