Docker Desktop WSL2 启动失败：distro stopped unexpectedly

Question

Docker Desktop WSL2 启动失败并提示“distro stopped unexpectedly”，是 Windows 下高频故障之一。典型表现为：启动 Docker Desktop 时卡在初始化阶段，WSL 状态显示 `Stopped`（通过 `wsl -l -v` 可见 `docker-desktop` 和 `docker-desktop-data` 两个发行版状态异常），日志中常含 `Failed to start distro: The operation timed out` 或 `WslRegisterDistribution failed: 0x80370102`。根本原因多为 WSL2 内核未正确加载、Hyper-V/虚拟机平台功能未启用、安全启动（Secure Boot）与 WSL2 兼容性冲突、或 `/etc/wsl.conf` 配置不当（如 `automount = false` 导致挂载失败）。此外，Windows 更新后内核版本不匹配、杀毒软件拦截、或 `docker-desktop-data` 分区损坏也会触发该错误。此问题非单纯重启可解，需系统性排查 WSL 基础环境、权限策略与 Docker 集成配置。

Answer 1

```html

一、现象层：精准识别故障表征

启动 Docker Desktop 时界面长期停滞在“Starting Docker Engine…”阶段，Windows 任务栏托盘图标呈灰色；执行 wsl -l -v 可见 docker-desktop 和 docker-desktop-data 均显示 Stopped 状态；事件查看器中 Applications and Services Logs > Microsoft > Windows > WSL 下频繁出现错误事件 ID 1001/1002；Docker 日志（%LOCALAPPDATA%\Docker\log.txt）含关键线索：Failed to start distro: The operation timed out 或 WslRegisterDistribution failed: 0x80370102（即“虚拟机未启用”错误码）。

二、环境层：验证 WSL2 底座健康度

• 检查 Windows 功能：运行 DISM /Online /Get-Features | findstr "VirtualMachinePlatform HypervisorPlatform"，确认 VirtualMachinePlatform 和 HypervisorPlatform 均为 Enabled
• 验证 Secure Boot 状态：以管理员身份运行 Confirm-SecureBootUEFI（PowerShell），返回 True 时需特别关注兼容性（部分 OEM 固件存在 WSL2 内核签名校验缺陷）
• 检查 WSL 内核版本：执行 wsl --status，比对 WSL kernel version 与 官方最新 wslkernel.exe 版本是否一致

三、配置层：解剖 /etc/wsl.conf 与注册表策略

进入任意 WSL 发行版（如 Ubuntu）执行 cat /etc/wsl.conf，重点排查以下高危配置：

配置项	危险值	影响说明
automount	false	Docker Desktop 依赖自动挂载 Windows 驱动器以加载配置和镜像元数据
interop	false	禁用 Windows 二进制互操作，导致 dockerd 无法调用 wsl.exe 启动辅助进程

四、数据层：诊断 docker-desktop-data 分区完整性

当 docker-desktop-data 损坏时，wsl --export docker-desktop-data 会报 I/O 错误。推荐诊断流程：

1. 备份当前状态：wsl --export docker-desktop-data C:\tmp\dd-data-backup.tar
2. 注销发行版：wsl --unregister docker-desktop-data
3. 重置初始化：wsl --import docker-desktop-data %LOCALAPPDATA%\Docker\wsl\data\ %LOCALAPPDATA%\Docker\wsl\distro\ --version 2

五、系统层：构建可复现的排障决策树

graph TD
    A[启动失败] --> B{wsl -l -v 显示 Stopped?}
    B -->|Yes| C[检查 wsl --status & Hyper-V 功能]
    B -->|No| D[检查 Docker Desktop 服务日志]
    C --> E{Secure Boot = True?}
    E -->|Yes| F[尝试禁用 Secure Boot 或更新 UEFI 固件]
    E -->|No| G[验证 wslkernel.exe 版本并手动更新]
    G --> H[/etc/wsl.conf 是否含 automount=false?]
    H -->|Yes| I[临时注释该行并 wsl --shutdown]
    H -->|No| J[杀毒软件白名单添加 wsl.exe/dockerd.exe]

六、进阶层：企业级策略兼容性分析

在域控环境中，组策略 Computer Configuration > Administrative Templates > System > Device Guard > Turn on Virtualization Based Security 若启用，会与 WSL2 的轻量级 VM 架构产生资源竞争；同理，第三方容器安全平台（如 Aqua Security、Sysdig Secure）的内核模块可能 hook WSL2 的 vmmem 进程导致超时。建议通过 driverquery /v | findstr "wsl\|vmmem" 排查冲突驱动。

七、验证层：闭环测试与黄金指标

修复后必须验证以下 4 项黄金指标：

• wsl -t docker-desktop && wsl -t docker-desktop-data && wsl -d docker-desktop -- ls /var/run/docker.sock（确认 socket 文件存在）
• docker info --format '{{.ServerVersion}} {{.DefaultRuntime}}' 返回非空且含 runc
• 在 WSL 中执行 cat /proc/sys/fs/inotify/max_user_watches ≥ 524288（避免文件监控不足导致构建失败）
• Windows 事件查看器中 WSL 日志无 Error 级别事件持续 5 分钟以上

```