SSH：从主机指纹开始
需要准备交付的主机地址、SSH 端口、用户名和对应公钥的私钥文件。私钥只保存在受控设备或密钥存储中，不要粘贴到工单。
- 首次连接：将控制台显示的主机指纹与客户端提示逐段比对。
- 权限检查：确认私钥文件仅对当前用户可读，公钥内容没有换行损坏。
- 断线排查：依次检查本地网络、DNS 或地址、端口可达性、用户名与密钥映射。
- 采集证据：保留带时间的详细模式输出，但移除地址、用户名和密钥路径中的敏感部分。
ssh -vvv -p <port> <user>@<host>
快速检索
输入错误信息、工具名称或任务目标
搜索会在本页指南、故障分流和术语解释中匹配。若错误信息含订单号、主机名或地址，请先脱敏再输入。
连接与访问
先核对交付信息，再判断连接方式
连接问题通常来自地址、端口、密钥权限、客户端缓存或本地网络路径。不要在尚未确认主机指纹时跳过验证。
VNC：先确认会话与显示状态
需要节点地址、端口、连接凭据和可用的图形会话。连接凭据应保存在密码管理工具中，不应写进脚本仓库或构建日志。
- 首次登录：检查系统版本、磁盘容量、时区、键盘布局和当前网络状态。
- 黑屏处理：先确认图形会话仍在运行，再检查客户端色深与缩放设置。
- 频繁断线：记录发生时间、持续时长、本地网络类型和是否能同时通过 SSH 访问。
- 画面卡顿：降低显示质量进行对照测试，不要把单次客户端卡顿直接判断为节点故障。
远程桌面：把客户端与节点分开验证
先确认所用客户端支持交付的连接方式，再核对地址、端口和会话凭据。不要重复尝试已失效的旧凭据，以免掩盖真正的错误原因。
- 本地侧：关闭代理或切换网络进行对照，记录客户端版本和错误原文。
- 节点侧：若 SSH 可用，检查图形服务进程、磁盘余量和系统负载。
- 链路侧：比较不同网络下的连接结果，确认问题是否只出现在单一路径。
- 提交工单：提供订单标识、节点、发生时间和脱敏截图，不提供连接密码。
MLX 推理支持
用五个检查点定位模型服务问题
先证明运行环境和模型文件完整，再检查监听地址、健康接口和日志。只开放业务实际需要的端口，并限制来源范围。
确认环境
记录 macOS 版本、Python 版本、虚拟环境路径、MLX 相关包版本和当前可用磁盘。确认任务运行在 VMMini M4、M4、16GB、256GB SSD 的独享物理节点上，而不是把共享环境参数带入。
准备模型
核对模型文件路径、文件数量、校验结果和所需空间。模型与缓存应放在明确目录，避免下载任务和服务进程同时写入同一临时位置。
检查监听
先绑定本机地址完成验证，再按实际访问需求调整监听范围。确认端口没有被其他进程占用，外部访问只开放必要端口和必要来源。
执行健康检查
从节点本机调用健康接口，记录 HTTP 状态、响应时间和返回正文。若本机正常而外部失败，应转向端口、访问规则和网络路径，而不是重复重启模型。
采集可复现日志
保留启动命令的脱敏版本、标准输出、标准错误、退出码、模型名称和发生时间。日志中如有访问令牌、请求正文或用户数据，提交前必须移除。
本机健康检查
先从回环地址验证服务
将实际端口和健康路径替换到命令中。健康接口应轻量、稳定，不触发完整推理任务。
curl --fail --show-error \
--max-time 10 \
http://127.0.0.1:<port>/health
持续集成支持
让 runner 可撤销、可清理、可复现
self-hosted runner 不只是一个常驻进程。注册、凭据、缓存、产物和撤销动作都需要明确负责人和保留边界。
注册 runner
使用专门的服务账户和独立工作目录，记录 runner 名称、标签、所属项目和注册时间。标签只描述真实能力，避免多个项目误调度到同一工作目录。
完成标准 队列可识别 runner，测试任务能返回明确退出码。隔离项目凭据
按项目和环境拆分令牌，优先使用受控密钥存储或运行时环境变量。禁止将长期凭据写入仓库、runner 配置备份或可下载产物。
完成标准 任务日志不输出秘密值，撤销单个项目不会影响其他项目。管理构建缓存
为依赖缓存、DerivedData、临时文件和归档设置不同目录。磁盘不足时先确认增长来源，再按项目清理，不要直接删除仍在运行任务使用的目录。
完成标准 缓存路径可追踪，清理动作不会删除最终产物。留存构建产物
为产物记录提交版本、构建编号、工具链版本和校验信息。任务结束后将需要保留的文件迁出 runner 工作目录，避免缓存清理时一并删除。
完成标准 失败日志和成功产物都能对应到同一次构建。安全撤销 runner
先停止接收新任务，等待当前作业结束，再从项目侧撤销注册令牌并移除服务。最后检查工作目录、缓存和凭据是否按数据迁出计划处理。
完成标准 控制端不再调度任务，节点上不残留可复用注册凭据。
术语小词典
八个词先统一含义
排查时使用一致的术语，可以避免把节点问题、软件问题、网络问题和计费问题混在一起。
- 物理节点
- 实际交付给订单使用的 Mac Mini M4 主机。它是云端 Mac 硬件节点，不是虚拟机实例。
- 独享
- 订单使用整台物理机的处理器、内存与本机存储资源，不与其他租用订单共享同一套计算资源。
- VNC
- 用于访问 macOS 图形界面的远程显示方式。排查时需要区分图形会话、客户端和网络链路。
- self-hosted runner
- 由团队注册并维护的持续集成执行端，负责拉取任务、运行构建并回传日志与产物。
- MLX
- 面向 Apple Silicon 的机器学习工具体系，可用于模型准备、推理实验与服务化验证。
- 构建缓存
- 为减少重复下载和编译而保留的数据，包括依赖缓存、DerivedData 与工具生成的中间文件。
- 节点
- 物理主机所在的服务区域。当前目录包括新加坡、日本（东京）、韩国（首尔）与香港四个节点。
- 计费周期
- 订单选定的使用时段，支持按天、周、月或季创建。周期、开始时间与到期时间以控制台订单记录为准。
故障分流树
按现象选择下一步，不要同时改动多项配置
每次只改变一个条件并记录结果。一次重置多个设置会丢失故障边界，也会让支持团队无法复现。
NET 无法连接节点 超时、拒绝连接、指纹变化或凭据不匹配
先检查
订单是否有效、地址与端口是否对应当前节点、本地网络是否能到达目标端口、用户名与密钥是否匹配。
收集信息
发生时间、客户端版本、错误原文、脱敏后的详细连接输出，以及切换网络后的对照结果。
提交工单时机
两个独立网络均无法连接，或主机指纹与控制台记录不一致时，停止继续尝试并提交工单。
BLD 构建失败 依赖解析、编译、签名步骤或 runner 作业异常
先检查
提交版本、锁文件、工具链版本、环境变量、runner 标签和工作目录是否与最近一次成功构建一致。
收集信息
完整退出码、失败阶段前后的日志、构建命令、工具版本和是否清理缓存后的对照结果。
提交工单时机
相同提交与配置在干净工作目录中仍稳定失败，且日志指向节点系统或磁盘异常时提交工单。
DSK 磁盘空间不足 模型、构建缓存、日志或归档持续增长
先检查
按目录统计占用，区分模型、依赖缓存、DerivedData、日志、临时文件和需要迁出的最终产物。
收集信息
文件系统余量、占用最大的目录、增长开始时间、正在运行的任务和最近一次清理记录。
提交工单时机
文件系统报告与目录统计明显不一致，或删除可清理内容后空间没有释放时提交工单。
SRV 服务无响应 进程存在，但健康接口超时或外部无法访问
先检查
进程状态、监听地址、端口占用、本机健康检查、可用内存与最近一段标准错误输出。
收集信息
启动命令的脱敏版本、进程退出码、本机与外部请求结果、响应时间和服务日志时间段。
提交工单时机
本机请求也失败且服务日志显示系统级异常，或多个服务同时失去响应时提交工单。
ORD 控制台订单异常 订单状态、周期、节点或账单记录与预期不符
先检查
订单标识、所选 VMMini M4 配置、节点、计费周期、附加项和支付记录是否属于同一订单。
收集信息
订单标识、页面所示状态、发生时间、操作步骤和脱敏截图。不要提交完整支付凭据。
提交工单时机
刷新并重新登录后记录仍不一致，或订单操作无法继续时，从控制台提交关联工单。
服务运行口径
节点全年运行，事件按订单记录核对
VMMini 节点按全年 365 天正常运行设计，持续提供全年运行且不设定期停机。具体订单可用性与事件记录以控制台实时返回和关联记录为准。
四节点运行范围
目录内节点均可用于 VMMini M4 下单，实际可用信息由控制台实时返回。
查看订单事件
新加坡
东南亚团队与工作负载可优先测试该路径。
日本（东京）
适合与日本或东亚代码源进行实测比较。
韩国（首尔）
适合东北亚访问路径的连接测试。
香港
可用于华南与东南亚链路的实测对照。
如何判断是不是服务事件：
先用两个独立网络复测连接，再确认节点本机服务与用户软件状态。外部网络路径、用户配置或单一进程失败，不应直接等同于物理节点不可用。
提交支持请求
一份可直接进入排查的工单应包含什么
已有订单优先使用控制台工单，以便关联节点、周期与事件记录。无法登录时，可使用 support@vmmini.com 联系服务团队。
请求信息清单
不含账户密钥
六项必要信息
- 01订单标识
提供控制台中的订单标识，不要用截图中的其他个人信息代替。
- 02相关节点
写明新加坡、日本（东京）、韩国（首尔）或香港，以及对应主机。
- 03发生时间
提供时区、首次发生时间、最后一次复现时间和是否持续发生。
- 04复现步骤
按操作顺序列出命令、输入条件、预期结果与实际结果。
- 05错误原文
保留退出码和关键上下文，不要只写“无法使用”或“构建失败”。
- 06脱敏日志
删除密码、私钥、访问令牌、用户数据和不必要的完整地址后再附上。
没有订单或无法登录
发送邮件至 support@vmmini.com，主题中写明问题类型。邮件仍需包含节点、时间、复现步骤与脱敏日志。
查看联系方式不要提交这些内容
密码、私钥、访问令牌、助记信息、完整支付凭据、未脱敏的用户数据，以及与问题无关的代码仓库内容。
阅读数据隐私