Oakmini Support Runbook

让云端 Mac 问题停在可定位的一步

先判断故障属于连接、开发环境、CI/CD、存储、网络还是账户管理，再按固定顺序验证状态、参数与日志。Oakmini 提供的是独享 Mac mini 物理节点，非虚拟机；排查时应把本地连接条件、节点状态与项目工具链分开验证。

查看主机状态 准备支持请求
6 类排查入口 5 个在售节点区域 365 天正常运行
云端 Mac 工程工作台与终端连接状态场景
connection-check 
$ uname -m
arm64
$ sw_vers -productVersion
macOS ready
$ ssh -v oak-node
debug1: Authentication succeeded
$ df -h /
Filesystem status: available
TRIAGE / 01

先把问题分到正确的排查路径

不要同时改动网络、凭据和工具版本。先选择最接近的症状，每次只验证一个变量，并记录发生时间、执行动作和结果。这样能避免一次修改掩盖另一个问题。

无法连接

适用于 SSH 超时、VNC 黑屏、凭据被拒绝或连接后立即断开的情况。

从主机状态开始检查

开发环境

适用于 Xcode 路径、Homebrew 包、Git 配置、Fastlane 或语言运行时版本不一致。

核对路径与版本清单

CI/CD

适用于 runner 离线、标签不匹配、任务排队、缓存异常或构建输出不完整。

从 runner 注册状态开始

存储

适用于磁盘空间不足、缓存持续增长、工作目录混乱或构建产物无法导出。

核对容量、目录与占用

网络

适用于交互延迟升高、偶发丢包、文件传输慢或仅特定本地网络无法访问。

对比不同链路与时间段

账户管理

适用于订单识别、主机管理权限、续用状态或控制台操作结果未更新。

先核对订单与操作记录
存储

先找出空间消耗位置

使用 df -h 查看卷容量，再用 du -sh 检查项目、构建缓存和导出目录。删除前确认产物已经备份，不要直接清空未知系统目录。

网络

把交互延迟与任务耗时分开

分别记录 SSH 建连、VNC 操作、代码拉取和本地构建耗时。若只有图形界面迟缓，应先调整 VNC 画质；若命令行与传输同时异常，再检查本地链路和节点可达性。

账户管理

以控制台订单状态为准

确认当前登录账户、订单标识、所选区域与最近一次操作时间。主机状态、订单和管理动作统一在控制台完成，支持请求中只提供订单标识，不发送登录凭据。

CONNECTION / 02

连接诊断按五层顺序执行

连接失败通常发生在主机状态、本地网络、连接参数、防火墙或凭据中的一层。按顺序验证，前一层未通过时不要继续改后一层。

  1. 01

    检查控制台中的主机状态

    确认订单对应的云端 Mac 处于可连接状态，核对节点区域和连接信息是否属于同一台物理节点。如果刚完成管理操作，记录操作时间与当前状态，不要反复提交相同动作。

    通过条件：主机状态正常，订单标识、节点区域与连接目标一致。
  2. 02

    验证网络可达性

    先确认本地网络可以访问目标地址与端口，再对比另一条可信网络。仅在办公网络失败时，应检查出口策略；所有网络都失败时，保留测试时间、目标端口与错误类型。

    nc -vz HOST PORT
ssh -vvv USER@HOST
    通过条件：端口可达，连接不会在握手前超时。
  3. 03

    逐字核对 SSH 或 VNC 参数

    确认主机地址、端口、用户名和连接方式来自当前订单。SSH 配置别名可能覆盖端口或密钥路径，可用详细日志查看最终采用的参数；VNC 则应核对目标地址、显示设置和客户端保存的旧记录。

    ssh -G oak-node
ssh -v USER@HOST -p PORT
    通过条件：客户端实际参数与控制台提供的信息完全一致。
  4. 04

    检查本地防火墙与安全策略

    临时测试前先记录原有规则。检查终端、SSH 客户端或 VNC 客户端是否允许发起连接，以及企业网络是否限制目标端口。不要为了排查长期关闭整套本地防护。

    通过条件：目标程序和端口拥有明确的出站权限，替代网络测试结果一致。
  5. 05

    验证凭据是否有效

    区分“网络超时”和“认证被拒绝”。前者不应通过更换密码解决；后者需要确认用户名、密钥文件、文件权限和最近是否更改过凭据。支持请求只能附认证错误文字，不得附密码或私钥内容。

    chmod 600 ~/.ssh/id_ed25519
ssh-add -l
    通过条件：握手完成，认证成功，连接进入 macOS 命令行或图形界面。
最小证据集：订单标识、节点区域、发生时间与时区、连接方式、客户端错误原文、已验证步骤。日志应删除用户名以外的敏感字段，并遮蔽主机凭据、密钥和令牌。
TOOLCHAIN / 03

用版本、路径和项目结果核对开发环境

“已安装”不等于“流水线正在使用”。工具链排查需要同时记录可执行文件路径、版本、当前 shell 环境和项目实际调用结果。

工具 先核对 建议命令 常见偏差
Xcode 当前开发者目录、版本、SDK 列表 xcode-select -p
xcodebuild -version		 命令行指向另一套 Xcode，项目要求的 SDK 不在当前版本中
Homebrew 二进制路径、软件清单、诊断结果 brew --prefix
brew doctor		 shell 未加载正确路径，迁移后包清单与本地环境不一致
Git 版本、远端地址、仓库权限与用户配置 git --version
git remote -v		 runner 与交互式 shell 使用不同凭据或不同工作目录
Fastlane 调用来源、依赖锁定、lane 与环境变量名称 bundle exec fastlane --version 直接调用全局版本，未按项目依赖文件执行
语言运行时 解释器路径、版本管理器和项目锁定版本 which ruby
which node		 交互式 shell 与非交互任务加载不同初始化文件
环境基线

保留一份机器可读清单

记录 macOS 版本、芯片架构、Xcode 版本、Homebrew 软件清单、Git 版本和语言运行时。每次升级只改变一个主要组件，并在升级前后各保存一次清单。

路径管理

检查任务真正看到的 PATH

在本地终端可运行但 runner 失败时，把 echo "$PATH"、which 与版本命令写入临时诊断步骤。确认后删除不必要的环境输出，避免日志带出敏感变量。

可复现验证

用最小项目复现

先运行依赖解析，再执行一次干净构建，最后确认产物路径和退出码。若最小项目成功而业务项目失败，应回到项目配置、依赖锁定和脚本权限继续定位。

BASELINE COMMANDS

环境快照命令

以下输出足以建立基础版本记录。提交支持请求前删除目录中的项目名称和任何敏感参数。

uname -m
sw_vers
xcode-select -p
xcodebuild -version
brew --prefix
git --version
which ruby
which node
df -h /
CI/CD / 04

从 runner 在线状态追到单次任务日志

CI/CD 问题应按“是否接单、是否进入工作目录、是否获得权限、是否命中依赖、是否完成构建”逐层判断。不要只依据最终失败提示下结论。

01

Runner 注册

确认 runner 服务正在运行，注册关系仍有效，并且控制台显示在线。重启前记录最后在线时间和最近一次成功任务。

  • 核对 runner 名称与目标项目
  • 确认服务进程和启动用户
  • 检查系统重启后是否自动恢复
02

标签匹配

任务长时间排队但 runner 在线时，比较任务要求的标签与 runner 实际标签。标签包含大小写、空格或架构差异时，任务可能不会被领取。

  • 保留一个明确的 Apple Silicon 标签
  • 删除已经停用的历史标签
  • 验证目标分支是否允许使用该 runner
03

权限与工作目录

确认 runner 用户对仓库目录、缓存目录和产物目录拥有所需权限。不要用扩大所有目录权限的方式掩盖单个路径配置错误。

  • 记录任务实际运行用户
  • 检查脚本是否具备执行权限
  • 确认临时目录可以创建和清理文件
04

缓存与并发

缓存失效时先做一次不读取旧缓存的对照任务。并发任务互相覆盖文件时，为每个任务分配独立工作目录，并检查 Oak Core 或 Oak Forge 的内存与存储是否符合任务规模。

  • 记录缓存键和依赖锁文件版本
  • 区分共享缓存与任务工作目录
  • 对比单任务和并发任务结果
05

日志与退出码

保留任务开始时间、runner 名称、提交标识、关键工具版本、失败步骤、退出码和末段日志。若失败可重复，记录最短复现步骤；若偶发，至少保留一次成功与一次失败的对照。

  • 为关键阶段打印开始与结束时间
  • 将构建日志和测试报告作为产物保存
  • 上传前移除令牌、密钥和签名材料

任务一直排队

优先检查 runner 在线状态、项目授权和标签。此时先不要清理缓存，因为任务尚未进入构建阶段。

任务启动后立即失败

优先检查工作目录、脚本权限、shell 初始化和工具路径。对比交互式终端与 runner 环境变量。

依赖安装不稳定

核对锁文件、缓存键、磁盘余量与网络下载日志。使用一次干净缓存任务建立对照，不要连续覆盖原始证据。

并发时才失败

检查内存占用、共享目录写入冲突、端口占用和临时文件命名。先降低并发验证，再决定调整任务拆分或配置。

GLOSSARY-MINI / 05

支持请求里常见的八个术语

使用一致术语可以减少来回确认。描述问题时，尽量指出具体对象，例如“东京节点的 SSH 连接超时”，而不是只写“服务器不可用”。

云端 Mac
通过网络远程使用的 macOS 开发环境，可用于图形界面、命令行、构建任务与自动化流程。
物理节点
实际部署的 Mac mini 设备。Oakmini 的服务以独享物理机提供，不把同一计算实例拆分成虚拟机供多人使用。
独享
订单周期内由该用户使用对应物理节点资源，有助于让构建并发、缓存和工具版本保持可控。
VNC
用于访问 macOS 图形界面的远程连接方式。画质、分辨率和本地链路都会影响交互体验。
SSH
用于安全访问命令行的连接方式，依赖主机地址、端口、用户名和有效凭据。
self-hosted runner
部署在用户控制环境中的 CI 执行程序，负责领取任务、进入工作目录并运行构建脚本。
构建缓存
为减少重复下载或编译而保存的中间数据。缓存键、依赖版本和工作目录不一致时可能产生错误结果。
节点区域
物理节点所在区域。当前在售范围仅包括新加坡、日本（东京）、韩国（首尔）、香港和美国西部。
REQUEST / 06

提交一份可以直接复现的支持请求

Oakmini 的联系渠道只有两种：登录控制台提交工单，或发送邮件至 support@oakmini.com。涉及现有订单、主机状态和持续排查记录时优先使用工单；售前或无法进入控制台时可使用邮件。

必须提供

问题上下文

  • 订单标识：只提供可用于定位订单的标识，不发送支付凭据。
  • 节点区域：新加坡、日本（东京）、韩国（首尔）、香港或美国西部。
  • 发生时间：写明日期、精确时间与时区，并指出是否可以重复。
  • 连接或任务类型：SSH、VNC、Xcode 构建、runner 任务或控制台操作。
  • 复现步骤：按执行顺序编号，注明预期结果与实际结果。
  • 脱敏日志：保留错误原文、退出码和相关上下文，删除敏感字段。
禁止附带

敏感内容不得进入工单或邮件

  • 账户密码 支持排查不需要知道密码原文。
  • 私钥或访问令牌 可提供密钥类型或错误信息，不提供密钥内容。
  • 签名证书原文 只描述证书用途、有效状态和报错，不上传完整材料。
  • 支付凭据 仅提供订单标识与交易状态，不发送卡片或钱包敏感数据。
  • 未脱敏项目日志 先移除仓库地址、环境变量、客户数据和内部路径。
COPYABLE STRUCTURE

支持请求结构

逐项填写，未知项目写“未确认”，不要猜测。若问题涉及多次尝试，请按时间顺序列出。

主题：订单标识 / 问题类别 / 节点区域
发生时间与时区：
连接方式或任务类型：
预期结果：
实际结果：
复现步骤：
1.
2.
3.
已完成的排查：
错误原文与退出码：
脱敏日志附件说明：
登录控制台提交工单 发送邮件至 support@oakmini.com
控制台 / 07

主机状态、订单与管理操作统一进入控制台

支持页提供排查顺序、命令与信息准备方法；实际下单、续用、查看订单、确认主机状态和管理云端 Mac 均在控制台完成。所有节点全年 365 天正常运行，不设置固定中断时段。若状态与实际连接结果不一致，请记录时间并提交工单。

控制台：订单与主机管理 支持页：诊断与证据准备 工单或邮箱：人工协助
管理云端 Mac 查看首次连接指南