当前位置：首页 > news >正文

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

news 2026/7/23 6:17:15

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

适用场景：Windows 11 开发环境，需要 RedisJSON + 向量检索能力，支持 LangChain4j RAG 应用

一、整体方案说明

为什么用 rootfs 离线导入而不是商店安装？

商店版 Ubuntu 默认安装在 C 盘，迁移极易翻车（灾难性故障 E_UNEXPECTED）
rootfs 导入方式纯净稳定，可直接指定安装目录到 D 盘
国内环境下载镜像更快，避开微软商店网络问题

最终环境

项目	说明
WSL 实例名	`linux`
系统版本	Ubuntu 22.04 LTS
安装路径	`D:\WSL\linux`
Redis 版本	Redis Stack Server（含 RedisJSON + RediSearch）
Windows 连接地址	`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 linux"D:\WSL\linux""D:\WSL\download\ubuntu.tar.gz"--version 2

3. 启动验证

wsl-d linux

看到Welcome to Ubuntu 22.04.5 LTS即为成功。

四、系统初始化配置

1. 创建普通用户

进入 WSL 后默认是 root，执行：

useradd-mtangkh# 创建用户（替换为你的用户名）passwdtangkh# 设置密码usermod-aGsudotangkh# 加入 sudo 组

2. 配置默认登录用户 + 开启 systemd

sudonano/etc/wsl.conf

写入内容：

[user] default=tangkh [boot] systemd=true

保存退出：Ctrl+O→ 回车 →Ctrl+X

3. 重启 WSL 生效

PowerShell 执行：

wsl--shutdown wsl-d linux

再次进入自动使用tangkh用户登录。

五、安装 Redis Stack

1. 添加官方软件源

curl-fsSLhttps://packages.redis.io/gpg|sudogpg--dearmor-o/usr/share/keyrings/redis-archive-keyring.gpgecho"deb [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.list

2. 安装 Redis Stack Server

sudoaptupdatesudoaptinstallredis-stack-server-y

3. 修改配置，允许外部访问

sudonano/opt/redis-stack/etc/redis-stack.conf

找到并修改：

bind 0.0.0.0 ::1 protected-mode no

⚠️ 开发环境可关闭 protected-mode；生产环境务必设置密码requirepass xxx

4. 启动服务并设置开机自启

sudosystemctl start redis-stack-serversudosystemctlenableredis-stack-server

5. 验证运行状态

sudosystemctl status redis-stack-server

看到active (running)即为正常。

六、Windows 端口转发（解决 WSL2 NAT 网络问题）

问题说明

WSL2 使用 NAT 网络，Windows 宿主机直接访问 WSL 内网 IP 可能不通，需要通过端口转发解决。

1. 获取 WSL 内网 IP

hostname-I

示例输出：172.28.113.202

2. 管理员 PowerShell 添加端口转发

# 清理旧规则（如果有）netsh interface portproxy delete v4tov4 listenport=6379 listenaddress=0.0.0.0# 添加转发netsh interface portproxy add v4tov4 listenport=6379 listenaddress=0.0.0.0 connectport=6379 connectaddress=172.28.113.202

3. 查看转发规则

netsh interface portproxy show all

4. Windows 测试连通性

Test-NetConnection127.0.0.1-Port 6379

TcpTestSucceeded : True即为成功。

5. 一键刷新脚本（解决 IP 变化问题）

WSL 重启后 IP 会变化，保存以下脚本为redis-forward.ps1，管理员运行即可自动刷新：

$wslIp= wsl-d linux--hostname-I$wslIp=$wslIp.Trim()netsh interface portproxy delete v4tov4 listenport=6379 listenaddress=0.0.0.0 netsh interface portproxy add v4tov4 listenport=6379 listenaddress=0.0.0.0 connectport=6379 connectaddress=$wslIpWrite-Host"Redis 端口转发完成，目标 WSL IP：$wslIp"

七、功能验证

1. 验证扩展模块（RAG 必备）

redis-cli

MODULE LIST

输出中必须包含：

ReJSON—— JSON 存储扩展
search—— 向量检索扩展

2. 测试 RedisJSON

JSON.SET demo:user $ '{"name":"test","age":30}' JSON.GET demo:user $.name

3. 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# 实时日志