每人独立密钥
不要让多人共用同一私钥。独立密钥便于识别访问者、单独撤销权限，并降低一次泄露影响整个团队的风险。
REMOTE ACCESS / 连接指南
用桌面或命令行连接你的云端 Mac
需要 Xcode、系统设置和图形工具时，从控制台打开浏览器远程桌面；执行构建、同步文件或运行自动化任务时，使用 SSH。两种方式连接的是同一台独享物理机，文件、依赖和运行环境会持续保留在该节点上。
节点全年 365 天运行
独享物理机
非虚拟机
DISPLAY
1920 × 1080
KEYBOARD
Local mapping
$ ssh node-user@$NODE_HOST
Host key verified
macOS session ready
$
Physical node online
SSH / DESKTOP
01 / 选择方式
先按任务选择连接入口
浏览器远程桌面与 SSH 不互相替代。前者提供完整 macOS 图形界面，后者适合可脚本化、低带宽和长时间运行的任务。
| 比较项 | 浏览器远程桌面 | SSH |
|---|---|---|
| 适用任务 | Xcode 图形操作、系统设置、应用界面检查、键盘与显示配置 | 构建脚本、Git 操作、依赖安装、日志检查、自动化与批量文件处理 |
| 交互方式 | 浏览器内显示远程桌面，通过本地键盘和指针操作 | 终端命令行，可配合密钥、终端复用和脚本运行 |
| 开始前准备 | 节点处于在线状态、浏览器允许必要的会话连接、已取得节点登录信息 | 节点地址、用户名、私钥文件、已核对的首次主机指纹 |
| 网络建议 | 稳定连接优先；高延迟时降低分辨率和色彩质量 | 带宽需求较低；长任务建议使用终端复用并将日志写入文件 |
| 退出方式 | 先保存工作，再从桌面会话退出或关闭远程视图 | 使用 exit 正常结束会话，不直接中断正在写入的任务 |
建议：首次接入先用浏览器远程桌面核对系统状态和键盘布局，再配置 SSH 密钥。日常开发可保留桌面用于图形操作，同时让构建和同步任务通过 SSH 执行。
02 / 图形界面
从控制台进入浏览器远程桌面
完整流程通常包含节点状态确认、凭据核对、会话建立和本地输入适配。若页面未进入桌面，不要连续重复提交登录请求。
-
01
打开节点详情
登录控制台，在实例列表中找到目标节点。先确认节点标识、区域和状态与订单一致，状态显示在线后再打开连接入口。团队管理多台云端 Mac 时，应先核对节点标识，避免进入错误环境。
核对 节点标识 · 区域 · 在线状态 -
02
验证登录信息
使用控制台为该节点显示的登录信息，不复用其他节点的凭据。粘贴时检查首尾是否带入空格；若团队内部交接访问权限，应通过受控的凭据流程完成，而不是在群聊或构建日志中传递。
核对 用户名 · 凭据范围 · 输入空格 -
03
进入桌面并检查输入
桌面加载后先打开一个无敏感内容的文本区域，测试字母、数字、符号、Command、Option 和中英文切换。若按键结果与本地键盘不一致，先统一本地布局和远程系统布局，再继续证书或命令输入。
测试 符号键 · 修饰键 · 输入法 -
04
调整分辨率与显示质量
文字编辑与 Xcode 操作可从 1920 × 1080 开始。画面延迟明显时，优先降低分辨率，其次降低色彩质量；网络恢复稳定后再逐项调高，便于判断是哪项设置造成卡顿。
起点 1920 × 1080
页面空白时
先等待当前连接完成，再刷新一次节点详情。确认浏览器没有阻止会话所需功能，并用无扩展的独立窗口复测。
键位错位时
记录具体按键、预期字符和实际字符。先让本地与远程布局一致，再检查浏览器是否截获组合键。
画面模糊时
确认浏览器缩放为标准比例，再匹配远程分辨率。不要同时调整浏览器缩放、系统缩放和远程画质。
03 / 命令行
建立可核验的 SSH 会话
SSH 连接前需要明确地址、用户名和私钥来源。首次出现的主机指纹必须与控制台记录核对，不能直接跳过。
创建独立密钥
LOCAL
ssh-keygen -t ed25519 -f ~/.ssh/mw_node为 MacWorker 节点单独创建密钥，设置本地密钥口令。不要覆盖团队已经使用的默认密钥。
设置连接参数
LOCAL
export NODE_HOST="控制台显示的节点地址"
export NODE_USER="控制台显示的用户名"地址和用户名以控制台当前显示为准。环境变量只作用于当前终端会话，可避免命令历史中反复出现连接参数。
首次连接
VERIFY
ssh -i ~/.ssh/mw_node "$NODE_USER@$NODE_HOST"终端显示指纹后暂停操作，将算法类型和完整指纹与控制台记录逐字符核对。完全一致时才确认连接。
正常退出
REMOTE
exit退出前确认文件写入、依赖安装和构建任务已经结束。长任务应放入可恢复会话，而不是依赖单一终端窗口持续在线。
04 / 安全基线
把访问权限控制到人和节点
独享物理节点不会与其他租户共享计算资源，但团队仍需管理密钥、凭据、成员变更和登录记录。
限制凭据共享
凭据不写入代码仓库、构建日志或项目文档。必须交接时使用团队批准的受控流程，并在交接后检查权限范围。
及时撤销成员权限
成员离开项目或职责变化时，当天移除对应公钥和控制台访问权限，同时轮换其可能接触过的共享凭据。
定期检查登录记录
至少按团队发布节奏检查登录时间、来源和失败记录。发现不符合工作时段或地区习惯的活动时，先冻结相关凭据再调查。
每次成员变更
移除公钥与控制台权限
每个发布周期
检查登录记录与活跃密钥
发现异常后
停止使用旧凭据并保留时间线证据
05 / 文件传输
通过加密连接移动输入与产物
上传前先确定任务真正需要的文件，下载时只拉取目标产物。依赖缓存、临时目录和历史归档不应默认随项目整体传输。
UPLOAD
上传构建资源
scp -i ~/.ssh/mw_node -r ./BuildInput "$NODE_USER@$NODE_HOST:~/Work/"适合一次性上传明确目录。传输前排除本地日志、临时产物和不需要的历史文件，并确认目标路径有足够磁盘空间。
DOWNLOAD
拉取构建产物
scp -i ~/.ssh/mw_node "$NODE_USER@$NODE_HOST:~/Work/output.zip" ./Artifacts/先在节点上整理并校验产物，再下载单个归档文件。下载完成后比较文件大小或摘要，避免使用不完整产物进入后续流程。
大文件传输控制
01
先缩小范围
只同步当前分支和任务所需资源，不默认复制整个工作目录。
02
再拆分时段
高延迟网络下分批传输，并避开本地网络拥塞时段。
03
最后做校验
保留源文件，确认大小与摘要一致后再删除中间归档。
06 / 会话优化
高延迟时优先减少交互成本
先判断问题发生在图形传输还是命令执行。远程桌面卡顿不一定代表节点计算性能下降，SSH 响应正常时应先调整画面参数。
DISPLAY
1920 × 1080
从适中分辨率开始
先保持单显示区域和适中分辨率。延迟明显时逐级降低，不同时改变多个参数；待操作流畅后再提高文字清晰度。
COLOR
逐级降低
优先保证输入响应
编写代码和调整系统设置通常不需要最高色彩质量。降低画质可减少画面更新量，完成视觉检查时再临时恢复。
TERMINAL
tmux
让任务脱离网络瞬断
构建、测试和依赖处理放入终端复用会话，并把输出同时写入日志文件。重新连接后恢复会话，不必从头执行任务。
tmux new -s build
tmux attach -t build
RECOVERY
保存状态
为断线准备恢复点
长流程拆成可重复步骤，输出写入固定目录，并记录最近完成阶段。连接中断后先检查进程和产物，不要立即重复启动同一任务。
07 / 错误速查
按症状缩小连接问题范围
排查时保留节点标识、发生时间、连接方式和完整错误摘要。每次只修改一个变量，避免无法判断哪一步真正生效。
SSH 提示认证失败
先核对用户名和私钥路径，再检查私钥文件权限以及公钥是否已配置到目标节点。使用详细模式确认客户端实际尝试了哪把密钥：
ssh -v -i ~/.ssh/mw_node "$NODE_USER@$NODE_HOST"不要把完整私钥或包含敏感字段的详细日志发送给他人。提交工单时只提供错误阶段、算法信息和经过处理的摘要。
浏览器连接后页面空白
确认节点仍处于在线状态，并等待当前会话建立完成。随后使用无扩展的独立浏览器窗口重试，检查浏览器是否阻止会话所需功能。若 SSH 可连接而桌面持续空白，应记录浏览器版本、发生时间和节点标识后提交工单。
键盘符号或修饰键错位
在无敏感内容的文本区域记录预期字符与实际字符，核对本地和远程系统的键盘布局。再检查 Command、Option、Control 是否被本地系统或浏览器快捷键截获。调整后逐键复测，不要在凭据输入区域直接试错。
桌面或 SSH 连接超时
按顺序检查本地网络、目标地址、节点状态和客户端设置。先更换到已知稳定的本地网络复测，再确认地址没有过期或复制错误。若同一节点的两种连接方式都超时，应记录本地时间、所在网络和错误持续时长。
SSH 提示主机指纹发生变化
立即停止连接，不要通过关闭校验或直接删除已知主机记录绕过提示。先确认节点地址是否改变，再通过控制台核对新指纹及变化原因。完成验证后，才可移除该地址对应的旧记录并建立新连接。
提交工单的最小信息：节点标识、问题发生时间与时区、连接方式、客户端及版本、完整错误摘要、已执行的排查步骤。不要附带私钥、密码、支付凭据或项目源代码。
READY TO CONNECT
选择节点后，直接从控制台开始连接
先确认节点在线，再按任务打开浏览器远程桌面或配置 SSH。需要图形操作与命令行协作时，两种会话可以连接同一台独享物理 Mac。