从零构建WSL2+Docker开发环境：问题排查与优化全记录

1. 环境准备与基础安装

作为一名长期在Windows平台开发的程序员，我最近决定将开发环境迁移到WSL2+Docker的组合上。这个决定源于对更接近生产环境的开发体验的追求，以及容器化带来的便利性。然而，这个过程并非一帆风顺，记录下这些经验希望能帮助遇到类似问题的开发者。

首先，我们需要确保系统满足基本要求：

• Windows 10版本2004或更高（建议使用Windows 11）
• 已启用"虚拟机平台"和"Linux的Windows子系统"功能
• 至少4GB内存（8GB以上更佳）

安装WSL2的Ubuntu发行版非常简单，只需在PowerShell中执行：

wsl --install -d Ubuntu-20.04

安装完成后，建议立即更新系统：

sudo apt update && sudo apt upgrade -y

接下来是Docker的安装。官方提供了详细的安装指南，但有几个关键点需要注意：

1. 确保使用Docker官方源而非Ubuntu默认源
2. 安装完整组件：docker-ce、docker-ce-cli、containerd.io和docker-compose-plugin

# 设置Docker官方GPG密钥
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# 添加Docker源
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 安装Docker引擎
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin

2. 常见问题排查：无法连接Docker守护进程

安装完成后，我遇到了第一个问题：执行docker ps时出现错误：

Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

这个问题在WSL2环境中相当常见，经过排查发现有几个可能的原因和解决方案：

2.1 检查Docker服务状态

首先确认Docker服务是否正在运行：

sudo service docker status

如果服务未运行，尝试手动启动：

sudo service docker start

2.2 WSL2集成设置

在Docker Desktop中，确保已启用WSL集成：

1. 打开Docker Desktop设置
2. 导航至"Resources" > "WSL Integration"
3. 确保对应的Ubuntu发行版已勾选
4. 点击"Apply & Restart"

2.3 iptables配置问题

WSL2中的Ubuntu 20.04及以上版本默认使用nftables后端，这可能导致Docker网络问题。解决方案是切换回legacy模式：

sudo update-alternatives --config iptables

在出现的菜单中选择iptables-legacy（通常选项1），然后重启Docker服务：

sudo service docker restart

2.4 用户组权限问题

默认情况下，只有root用户和docker组的用户才能访问Docker守护进程。将当前用户加入docker组：

sudo usermod -aG docker $USER

执行后需要退出并重新登录WSL会话使更改生效。

3. 网络配置优化

WSL2的网络实现有其特殊性，这可能导致Docker容器网络问题。以下是几个优化建议：

3.1 自定义Docker网络地址池

当WSL2和Docker网络地址冲突时，可以自定义Docker的网络地址池：

sudo tee /etc/docker/daemon.json <<EOF
{
  "default-address-pools": [
    {
      "base": "192.168.0.0/16",
      "size": 24
    }
  ]
}
EOF

然后重启Docker服务使配置生效。

3.2 检查端口冲突

使用以下命令检查端口占用情况：

sudo netstat -tulnp

如果发现端口冲突，可以：

1. 修改Docker服务的监听端口
2. 停止占用端口的其他服务
3. 修改应用程序配置使用不同端口

3.3 防火墙设置

虽然WSL2有自己的网络接口，但Windows防火墙仍可能影响连接。确保以下端口在Windows防火墙中开放：

• 2375/tcp (Docker守护进程)
• 2376/tcp (Docker TLS)
• 80/tcp和443/tcp (Web应用)

4. 系统集成与自动化

4.1 启用systemd支持

较新版本的WSL2支持systemd，可以像常规Linux系统一样管理服务。编辑/etc/wsl.conf：

[boot]
systemd=true

重启WSL后，Docker服务将自动启动。

4.2 自动启动脚本

对于不使用systemd的情况，可以创建启动脚本~/.bashrc中添加：

# 启动Docker服务
if service docker status 2>&1 | grep -q "is not running"; then
    sudo service docker start
fi

4.3 性能优化

WSL2的磁盘性能可能不如原生Linux，特别是对于大量小文件操作。可以通过以下方式优化：

1. 将项目文件存储在WSL文件系统中（而非Windows文件系统）
2. 增加WSL内存限制（在%USERPROFILE%\.wslconfig中配置）

[wsl2]
memory=8GB
processors=4
swap=4GB

5. 开发环境检查清单

基于我的经验，总结了一份WSL2+Docker开发环境检查清单：

1. 基础环境验证

   • WSL2版本正确（wsl -l -v）
   • Ubuntu系统更新到最新
   • Docker Desktop安装并运行

2. Docker功能测试

   • 运行测试容器：docker run hello-world
   • 检查网络连接：docker run -it alpine ping google.com
   • 验证卷挂载：docker run -v $(pwd):/data alpine ls /data

3. 日常维护命令

   • 清理无用容器：docker container prune
   • 清理无用镜像：docker image prune -a
   • 查看磁盘使用：docker system df

4. 故障排查工具

   • Docker日志：journalctl -u docker或cat /var/log/docker.log
   • 检查服务状态：sudo service docker status
   • 详细版本信息：docker info

经过一周的使用和调优，我的WSL2+Docker环境已经稳定运行，开发体验显著提升。最大的收获是理解了WSL2的网络架构和Docker在其中的工作方式，这为后续更复杂的容器化开发打下了坚实基础。