先查执行任务的 macOS 账户下 Docker Desktop 是否运行，再核对 Docker context、socket 和 CLI 路径。 Docker 官方列出的 Mac 最低内存要求为 4 GB；但即使机器满足要求，SSH 登录成功或 docker 命令存在，也不能证明 CI 已连上引擎。(docs.docker.com)
本文适合维护 Xcode 与容器任务共用节点的 CI 工程师、通过 SSH 操作远程 Mac 的开发者，以及负责节点准入和重启验收的 DevOps 工程师。
[ SECTION_01 ] 先区分主机连接、CLI 和引擎连接
SSH 能登录，只能说明远程主机接受了连接。docker 命令能运行，只能说明当前环境找到了 Docker CLI。只有 Docker CLI 成功查询到 Docker Engine，后续构建才进入容器任务排查阶段。
建议把错误先归入对应层级。评分表示诊断线索的直接程度，不是性能评分：5 分代表该信号通常能直接指向检查位置，仍需用实际命令确认。
| 错误表现 | 优先检查 | 线索评分 |
|---|---|---|
docker: command not found |
任务账户、Shell、PATH 和 CLI 安装位置 | 4/5 |
| CLI 有版本输出，但报无法连接 daemon | Desktop 状态、context、socket 和相关环境变量 | 5/5 |
| 手动 SSH 能用，CI job 失败 | CI 执行账户与交互会话的环境差异 | 5/5 |
docker info 成功，构建仍失败 |
仓库认证、网络、镜像与项目日志 | 4/5 |
排查时别只记“失败了”。保留 CI 日志中的完整报错、执行账户、退出状态和检查命令输出，才能判断问题是否从一层转移到另一层。
⚠️ Docker 官方在 Mac 连接说明中提到
unix:///var/run/docker.sock。但路径存在不等于引擎可访问：还要让实际任务账户使用该连接完成一次 Docker CLI 请求。(docs.docker.com)
[ SECTION_02 ] CLI 不存在或版本不对，先核对执行环境
CI 与人工 SSH 会话可能不是同一个账户，也可能使用不同的 Shell 启动配置。交互式终端加载了用户级 PATH，不代表后台任务也会加载相同配置。Docker 官方设置文档说明，Mac 上的 CLI 工具可以安装在系统路径或用户级路径；自 4.89.0 起，用户级 CLI 工具安装路径默认为 $HOME/.docker/bin，并可自动加入 PATH。实际版本与设置仍应以当前安装为准。(docs.docker.com)
在失败的 CI job 里运行以下命令，并与 SSH 终端的输出逐项比较：
id -un
echo "$SHELL"
printf '%s\n' "$PATH"
command -v docker
docker --version
若 command -v docker 没有结果，先确认该账户是否安装或能访问 CLI，再处理 PATH。若路径指向了非预期位置，或版本与人工会话不同，就先统一 CI 的可执行文件路径，不要把 CLI 问题误判为引擎故障。
Docker 官方提供的 Desktop CLI 可查询运行状态，也支持启动、停止和重启 Desktop。可以在目标账户下检查 docker desktop status；若该命令不可用，先核实安装的 Desktop 版本及 CLI 插件，再使用图形界面确认状态。CLI 存在、Desktop 已启动、Engine 可响应，是三个不同检查点。(docs.docker.com)
[ SECTION_03 ] CLI 可用但连不上，引擎入口要一起核验
先执行：
docker context ls
docker context show
docker context inspect <context名称>
env | grep -E '^(DOCKER_HOST|DOCKER_CONTEXT|DOCKER_CONFIG)='
docker version
docker context inspect 可显示 context 的端点信息；而 DOCKER_CONTEXT、DOCKER_HOST、DOCKER_CONFIG 等环境变量会影响客户端连接目标或配置读取。命令行参数也可能覆盖默认设置，所以要在失败的 CI job 内核验，而不是只看个人终端。(docs.docker.com)
SSH 登录远程 Mac 后，Docker 命令仍连不上引擎，先看什么？ 先看当前账户下 Desktop 是否运行，再看 docker context show 和 docker context inspect 输出的端点；之后检查 DOCKER_HOST、DOCKER_CONTEXT 是否把 CLI 指向了错误目标。不要因为默认 context 名称看起来正常，就跳过端点核验。
Docker 官方的 context 文档说明，docker context use 会更新用户级 CLI 配置，影响共享该配置的新会话；单次命令则可用 --context 指定目标。因此，对 CI 的诊断优先采用显式检查，确认后再决定是否修改默认 context。(docs.docker.com)
| 连接检查结果 | 更可能的问题 | 下一步 |
|---|---|---|
Desktop 状态为停止，docker version 只有 Client 信息 |
引擎尚未运行或未完成启动 | 在任务账户下启动 Desktop，等待状态稳定后复测 |
| context 端点与预期不符 | 默认 context 或环境变量覆盖 | 核对 DOCKER_CONTEXT、DOCKER_HOST，用预期 context 单次验证 |
| 端点看似正确，但请求仍失败 | socket 权限、socket 配置或引擎状态 | 从目标账户执行 Docker 请求；查 Desktop 设置及错误日志 |
| Client 与 Server 信息均可返回 | 已越过引擎连接层 | 停止改主机连接配置，转查拉取和构建日志 |
Docker Desktop 的 Mac 设置中包含默认 socket 相关选项；该选项是否启用、当前用户是否有权访问，都应在实际节点上确认。官方文档还说明，Desktop 启动时会检查配置，包括默认 socket 符号链接与 context 状态。由此可见，手动更改路径后仍未复测 Desktop 状态，容易留下配置不一致。(docs.docker.com)
[ SECTION_04 ] 终端成功而 CI 失败，比较账户和配置边界
Docker Desktop 已启动，但 CI 仍提示无法连接 daemon，怎么缩小范围？ 对照人工 SSH 会话与 CI job 的 id -un、HOME、PATH、DOCKER_CONFIG、DOCKER_HOST 和 DOCKER_CONTEXT。如果账户不同，用户级 CLI 路径、Docker 配置和应用状态都不能直接假定为共享。
Docker 官方的 Mac 安装说明提供了安装时指定用户的选项；这进一步说明安装和权限配置可能与用户边界有关。对于后台任务或无人值守运行，不要将“某账户能打开 Desktop”当成“另一个账户也能使用引擎”。先由实际执行账户完成连接测试。(docs.docker.com)
检查与修复按这 5 步进行：
- 确认实际账户。 在失败的 CI job 内记录
id -un、HOME和SHELL，不要用登录账号名称推断任务账户。 - 确认 CLI 来源。 运行
command -v docker与docker --version，核实路径、版本和 PATH 是否符合预期。 - 确认 Desktop 状态。 在同一账户下查看
docker desktop status；不可用时，用 Desktop 界面或对应版本支持的方式确认应用状态。 - 确认连接目标。 检查当前 context、端点及
DOCKER_HOST等变量，再通过docker version或docker info判断 Server 是否可访问。 - 在 CI 中复测并保存证据。 用目标任务执行最小容器请求，记录日志、退出状态与账户信息；修完后再次运行同一任务，不以 SSH 命令成功代替 CI 验收。
Docker 官方发布说明会记录版本更新和兼容性变化；发生升级后，若 CLI 路径或连接行为出现差异，应对照对应版本说明，而不是沿用旧节点的路径假设。(docs.docker.com)
[ SECTION_05 ] 引擎已连通，构建失败要换一层排查
当 docker version 能返回 Client 与 Server 信息，说明至少这次客户端请求已与引擎通信。接下来依次查看镜像拉取、仓库认证、网络访问和项目构建日志。拉取失败可能与仓库凭据或网络有关；构建命令已经启动后出现的错误，也可能来自镜像平台、容器内依赖或应用自身。
更换 CI 执行账户后，为什么 Desktop 可能不可用？ 新账户可能没有原账户的 PATH、Docker 配置或应用访问条件。比较两边的执行输出，定位差异后只修对应项；不要为了让 CLI“看起来能跑”而盲目切换 context、socket 或账户权限。
[ SECTION_06 ] 用真实任务和重启结果决定节点准入
无人值守节点必须证明任务账户能够恢复工作，不能只证明人工登录后临时可用。Docker Desktop 设置中有登录时启动相关选项，但这不等于任何 CI 账户、后台任务或重启流程都能自动恢复；应把实际重启复测作为验收条件。(docs.docker.com)
决策条件：
- 若目标 CI 账户能确认 Desktop 已运行、context 与 socket 指向预期引擎，且最小容器任务成功，则进入真实项目构建验收。
- 若只有人工 SSH 账户能访问，而 CI 账户失败，则先修正账户、PATH 或配置边界；修复前不要把节点标为可用。
- 若首次任务成功但受控重启后未能恢复，则限制为需人工介入的用途，或更换执行环境。
- 若引擎连接成功而项目构建失败，则保留主机连接配置，按拉取、认证、网络和项目日志逐项定位。
| 验收证据 | 通过标准 | 未通过时的处理 |
|---|---|---|
| 目标账户与 CLI 路径 | CI 日志可确认账户、PATH 和 CLI 来源 | 统一任务环境后重跑 |
| context、socket 与引擎响应 | 目标任务账户能查询到 Engine 信息 | 修正端点或访问配置后复测 |
| 最小真实容器任务 | 拉取或使用目标镜像并完成项目定义的最小任务 | 分层检查仓库、网络和构建日志 |
| 受控重启后的复测 | 重启后重复相同检查并取得成功记录 | 暂缓无人值守准入，调整恢复流程 |
这份排障过程没有本站节点实测记录，因此不提供 NOVAKVM 的具体配置、交付方式或重启测试结论。若当前方案依赖人工登录、账户环境漂移，或重启后需手动恢复，它就会增加维护成本，也难以作为稳定 CI 节点。若项目需要持续可访问的 macOS 构建环境，可先阅读 NOVAKVM 远程 Mac 环境信息，并结合 Mac mini 购买方案与远程使用选择比较自购与租赁：临时扩容、并行测试或短周期项目可评估租赁；长期持续高负载或必须接入本地物理设备的场景，则应优先核算自购。任何方案都应先用目标 CI 账户完成真实任务与重启复测。