跳至主要內容

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

高谷深陵大约 13 分钟约 3976 字
Rancher Desktop 虚拟机containerd Moby镜像存储Kubernetes rdctl与退出治理知识海报
Rancher Desktop VM、引擎与存储边界宿主设置进入受管 Linux VM，再选择 containerd/nerdctl 或 Moby/Docker API；引擎、namespace、Kubernetes、快照与重置各有独立状态。高清原图

Rancher Desktop 管理一套本地 Linux 环境，其中可以运行 containerd 或 Moby/dockerd，并按需启用 Kubernetes。官方 Container Engine 说明明确两条引擎一次只能有一条工作。切换引擎后，旧引擎的镜像和容器仍保存在原来的存储中，新引擎不会自动接管。

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

安装先满足宿主责任

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

以带图形桌面的 Ubuntu/Debian 开发机为例，先确认 test -r /dev/kvm && test -w /dev/kvm 成功；失败时按安装页检查硬件虚拟化与当前用户的 KVM 访问权限。它不是无图形服务器上的 Docker Engine 替代安装方式。从官方安装页进入 release，选择与 uname -m 对应的 .deb，完成发布页提供的摘要核对后，在下载目录执行：

# 将占位文件名替换为刚核验的实际 .deb；不要用通配符安装整个下载目录。
sudo apt install ./rancher-desktop_实际版本_amd64.deb

从桌面启动 Rancher Desktop，首次选择 containerd 或 Moby；无 Kubernetes 需求时取消启用，等待所选引擎启动完成。Windows 使用官方安装包和 WSL 2 前提，macOS 使用与 CPU 对应的应用包；安装操作按同一官方安装页执行。首次启动后保存：

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 APIMobysocket、API 字段、context、辅助容器与端口
团队直接操作 containerd namespace 或贴近 Kubernetes 镜像模型containerddefault / 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，不用依赖尚未准备好的业务工程：

FROM docker.io/library/alpine:3.22
USER 10001:10001
CMD ["sh", "-c", "printf 'containerd-ready uid='; id -u"]

确认 rdctl list-settings 中的 containerEngine.name 为 containerd，在这个新建的 Dockerfile 目录、Bash 终端中执行。临时目录只用于生成本轮唯一 tag，构建结果及其删除均明确限定在 default namespace；预期输出 containerd-ready uid=10001：

(
set -eu
work="$(mktemp -d "${TMPDIR:-/tmp}/te05-rd-build.XXXXXXXX")"
tag="te05-rd-containerd:$(basename "$work")"
owned=0
cleanup() {
  if [ "$owned" = 1 ]; then
    if nerdctl --namespace default image inspect "$tag" >/dev/null 2>&1; then
      nerdctl --namespace default image rm "$tag" >/dev/null || \
        printf 'inspect remaining image tag: %s\n' "$tag" >&2
    fi
  fi
  rmdir -- "$work" || printf 'retain nonempty lab directory: %s\n' "$work" >&2
}
trap cleanup EXIT
if nerdctl --namespace default image inspect "$tag" >/dev/null 2>&1; then
  printf 'tag already exists: %s\n' "$tag" >&2; exit 23
fi
owned=1
nerdctl --namespace default build -t "$tag" .
nerdctl --namespace default run --rm "$tag"
nerdctl --namespace default image inspect "$tag"
printf 'CONTAINERD_RUN_OK tag=%s\n' "$tag"
)

完成时应看到非 root 的 uid=10001 和 CONTAINERD_RUN_OK；失败时本轮 tag 也会尝试清理，若清理失败，先按打印的 tag 与 nerdctl --namespace default image inspect 核对，勿执行全局 prune。把 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 内部还可能存在 classic 与 containerd snapshotter 两套 image store；官方镜像迁移说明解释了切换后镜像暂不可见以及怎样识别旧 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 会重启后端，而且可能重置 Kubernetes。先从 rdctl list-settings 人工确认当前引擎与目标引擎。如果当前确为 Moby、目标是 containerd，只执行：

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

如果当前确为 containerd、目标是 Moby，只执行另一条路径，不与上一组连续运行：

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

命令返回不代表工作负载已恢复。等待条件应同时包括设置值、目标 CLI 可达、项目夹具通过和旧引擎测试标签在新存储中不可见。恢复原引擎前先停止目标引擎中的新写入，盘点切换期间产生的镜像、容器与卷并导出需要保留的数据；旧 store 恢复可见不会自动合并目标 store 的新数据。再运行反向 rdctl set，核对旧项目数据和新写入是否已按业务策略导入，不把“镜像又看得见”当作回退成功。

这项反向检查很重要：它把“镜像没有跨 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，需要局域网访问时显式评估防火墙、身份和测试数据暴露。

正向实验只用于已选择 Moby 的开发机。先用 rdctl list-settings 确认 containerEngine.name=moby；再运行 docker context show、docker context inspect "$(docker context show)" 与 docker info，确认 context 的 endpoint 确属本机 Rancher Desktop，而非 Docker Desktop 或远端 daemon。还要检查 DOCKER_HOST、DOCKER_CONTEXT 环境变量没有把 CLI 改指他处。把人工核对过的 context 名称（可能是 rancher-desktop，也可能是接到 Rancher Desktop socket 的 default）填入 RD_DOCKER_CONTEXT。Docker 端口发布参考给出省略宿主端口后的随机分配语义。以下 Bash 实验不占用预设端口：

(
set -eu
context="${RD_DOCKER_CONTEXT:?set verified Rancher Desktop Docker context}"
unset DOCKER_HOST DOCKER_CONTEXT
work="$(mktemp -d "${TMPDIR:-/tmp}/te05-rd-port.XXXXXXXX")"
name="$(basename "$work")"
docker_rd() { docker --context "$context" "$@"; }
cleanup() {
  label="$(docker_rd inspect "$name" --format '{{ index .Config.Labels "te05.lab" }}' 2>/dev/null || true)"
  if [ "$label" = "$name" ]; then
    docker_rd rm -f "$name" >/dev/null || printf 'container cleanup failed: %s\n' "$name" >&2
  fi
  rmdir -- "$work" || printf 'retain nonempty lab directory: %s\n' "$work" >&2
}
trap cleanup EXIT
docker_rd run -d --name "$name" --label "te05.lab=$name" -p 127.0.0.1::8080 \
  docker.io/nginxinc/nginx-unprivileged:1.28.2-alpine
host_port="$(docker_rd port "$name" 8080/tcp | awk -F: '{print $NF}')"
case "$host_port" in ''|*[!0-9]*) printf 'invalid mapped port: %s\n' "$host_port" >&2; exit 23 ;; esac
body="$(curl -q --noproxy '*' --retry 10 --retry-connrefused --retry-delay 1 \
  --fail-with-body --silent --show-error --max-time 5 "http://127.0.0.1:$host_port/")"
test -n "$body"
printf 'MOBY_HTTP_OK host_port=%s context=%s\n' "$host_port" "$context"
)

预期打印 MOBY_HTTP_OK，失败时只清理带有本轮标签的容器；清理失败会给出具体名称，先 inspect 再处理。在 containerd 路径另用 nerdctl --namespace default 做对应的端口夹具，不能沿用 Docker context。端口冲突反例应在隔离端口与独立实验对象上做；若界面显示运行而端口不可达，检查实际引擎、端口转发、宿主防火墙和 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、网络暴露、允许镜像等组织策略不能混在个人截图里。官方 Deployment Profiles 文档区分 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、数据库导出和源码提交。官方快照说明明确恢复会替换当前安装状态，包括偏好设置，而非合并新旧数据。恢复前停止项目写入，盘点快照后新增的制品与卷数据并独立导出，确认快照可用和当前版本兼容；选择要恢复的快照时，先从 rdctl snapshot list --json 核对名称，再在 Rancher Desktop 的 Snapshots 界面执行 Restore。恢复期间应用不可用；恢复后重新检查引擎、namespace、端口、volume 与项目夹具，并将导出的新增数据按业务规则重新导入。不能因为 snapshot restore 命令存在，就对正在写入的项目直接执行。

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

故障证据按五层收集

层证据典型问题
宿主OS/CPU、虚拟化、磁盘、WSL/KVM、代理后端启动失败、磁盘不足、网络被 VPN 截断
Rancher Desktoprdctl 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 自身的控制面。

权威资料与规范地址

安装、引擎与对象状态

配置、策略与命令

跳到正文