客户端
准备受支持的连接工具
确认客户端版本可用，并保留一种备用接入方式。首次会话前关闭会重写键盘映射、代理或显示缩放的扩展。
连接与迁移手册
从交付信息到可复现的云端 Mac 工作流
先验证节点、凭据与本地网络，再建立远程会话。连接稳定后，按代码数据、工具链和 CI 三条路径迁移，不把本地环境一次性整包搬过去。
- 连接顺序
- 核对交付 → 建立会话 → 修改凭据
- 迁移顺序
- 代码数据 → 工具链 → CI
会话交接登记板
REMOTE / READY
01
验证交付
节点地址、用户名、访问方式
02
建立会话
网络、画面、键盘与权限
03
迁移工作流
数据、工具链、Runner 与产物
物理形态
独享物理机
运行环境
非虚拟机
处理原则
小批迁移，可验证回退
连接前检查
先把会话失败因素留在本地排除
首次连接不要同时迁移项目。先完成五项基础检查，确认本地客户端、网络和交付资料能够支持一段稳定会话。
网络
使用稳定链路完成首连
优先使用有线网络或稳定 Wi-Fi，暂停大文件同步和本地上传。若经过企业代理，先确认远程会话与 SSH 流量未被改写。
交付资料
逐项核对地址和凭据
从控制台读取节点地址、用户名和连接方式，不从聊天记录或旧工单复制。凭据只放入密码管理工具，不写进脚本和仓库。
显示
先用保守分辨率接入
首次连接使用单显示器和常规缩放，确认文字、光标与快捷键正常后再提高分辨率，避免把显示问题误判为网络问题。
本地文件
只准备首轮验证所需数据
首批仅带项目清单、依赖锁文件和一个可验证的小型分支。媒体源文件、历史缓存和归档包留到连接验证完成后分批传输。
首次连接流程
一次只验证一个变量
把第一次会话拆成地址、连接、凭据、输入和显示五步。每一步都有明确完成条件，出现异常时能定位到最近一次变更。
-
01
完成条件：目标信息逐项一致
验证节点地址
对照控制台交付信息检查主机名或地址、用户名与连接协议。先确认目标节点一致，再尝试建立会话。
-
02
完成条件：输入与画面连续可用
建立最小会话
使用单显示器、常规分辨率和默认画质接入，保持数分钟并完成窗口切换、文本输入与文件浏览。
-
03
完成条件：新凭据重新登录成功
修改初始凭据
首次进入后立即设置独立强凭据，更新密码管理工具中的记录，并使交付阶段使用的初始凭据退出日常流程。
-
04
完成条件：编辑器快捷键无冲突
确认键盘布局
测试 Command、Option、Control、方向键及常用中英文输入。远程客户端与 macOS 布局应保持一致。
-
05
完成条件：目标画面下稳定操作
调整显示设置
基础会话稳定后再提高分辨率、缩放和画质。每次只改一项，并观察文字清晰度、光标延迟和网络占用。
迁移路径
本地 Mac 到云端 Mac，拆成三条可回退路径
三条路径按顺序执行。每栏都记录输入、操作、验证结果与回退点，避免在远端环境尚未稳定时同时改变代码、工具版本和自动化配置。
数据迁移
- 输入
- 代码仓库、依赖锁文件、必要素材与校验清单
- 操作
- 先传小型可构建分支，再按目录分批同步缓存、素材和归档
- 验证结果
- 仓库状态一致，关键文件校验通过，样例项目可读取
- 回退点
- 保留本地原始副本，远端批次进入独立暂存目录
工具链复现
- 输入
- macOS、Xcode、命令行工具、包管理器和脚本版本表
- 操作
- 按依赖顺序安装并锁定版本，逐项运行诊断命令
- 验证结果
- 同一提交可完成解析、编译、测试和归档前检查
- 回退点
- 保存版本清单与配置副本，失败时回到上一组已验证版本
CI 接入
- 输入
- Runner 配置、变量清单、密钥范围、构建目录与产物规则
- 操作
- 先注册隔离 Runner，再接入最小构建任务和产物上传
- 验证结果
- 任务可重复执行，日志、退出码和产物位置明确
- 回退点
- 停用新 Runner，恢复原执行器并清理远端临时目录
数据迁移指南
按可重建性决定传输优先级
代码和配置先行，可重新生成的缓存后置，难以重建的签名材料与媒体源文件独立核验。大包迁移前先用小样本验证路径和权限。
| 数据类型 | 首批内容 | 建议操作 | 验证方式 | 回退处理 |
|---|---|---|---|---|
| 代码仓库 | 主仓库、子模块、依赖锁文件 | 从干净克隆开始，避免直接复制带本地状态的工作目录 | 检查分支、提交号、子模块与未跟踪文件 | 删除远端副本后重新克隆 |
| 构建缓存 | 只迁移已确认能复用的缓存 | 先完成一次无缓存构建，再按工具分别恢复缓存 | 比较命中日志、构建结果与磁盘占用 | 清空对应缓存目录并重新生成 |
| 签名材料 | 项目实际需要的最小集合 | 通过受控加密通道传输，限制文件与钥匙串权限 | 执行不上传产物的签名验证 | 移除导入项并撤销临时访问权限 |
| 媒体素材 | 一组可完成流程验证的小样本 | 按项目、批次和用途建立目录，不与缓存混放 | 检查文件数、大小与内容校验值 | 删除当前批次并从本地原件重传 |
| 大体积归档 | 索引、清单与单个测试归档 | 分卷传输，记录每卷状态，避免一次性覆盖目标目录 | 逐卷校验并抽查解包结果 | 仅重传失败分卷，不重复全量传输 |
迁移完成判据
不是“文件已经传完”，而是远端能从明确提交和依赖清单复现一次可核对的构建结果。
工具链复现
先登记版本，再恢复项目环境
不要从“安装所有常用工具”开始。以项目实际依赖为边界，按系统、编译器、命令行工具、依赖管理、证书和脚本的顺序复现。
登记项
核对动作
通过信号
macOS
记录系统版本、架构、磁盘空间和区域设置，确认项目要求与系统能力相容。
系统信息已归档
Xcode
确认项目指定版本、首次启动组件和当前开发者目录，不依赖图形界面中的临时选择。
版本与路径一致
命令行工具
检查编译器、SDK、Git、Ruby 或项目需要的其他运行时，记录实际解析到的路径。
命令解析无歧义
包管理器
按锁文件恢复依赖，区分全局工具和项目内依赖，避免用本地已有缓存掩盖缺项。
干净安装可重复
证书与权限
仅导入当前任务需要的材料，核对钥匙串访问范围、文件权限和自动化进程可见性。
最小范围验证通过
项目脚本
从只读检查开始，再运行依赖解析、测试和构建。脚本不得依赖本地未登记的绝对路径。
同一提交结果一致
CI 接入
先跑通最小任务，再接入正式流水线
Runner 接入不应与工具链迁移同时发生。先确认人工会话中的构建可重复，再把同一命令放入自动化任务。
注册隔离执行器
为云端 Mac 使用独立 Runner 标识和标签，限制可接收的仓库与任务类型。先运行只输出系统信息的诊断任务。
分开配置变量与密钥
普通环境变量记录版本和路径，敏感值交给受控密钥存储。日志中禁止回显令牌、私钥和签名材料。
固定构建目录边界
区分源码、依赖缓存、临时输出和最终产物目录。任务开始前检查剩余容量，结束后只清理可重建内容。
明确产物上传规则
上传动作只读取约定输出目录，同时保留提交号、构建号和校验信息，避免把临时日志混入交付包。
让失败任务可安全重跑
捕获退出码并清理锁文件、挂起进程和临时目录。保留诊断日志后，下一次任务应从已知状态开始。
转入正式流水线前
至少验证一次全新工作目录构建、一次失败后的重跑，以及一次产物上传与校验。三项都通过后再扩大任务范围。
连接命令示例
用只读命令确认会话与基础环境
以下检查不修改系统配置。先在本地终端设置控制台交付的主机和用户名，再建立 SSH 会话并记录系统、架构、磁盘与开发工具路径。
不要写入仓库
主机、用户名、密钥路径和令牌不进入项目脚本或版本控制。
不要立即安装
先完成只读检查，确认当前状态后再执行工具链变更。
会话验证清单
READ ONLY
export SETMINI_HOST="控制台交付的节点地址"
export SETMINI_USER="控制台交付的用户名"
ssh "${SETMINI_USER}@${SETMINI_HOST}"
hostname
sw_vers
uname -m
df -h /
xcode-select -p
xcodebuild -version
git --version
echo "$SHELL"
会话安全
把远程会话当作生产访问管理
独享物理机不等于可以放松访问控制。凭据、权限、锁屏、退出和敏感文件清理都需要进入团队交接清单。
强凭据
为节点设置独立凭据并由密码管理工具保存。成员变更、疑似泄露或异常登录后立即更新。
最小权限
日常开发使用完成任务所需的最低权限。临时提升权限后及时退出，不把高权限写入自动化脚本。
离席锁屏
短暂离席也要锁定会话。共享办公环境中同时关闭本地屏幕预览，避免远端内容暴露。
完整结束会话
任务完成后退出远程客户端和 SSH 会话，确认后台没有遗留交互式进程或临时端口转发。
清理敏感文件
移除临时下载、调试导出、未加密归档和不再需要的签名材料，保留清理记录。
上报访问异常
发现未知会话、异常进程或凭据风险时，先保存发生时间和必要日志，再通过控制台提交工单。
登录控制台提交工单