企业官网建设流程全解析

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

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

一、整体方案说明

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

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

最终环境

二、前置准备

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

九、常见问题排查

Q1: wsl --import 后启动报「灾难性故障 E_UNEXPECTED」

原因：ext4.vhdx 文件被压缩/加密，或权限不足
解决：

1. 右键ext4.vhdx→ 属性 → 高级 → 取消「压缩内容」「加密内容」
2. 安全选项卡 → 添加当前用户完全控制权限

Q2: Windows 连不上 Redis，但 WSL 内部可以

原因：WSL2 NAT 网络限制
解决：执行端口转发（见第六章）

Q3: Redis 配置修改不生效

原因：改错了配置文件路径
正确路径：/opt/redis-stack/etc/redis-stack.conf
验证启动加载的配置：

sudosystemctlcatredis-stack-server

Q4: WSL 内存占用越来越大

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

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

保存后执行wsl --shutdown生效。

十、避坑总结

1. ❌ 不要用商店版 Ubuntu + wsl --export/import 迁移，翻车率极高
2. ✅ 优先使用 rootfs 离线导入，直接指定安装目录
3. ❌ 不要用 WSL1，不支持 systemd 和很多 Linux 特性
4. ✅ Redis Stack 配置文件在/opt/redis-stack/etc/，不在/etc/redis/
5. ✅ Windows 连接用127.0.0.1+ 端口转发，不要直连 WSL 内网 IP（会变）