Xcode
固定项目要求的工具链版本
先读取项目文档和 CI 配置中的版本约束，再选择对应 Xcode。切换后同时检查编译器路径、SDK 列表和命令行工具，避免图形界面版本与终端实际路径不一致。
xcode-select -p
xcodebuild -version
xcrun --show-sdk-path判断标准：本地开发与持续集成输出的 Xcode 主版本、SDK 和工具路径一致。
先找到正确路径
六类问题，对应六条最短处理路径
如果现象跨越多个分类，先从“首次连接”核对基础信息，再进入“故障处理”。账户、订单和节点实际状态以控制台返回为准。
首次连接
不要从反复重连开始，先完成五项基础核对
首次使用时，最常见的问题来自节点信息抄写错误、本地网络限制或显示参数不合适。按顺序检查可以避免把环境问题误判为节点问题。
-
01
在控制台读取本次订单信息
确认订单号、机型、节点区域、连接地址、用户名和访问凭据属于同一份订单。不要使用旧订单截图或聊天记录中的历史信息。凭据只应保存在受控密码管理工具中。
完成标准：机型、区域与当前订单一致 -
02
建立远程桌面连接
使用支持 macOS 图形界面的远程桌面客户端，逐字输入连接地址和用户名。连接失败时先切换一次本地网络，排除公司代理、出口防火墙或公共网络策略的影响。
完成标准：可以看到 macOS 图形界面并操作桌面 -
03
完成基础安全设置
首次进入后更换系统登录密码，检查屏幕锁定时间，并确认项目私钥、签名凭据和访问令牌没有写入共享脚本、命令历史或公开仓库。不要把密码或私钥提交给支持人员。
完成标准：访问凭据已更换并由团队安全保存 -
04
调整分辨率与图像质量
根据本地显示器选择合适的缩放比例。网络波动时先降低图像质量和分辨率，再判断节点响应；鼠标延迟与画面模糊并不等同于编译或磁盘性能下降。
完成标准：文字清晰，输入和窗口拖动可稳定响应 -
05
执行首次登录检查
打开终端确认系统时间、可用磁盘空间、网络解析和 Xcode 命令行路径。然后创建一个临时目录，完成写入、读取和删除测试，确认当前用户拥有项目目录所需权限。
完成标准：时间、磁盘、网络和目录权限均正常
开发环境
先固定版本和目录，再安装项目依赖
云端 Mac 是独享物理机、非虚拟机。团队仍应把环境配置写成可复现清单，避免个人手动修改长期累积后无法还原。
Homebrew
用 Brewfile 管理可复现依赖
不要把已安装工具列表留在个人记忆里。先从现有环境导出 Brewfile，清理无关包，再在云端 Mac 上按清单安装。私有源的访问令牌应通过受控环境变量注入。
brew bundle dump --force
brew bundle check
brew bundle install判断标准：Brewfile 可在干净目录执行，且不会要求把敏感令牌写入仓库。
Git
把仓库身份与项目权限分开
检查用户名、提交邮箱、默认分支和换行规则。多个项目使用不同仓库权限时，分别配置密钥文件和主机别名，不要让一个高权限凭据覆盖所有构建任务。
git config --global --list
git remote -v
ssh -T git@your-git-host判断标准：拉取、提交与子模块访问分别使用预期身份，日志中不输出令牌。
签名与命令行
把敏感材料放到构建过程之外
证书、私钥和签名凭据应通过团队批准的安全流程导入，按项目设置最小访问范围。Node、Ruby、Python、CocoaPods 等工具应固定版本，并将版本文件纳入仓库。
node --version
ruby --version
python3 --version
pod --version判断标准：新会话可以从版本文件恢复环境，构建日志不包含凭据正文。
CI/CD 接入
把云端 Mac 作为可追踪的常驻构建节点
接入 GitLab CI Runner 时，先定义节点职责，再注册执行器。一个节点可以承载多个队列，但高权限签名任务和普通编译任务应使用不同标签、目录与凭据范围。
安装并注册 GitLab CI Runner
使用项目或团队分配的注册信息完成安装。给节点设置能表达架构、Xcode 版本和任务类型的标签，关闭无标签任务接入，避免任意流水线占用构建节点。
- 记录 Runner 名称与所属项目
- 标签包含工具链和任务类型
- 验证执行用户的目录权限
管理常驻构建任务
将 Runner 作为受控后台任务运行，确认重启后能恢复。不要用个人终端会话长期挂起构建进程；会话断开不应中断正在执行的编译或测试。
- 检查进程所有者与启动方式
- 限制同时执行的任务数量
- 为超时任务设置退出规则
固定缓存目录与清理边界
将依赖缓存、DerivedData、归档和最终产物分开。缓存可以复用，归档需要追踪，临时文件应按流水线清理。磁盘异常增长时先定位目录，不要直接删除未知项目数据。
- 分别记录缓存与产物路径
- 按项目设置独立目录
- 定期检查磁盘余量和增长来源
隔离签名凭据与仓库权限
按项目注入最小权限凭据，限制受保护分支才能运行签名任务。日志中只记录凭据是否加载成功，不输出密码、私钥、令牌或签名材料正文。
- 保护敏感变量并限制分支
- 普通编译与签名任务分标签
- 任务结束后清理临时文件
接入验收
用一条最小流水线验证，而不是直接迁移全部任务
- 拉取一个无敏感数据的测试仓库。
- 输出 Xcode、SDK 和依赖工具版本。
- 执行一次无签名编译并保存产物。
- 检查任务退出后缓存、日志和临时目录。
服务可用率
用统一指标判断服务状态，不用单次网络波动代替结论
MacMLab 云端 Mac 节点全年 365 天正常运行。连接质量还会受到用户本地网络、出口策略、远程桌面参数和任务负载影响，排查时需要把这些因素与节点状态分开记录。
- 服务可用率指标
- 99.9%
- 状态观察范围
- 90天
订单满足适用条件且核验为平台服务问题后，将依据服务条款和对应订单记录处理服务赔付。
正常运行记录
从较早记录到最近记录
故障决策树
从现象进入分支，每次只改变一个变量
先记录发生时间和原始错误，再执行检查。不要同时重装工具、切换网络和清理目录，否则即使恢复也无法确认根因。
节点能否建立远程连接？
先确认控制台中的订单状态、节点区域和连接信息，再选择下方与现象最接近的分支。
地址无响应或凭据被拒绝
- 确认连接信息来自当前订单。
- 切换本地网络并暂停代理后复测。
- 记录客户端错误原文与发生时间。
提交：订单号、节点区域、本地网络类型、错误截图和客户端名称。
画面延迟、输入迟缓或任务变慢
- 降低远程桌面分辨率和图像质量。
- 区分桌面画面延迟与终端命令耗时。
- 检查 CPU、内存、磁盘和并发任务。
提交：慢操作名称、开始与结束时间、任务并发数和脱敏资源摘要。
写入失败或可用空间持续下降
- 查看项目、缓存、归档和日志目录大小。
- 确认是否有失败任务留下临时文件。
- 只清理可重建缓存，不删除未知数据。
提交：磁盘余量、增长最快目录、最近任务和清理前后的脱敏结果。
编译器、依赖或签名流程报错
- 记录 Xcode、SDK 和依赖工具版本。
- 在干净目录复现最小构建任务。
- 比较本地与 CI 的环境变量名称。
提交：失败命令、退出码、首个有效错误和已脱敏的相关日志片段。
多个独立操作同时失效
- 排除单个仓库、单个工具和单个客户端。
- 记录终端与图形界面的共同现象。
- 停止重复重试，保留现场信息。
提交：订单号、节点区域、异常时间线、影响范围和最近一次正常操作。
联系支持
技术问题优先走工单，普通咨询可发支持邮箱
MacMLab 对外仅提供控制台工单和支持邮箱两种联系渠道。涉及现有订单、节点或账单的事项优先提交工单，便于关联订单记录和持续更新处理状态。
推荐路径
登录控制台提交工单
适合连接失败、节点异常、构建环境、账单状态和订单相关问题。工单中请先写结论，再按时间顺序列复现步骤。
标题建议
节点区域 + 现象 + 首次发生时间
正文顺序
订单号 → 影响范围 → 复现步骤 → 错误原文 → 已执行检查
附件要求
只上传脱敏截图和日志摘要，遮盖密码、私钥、令牌与签名凭据
一般咨询
support@macminilab.com
发送支持邮件
适合尚未下单的配置确认、企业需求背景、文档反馈或无法登录控制台的情况。
隐私提醒
查看数据处理说明
支持人员不需要你的秘密信息
不要发送系统密码、私钥、访问令牌、签名凭据或完整业务数据。日志应保留错误上下文，同时替换仓库地址、用户名和密钥内容。