windows系统部署funrec项目：安装WSL2

注意WSL系统与Windows系统环境是完全隔离开的只有代码文件可以互通windows的anaconda、python、uv、torch、tensorflow等WSL都不能用都需要另外安装WSL 可以访问 Windows 的项目文件比如 /mnt/d/MyProject/…WSL 内的文件Windows 在文件管理器地址栏输入 \wsl$ 访问但是不建议在资源管理器里进行任何的修改1. 安装WSL以管理员权限打开命令行cmd、powershell或者anaconda prompt都行依次输入 以下命令# 启用 Windows 子系统 Linux 版dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart# 启用虚拟机平台dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart# 安装wslwsl --set-default-version2wsl--list--online# 列出 Linux 分发版本wsl--install# 安装wsl默认ubuntuwsl默认安装路径是C盘如果想换盘可以参考 更改 WSL 安装路径2. Docker desktop配置相信你已经安装了Docker desktop右上角打开Setting图标把这几个选项打开并且点击“refeetch distros”按钮。3. 将项目提供的docker容器导入WSL确定现在已经处于wsl系统如果没有在命令行输入wsl或者wsl -d Ubuntu再输入sudo -i进入root这一步会让你去设置用户名和密码用户名一般默认是你的windows系统用户名密码输入时界面不会显示。进入root后是这样进入项目web_project/backend文件夹注意在wsl系统中文件路径的表示很特殊你可以在wsl中访问windows的本地文件C盘是/mnt/cD盘是/mnt/dE盘是/mnt/e所以如果项目本来的路径是C:\MyProject\rec\fun-rec-doc\web_project/backend在WSL系统里就要写成/mnt/c/MyProject/rec/fun-rec-doc/web_project/backendcd/mnt/c/MyProject/rec/fun-rec-doc/web_project/backend补充在wsl系统中所有的路径都要遵循这一规则包括代码里的路径之前可能有一些地方你设置了Windows路径比如.env去检查一下更改过来4. 导入docker容器4. 继续其他配置根据官方教程现在需要安装uv在wsl中继续输入# 官方安装命令curl-LsSfhttps://astral.sh/uv/install.sh|sh# 刷新当前终端环境让系统识别 uv 命令source$HOME/.cargo/env# 验证 uv 安装成功uv--version进入 backend 目录cdbackend同步依赖uvsync可能会报错意思是程序需要python3.11但你是其他版本rootDESKTOP-OGFTUK7:/mnt/e/MyProject/rec/fun-rec-doc/web_project/backend# uv syncwarning: Ignoring unsupported Python requestD:\anaconda3\envs\funrec\python.exeinversion file: /mnt/e/MyProject/rec/fun-rec-doc/web_project/backend/.python-version Using CPython3.12.3 interpreter at: /usr/bin/python3 Removed virtual environment at: .venv Creating virtual environment at: .venv Resolved94packagesin1.96s error: Distributiontensorflow2.15.0 registryhttps://pypi.org/simplecant be installed because it doesnt have asourcedistribution or wheelforthe current platform hint: Youre using CPython3.12(cp312), buttensorflow(v2.15.0)only has wheels with the following Python ABI tag:cp311用uv自动换版本就行uvsync--python3.11# 验证uv run python--version5. 运行程序代码官方教程给的命令例如make ingest-data-to-database需要改成# 在 WSL 中运行exportPYTHONPATH/mnt/e/MyProject/rec/fun-rec-doc:$PYTHONPATHmakerun-offline-pipeline我到这里就没有任何报错了祝你成功。补充1更改 WSL 安装路径WSL 默认安装在系统盘C盘但可以通过 **导出-导入法** 安全迁移到其他盘D/E/F盘等。完成迁移后在 WSL 内安装其他软件比如 Anaconda/Miniconda文件会存放在新路径下的 Linux 文件系统中WSL 内路径/home/你的用户名/anaconda3/Windows 侧对应路径D:\WSL\Ubuntu\home\你的用户名\anaconda3\1. 前置准备关闭所有 WSL 进程# 以管理员身份打开 PowerShell 执行wsl--shutdown确认当前 WSL 发行版名称wsl--list--verbose输出示例NAME STATE VERSION * Ubuntu Running 2记住NAME列的名称如Ubuntu后续命令会用到。在目标盘创建文件夹例如迁移到D:\WSL\mkdir D:\WSL\Ubuntu2. 核心步骤导出 → 注销 → 导入1. 导出当前 WSL 发行版为备份文件# 格式wsl --export 发行版名 备份文件路径wsl--export Ubuntu D:\WSL\Ubuntu\ubuntu_backup.tar执行后会在D:\WSL\Ubuntu\生成ubuntu_backup.tar备份文件大小等于当前 WSL 占用空间等待命令执行完成无报错即成功2. 注销原 WSL 发行版仅删除C盘原文件不删除备份# 格式wsl --unregister 发行版名wsl--unregister Ubuntu⚠️ 注意此操作仅删除C盘的原WSL文件不会删除你刚导出的备份文件数据安全。3. 导入备份到新路径完成迁移# 格式wsl --import 发行版名 新安装路径 备份文件路径 --version 2wsl--import Ubuntu D:\WSL\Ubuntu D:\WSL\Ubuntu\ubuntu_backup.tar--version 2--version 2强制使用 WSL2推荐兼容性更好执行完成后WSL 就成功迁移到D:\WSL\Ubuntu\了3. 验证迁移成功检查 WSL 状态wsl--list--verbose确认发行版状态为Stopped版本为2。启动 WSL 测试wsl-d Ubuntu正常进入 Linux 终端说明迁移成功。可选删除备份文件迁移成功后可删除D:\WSL\Ubuntu\ubuntu_backup.tar释放空间。4. 进阶优化可选1. 设置默认用户解决迁移后默认root问题WSL 迁移后默认以root用户登录可手动改回原用户# 进入WSL后执行替换为你的用户名ubuntu config--default-user 你的用户名或在 PowerShell 中执行wsl-d Ubuntu--user 你的用户名2. 迁移 WSL 核心组件wsl.exe所在目录WSL 核心组件默认在C:\Program Files\WSL\不建议手动修改若需迁移需通过winget重新安装指定路径操作复杂且风险高普通用户无需操作核心组件仅占用几十MB不影响系统盘空间无需迁移5. 避坑指南必须先wsl --shutdown否则导出时会因文件被占用导致备份损坏不要直接复制/剪切 WSL 文件夹WSL 使用虚拟磁盘.vhdx存储直接操作会损坏系统目标路径不要有中文/空格否则导入会失败建议用纯英文路径如D:\WSL\Ubuntu备份文件不要删除迁移成功前务必保留防止数据丢失6. 快速总结步骤命令作用1wsl --shutdown关闭WSL进程2wsl --export Ubuntu D:\WSL\Ubuntu\ubuntu_backup.tar导出备份3wsl --unregister Ubuntu注销原WSL4wsl --import Ubuntu D:\WSL\Ubuntu D:\WSL\Ubuntu\ubuntu_backup.tar --version 2导入到新路径5wsl -d Ubuntu验证启动