Rancher Desktop 工程手册：管住 VM、容器引擎与双份镜像状态

Rancher Desktop VM、引擎与存储边界宿主设置进入受管 Linux VM，再选择 containerd/nerdctl 或 Moby/Docker API；引擎、namespace、Kubernetes、快照与重置各有独立状态。高清原图

Rancher Desktop 不是“另一个 Docker 图形界面”。它管理一套本地 Linux 环境，并在其中提供 containerd 或 Moby/dockerd 两条容器路径，还可以启用本地 Kubernetes。官方 Container Engine 说明明确两条引擎一次只能有一条工作；切换后，旧引擎的镜像和 workload 在新引擎中不可见。这个行为是存储边界，不应被写成“升级后随机丢镜像”。

团队采用它之前要先回答：项目需要 Docker API，还是接受 containerd/nerdctl 语义；本地 Kubernetes 是否真有交付物；宿主虚拟化、磁盘和代理是否稳定；哪些设置由个人选择，哪些必须通过 deployment profile 固定。

安装先满足宿主责任

官方安装页持续维护 Windows、macOS 和 Linux 的实际要求。Windows 路径依赖 WSL 与虚拟化；macOS 同时存在 Intel 和 Apple Silicon 架构差异；Linux 需要受支持的包形态和 /dev/kvm 访问。不要把某次安装界面的最低版本或下载文件名抄成永久结论，团队文档保存官方入口和当前验证矩阵。

安装包从官方发布页或官方维护的软件仓库获得，并记录校验来源。首次启动后保存：

rdctl version
rdctl info
rdctl list-settings
rdctl snapshot list

rdctl 命令参考列出设置、启动、快照、重置和关闭等公开入口。rdctl list-settings 是比截图更适合审查的配置证据；至少关注 container engine、Kubernetes、VM CPU/内存、磁盘、网络、代理、端口和允许镜像策略。GUI 显示“Running”只能证明后端已启动，不能证明项目连接了正确引擎。

先选 containerd 还是 Moby

containerd 路径以 nerdctl 为主要命令入口，并使用 namespace 隔离对象；Moby/dockerd 路径提供 Docker API、Docker CLI 与 Compose 生态。用实际需求选择：

项目事实	更接近的默认路径	必须额外验证
Testcontainers、IDE 或工具硬依赖 Docker API	Moby	socket、API 字段、context、辅助容器与端口
团队直接操作 containerd namespace 或贴近 Kubernetes 镜像模型	containerd	default / k8s.io namespace、nerdctl 参数与 Compose 兼容
只需要构建、运行普通 OCI 容器	两者都可候选	Dockerfile、网络、volume、退出码和清理的正反夹具
频繁在两条引擎间切换	不应成为基线	双份存储、重复拉取、故障归属和回滚成本

当前选择与实际命令要同时验证：

rdctl list-settings
nerdctl info
docker context show
docker info

只有所选引擎的主要入口应成功连接。containerd 本身不提供 Docker-compatible API；需要 Docker API 的项目不能仅因为 nerdctl run 成功就判定兼容。

containerd 的 namespace 是对象身份的一部分

在 containerd 路径下先列出 namespace：

nerdctl namespace ls
nerdctl --namespace default containers
nerdctl --namespace default images
nerdctl --namespace k8s.io containers
nerdctl --namespace k8s.io images

普通本地 workload 常落在 default，Kubernetes 对象常见于 k8s.io。不指定 namespace 时“看不到”并不等于对象被删除。团队脚本应显式写 namespace，不依赖开发者当前习惯；清理也必须限定 namespace、label 和名称。

用项目 Dockerfile 完成最小闭环：

set -eu
tag="te05-rd-containerd:check"
nerdctl --namespace default build -t "$tag" .
nerdctl --namespace default run --rm "$tag"
nerdctl --namespace default image inspect "$tag"
nerdctl --namespace default image rm "$tag"

把 run 改成错误参数或占用端口，命令应非零退出并留下可定位日志。只验证 build 成功不足以证明网络、volume、用户或停止语义。

Moby 路径必须同时检查 context 和 image store

切到 Moby 后，Docker CLI 还可能保留其他 Desktop、远端 daemon 或历史 context。先确认：

docker context show
docker context inspect "$(docker context show)"
docker version
docker info
docker image ls --digests

客户端版本存在不代表连接的是 Rancher Desktop 后端。把 docker info 中的 server、storage driver、root directory 与 Rancher Desktop Diagnostics 一起保存。Moby 内部还可能存在不同 image store；设置变化导致对象不可见时，先确认 store，而不是立刻 reset。

官方 Testcontainers 指南明确要求选择 Moby，因为该工具依赖 Docker API。类似依赖不能按“容器能运行”推断，应为每种语言实现运行真实集成测试，并检查 socket、端口回连和清理辅助容器。

切换引擎前先把本地状态当作不可移植

切换前保存两边清单并把重要制品推到 Registry：

nerdctl namespace ls
nerdctl --namespace default images
nerdctl --namespace k8s.io images
docker image ls --digests
docker volume ls
rdctl list-settings

然后停止项目容器，确认卷 owner 与备份，使用 Digest 记录可交付镜像。执行切换：

rdctl set --container-engine.name=containerd
rdctl list-settings
nerdctl info

rdctl set --container-engine.name=moby
rdctl list-settings
docker info

rdctl set 会重启后端；命令返回不代表工作负载已恢复。等待条件应同时包括设置值、目标 CLI 可达、项目夹具通过和旧引擎测试标签在新存储中不可见。最后回到团队批准的主引擎并复验。

这项反向检查很重要：它把“镜像没有跨 store 出现”确认为预期边界。迁移所需镜像应从受控 Registry 按 Digest 重新拉取，不能复制 Rancher Desktop VM 内部目录。

本地 Kubernetes 是额外控制面

启用 Kubernetes 会增加镜像、节点、网络、Ingress、持久卷和升级状态，也会改变 CPU、内存、磁盘和端口占用。项目不需要验证 Kubernetes 行为时保持关闭；需要时则保存：

rdctl list-settings
kubectl config current-context
kubectl cluster-info
kubectl get nodes -o wide
kubectl get storageclass

context 必须明确指向 Rancher Desktop，不能把测试命令误发到共享集群。containerd 的 k8s.io namespace 由 Kubernetes 管理，不应使用无范围 nerdctl rm 清理。关闭 Kubernetes 前先导出需要的数据和声明；“容器引擎仍在”不保证集群 volume 或 workload 自动保留。

端口与特权服务不能靠 UI 猜

宿主到 VM、容器或 Kubernetes service 之间存在多层转发。Windows 安装可选择 privileged service；缺少它时，某些非 loopback 暴露能力会受限。开发机默认优先绑定 127.0.0.1，需要局域网访问时显式评估防火墙、身份和测试数据暴露。

正向实验：

set -eu
name=te05-rd-port
docker rm -f "$name" >/dev/null 2>&1 || true
docker run -d --name "$name" -p 127.0.0.1:18088:8080 \
  docker.io/library/nginxinc/nginx-unprivileged:alpine
curl --fail --silent http://127.0.0.1:18088/ >/dev/null
docker rm -f "$name"

在 containerd 路径使用等价的 nerdctl --namespace default 夹具。反向实验占用同一宿主端口，第二个容器应非零退出；若界面显示运行而端口不可达，检查实际引擎、端口转发、宿主防火墙和 privileged service，而不是先删镜像。

代理、CA、Registry 和允许镜像策略

流量可能由宿主应用、Rancher Desktop VM、containerd、dockerd、Kubernetes 组件或容器内进程发起。代理和 CA 必须按发起层验证。保存：

rdctl list-settings
nerdctl info
docker info

再分别从当前引擎按 Digest 拉取批准镜像。宿主浏览器能打开 Registry 只证明宿主链路；VM 内 TLS 失败要检查 Rancher Desktop 的代理与证书注入。Registry 凭证进入系统批准的 credential store，不能写入 deployment profile、仓库或截图。

Allowed Images 能限制可访问的 registry/repository pattern，但它不是签名或内容信任的替代品。团队仍需验证 Digest、来源审批和漏洞策略。策略启用后应同时做正例和反例：批准镜像可拉取，未批准 registry 被拒绝并留下明确错误。

Deployment Profile 固定组织基线

CPU、内存等个人可调参数与 container engine、Kubernetes、网络暴露、允许镜像等组织策略不能混在个人截图里。Rancher Desktop deployment profile 区分 defaults 与 locked：前者提供初值，后者禁止用户改动。

配置变更先以 rdctl list-settings 形成机器可读基线，再由官方 profile schema 生成对应 macOS plist、Windows Registry 或 Linux JSON。schema 会演进，不能从旧版本复制字段后假设仍被识别。部署后做反证：锁定字段在 UI 和 CLI 都无法越权修改，非锁定字段仍可按制度调整。

Snapshot、Factory Reset 与卸载不是同一动作

快照适合在高风险升级或配置实验前保存 Rancher Desktop 管理的 VM 状态：

rdctl snapshot create before-runtime-change
rdctl snapshot list --json

快照不是项目数据备份的唯一副本，也不替代 Registry、数据库导出和源码提交。恢复前停止项目写入并确认当前版本兼容；恢复后重新检查引擎、namespace、端口、volume 与项目夹具。

风险从低到高依次是应用重启、后端重启、引擎切换、Factory Reset、卸载并删除残留数据。官方安装文档说明，普通卸载可能留下 VM、配置、快照或缓存；Factory Reset 也可能按选项保留部分材料。团队清理流程应依据当前官方路径和实际目录逐项盘点，不能维护一条跨平台的无条件递归删除命令。

故障证据按五层收集

层	证据	典型问题
宿主	OS/CPU、虚拟化、磁盘、WSL/KVM、代理	后端启动失败、磁盘不足、网络被 VPN 截断
Rancher Desktop	rdctl version/info/list-settings、Diagnostics	配置未生效、后端重启、profile 锁定
引擎	nerdctl info 或 docker info	选错 engine、store、socket 或 storage driver
对象	namespace、image、container、volume、network 清单	对象在另一 namespace/store、owner 不明
项目	build/run/test、端口、日志、退出码	Dockerfile、挂载、健康检查或工具 API 不兼容

Factory Reset 会同时抹掉多层证据，应是已完成导出后的恢复动作，不是第一条排障命令。

升级、交接与退出

团队基线写清安装渠道、支持宿主、VM 资源、主引擎、Kubernetes 开关、namespace、Docker context、代理/CA、Allowed Images、deployment profile、快照策略和数据 owner。升级前创建受控快照或外部备份，在代表性平台完成构建、运行、端口、volume、API 和重启夹具，再分批推广。

退出前保存：

rdctl list-settings
rdctl snapshot list --json
nerdctl namespace ls
nerdctl --namespace default images
nerdctl --namespace k8s.io images
docker image ls --digests
docker volume ls

未推送源码和业务数据先导出并验证恢复，镜像推 Registry，凭证撤销，profile 由 owner 拆除。然后按当前平台的官方卸载步骤处理应用、VM、缓存与快照；结束后确认命令路径、context、WSL/KVM 资源和残留目录符合预期。

若还需要与 Docker Desktop 或 Podman 比较迁移成本，进入替代运行时选型与迁移；这篇主文只维护 Rancher Desktop 自身的控制面。