云端 Mac 帮助中心与故障排查指南

按问题类型进入

先选范围，再执行最短检查路径

五类入口对应订单生命周期中的不同环节。切换分类会显示建议先确认的信息、常见原因与下一步去向。

订单生命周期

订购与交付

适合处理付款结果待确认、节点信息尚未出现、区域或机型核对、首次连接资料确认等问题。

确认控制台中的订单编号、机型、租期和区域与提交内容一致。
付款确认后，系统依次执行节点分配、健康检查和连接信息生成，典型流程约 4 分钟。
超过典型时间仍无连接资料时，不要重复创建订单；记录订单编号并提交工单。

快速诊断

五类高频故障的首轮检查

每张卡按“先确认状态、再缩小变量、最后保留证据”的顺序排列。一次只改一个变量，才能判断是哪一步恢复了服务。

无法连接节点

在控制台确认节点处于正常运行状态。
逐项核对地址、端口、用户名和连接协议。
从另一网络测试同一端口，排除本地出口或防火墙限制。
记录客户端错误原文与发生时间，不要连续尝试大量密码。

查看远程访问指南

构建突然失败

记录失败提交、构建命令、退出码和首个有效错误。
执行 xcodebuild -version 确认当前工具链。
检查依赖锁文件、环境变量和签名资产是否发生变化。
仅在确认缓存异常后清理对应缓存，避免先删除全部证据。

进入 Xcode 排查步骤

磁盘空间不足

使用 df -h 查看卷容量，不要只看单个目录。
检查 DerivedData、归档、模拟器数据和包管理器缓存。
先删除可重建内容，再处理构建制品与项目文件。
持续增长的目录应加入流水线清理规则并设置容量监控。

查看安全清理顺序

凭据失效

区分是系统登录、SSH 密钥、仓库令牌还是签名权限失效。
确认凭据有效期、文件权限和调用它的用户身份。
轮换凭据后同步更新流水线变量，撤销旧值。
不要把完整凭据粘贴到命令历史、截图或工单正文。

查看安全与权限说明

网络延迟或抖动

记录本地城市、运营商、节点区域和问题发生时间。
连续测试多次并取中位数，不以单次峰值下结论。
分别检查交互延迟、丢包和大文件传输吞吐。
关闭非必要音视频与高色彩质量，再比较 VNC 体验。

查看连接优化方法

核心术语

读懂节点、连接与构建上下文

以下定义采用本服务中的实际含义。提交工单时使用一致术语，可以减少对问题范围的反复确认。

物理节点: 实际运行工作负载的独立 Mac mini 设备。它有明确的芯片、内存、存储和所在区域，不是共享计算实例。
独享: 租期内该节点计算资源对应当前订单使用，不与其他客户的工作负载混合调度，性能与环境边界更清晰。
VNC: 用于访问 macOS 图形界面的远程显示协议。适合需要桌面操作、查看 Xcode 界面或调整系统设置的任务。
SSH: 用于加密命令行连接的协议。适合执行脚本、传输文件、管理 runner 和排查无需图形界面的任务。
self-hosted runner: 由团队自行管理并接入代码托管流水线的执行器。任务在指定云端 Mac 上运行，工具链、缓存和并发策略由团队控制。
代码签名: 使用证书、私钥与描述文件确认应用来源和授权范围的流程。相关资产应限制权限、定期轮换并避免写入仓库。
构建缓存: 用于复用依赖、编译中间结果或工具下载内容的数据。它能缩短构建时间，但错误或过期缓存也可能造成不一致。
节点区域: Mac mini 所在的数据中心区域。当前目录覆盖新加坡、日本（东京）、韩国（首尔）、香港、美国东部、美国西部 6 个区域。

交付与凭据

从订单确认到首次安全登录

典型交付约 4 分钟，由四个连续步骤组成。实际可用状态与连接资料以控制台实时返回为准。

01

订单与付款确认
约 1 分钟

核对机型、租期、节点区域与附加项。付款结果确认后订单进入分配流程；不要通过重复付款来尝试加速处理。
应保存：订单编号、付款结果标识、提交时间。
02

节点分配
约 1 分钟

系统按订单目录分配独立 Mac mini 物理节点。两档机型均可在新加坡、日本（东京）、韩国（首尔）、香港、美国东部、美国西部选择。
应核对：节点 ID、机型、区域。
03

节点健康检查
约 1 分钟

交付前检查系统启动、网络连通和远程访问服务。所有节点全年 365 天正常运行，不设置定期停机时段。
应等待：控制台状态变为可连接。
04

连接信息送达
约 1 分钟

控制台提供地址、端口、用户名和临时凭据。首次登录后立即更新临时密码，配置独立 SSH 密钥，并把凭据保存在受控的密钥管理工具中。
应完成：首次登录、密码更新、SSH 密钥验证。

凭据边界

不要在截图、仓库、构建日志或工单中提交私钥、完整密码、完整访问令牌。需要说明凭据类型时，只提供用途、创建时间和末尾少量字符。

Xcode 排查路径

从版本基线定位到可复现日志

不要一开始就清空全部缓存或重装工具链。先确认版本与路径，再检查签名资产，最后执行范围明确的清理。

01

确认 Xcode 与 macOS 版本

记录图形界面显示的版本，同时在流水线用户下执行命令。若本地交互构建成功、runner 失败，还要比较两者的执行用户和环境变量。

xcodebuild -version
sw_vers
whoami

02

确认命令行工具选择

使用 xcode-select -p 检查当前开发者目录。团队并行维护多个版本时，应在流水线启动阶段明确选择路径，避免系统默认值变化。

xcode-select -p
xcrun --find xcodebuild
xcrun xcodebuild -version

03

检查证书与描述文件

确认签名证书未过期、私钥可由构建用户读取、描述文件与目标标识匹配。自动签名失败时，应先保留原始错误，再检查钥匙串权限和流水线变量。

security find-identity -v -p codesigning
ls -la ~/Library/MobileDevice/Provisioning\ Profiles

04

按范围清理 DerivedData

优先删除当前项目对应目录，而不是直接清空所有项目缓存。清理前记录磁盘占用与失败日志，以便判断问题是否确由缓存造成。

du -sh ~/Library/Developer/Xcode/DerivedData
find ~/Library/Developer/Xcode/DerivedData -maxdepth 1 -type d

05

收集 xcodebuild 日志

保留完整命令、退出码和首个有效错误。提交工单前移除仓库令牌、签名秘密、用户名路径和内部地址，但不要只截取最后一行。

set -o pipefail
xcodebuild test 2>&1 | tee build.log
printf "exit=%s\n" "$?"

服务请求规范

让支持工程师能够直接复现

完整请求不等于上传全部数据。目标是提供明确时间线、受影响范围和经过脱敏的技术证据。

工单正文建议结构

节点 ID: 从控制台复制准确标识，不用自定义设备昵称代替。
发生时间: 写明日期、时区、开始时间和最近一次正常时间。
节点区域: 填写订单中的区域，不要仅填写本地所在城市。
影响范围: 说明是单个命令、一个流水线、全部连接还是整个团队受影响。
复现步骤: 按实际执行顺序列出命令、输入、预期结果和实际结果。
已做检查: 逐项写明操作及结果，避免只写“都试过了”。

日志脱敏规则

把访问令牌、密码、私钥内容替换为明确的脱敏标记。
仓库地址可保留平台类型，移除组织名、项目名和认证参数。
用户目录可替换为通用路径，但保留相对目录层级。
证书问题可提供名称、有效期和错误信息，不提交私钥。
支付问题可提供订单编号与结果标识，不提交完整支付信息。
截图前检查终端历史、菜单栏、文件名和通知内容。

禁止上传

私钥、完整登录凭据、完整访问令牌、未脱敏环境变量、包含敏感参数的配置文件。

什么时候应该跳过自助检查并立即提交工单？

出现异常凭据活动、主机指纹意外变化、节点状态与实际连通性明显不一致，或操作可能进一步破坏证据时，应停止重复尝试并立即提交控制台工单。

为什么节点操作需要订单归属验证？

重置访问、调整节点状态或处理敏感配置会影响独享物理机。支持团队需要核对登录会话、订单编号和授权关系，避免未授权人员请求节点级操作。

连接和构建同时失败，应该提交一个还是多个工单？

若两者发生在同一时间且可能由同一节点状态引起，可在一个工单中分别列出连接与构建证据。若发生时间、节点或责任范围不同，应分开提交，便于独立跟踪。

升级支持

携带诊断结果提交可追踪请求

现有订单、节点连接、构建故障和账单问题优先通过控制台工单提交。售前评估、团队部署与安全报告可通过联系页面使用 support@hexvm.com。涉及节点操作时，需要完成订单归属验证。

进入控制台提交工单查看联系团队方式阅读远程访问指南

云端 Mac 帮助中心