一、 背景描述

在 Windows 11 环境下使用 Docker Desktop 开发 Java 项目时，打算拉取一个 redis:7-alpine 镜像作为缓存数据库。原以为只需一行命令，结果却在镜像拉取、WSL 版本、网络代理以及 Java 连接配置上踩了一连串的坑。

二、 踩坑记录与解决方案

1. 镜像拉取报错：500 Internal Server Error / EOF

现象：

执行 docker pull redis:7.0 时提示 API 版本不支持或连接被强制关闭（EOF）。

解决方法：

• 代理冲突： Docker Desktop 运行在 WSL2 虚拟机里，不直接识别 Windows 宿主机的插件代理。

• 配置关键： 在 Docker 设置中开启 Manual proxy configuration，并将地址设为 http://host.docker.internal:7890（而非 127.0.0.1）。

• Clash 必杀技： 开启 Service Mode（服务模式） 并打开 TUN Mode，这是解决 Docker 网络最稳妥的办法。

• 或者开启国内镜像

  {
    "builder": {
      "gc": {
        "defaultKeepStorage": "20GB",
        "enabled": true
      }
    },
    "experimental": false,
    "registry-mirrors": [
      "https://inhj05a1.mirror.aliyuncs.com"
    ]
  }

2. WSL2 引擎报错：WSL needs updating

现象：

Docker 提示 WSL 版本过旧，无法启动。

解决方法：

• 不要只点更新按钮，去 PowerShell 执行 wsl --update。

• 关键点： 如果提示没有分发版，必须安装一个轻量级的 Ubuntu：wsl --install -d Ubuntu。Docker 需要一个标准的 Linux 环境作为“锚点”来完成网络集成。

3. 存储迷思：镜像拉到哪里去了？

纠错记录：

我原本以为执行 docker pull 会把镜像下到刚装的 Ubuntu 里。

真相：

WSL2 架构下，镜像存储在独立的 docker-desktop-data 虚拟磁盘中。Ubuntu 只是我们的“命令行办公室”。通过在设置里勾选 WSL Integration -> Ubuntu，我们可以在 Ubuntu 里无缝操作 Docker。

---

三、 核心技术点：Spring Boot 连接 Redis 的“玄学”

这是最折磨人的地方。在 Java 代码连接 Redis 时，我尝试了多种 Host 配置：

Host 配置	结果	原因分析
172.17.0.1	失败	这是 Docker 内部私有 IP，Win11 宿主机无法直接访问。
127.0.0.1	不稳定	Jedis 直连报错。强制走 IPv4 且绕过了 Docker 的透明代理。
localhost	成功	唯一保险方案。触发了 Docker Desktop 的 wslproxy 转发，且自动兼容 IPv6。

结论： 在 Win11 + WSL2 开发模式下，配置文件里必须写 host: localhost。

二更：

即使是使用localhost，也不能保证100%连接成功，因为docker给win11解包的时候，默认走的是ipv6::1，即使在虚拟机使用参数-Djava.net.preferIPv4Stack=true那也不行。所以终极解决方案是：创建的时候就显式指定IP与端口

# 先删掉刚才那个没启动成功的容器
docker rm -f my-redis

# 改用 ipv4 指定本地端口
docker run --name my-redis -p 127.0.0.1:6380:6379 -d redis:7-alpine

---

四、 总结：我的最终开发架构

• 操作系统： Windows 11

• 容器引擎： Docker Desktop (WSL2 Based)

• Linux 环境： Ubuntu (已开启 WSL Integration)

• Java 栈： Spring Boot + Jedis/Lettuce

• 网络代理： Clash (TUN Mode)

---

五、 常用命令速查手册

PowerShell

# 拉取轻量版镜像
docker pull redis:7-alpine

# 启动并映射端口
docker run --name my-redis -p 6379:6379 -d redis:7-alpine

# 检查容器状态
docker ps

# 在 Win11 测试连接
docker exec -it my-redis redis-cli ping

---

给读者的建议

如果你的 Redis 连接池能通，但单连接（Jedis 直连）报错，不要怀疑自己的代码，去检查你的 localhost 转发逻辑。永远记住：在 Windows 上调 Docker，localhost 才是永远的神！