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 执行：

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. 清理旧实例（如有）

powershell 复制代码

wsl --shutdown
wsl --unregister Ubuntu   # 删除旧的损坏实例

2. 导入新实例

powershell 复制代码

wsl --import linux "D:\WSL\linux" "D:\WSL\download\ubuntu.tar.gz" --version 2

3. 启动验证

powershell 复制代码

wsl -d linux

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

四、系统初始化配置

1. 创建普通用户

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

bash 复制代码

useradd -m tangkh        # 创建用户（替换为你的用户名）
passwd tangkh            # 设置密码
usermod -aG sudo tangkh  # 加入 sudo 组

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

bash 复制代码

sudo nano /etc/wsl.conf

写入内容：

ini 复制代码

[user]
default=tangkh

[boot]
systemd=true

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

3. 重启 WSL 生效

PowerShell 执行：

powershell 复制代码

wsl --shutdown
wsl -d linux

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

五、安装 Redis Stack

1. 添加官方软件源

bash 复制代码

curl -fsSL https://packages.redis.io/gpg | sudo gpg --dearmor -o /usr/share/keyrings/redis-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] https://packages.redis.io/deb $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/redis.list

2. 安装 Redis Stack Server

bash 复制代码

sudo apt update
sudo apt install redis-stack-server -y

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

bash 复制代码

sudo nano /opt/redis-stack/etc/redis-stack.conf

找到并修改：

conf 复制代码

bind 0.0.0.0 ::1
protected-mode no

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

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

bash 复制代码

sudo systemctl start redis-stack-server
sudo systemctl enable redis-stack-server

5. 验证运行状态

bash 复制代码

sudo systemctl status redis-stack-server

看到 active (running) 即为正常。

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

问题说明

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

1. 获取 WSL 内网 IP

bash 复制代码

hostname -I

示例输出：172.28.113.202

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

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. 查看转发规则

powershell 复制代码

netsh interface portproxy show all

4. Windows 测试连通性

powershell 复制代码

Test-NetConnection 127.0.0.1 -Port 6379

TcpTestSucceeded : True 即为成功。

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

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

powershell 复制代码

$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=$wslIp
Write-Host "Redis 端口转发完成，目标 WSL IP：$wslIp"

七、功能验证

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

bash 复制代码

redis-cli

redis 复制代码

MODULE LIST

输出中必须包含：

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

2. 测试 RedisJSON

redis 复制代码

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

3. Java 项目连接配置

yaml 复制代码

spring:
  redis:
    host: 127.0.0.1
    port: 6379
    # password: xxx   # 生产环境务必设置密码

八、常用命令速查

WSL 相关

powershell 复制代码

wsl -l -v                    # 查看所有实例
wsl --shutdown               # 关闭所有 WSL
wsl --unregister linux       # 删除实例（谨慎！数据全丢）

Redis 相关

bash 复制代码

sudo systemctl start redis-stack-server    # 启动
sudo systemctl stop redis-stack-server     # 停止
sudo systemctl restart redis-stack-server  # 重启
sudo systemctl status redis-stack-server   # 状态
sudo journalctl -u redis-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

验证启动加载的配置：

bash 复制代码

sudo systemctl cat redis-stack-server

Q4: WSL 内存占用越来越大

解决：创建 C:\Users\你的用户名\.wslconfig

ini 复制代码

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

保存后执行 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（会变）