连接、迁移与排障

把云端 Mac 接入现有工作流

先确认控制台里的节点与连接资料，再从 SSH 或 VNC 建立首次会话。迁移、构建和 MLX 服务出现异常时，按本页顺序缩小问题范围，避免在配置、网络与任务日志之间反复猜测。

3 个阶段
连接、迁移、接入
2 种入口
SSH 与 VNC
365 天
节点正常运行
立即租用云端 Mac 登录控制台
首次接入卷宗 VMKeep / CONNECT
待核对
01
账户与订单

确认订单状态、节点区域、机器名称与租期信息一致。

控制台
02
连接资料

复制主机地址、用户名和临时凭据，不转发给无关成员。

SSH / VNC
03
凭据更新

首次连接后更新密码，添加团队使用的 SSH 公钥。

必要
04
基线验证

记录 macOS、Xcode、磁盘空间与网络访问结果。

建议
提交工单前保留命令输出与发生时间 RUNBOOK-04
首次连接路径

先建立可复现的连接基线

不要一开始就迁移仓库或安装大量依赖。先完成四项基础核对，确认机器身份、连接方式和凭据更新均可正常执行。

  1. 01 账户确认

    核对控制台资料

    登录控制台，检查订单号、节点区域、机器名称、租期与连接资料。节点与订单不一致时先停止操作，避免把文件迁移到错误机器。

    • 记录订单号与节点区域
    • 确认机器名称和租期
    • 仅从控制台读取连接资料
  2. 02 建立会话

    选择 SSH 或 VNC

    命令行配置、自动化和日志检查优先使用 SSH；需要图形界面、Xcode 设置或桌面操作时使用 VNC。首次连接建议分别验证一次。

    • SSH 核对主机指纹与用户名
    • VNC 核对地址与显示分辨率
    • 记录成功连接所用网络环境
  3. 03 更新凭据

    更换密码并写入公钥

    进入机器后立即更新临时密码，再把团队批准的 SSH 公钥写入授权列表。密钥应按成员区分，离开项目时单独撤销。

    • 使用独立且足够长的密码
    • 为每位成员保留独立公钥
    • 限制私钥与连接资料的分发范围
  4. 04 记录基线

    验证系统与磁盘状态

    在安装工具前记录系统版本、Xcode 路径、可用磁盘和基础网络结果。后续故障可以直接与这份基线比较。

    • sw_vers 查看系统版本
    • xcode-select -p 查看工具链路径
    • df -h 查看磁盘空间
迁移路径

从本地 Mac 到云端 Mac，分三次迁移

迁移顺序决定排障成本。先移动可校验的数据，再恢复固定版本的工具链，最后接入 CI 或 self-hosted runner。

01
数据同步

只迁移必要文件

优先通过 Git 拉取代码仓库。大型模型、构建缓存和制品应单独同步，并在传输完成后核对文件大小或校验值。

输入
仓库、模型文件、脚本、必要配置
检查
目录权限、忽略规则、剩余磁盘
产出
可独立验证的项目工作副本
02
工具链复原

固定 Xcode 与依赖版本

确认项目要求的 Xcode、命令行工具、Ruby、Node.js 和 CocoaPods 版本。先跑最小构建，再恢复完整依赖缓存。

输入
版本清单、锁文件、安装脚本
检查
默认 Xcode、SDK、运行时与 PATH
产出
可重复执行的本机构建命令
03
自动化接入

注册 runner 并观察首轮任务

把 runner 工作目录、缓存目录和日志目录分开。首次任务不要并行，先观察拉取、构建、测试和归档各阶段的输出。

输入
runner 注册信息与任务标签
检查
执行用户、目录权限、失败退出码
产出
可重复运行并可追踪日志的任务
命令执行记录

用一条最短链路验证 SSH、构建与归档

以下记录展示排查顺序，不包含项目专属凭据。先确认远程会话，再执行 Xcode 构建，最后观察自动化工具是否返回成功状态。

VMKeep 构建会话 · zsh SESSION 01
09:14:02 $ ssh vmkeep@203.0.113.24
host vmkeep-m4-plus region JP shell /bin/zsh
09:14:18 $ xcodebuild -workspace Client.xcworkspace -scheme Client -configuration Release build

[1/4] Resolve package dependencies

[2/4] Compile sources and resources

[3/4] Run unit tests

[4/4] Archive build output

09:22:41 $ bundle exec fastlane ios build
构建成功
exit=0 · archive=Client.xcarchive · duration=08m23s

若某一步失败，保留失败命令前后至少 30 行输出、退出码、Xcode 版本和发生时间。提交工单前请移除令牌、私钥和签名材料原文。

CI/CD 接入

把 runner、工作目录和缓存分开管理

持续构建的问题通常来自执行身份、目录权限、版本漂移或缓存污染。下面五项应在第一条正式流水线运行前确定。

A1

注册 runner

使用独立执行用户注册 self-hosted runner，为构建类型设置清晰标签。确认服务重启后 runner 能自动恢复在线状态。

身份与标签
A2

规划工作目录

把源码检出、临时构建、归档制品和任务日志放在不同目录，避免失败任务留下的文件影响下一次运行。

权限与清理
A3

设置缓存边界

缓存键至少包含依赖锁文件、Xcode 版本和架构信息。出现不可解释的编译错误时，先用空缓存复跑一次。

版本与命中
A4

保管签名材料

签名文件、密码与令牌仅在任务运行时注入，不写入仓库、普通日志或长期共享目录。任务结束后清理临时副本。

最小暴露
A5

定义失败重试

先区分网络拉取失败、依赖解析失败、编译失败和测试失败。只有确认任务具备幂等性后，才自动重试对应阶段。

退出码与日志
CI/CD 常见阶段与核对内容
阶段 优先核对 应保留的结果 不应进入日志
代码拉取 仓库权限、远端地址、网络解析 提交哈希、分支、失败命令 访问令牌原文
依赖安装 锁文件、镜像配置、缓存键 工具版本、依赖解析输出 私有凭据原文
Xcode 构建 scheme、SDK、构建配置、目标平台 完整命令、退出码、关键报错 签名密码
测试与归档 测试目标、超时、制品目录 测试报告、归档路径、任务时长 签名材料原文件
MLX 服务排查

从本机推理结果追到远程 API

先证明模型能在机器本地完成一次请求，再检查监听地址和端口访问。不要在模型尚未加载成功时直接排查远程客户端。

  1. 01

    确认模型路径

    检查配置中的模型目录、权重文件和读取权限。相对路径应以服务实际工作目录为基准。

    test -r /srv/models/model && echo readable
  2. 02

    观察内存占用

    先用单请求加载模型，记录加载前后内存变化。若进程退出，检查系统日志和应用退出码。

    ps -o pid,rss,command -p <PID>
  3. 03

    验证本机监听

    确认服务绑定的地址与端口。仅监听回环地址时，远程客户端无法直接连接。

    lsof -nP -iTCP:<PORT> -sTCP:LISTEN
  4. 04

    执行本机请求

    在云端 Mac 内部发送最小请求，记录响应状态、首字延迟、总耗时和模型返回内容。

    curl -sS http://127.0.0.1:<PORT>/health
  5. 05

    再测远程 API

    本机请求成功后，再从授权客户端验证远程访问。对比客户端时间、服务日志与请求标识。

    curl -sS https://<YOUR-ENDPOINT>/health
模型兼容性

具体模型能否运行取决于模型格式、量化方式、依赖版本和所选内存配置。

性能判断

首字延迟与持续吞吐应在固定模型、固定参数、固定并发条件下比较。

工单证据

提交模型路径结构、启动命令、进程日志、监听结果与脱敏后的最小请求。

术语小词典

八个接入与排障常用术语

统一术语能减少团队沟通偏差。提交工单时尽量使用下列名称描述机器、连接方式和任务角色。

物理节点
实际运行 macOS 与任务的 Apple Silicon 设备，不是抽象出来的计算实例。
独享
一个订单对应一台独立物理机，运行资源不与其他租户共享同一实例。
非虚拟机
系统与任务直接运行在所分配的物理设备上，不通过共享虚拟化实例交付。
VNC
用于访问 macOS 图形界面的远程连接方式，适合 Xcode 设置与桌面操作。
SSH
用于命令行管理、文件传输、日志检查和自动化执行的加密远程连接方式。
self-hosted runner
注册在团队 CI 系统中、由这台云端 Mac 执行构建任务的自托管运行器。
MLX
面向 Apple Silicon 的机器学习框架，可用于模型转换、量化、推理和服务封装。
构建缓存
为减少重复下载与编译而保留的中间文件，缓存键不完整时可能引入旧结果。
常见连接问题

按现象检查，不跳过基础项

每类问题都先核对订单与节点，再检查客户端、网络和机器内部状态。展开对应条目可查看建议顺序与工单信息。

无法登录 SSH 或 VNC

检查顺序：确认订单与节点资料，重新复制主机地址和用户名，检查输入法与密码字符，核对 SSH 主机指纹或 VNC 地址，再换一个已知可用网络复测。

工单信息：订单号、节点区域、发生时间、客户端名称、完整错误文本，以及已隐藏主机敏感部分的连接命令。

连接建立后频繁中断

检查顺序：记录中断时刻，测试本地网络稳定性，关闭可能改写路由的代理后复测，观察 SSH keepalive 设置，并确认中断是否与高负载任务同时发生。

工单信息：中断时间段、所在网络环境、连续测试次数、客户端日志、任务类型和中断前后的系统负载。

VNC 画面延迟或操作不连贯

检查顺序：降低显示分辨率与色彩质量，暂停占用大量带宽的同步任务，比较有线与无线网络，确认是否仅在特定时间或特定客户端出现。

工单信息：节点区域、客户端版本、显示分辨率、本地网络类型、延迟出现时间和可复现的操作步骤。

磁盘空间不足或构建目录持续增长

检查顺序：运行 df -h 查看分区，再按目录统计 DerivedData、归档制品、依赖缓存、模拟器数据与任务工作区。删除前先确认制品已导出。

工单信息：磁盘使用结果、增长最快的目录、最近运行的任务、已执行的清理命令，以及是否需要评估存储附加项。

本地可构建，但 runner 任务失败

检查顺序：比较执行用户、环境变量、工作目录、Xcode 版本、依赖锁文件和缓存键。使用 runner 的执行身份手动运行同一条构建命令，找到最早出现差异的位置。

工单信息：完整构建命令、Xcode 版本、runner 标签、失败退出码、脱敏日志，以及手动执行与自动任务之间的差异。

支持入口

先整理证据，再选择联系路径

已有订单和运行中的节点问题优先通过控制台提交工单；方案选择、部署范围与尚未下单的问题可通过联系页发送邮件咨询。

工单资料清单

一次提交可直接进入排查的信息

5 ITEMS
订单号

用于定位对应机器与租期，不要提交账户密码。

节点区域

写明新加坡、日本（东京）、韩国（首尔）、香港或美国东部。

发生时间

提供包含时区的时间范围，便于对应连接与任务记录。

命令输出

保留退出码和报错前后上下文，并移除令牌与敏感凭据。

复现步骤

从起始状态写到问题出现，每一步注明预期结果与实际结果。

已有订单

通过控制台提交工单

适合连接异常、机器状态、构建问题、账单与订单关联问题。工单会保留上下文，方便继续补充脱敏日志。

登录控制台提交工单
售前与部署

通过联系页准备邮件

适合配置选择、团队部署范围、目标节点与租期咨询。对外联系邮箱统一为 support@vmkeep.com。

前往联系服务团队
下一步

先选配置，再按本页建立连接基线

三档 Apple Silicon 独享物理机均为非虚拟机，可按天、周、月或季租用。节点实时可用情况以控制台返回为准。

选择配置并租用 查看三档租用方案