一、 背景描述在 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。关键点如果提示没有分发版必须安装一个轻量级的 Ubuntuwsl --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 内部私有 IPWin11 宿主机无法直接访问。127.0.0.1不稳定Jedis 直连报错。强制走 IPv4 且绕过了 Docker 的透明代理。localhost成功唯一保险方案。触发了 Docker Desktop 的wslproxy转发且自动兼容 IPv6。结论在 Win11 WSL2 开发模式下配置文件里必须写host: localhost。二更即使是使用localhost也不能保证100%连接成功因为docker给win11解包的时候默认走的是ipv6::1即使在虚拟机使用参数-Djava.net.preferIPv4Stacktrue那也不行。所以终极解决方案是创建的时候就显式指定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 上调 Dockerlocalhost才是永远的神