Connection · Migration · CI/CD

问题怎么解决：从连接检查到流水线恢复

先确定问题发生在哪一层，再收集节点、时间戳、完整错误和最近一次变更。这里给出可直接执行的检查顺序，适用于 ArmMacs 云端 Mac 的图形界面、命令行、Xcode 与自托管 Runner。

登录控制台提交技术工单 查看首次连接步骤
diagnostic-checklist

01 identify node and model

02 record local network state

03 reproduce once with timestamp

04 collect sanitized logs

05 attach evidence to ticket

图形界面与命令行完整可用 独享物理节点，非虚拟机 节点全年 365 天正常运行

Support routing

先按问题类型分流

同一个现象可能来自本地网络、节点系统、工具链或流水线配置。先选择最接近的类别，并记录发生问题的节点、当地时间与时区、错误原文及最近一次成功时间。

无法连接

适用于 VNC、SSH、凭据拒绝、连接超时或会话突然断开。先区分“目标不可达”与“身份验证失败”。

需要：节点 · 协议 · 时间戳

开发环境

适用于 Xcode 版本、命令行工具、依赖解析、签名材料权限、构建缓存和磁盘空间问题。

需要：版本 · 命令 · 错误原文

CI/CD

适用于 Runner 离线、标签不匹配、任务排队、并发冲突、工作目录污染或构建后清理失败。

需要：任务 ID · 标签 · Runner 日志

存储

适用于空间不足、构建产物增长、缓存占用、数据迁入、外部备份和租期结束前导出。

需要：剩余空间 · 路径 · 数据量

账单

适用于订单状态、租期、续期和付款记录。订单以美元结算，仅支持规定的两类支付方式。

需要：订单号 · 金额 · 付款时间

请保留错误原文，不要只写“无法使用”。日志提交前删除密码、私钥、访问令牌、签名材料内容和仓库中的业务数据。

First connection

首次连接按四步完成

不要同时修改网络、凭据和系统设置。每完成一步先验证结果，这样出现问题时能确定故障落在哪个环节。

  1. 01

    领取并核对凭据

    在控制台打开对应订单，核对机型、节点、连接地址、用户名、临时密码或 SSH 凭据。确认当前查看的是目标实例，而不是已结束或其他区域的订单。凭据只保存在受控的密码管理工具中。

  2. 02

    验证本地到节点的网络

    先记录本地网络类型、出口环境和测试时间，再检查域名解析、目标地址可达性与所需端口。若公司网络失败而备用网络可用，应优先检查本地防火墙、代理或出口策略，不要反复重置节点。

  3. 03

    建立 VNC 或 SSH 连接

    需要图形界面时使用 VNC 远程桌面；执行脚本、同步仓库或接入自动化时优先使用 SSH。首次连接先完成一个短会话，验证键盘输入、文件读写和命令执行，再开始迁移大型数据或安装依赖。

  4. 04

    修改初始安全设置

    立即更换临时密码，按团队规则配置 SSH 公钥，限制凭据可见范围，并检查远程访问设置。不要把私钥、证书口令或流水线令牌写入共享脚本、构建日志和仓库文件。

Connection evidence

连接失败时至少记录这些信息

node: SG / JP / KR / HK / US-W
protocol: VNC or SSH
local_network: office / home / mobile
timestamp: YYYY-MM-DD HH:MM timezone
result: timeout / refused / authentication failed
last_success: YYYY-MM-DD HH:MM timezone

Migration path

从本地 Mac 到可重复流水线

迁移不等于复制整个用户目录。把项目数据、工具链定义和 Runner 配置分开处理，能减少环境漂移，也便于租期结束前完整导出。

PATH 01

迁移项目数据

  1. 整理范围仅迁移仓库、必要数据集、配置模板与构建输入，不复制无关缓存。
  2. 计算体积记录源目录大小、文件数量与校验值，预留依赖和构建产物空间。
  3. 分批传输小型仓库先验证权限和换行格式，大型数据按目录拆分并在传输后抽查。
  4. 隔离秘密敏感凭据通过受控方式单独配置，不进入压缩包、仓库或普通同步目录。
PATH 02

复现 Xcode 与依赖

  1. 锁定版本记录 Xcode、命令行工具、语言运行时与包管理工具版本。
  2. 恢复依赖优先使用锁文件和可执行安装脚本，不直接复制本地构建缓存。
  3. 执行基线构建先跑最小目标，再执行测试与完整归档，分别保存退出码和日志。
  4. 固化清单把版本、安装顺序、环境变量名称和验证命令写入团队运行手册。
PATH 03

接入 CI/CD Runner

  1. 创建专用执行环境流水线任务与日常远程桌面操作分开，减少权限和目录冲突。
  2. 设置精确标签标签至少表达平台、芯片档位和 Xcode 主版本，避免任务误投。
  3. 从单并发开始先验证构建、测试、归档和产物回传，再评估是否需要并发。
  4. 定义清理动作任务结束后清理临时凭据、派生数据和无用产物，同时保留必要日志。

Xcode diagnostics

Xcode 云编译按层排查

先确认工具链，再检查权限、缓存与存储。不要在同一次重试里同时升级 Xcode、更新依赖并替换签名文件，否则日志无法说明是哪项变更起效。

检查层 要核对的事实 建议动作 工单证据
版本选择 Xcode 图形版本、命令行工具路径、项目要求的 SDK 是否一致 固定一个版本完成最小构建，确认流水线与交互终端使用同一路径 版本输出、选择路径、失败目标
签名文件 文件是否完整、是否过期、目标与配置是否引用正确 在隔离环境验证文件可读性，避免把敏感内容写入日志 脱敏后的名称、有效期、错误原文
证书权限 执行构建的用户能否访问所需证书与密钥材料 比较交互构建与 Runner 用户的权限环境，缩小差异 执行用户、权限结果、失败阶段
Derived Data 旧缓存是否来自其他分支、Xcode 版本或构建配置 保存一次失败日志后清理目标缓存，再执行同一命令对照 清理前后退出码与日志差异
磁盘空间 系统卷剩余空间、归档目录、模拟器数据与依赖缓存占用 先删除可再生缓存和过期产物，不删除唯一副本 失败前剩余空间与最大目录
构建日志 首个真实错误、失败目标、退出码和前后文是否完整 保存原始文本日志，截取首个错误前后相关行并进行脱敏 命令、时间戳、退出码、日志附件

日志只需保留定位问题所需的上下文。提交前搜索并删除令牌、密码、私钥内容、证书口令、内部仓库地址和业务数据。

Runner handbook

两类 Runner 的接入与清理基线

ArmMacs 提供独享物理机，因此任务目录和工具链可以跨构建保留。持久化同时意味着缓存、凭据和旧产物不会自动消失，必须在流水线中明确清理边界。

GitHub Actions

自托管 Mac Runner

  1. 注册使用专用 Runner 身份完成注册，确认服务启动后能持续显示在线，并记录 Runner 名称与工作目录。
  2. 标签保留平台标签，并增加芯片档位、Xcode 主版本和用途标签。工作流只匹配实际需要的标签组合。
  3. 并发先按单任务串行运行。多个 Xcode 归档同时执行会竞争磁盘、缓存和签名资源，增加偶发失败。
  4. 清理每个任务结束后删除临时凭据与任务级文件；缓存按键和容量限制保留，归档成功回传后清除本地过期副本。
GitLab CI

macOS Runner

  1. 注册明确 Runner 归属范围和执行方式，验证构建用户的目录权限，并保存注册时间与配置摘要。
  2. 标签为 macOS、芯片档位、Xcode 主版本和任务类型设置标签，禁止无标签任务误占专用节点。
  3. 并发初始并发设为 1。只有在任务目录、端口、缓存与签名材料完全隔离后，才评估增加并发。
  4. 清理在任务结束阶段清理工作目录中的秘密文件和临时产物；失败任务也要执行清理，并单独保留脱敏日志。

上线前最小验证矩阵

checkout ✓ dependency restore ✓ build ✓ test ✓ artifact export ✓ secret cleanup ✓

Remote desktop

远程桌面问题先区分画面、输入与会话

VNC 体验同时受本地网络、跨区域路径、分辨率与画面变化频率影响。出现问题时先记录节点和本地网络状态，再改变一个变量进行对照。

画面延迟或滚动不连贯怎么处理

记录节点、本地网络类型、测试时间和是否存在代理。先降低远程桌面分辨率与画面质量，关闭持续变化的动画或视频，再比较输入回显。若备用网络明显改善，应检查本地出口拥塞或策略；若多个网络在同一时间表现一致，再提交节点和时间戳。

分辨率不匹配或界面缩放异常怎么处理

先在单显示器环境下设置常用分辨率，断开后重新建立会话。确认客户端缩放模式与远端显示设置没有同时放大。需要录制问题时，请同时保留客户端窗口尺寸和远端分辨率数值。

快捷键或符号输入不一致怎么处理

核对本地与远端键盘布局，先用纯文本编辑器测试字母、数字、符号和组合键。问题只出现在特定应用时，记录应用名称与快捷键；所有应用均异常时，附上两端布局和客户端版本信息。

会话中断后应立即重启节点吗

不要立即重启。先确认本地网络是否切换、设备是否休眠、VNC 是否断开但 SSH 仍可连接，并记录中断时间。能通过 SSH 访问时，先保存工作状态和相关日志；两个协议都不可达时，再通过控制台提交工单。

重新连接前要保留哪些信息

保留节点、协议、本地网络、客户端版本、最后成功时间、中断时间和错误原文。重新连接只改变一个条件，例如切换网络或降低分辨率，并记录结果，避免多项变化让对照失效。

Storage responsibility

存储、备份与租期结束前导出

物理节点上的工作目录适合构建和实验，但不应成为代码、证书、模型或构建产物的唯一副本。数据迁入、外部备份与最终导出需要由使用团队纳入项目计划。

01

迁入前分类

把数据分为可从仓库恢复、可从依赖源重建、必须备份和禁止上传四类。估算项目、依赖、Derived Data、归档与日志的峰值容量，不要只看源代码大小。

02

建立快照外备份

关键代码、证书、模型、数据集与最终产物应保存到团队控制的外部备份位置。定期执行恢复抽查，确认备份不是只有文件列表而没有可用内容。

03

管理敏感凭据

凭据按最少必要权限配置，区分人工操作与流水线用途。不要写入 shell 历史、仓库、普通环境文件或构建产物；轮换后及时删除旧副本。

04

控制缓存增长

为依赖缓存、Derived Data、模拟器数据和归档设置保留规则。删除前先确认内容可重建，磁盘不足时优先处理过期缓存与已回传产物。

Before expiry

租期结束前操作清单

  • 导出未推送的代码、数据集、模型、归档和测试结果
  • 验证外部副本的文件数量、大小与关键校验值
  • 停止 Runner 并从流水线移除对应执行节点
  • 撤销令牌、SSH 密钥授权和临时访问凭据
  • 删除节点上的业务数据、秘密文件与不再需要的日志
  • 在控制台核对租期、续期状态和订单结束时间

Support ticket

提交一张可以直接复现的工单

在租节点故障优先登录控制台提交工单。控制台能把问题与订单关联，便于核对机型、节点和交付状态。无法进入控制台时，可发送邮件至 support@armmacs.com。

前往控制台提交工单 发送支持邮件
ticket-evidence.txt 
订单号：
机型：
节点：
问题类型：
发生时间与时区：
最后成功时间：
复现步骤：
预期结果：
实际结果：
错误原文：
最近一次配置变更：
本地网络状态：
附件：脱敏日志 / 截图

复现步骤要可执行

按实际顺序写出连接方式、执行命令、目标项目和失败阶段。若问题不是每次出现，请说明出现频率与已验证过的对照条件。

时间戳必须带时区

使用完整日期、小时、分钟和时区。仅写“刚才”或“今天”无法与节点事件和 Runner 日志准确对应。

附件先做脱敏

截图与日志中不得包含密码、私钥、令牌、证书口令和业务数据。保留错误原文、退出码与必要上下文即可。

Ready for diagnosis

节点、时间戳和日志都准备好了

登录控制台关联订单并提交工单。账单仅以美元结算，支持 USDT-TRC20 与 Visa / Mastercard / Amex（经 Stripe），实际可用网关以控制台返回结果为准。

立即提交技术支持工单 立即租用云端 Mac