WSL2 + Redis Stack 完整部署教程（Windows 11）

WSL2 Redis Stack 完整部署教程Windows 11适用场景Windows 11 开发环境需要 RedisJSON 向量检索能力支持 LangChain4j RAG 应用一、整体方案说明为什么用 rootfs 离线导入而不是商店安装商店版 Ubuntu 默认安装在 C 盘迁移极易翻车灾难性故障 E_UNEXPECTEDrootfs 导入方式纯净稳定可直接指定安装目录到 D 盘国内环境下载镜像更快避开微软商店网络问题最终环境项目说明WSL 实例名linux系统版本Ubuntu 22.04 LTS安装路径D:\WSL\linuxRedis 版本Redis Stack Server含 RedisJSON RediSearchWindows 连接地址127.0.0.1:6379端口转发二、前置准备1. 启用 WSL 功能管理员 PowerShell 执行dism.exe/online/enable-feature/featurename:Microsoft-Windows-Subsystem-Linux/all/norestart dism.exe/online/enable-feature/featurename:VirtualMachinePlatform/all/norestart执行完重启电脑。2. 下载 Ubuntu 22.04 rootfs 镜像国内镜像源推荐https://mirror.sjtu.edu.cn/ubuntu-cloud-images/server/wsl/jammy/current/ubuntu-jammy-wsl-amd64-ubuntu22.04lts.rootfs.tar.gz下载后保存到D:\WSL\download\ubuntu.tar.gz文件大小约 341MB下载完成核对大小避免残缺包。三、导入 WSL 实例1. 清理旧实例如有wsl--shutdown wsl--unregister Ubuntu# 删除旧的损坏实例2. 导入新实例wsl--import linuxD:\WSL\linuxD:\WSL\download\ubuntu.tar.gz--version 23. 启动验证wsl-d linux看到Welcome to Ubuntu 22.04.5 LTS即为成功。四、系统初始化配置1. 创建普通用户进入 WSL 后默认是 root执行useradd-mtangkh# 创建用户替换为你的用户名passwdtangkh# 设置密码usermod-aGsudotangkh# 加入 sudo 组2. 配置默认登录用户 开启 systemdsudonano/etc/wsl.conf写入内容[user] defaulttangkh [boot] systemdtrue保存退出CtrlO→ 回车 →CtrlX3. 重启 WSL 生效PowerShell 执行wsl--shutdown wsl-d linux再次进入自动使用tangkh用户登录。五、安装 Redis Stack1. 添加官方软件源curl-fsSLhttps://packages.redis.io/gpg|sudogpg--dearmor-o/usr/share/keyrings/redis-archive-keyring.gpgechodeb [signed-by/usr/share/keyrings/redis-archive-keyring.gpg] https://packages.redis.io/deb$(lsb_release-cs)main|sudotee/etc/apt/sources.list.d/redis.list2. 安装 Redis Stack Serversudoaptupdatesudoaptinstallredis-stack-server-y3. 修改配置允许外部访问sudonano/opt/redis-stack/etc/redis-stack.conf找到并修改bind 0.0.0.0 ::1 protected-mode no⚠️ 开发环境可关闭 protected-mode生产环境务必设置密码requirepass xxx4. 启动服务并设置开机自启sudosystemctl start redis-stack-serversudosystemctlenableredis-stack-server5. 验证运行状态sudosystemctl status redis-stack-server看到active (running)即为正常。六、Windows 端口转发解决 WSL2 NAT 网络问题问题说明WSL2 使用 NAT 网络Windows 宿主机直接访问 WSL 内网 IP 可能不通需要通过端口转发解决。1. 获取 WSL 内网 IPhostname-I示例输出172.28.113.2022. 管理员 PowerShell 添加端口转发# 清理旧规则如果有netsh interface portproxy delete v4tov4 listenport6379 listenaddress0.0.0.0# 添加转发netsh interface portproxy add v4tov4 listenport6379 listenaddress0.0.0.0 connectport6379 connectaddress172.28.113.2023. 查看转发规则netsh interface portproxy show all4. Windows 测试连通性Test-NetConnection127.0.0.1-Port 6379TcpTestSucceeded : True即为成功。5. 一键刷新脚本解决 IP 变化问题WSL 重启后 IP 会变化保存以下脚本为redis-forward.ps1管理员运行即可自动刷新$wslIp wsl-d linux--hostname-I$wslIp$wslIp.Trim()netsh interface portproxy delete v4tov4 listenport6379 listenaddress0.0.0.0 netsh interface portproxy add v4tov4 listenport6379 listenaddress0.0.0.0 connectport6379 connectaddress$wslIpWrite-HostRedis 端口转发完成目标 WSL IP$wslIp七、功能验证1. 验证扩展模块RAG 必备redis-cliMODULE LIST输出中必须包含ReJSON—— JSON 存储扩展search—— 向量检索扩展2. 测试 RedisJSONJSON.SET demo:user $ {name:test,age:30} JSON.GET demo:user $.name3. Java 项目连接配置spring:redis:host:127.0.0.1port:6379# password: xxx # 生产环境务必设置密码八、常用命令速查WSL 相关wsl-l-v# 查看所有实例wsl--shutdown# 关闭所有 WSLwsl--unregister linux# 删除实例谨慎数据全丢Redis 相关sudosystemctl start redis-stack-server# 启动sudosystemctl stop redis-stack-server# 停止sudosystemctl restart redis-stack-server# 重启sudosystemctl status redis-stack-server# 状态sudojournalctl-uredis-stack-server-f# 实时日志九、常见问题排查Q1: wsl --import 后启动报「灾难性故障 E_UNEXPECTED」原因ext4.vhdx 文件被压缩/加密或权限不足解决右键ext4.vhdx→ 属性 → 高级 → 取消「压缩内容」「加密内容」安全选项卡 → 添加当前用户完全控制权限Q2: Windows 连不上 Redis但 WSL 内部可以原因WSL2 NAT 网络限制解决执行端口转发见第六章Q3: Redis 配置修改不生效原因改错了配置文件路径正确路径/opt/redis-stack/etc/redis-stack.conf验证启动加载的配置sudosystemctlcatredis-stack-serverQ4: WSL 内存占用越来越大解决创建C:\Users\你的用户名\.wslconfig[wsl2] memory4GB processors4 swap2GB保存后执行wsl --shutdown生效。十、避坑总结❌ 不要用商店版 Ubuntu wsl --export/import 迁移翻车率极高✅ 优先使用 rootfs 离线导入直接指定安装目录❌ 不要用 WSL1不支持 systemd 和很多 Linux 特性✅ Redis Stack 配置文件在/opt/redis-stack/etc/不在/etc/redis/✅ Windows 连接用127.0.0.1 端口转发不要直连 WSL 内网 IP会变