【保姆级教程】windows 安装 docker 全流程

一、背景

许多小伙伴在安装 Dify 或是 RagFlow 这些工具的时候，往往会遇到一个难题，那就是 Docker 的安装。

首先，我们的PC安装的绝大部分是 Windows，但众所周知的原因，Windows 对 Docker 的支持并不是特别好，这方面的历史原因有很多，实际上 Docker 是 Linux 流派的技术，它主要得益于 Linux Namespace 和 CGroups 这些内核隔离技术，然而 Docker 大火之际，Windows 并没有提供类似的技术，这也导致了 Windows 在容器领域一直处于滞后的地位。

后来的演进过程中，Windows 为了跟进这项技术，也做了一些演进。目前市场上流行的个人PC 操作系统，主要还是以 Windows 10 和 Windows 11为主。而这两个版本对 Docker 的支持是略有不同的，这也导致了许多小伙伴在安装 Docker 时会出现不少问题。

在通过 Windows 安装 Docker 之前，我们有必要花点时间了解下 WSL 和 HyperV 这两项技术。

HyperV

HyperV 是微软最早提供的虚拟化技术，得益于现代 CPU 硬件层虚拟化的发展，如Intel的 VT - x 和 AMD 的AMD - V，操作系统可以通过硬件层扩展接口来完成虚拟化。HyperV 主要通过对CPU、内存、网络、硬件外设等模块进行技术抽象来完成虚拟化管理和调度，并提供了 VMM 来支持虚拟机的生命周期管理。

需要注意的是 HyperV 是2008年发布的技术（对标的是 VMware ESX、开源的XEN/KVM等虚拟化技术），而 Docker 是 2013 年开始出现的，也就是说 HyperV 是后来支持的 Docker，最早在 Windows 10 版本上出现了支持容器的 HyperV 组件，然而也仅限于专业版/企业版/教育版，如果是 Windows 10 个人家庭版本，需要单独安装 HyperV。

WSL

WSL 是 windows subsystem for linux 的简称，意思是Windows 上用于运行 Linux 的子系统。然而 WSL 历史上存在两个版本，这点同样也造成了大家的困扰。

WSL1 发布于 2016 年 8 月，随 Windows 10-1607 版本发布，它是一种基于 Windows NT 内核实现的组件，支持在用户模式下运行 Linux 二进制文件，原理是将 Linux 系统调用转换为 Windows 系统调用。简单说，由于 WSL1 仅仅是做了一层系统调用的转换，它并没有真正的 Linux 内核，所以对 Docker 的支持不是太好。
WSL2 于 2019 年 5 月，随 Windows 10-1903（高阶版本）发布。WSL2 相比 WSL1 带来了一个革命性的变化，那就是 WSL2 利用了 HyperV 的虚拟化功能来提供完整的 Linux 内核支持，而 WSL2 相比 HyperV 提供了更简单、简洁的操作接口。

不难发现，想要在 Windows 上完美运行 Docker，我们需要 WSL2 + HyperV 这两个底层技术，并至少确保操作系统在 Windows 10-1903 版本或以上。

二、环境准备

首先，我们需要明确 Windows 安装 Docker 的一些先决条件：

确保 Window 版本在 10/11 以上
确保系统启用了虚拟化支持
确保系统支持 HyperV 组件
确保系统安装了 WSL2 最新版本
确保虚拟化所需的 Windows 功能服务已经开启

1. 查询 Windows 版本

打开设置 -> 系统 -> 系统信息 -> Windows 规格

查看 Window 版本，如下：

2. 检查虚拟化支持

打开任务管理器 -> 性能 -> CPU，查看虚拟化是否开启：

如果虚拟化未开启支持，需要重启电脑，打开BIOS/UEFI 设置，启用硬件虚拟化技术。

3. HyperV 组件支持

在程序中搜索 Hyper-V 管理器或控制台，检查是否已经安装了 HyperV组件。

此外还可以通过命令行进行检查：

systeminfo | findstr /C:"Hyper-V"

Hyper-V 要求:     已检测到虚拟机监控程序。将不显示 Hyper-V 所需的功能。

一般的 Windows 个人家庭版默认不带 HyperV，如果发现 HyperV组件未安装，可通过脚本进行安装。

pushd "%~dp0"

dir /b %SystemRoot%\servicing\Packages\*Hyper-V*.mum >hyper-v.txt

for /f %%i in ('findstr /i . hyper-v.txt 2^>nul') do dism /online /norestart /add-package:"%SystemRoot%\servicing\Packages\%%i"

del hyper-v.txt

Dism /online /enable-feature /featurename:Microsoft-Hyper-V-All /LimitAccess /ALL

将以上脚本保存为 hyperv.cmd 文件，双击运行可完成安装。

脚本执行完成后，重新检查以确认 HyperV 安装完成。

4. 安装 WSL2 最新版本

访问如下地址获取安装包进行安装：

https://github.com/microsoft/WSL/releases

另一种办法，也可以通过 Microsoft Store进行下载安装。

安装完成之后，设置版本并检查状态：

> wsl --set-default-version 2

> wsl -v

WSL 版本: 2.5.4.0

内核版本: 6.6.75.1-1

WSLg 版本: 1.0.66

MSRDC 版本: 1.2.6074

Direct3D 版本: 1.611.1-81528511

DXCore 版本: 10.0.26100.1-240331-1435.ge-release

Windows: 10.0.22631.5039

4.1. 配置 WSL2

编辑 %USER_HOME%/.wslconfig文件：

对于 Windows 10 版本，采用如下配置：

[wsl2]

networkingMode=nat

[experimental]

autoMemoryReclaim=dropcache

对于 Windows 11 版本，采用如下配置

[wsl2]

networkingMode=mirrored

dnsTunneling=true

autoProxy=true

firewall=true

[experimental]

autoMemoryReclaim=dropcache

useWindowsDnsCache=true

bestEffortDnsParsing=true

hostAddressLoopback=true

保存 .wslconfig 文件，重启wsl服务：

 wsl --shutdown

 wsl

4.2. 参数差异

在 Windows 11 版本中，WSL 可支持镜像网络模式，并带来了一系列的性能提升配置。

具体的参数差异如下表所示：


参数示例	说明	版本要求
networkingMode=mirrored	网络模式，mirrored为镜像模式，nat 为代理模式。 mirrored 模式下 WSL实例与主机系统共享网络接口，nat 则无法共享。	镜像模式要求 windows 11
dnsTunneling=true	是否启用启用DNS隧道功能，以便WSL实例通过主机操作系统的网络接口解析DNS请求	windows 11
autoProxy=true	启用自动代理功能，WSL实例能够自动同步主机的网络代理设置	windows 11
firewall=true	启用WSL的防火墙支持，允许HyperV对WSL网络流量进行控制	windows 11
autoMemoryReclaim=dropcache	开启内存自动回收功能，当内存紧张时，WSL实例会释放缓存	windows 10/11
useWindowsDnsCache=true	允许WSL使用主机Windows系统的DNS缓存	windows 10/11
bestEffortDnsParsing=true	启用“尽力而为”DNS解析功能，当DNS请求失败时，系统会尝试通过其他方法解析以提供更稳定的网络体验。	windows 11
hostAddressLoopback=true	除了环回地址之外，允许 WSL 2 子系统使用分配给主机的IP 与主机进行互访（通常使用不同网口）	镜像模式要求windows 11

5. 开启虚拟化服务功能

打开控制面板 -> 程序 -> 启用或关闭系统功能，

将如下系统功能打开：

虚拟机平台
HyperV
适用于WIndows的Linux子系统

启用后根据提示重启系统后生效。

三、安装 Linux 发行版

WSL 2 利用了 Hyper - V 的虚拟化功能来提供更高效的 Linux 环境。

而为了让 Docker 在 WSL 2 上运行，需要安装一个支持 Docker 的Linux 发行版，如Ubuntu或Debian等，使得Docker 能找到所需的Linux 的内核功能和服务。

方式一：命令行安装方式

查看可用系统版本：

wsl --list --online

NAME                            FRIENDLY NAME

Ubuntu                          Ubuntu

Debian                          Debian GNU/Linux

kali-linux                      Kali Linux Rolling

Ubuntu-18.04                    Ubuntu 18.04 LTS

Ubuntu-20.04                    Ubuntu 20.04 LTS

Ubuntu-22.04                    Ubuntu 22.04 LTS

Ubuntu-24.04                    Ubuntu 24.04 LTS

OracleLinux_7_9                 Oracle Linux 7.9

OracleLinux_8_7                 Oracle Linux 8.7

OracleLinux_9_1                 Oracle Linux 9.1

openSUSE-Leap-15.6              openSUSE Leap 15.6

SUSE-Linux-Enterprise-15-SP5    SUSE Linux Enterprise 15 SP5

SUSE-Linux-Enterprise-15-SP6    SUSE Linux Enterprise 15 SP6

openSUSE-Tumbleweed             openSUSE Tumbleweed

安装 ubuntu

wsl --install ubuntu

方式二：应用市场安装

打开 MicroSoft Store，搜索 Ubuntu，点击进行安装：

方式三：离线安装

如果在线安装失败，可进行离线安装，参考文档：

https://learn.microsoft.com/en-us/windows/wsl/install-manual

通过以上链接下载对应的 Linux 发行版，如 Ubuntu2204-221101。

下载完毕后，打开PowerShell进入离线包所在目录，执行命令：

Add-AppxPackage .\Ubuntu2204-221101.AppxBundle

随后会生成 xxx.AppxBundle文件，双击该文件进行安装。

配置软件镜像

执行如下命令进入 Ubuntu 系统：

wsl -d Ubuntu

基于当前的网络配置方式，可根据需要配置网络代理

编辑 ~/.bashrc 命令，添加如下内容：

export http_proxy=http://xxx

export https_proxy=http://xxx

编辑 /etc/apt/sources.list ，添加国内镜像站，如阿里云镜像：

https://developer.aliyun.com/mirror/

更新镜像站：

sudo apt update

三、安装 Docker

Windows 上安装 DockerDesktop 来实现 Docker 的安装和管理。

1. 安装DockerDesktop

访问 Docker 官网，下载 Docker-Desktop：

https://docs.docker.com/desktop/setup/install/windows-install/

双机运行，直接安装，注意勾选 Use WSL Instead Of HyperV。

2. 配置Docker镜像源

安装完成之后，启动 DockerDesktop。

如果启动成功，可以看到启动界面。

选择设定 -> Docker Engine：

编辑 yaml ，在其中添加镜像源地址，添加如下内容

{

    ...

    "registry-mirrors": [

        "https://xxx.com"

    ]

}

其中将地址替换为可用源，以如华为云镜像为例：

访问华为云容器镜像服务：https://console.huaweicloud.com/swr/，可获得自有镜像源地址。

四、安装容器

以 Neo4j 为例，进行容器的安装测试。

输入如下命令，拉取 Neo4j 镜像：

docker pull neo4j

打开 Docker Desktop 界面，找到 Neo4j 镜像，点击Run，配置参数：

设置端口，挂载目录，设置 NEO4J_AUTH=neo4j/password 环境变量。

执行 Run 动作后，可以看到 Neo4j 已经启动。

访问 http://localhost:7474 ，可以访问 Neo4j 的界面：

五、网络访问

NAT 网络模式

在 NAT 网络模式，WSL 2 借助 Hyper - V 虚拟交换机创建一个虚拟网络环境，它有自己独立的虚拟网卡（在 Windows 主机上显示为 vEthernet (WSL)，在 WSL 2 内部通常为 eth0），通过该桥接网络，WSL2 子系统可访问外部网络，同时 Windows 主机也可以访问 WSL 2 实例暴露的端口，但该端口对外部主机不可见（需单独配置转发）

可以执行 ipconfig 命令，查看 WSL 实例的网络接口：

ipconfig

以太网适配器 vEthernet (WSL):

   连接特定的 DNS 后缀 . . . . . . . :

   IPv4 地址 . . . . . . . . . . . . : xxx

   子网掩码  . . . . . . . . . . . . : 255.255.240.0

   默认网关. . . . . . . . . . . . . :

容器可以通过 host.docker.internal 特殊域名访问宿主机
宿主机可以通过环回地址访问容器端口
容器可以通过 WSL 的 IP 地址访问宿主机

Mirrored 网络模式

在镜像网络模式中，WSL2 子系统与主机共享网络接口，此时不需要独立的 WSL 网卡。

容器可以通过 host.docker.internal 特殊域名访问宿主机
宿主机可以通过环回地址访问容器端口
容器和宿主机可以通过主机的 IP 地址进行互访（需检测分别WSL和主机分别绑定的IP）

六、常见问题

端口绑定失败

对于windows 10来说，wsl2 尽管配置了镜像模式，也会自动降级为 NAT 模式。

如果发现端口没有被主机占用，但启动提示没有绑定端口权限，需要注意端口是否在 HyperV 的保留端口范围之内。

由于 HyperV 的保留端口是动态生成的，需通过如下命令检查 HyperV 保留范围内：

netsh interface ipv4 show excludedportrange protocol=tcp

开始端口    结束端口

----------    --------

        80          80

      2698        2797

      2929        3028

      8985        9084

      9085        9184

      9185        9284

      9285        9384

      9385        9484

      9485        9584

      9585        9684

如果存在冲突，最简单的做法是重启 NAT，让它的保留端口发生变化避免冲突

net stop winnat

docker start xxx

net start winnat

另一种彻底的做法是，直接添加动态端口范围，如下：

netsh int ipv4 set dynamic tcp start=49152 num=16384