macOS 屏幕共享
适合从 Mac 客户端进入图形界面。连接目标应使用控制台给出的主机地址与端口，登录账户必须与系统账户完全一致。
- 初始分辨率
- 1920×1080
- 色深
- 24-bit
- 建议可用带宽
- ≥ 15 Mbps
- 交互建议
- 优先自适应质量
画面迟滞时先停止后台同步，再降低远端分辨率。不要同时调整分辨率、色深和压缩级别，否则难以判断真正影响项。
Connection / Toolchain / Diagnosis
先完成远程连接，
再逐层定位问题。
这份手册用于接入独享物理节点：先核对节点地址与系统凭据，再配置 SSH、VNC、Xcode 和 CI runner。遇到异常时，按网络、认证、系统、工具链、存储的顺序排查，减少无效重试。
连接方式
SSH / VNC
系统界面
GUI / CLI
资源形态
独享物理机
节点运行
365 天
01 / First connection
首次连接前，逐项核对五类信息
不要先猜网络或重置系统。控制台中的节点记录是唯一核对基准，复制地址时不要附带协议前缀、空格或端口之外的字符。
-
01
节点地址与区域
确认当前实例的节点编号、区域、主机地址和连接端口。区域应与订单一致；若团队使用网络白名单，同时记录客户端当前公网出口地址。
检查：NODE ID / HOST / REGION / PORT
-
02
系统账户
账户名区分大小写。SSH 命令中的账户名、VNC 登录框中的账户名和控制台展示值必须一致，不要用邮箱地址代替系统用户名。
格式：username@host
-
03
临时凭据
首次使用前确认凭据仍为控制台当前版本。完成登录后立即更换临时密码；若已更新过密码，后续连接应使用新值，旧值不会继续生效。
动作：登录 → 更换 → 安全保存
-
04
SSH 客户端
macOS 与常见 Linux 环境可直接使用终端。先执行端口连通性检查，再发起 SSH；首次出现主机指纹时，核对节点地址后再确认。
建议：连接超时 10s / 保活 30s
-
05
屏幕共享或 VNC 客户端
准备支持 VNC 的客户端，并确认连接目标包含正确端口。首次连接先采用较低分辨率和自适应画质，确认输入稳定后再提高显示参数。
起步：1920×1080 / 24-bit / 自适应
建议的验证顺序：先用 SSH 验证地址、端口、账户和凭据，再连接图形界面。SSH 正常而 VNC 异常时，排查范围可直接收敛到图形服务、VNC 端口和客户端参数。
02 / Glossary mini
先统一术语，再对照配置
以下词语会出现在订单、控制台、连接文档和故障记录中。每个术语对应明确的资源边界或技术动作。
- 物理节点
- 实际运行 macOS 的 Mac mini 硬件。节点地址、区域和节点编号共同标识当前交付资源。
- 独享
- 单一租户使用整台设备的芯片、内存和存储，不与其他租户共享操作系统实例。
- 云端 Mac
- 部署在远程节点、通过网络访问的 Mac。MiniDeploy 提供的是独享物理机，非虚拟机。
- VNC
- 传输远程图形界面、键盘与指针操作的协议。体验主要受往返延迟、分辨率、色深和画面变化量影响。
- SSH
- 用于远程命令行、文件同步和自动化操作的加密连接方式，适合环境检查、构建和日志采集。
- self-hosted runner
- 由团队自行管理、接收 CI 作业的执行端。可固定 Xcode 版本、缓存路径、工作目录和构建依赖。
- 工具链
- 完成构建所需的 Xcode、命令行工具、包管理器、Ruby、fastlane、脚本和环境变量集合。
- 节点延迟
- 客户端与节点之间的数据往返时间，通常以毫秒表示。数值越低，远程桌面的输入反馈通常越及时。
03 / Terminal mock
用三段输出验证连接、构建与上传
终端输出应能回答三个问题：是否进入正确节点、Xcode 是否选择了预期版本、构建产物是否已被流水线接收。
$ ssh -o ConnectTimeout=10 developer@node.example
Last login: Tue Mar 11 09:42:18
node: M4-Core / memory: 16GB / storage: 256GB
$ xcode-select -p
/Applications/Xcode.app/Contents/Developer
$ xcodebuild -workspace Demo.xcworkspace \
-scheme Demo -configuration Release build
Resolve Package Graph
CompileSwiftSources normal arm64
** BUILD SUCCEEDED **
$ bundle exec fastlane upload_build
[09:47:22]: Validating archive
[09:47:36]: Uploading artifact
[09:48:04]: Upload complete
[09:48:04]: Pipeline result: success
SSH 可达
Xcode 路径已确认
产物上传成功
示例中的主机名仅说明命令结构。实际地址、端口、账户和节点编号以控制台记录为准。采集日志时保留时间戳和失败命令，移除密码、私钥与签名材料。
04 / Migration path
本地 Mac 到云端 Mac 的三段迁移路径
不要一次搬迁全部目录。先迁项目数据，再复刻工具链，最后接入 CI。每一步都设置可验证的完成条件。
-
STEP 01
同步项目与配置清单
优先同步代码仓库、构建脚本和必要资源。大文件单独传输，并在传输前后计算校验值。不要直接复制旧机器上的全部缓存。
- 记录仓库分支与提交哈希
- 导出依赖版本清单
- 校验关键文件数量与大小
验收条件 代码可检出，依赖清单可读取 -
STEP 02
复刻 Xcode 与签名工具链
明确 Xcode 主版本、命令行工具路径、Ruby 与 fastlane 版本。签名材料应通过受控流程导入，并检查文件权限与有效范围。
- 确认 xcode-select -p
- 锁定包管理器与脚本版本
- 执行一次本地 Release 构建
验收条件 同一提交可稳定完成归档 -
STEP 03
接入 self-hosted runner
为 runner 建立独立工作目录与服务账户。限制标签匹配范围，设置并发数，并把缓存、日志和产物路径从源码目录中分离。
- 注册后执行最小测试任务
- 验证缓存命中与清理规则
- 确认失败日志能够回传
验收条件 提交触发、构建、回传闭环完成
05 / Remote desktop
远程 Mac 桌面参数从低负载开始
远程桌面体验不只由带宽决定。节点延迟、分辨率、色深、帧率、客户端缩放和后台文件传输都会影响输入反馈。
通用 VNC 客户端
适合跨平台访问。启用自适应压缩，并关闭不必要的动画效果。若客户端支持单独控制画质与色深，先保持画质自动，仅降低色深。
- 初始分辨率
- 1600×900
- 弱网色深
- 16-bit
- 建议可用带宽
- ≥ 10 Mbps
- 连接保活
- 30–60s
输入有明显延迟但画面清晰时，优先检查客户端到节点的往返延迟。高分辨率不会修复网络抖动，只会增加编码与传输负担。
| 使用状态 | 分辨率起点 | 色深 | 带宽建议 | 优先调整项 |
|---|---|---|---|---|
| 终端与轻量编辑 | 1600×900 | 16-bit | ≥ 8 Mbps | 降低动态画面 |
| Xcode 编码与调试 | 1920×1080 | 24-bit | ≥ 15 Mbps | 保持低延迟链路 |
| 多窗口开发 | 2560×1440 | 24-bit | ≥ 25 Mbps | 先确认稳定性 |
| 画面变化频繁 | 1920×1080 | 24-bit | ≥ 30 Mbps | 降低帧率或质量 |
带宽数值是配置起点，不代表延迟结论。远程桌面主要用于开发与管理时，应优先选择距离客户端较近的节点，并在实际网络环境中验证。
06 / CI/CD
让 runner 可复现，而不是只运行一次
CI 接入完成的标准不是看到一次绿色结果，而是相同提交在清理工作目录后仍能重复构建，失败时也能保留足够日志。
runner 注册
- 使用独立服务账户运行
- 标签至少区分架构与 Xcode 版本
- 默认并发设为 1，确认负载后再调整
- 注册令牌仅在配置阶段使用
工作目录隔离
- 每个作业使用独立检出目录
- 源码、缓存、日志和产物分开存放
- 任务结束后清理临时文件
- 禁止不同项目共用可写配置文件
缓存策略
- 缓存键包含依赖锁文件摘要
- 为缓存设置容量上限和失效条件
- 命中异常时允许完整重建
- 不要缓存签名材料和短期凭据
构建证书
- 按项目导入必要材料
- 限制文件权限与可访问账户
- 记录有效期并提前检查
- 任务日志不得输出敏感内容
日志留存
- 保留作业编号、提交哈希和时间戳
- 同时保存标准输出与错误输出
- 失败阶段上传诊断摘要
- 提交支持前先完成脱敏
最小验收任务
- 输出系统与 Xcode 版本
- 拉取依赖并运行单元测试
- 生成一个可识别的构建产物
- 清理目录后再次执行
资源边界：M4 Core 配置为 Mac Mini M4、16GB RAM、256GB SSD。并行任务会同时占用内存、存储 I/O 与网络，接入多个流水线前应先测量单任务峰值，而不是直接提高并发数。
07 / Diagnosis tree
按症状进入故障定位树
每次只改变一个变量，并记录时间点、命令、返回值与客户端网络。重复点击连接按钮通常不会增加有效信息。
无法连接：先判断地址不可达还是端口不可达
- 在控制台确认节点状态、地址、区域和端口没有抄错。
- 检查本地网络是否限制目标端口，切换网络仅用于对照，不作为长期解决方法。
- 使用端口探测确认是超时、拒绝还是能够建立连接，并记录完整时间点。
- 若 SSH 与 VNC 均不可达，提交节点编号、客户端城市、网络运营商和探测结果。
- 若 SSH 可达而 VNC 不可达，继续检查 VNC 端口、客户端目标格式和图形服务状态。
认证失败：核对账户、凭据版本与输入方式
- 确认使用的是系统账户名，不是邮箱、节点编号或设备名称。
- 重新从控制台核对临时凭据；若已更换密码，应使用更新后的凭据。
- 检查键盘布局、大小写、前后空格和特殊字符输入，避免从富文本中复制。
- SSH 密钥认证失败时检查公钥是否写入正确账户，以及目录和文件权限。
- 连续失败后停止重试，记录客户端、时间点和返回信息，再提交工单。
画面迟滞：区分高延迟、带宽不足与后台占用
- 先测客户端到节点的往返延迟，并连续观察是否存在明显抖动或丢包。
- 暂停代码同步、依赖下载和大文件上传，观察输入反馈是否恢复。
- 将分辨率降到 1600×900，色深降到 16-bit，保留其他设置不变。
- 关闭动态桌面、透明效果和高频刷新窗口，减少画面变化量。
- 若只在特定客户端异常，用另一客户端进行对照并记录版本。
构建失败：从版本、依赖、权限与环境变量收敛
- 输出当前 Xcode 版本、命令行工具路径、架构和目标 SDK。
- 核对依赖锁文件，清理项目级派生数据后执行一次完整构建。
- 比较本地与节点的 Ruby、fastlane、包管理器和脚本版本。
- 检查工作目录、临时目录和产物目录是否具备正确读写权限。
- 保存第一处实际错误及其前后日志，不要只提交最终退出码。
磁盘不足：先定位增长目录，再执行可回滚清理
- 查看系统卷剩余空间，并按目录统计源码、缓存、派生数据、模拟器数据和归档体积。
- 先删除可重新生成的项目缓存与失败任务临时文件。
- 为 CI 工作目录设置保留数量，避免历史检出和产物持续累积。
- 将长期产物同步到团队存储，确认校验结果后再删除节点副本。
- 若工作负载长期超过 256GB SSD 容量，订购时评估存储附加项。
08 / Security operations
把首次连接当作安全交接
独享物理机提供清晰的资源边界，节点内部的账户、密钥、项目文件与访问来源仍应由团队按最小权限原则管理。
更换临时凭据
首次登录后立即设置新的高强度密码，并存入团队认可的凭据管理工具。不要通过构建日志或普通文档传递密码。
限制远程访问来源
将 SSH 与 VNC 暴露范围限制到实际需要的团队出口地址。成员网络变化时更新规则，不长期保留临时测试来源。
使用最小权限账户
日常构建、远程操作和 runner 服务分别使用职责明确的账户。仅在安装或系统配置时临时提升权限，完成后及时退出。
移除临时密钥
迁移、排障或外部协作结束后，删除临时公钥、短期令牌和测试账户。同步检查自动化脚本中是否仍引用旧凭据。
日志脱敏边界：可保留节点编号、时间戳、命令名称、退出码和错误堆栈；应移除密码、私钥、访问令牌、签名材料、完整环境变量和项目中的敏感业务数据。
09 / Support escalation
提交可复现信息，支持才能直接进入定位
技术问题优先通过控制台工单提交，便于关联实例与持续补充日志。无法进入控制台或进行售前确认时，可发送邮件。
适合节点与连接问题
登录控制台后进入工单区域，新建技术支持请求并关联对应节点。一个工单聚焦一个主要问题，避免将无关异常混在同一记录中。
- 节点编号与所在区域
- 含时区的发生时间
- 客户端城市、网络与连接方式
- 最短复现步骤和预期结果
- 脱敏后的命令输出与日志
适合账户访问与售前确认
邮件主题建议使用“问题类型 + 节点编号或订单标识”。正文按时间顺序描述已经完成的检查，不发送密码、私钥或未脱敏的签名材料。
- 联系邮箱与所在时区
- 问题影响范围和优先级
- 已执行的排查步骤
- 可配合排查的时间段
- 需要确认的具体问题
提交前
复现一次并记录准确时间
提交时
附节点编号与脱敏日志
提交后
在同一工单持续补充信息