工程操作手册

把云端 Mac 从交付状态带到可重复运行

这里不从概念开始。先核对订单与节点信息,再配置访问凭据、Xcode、持续集成和 MLX 推理环境。每一节都给出检查顺序、完成标准与需要保留的诊断信息。

服务形态
独享物理机,非虚拟机
启用目标
约 4 分钟
运行范围
全年 365 天正常运行
节点运行单 首次启用配方
4 项核对
01
订单与节点 机型、区域、租期与附加项一致
核对
02
访问凭据 首次连接后立即更新并妥善保存
更新
03
开发工具链 确认 macOS、Xcode 与命令行工具版本
验证
04
网络与工作目录 检查连通性、剩余空间和任务目录权限
就绪
完成标准 能连接、能构建、能复现
首次启用

四分钟启用清单

计时从订单确认后开始。实际可用状态以控制台实时返回为准;如果任一步骤的输入不完整,不要跳到下一步继续配置。

  1. 01
    核对订单 约 45 秒

    确认机型、节点区域、租期和附加项与计划一致。基础方案为 M4、16GB、256GB;高内存方案为 M4 Pro、64GB、2TB。发现配置不符时先停止后续操作并提交工单。

    • 记录订单号和节点区域。
    • 确认存储扩展与 Thunderbolt 5 并联需求。
  2. 02
    接收节点信息 约 2 分钟

    等待自动分配与系统检查完成,随后在控制台读取节点地址和连接信息。不要把连接信息转发到公共频道,也不要在代码仓库中保存明文凭据。

    • 核对地址与订单对应的区域。
    • 把初始信息放入团队认可的凭据管理工具。
  3. 03
    更新访问凭据 约 1 分钟

    完成首次连接后立即更新凭据,并为自动化任务配置独立密钥。交互账户和 CI 执行账户应分开,避免脚本获得不必要的系统权限。

    • 更新初始密码并验证新凭据可用。
    • 为命令连接准备密钥并核对主机指纹。
  4. 04
    验证系统与网络 约 15 秒

    记录 macOS 与 Xcode 版本,检查默认路由、域名解析、可用磁盘空间和工作目录写入权限。完成后执行一个小型构建或推理请求,确认环境能产生可验证结果。

开发环境

Xcode 与签名环境先固定基线

可重复构建依赖明确版本、可访问的钥匙串和一致的命令行工具。不要以“图形界面能打开项目”代替命令行验收。

配置顺序

  1. 01
    确认 Xcode 版本

    记录完整版本号与构建号,检查项目要求的 SDK、模拟器运行时和最低系统版本是否齐全。

  2. 02
    导入证书与描述文件

    只导入当前项目需要的材料,命名时附上项目和用途,避免多人交接后无法判断来源。

  3. 03
    检查钥匙串权限

    在目标执行账户下验证私钥可读。自动化构建应先完成非交互式签名测试,避免队列卡在权限确认界面。

  4. 04
    选择命令行工具

    确认当前选择指向预期的 Xcode,并把结果写入项目环境记录。切换版本后必须重新执行一次依赖与签名检查。

  5. 05
    完成首次构建验证

    先清理旧产物,再执行测试、归档与签名校验。保留命令、退出码、日志路径和最终产物校验值。

持续集成

把执行器当成固定资源,而不是临时目录

独享物理机提供固定硬件资源,但任务仍可能因缓存污染、并发过高或日志不足而失败。接入前先定义目录和清理责任。

01

安装自托管执行器

为执行器建立独立系统账户和服务目录,只授予构建所需权限。注册完成后先运行无签名的小任务,验证队列、网络和退出状态。

完成标准:重启后自动恢复接单
02

规划工作目录

将源码检出、依赖缓存、临时构建、归档产物和长期日志分开。任务结束时只清理临时目录,不要误删下一任务需要的共享缓存。

完成标准:目录所有者与清理规则明确
03

限制并发数量

从单任务建立内存、磁盘和耗时基线,再逐步增加并发。Xcode 构建与 MLX 推理同时运行时,应分别观察峰值内存和磁盘写入。

完成标准:高峰期不发生交换与空间耗尽
04

保留失败证据

失败任务至少保留任务编号、提交版本、执行器版本、开始时间、退出码、关键日志和产物路径。日志上传前移除令牌与签名材料。

完成标准:另一名成员可以独立复现
缓存清理边界

优先按项目、分支和工具版本建立缓存键。不要用定时全盘删除代替容量管理;清理前先确认当前没有运行中的构建或归档任务。

AI 与 MLX

推理服务要能压测、观察和恢复

先把单请求跑通,再增加上下文长度和并发。模型目录、运行环境与服务日志必须分离,避免更新依赖时同时破坏模型文件。

MLX 服务配方 从单请求基线开始
Apple Silicon
环境隔离
每个服务使用独立 Python 环境,锁定依赖版本并保存安装清单。
模型目录
模型文件与源码分开,记录模型名称、量化格式、校验值和占用空间。
监听范围
默认只监听任务需要的接口和地址,不把调试端点暴露给无关网络。
并发压测
依次测试 1、2、4 个并发请求,记录首字延迟、总耗时、失败率和峰值内存。
内存观察
区分模型常驻、上下文增长与请求缓存,接近稳定上限前停止继续加压。
重启策略
把启动命令、工作目录、环境变量和日志路径写入服务配置,并验证异常退出后可恢复。
容量与并联

按工作集选择存储,不按项目名称猜容量

先计算源码、依赖、模型、构建产物、日志和临时文件的峰值总量,再保留清理与回滚空间。基础 SSD 容量由所选机型决定。

ArmMesh M4

256GB 基础 SSD

适合代码检出、常规依赖缓存、单项目构建和短期发布任务。大型模型、多版本 Xcode 运行时或大量视频素材应先核算峰值空间。

ArmMesh M4 Pro

2TB 基础 SSD

适合较大的模型仓库、长期构建缓存、并行项目和音视频导出。固定容量不替代清理策略,仍需设置日志与产物保留期限。

存储与 Thunderbolt 5 附加项价格,统一以美元结算
附加项 每天 每周 每月 每季 适用检查
+1TB SSD $2.4 $6.4 $11.9 $32.4 依赖缓存、构建归档或中等规模模型超过基础容量时使用。
+2TB SSD $4.8 $12.8 $23.8 $64.8 大型模型、长期产物保留或音视频素材工作流需要更大工作集时使用。
Thunderbolt 5 并联,每台 $1.2 $3.2 $5.9 $16 多台设备协同前,先确认任务拆分、数据同步、失败恢复和结果汇总方式。

多台设备并联前的五项检查

  • 任务能否拆成相互独立且可重试的工作单元。
  • 输入数据是否有唯一来源,是否会被多台设备同时写入。
  • 模型、依赖和工具版本能否保持一致。
  • 失败节点的任务能否安全转移而不重复生成结果。
  • 输出产物是否有统一命名、校验和汇总位置。
故障定位

先缩小范围,再改配置

一次只改变一个条件,并记录改变前后的结果。连续重装、反复清缓存或同时修改网络与工具链,会让真正原因更难确认。

无法连接

从本地网络查到节点状态

  1. 确认本地网络可用且没有代理或防火墙拦截。
  2. 重新核对节点地址、端口和主机指纹。
  3. 检查凭据是否更新、复制时是否带入空格。
  4. 在控制台确认节点状态,再记录客户端版本和错误原文。
速度异常

区分延迟、带宽和节点负载

  1. 在固定网络下重复测试,排除无线网络波动。
  2. 比较交互延迟与文件传输速度,不把两者混为一项。
  3. 检查是否有构建、同步或推理任务占用资源。
  4. 记录访问位置、节点区域、时间段和连续测试结果。
构建失败

先判断代码问题还是环境问题

  1. 固定提交版本并重新执行同一条构建命令。
  2. 记录 Xcode、SDK、依赖和命令行工具版本。
  3. 检查签名材料、钥匙串权限和工作目录权限。
  4. 清理当前项目的临时产物后重试,不做全盘删除。
磁盘不足

先找增长来源,再决定扩容

  1. 分别统计模型、依赖缓存、归档、日志和临时目录。
  2. 确认是否存在重复模型、旧归档或未结束任务的残留。
  3. 按保留规则清理可再生成内容,并重新记录峰值。
  4. 峰值仍超过安全余量时,再选择 +1TB 或 +2TB SSD。
推理进程退出

比较请求规模与内存峰值

  1. 确认退出发生在启动、加载模型还是处理请求阶段。
  2. 检查模型格式、上下文长度和并发数是否变化。
  3. 查看退出前内存、磁盘和服务日志。
  4. 用单请求恢复基线,再逐项增加负载。
凭据失效

停止重试并确认变更来源

  1. 核对使用的是交互账户还是自动化账户。
  2. 确认近期是否更新密码、密钥或访问成员。
  3. 移除脚本和缓存中的旧凭据,再测试新凭据。
  4. 无法确认变更来源时,通过控制台提交工单。
服务请求

让工单具备直接排查所需的信息

技术问题优先通过控制台提交工单,以便关联订单和节点。无法登录控制台时,可发送邮件至 support@armmesh.com。

提交前准备六项内容

01 订单号

提供发生问题的订单号;多台节点受影响时分别列出,不要只写团队名称。

02 节点区域

写明实际使用区域,并说明问题是否只出现在一个节点或多个节点。

03 macOS 版本

附完整版本与构建号;涉及构建时同时提供 Xcode 和命令行工具版本。

04 发生时间

写明时区、首次发生时间、最近一次发生时间以及问题是否可以稳定复现。

05 复现步骤

从正常状态开始逐步列出操作、输入、预期结果和实际结果。

06 脱敏日志

保留时间戳、错误码与上下文,移除密码、密钥、令牌、签名材料和项目机密。

下一步

先选物理节点,再按清单完成验收

两档机型均为独享物理机、非虚拟机,支持按天、周、月、季租用。节点实际可用状态以控制台实时返回为准。