一、背景
许多小伙伴在安装 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