nvm list

安装最新的长期支持版 (LTS):

nvm install lts

安装指定版本 (例如 18.20.2):

nvm install 18.20.2

切换到已安装的版本:

nvm use 18.20.2

删除不需要的版本

nvm uninstall 16.20.2

设置默认版本

nvm alias default 18.20.2

如果安装失败，就刷新nvm缓存再进行安装

nvm list available

适用环境：Windows 11 / Windows 10 21H2+，NVIDIA GPU（显存 ≥ 8 GB），Ubuntu 22.04 / 24.04 (WSL2)
最终目标：在本地通过 vLLM 启动 OpenAI 兼容 API 服务，运行 Qwen 系列大模型

前置条件检查

在开始之前，请确认你的机器满足以下全部条件：

重要：WSL2 的 GPU 直通依赖 Windows 侧 的 NVIDIA 驱动，不要在 WSL 内部单独安装 CUDA Toolkit 或 GPU 驱动，否则可能冲突。

第一步：安装 WSL2 并初始化

1.1 安装 WSL

以 管理员身份 打开 PowerShell，执行：

wsl --install

该命令默认安装 Ubuntu（最新 LTS）。如需指定发行版：

# 查看可用发行版列表
wsl --list --online

# 指定安装 Ubuntu 22.04（推荐，兼容性最好）
wsl --install -d Ubuntu-22.04

1.2 重启电脑

安装完成后 必须重启，否则内核组件不会生效。

1.3 设置 Linux 用户

重启后会自动弹出 Ubuntu 终端，按提示设置：

Enter new UNIX username: xxxx
New password: xxxx
Retype new password: xxxx

此账号与 Windows 账号无关，是 Linux 子系统的独立用户，请牢记。

1.4 确认 WSL2 与 GPU 可用

# 确认 WSL 版本为 2（在 PowerShell 中执行）
wsl -l -v
# 输出示例：  NAME            STATE     VERSION
#           Ubuntu-22.04    Running   2

# 在 WSL 终端中确认 GPU 可见
nvidia-smi

若 nvidia-smi 正常输出 GPU 型号、显存、驱动版本，说明 GPU 直通成功。若报错，请回到 Windows 侧更新/重装 NVIDIA 驱动（≥ 535）。

第二步：更新系统并配置国内镜像源

2.1 替换 APT 源

Ubuntu 24.04 注意：24.04 已将源配置迁移至 /etc/apt/sources.list.d/ubuntu.sources（DEB822 格式），下方命令仅适用于 22.04 及更早版本。24.04 用户请跳到 2.1b。

Ubuntu 22.04：

# 备份原始源
sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak

# 替换为阿里云镜像
sudo sed -i 's|http://archive.ubuntu.com|https://mirrors.aliyun.com|g' /etc/apt/sources.list
sudo sed -i 's|http://security.ubuntu.com|https://mirrors.aliyun.com|g' /etc/apt/sources.list

Ubuntu 24.04（2.1b）：

sudo cp /etc/apt/sources.list.d/ubuntu.sources /etc/apt/sources.list.d/ubuntu.sources.bak

sudo sed -i 's|http://archive.ubuntu.com|https://mirrors.aliyun.com|g' /etc/apt/sources.list.d/ubuntu.sources
sudo sed -i 's|http://security.ubuntu.com|https://mirrors.aliyun.com|g' /etc/apt/sources.list.d/ubuntu.sources

2.2 更新系统

sudo apt update && sudo apt upgrade -y

若升级过程中提示重启，执行 sudo reboot 后重新进入 WSL 即可。

第三步：安装基础开发工具

sudo apt install -y \
    python3-pip \
    python3-venv \
    python3-dev \
    build-essential \
    git \
    curl \
    wget \
    htop

验证 Python 版本（vLLM 要求 ≥ 3.9，推荐 3.10 / 3.11）：

python3 --version

第四步：创建并激活 Python 虚拟环境

# 创建虚拟环境（放在用户主目录下）
python3 -m venv ~/vllm-env

# 激活虚拟环境
source ~/vllm-env/bin/activate

# 激活成功后，命令行前缀变为 (vllm-env)
# 升级 pip 与基础打包工具
pip install --upgrade pip setuptools wheel

每次打开新终端都需要重新执行 source ~/vllm-env/bin/activate。
可将该行追加到 ~/.bashrc 末尾实现自动激活（可选，不推荐全局自动激活）。

第五步：配置 pip 国内镜像并安装 vLLM

5.1 配置阿里云 PyPI 镜像

pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/
pip config set global.trusted-host mirrors.aliyun.com

5.2 安装 vLLM

方式 A：使用 uv（推荐，速度快 5-10 倍）

pip install uv
uv pip install vllm

方式 B：直接使用 pip

pip install vllm

5.3 验证安装

python -c "import vllm; print('vLLM version:', vllm.__version__)"

正常输出版本号即安装成功。若报 CUDA 相关错误，请确认第一步中 nvidia-smi 正常。

第六步：下载大模型文件

6.1 安装 ModelScope CLI

pip install modelscope

6.2 选择存储位置

性能提示：如果显存和磁盘允许，强烈建议将模型放在 WSL 内部路径（如 ~/ai-models/），跨 /mnt/ 读取大文件会显著拖慢模型加载速度（可能慢 3-5 倍）。若必须放 D 盘，可在 WSL 配置中扩大虚拟磁盘或挂载物理磁盘。

6.3 下载模型

# ---------- 模型 1：Qwen2.5-7B-Instruct（约 15 GB，适合 8-12 GB 显存） ----------
mkdir -p /mnt/d/LLM_Models
modelscope download \
    --model Qwen/Qwen2.5-7B-Instruct \
    --local_dir /mnt/d/LLM_Models/Qwen2.5-7B-Instruct

# ---------- 模型 2：Qwen3.6-35B-A3B-FP8（MoE 模型，约 35 GB，适合 16 GB+ 显存） ----------
mkdir -p ~/ai-models
modelscope download \
    --model Qwen/Qwen3.6-35B-A3B-FP8 \
    --local_dir ~/ai-models/Qwen3.6-35B-A3B-FP8

6.4 验证模型完整性

# 检查文件是否齐全（应包含 config.json、tokenizer、*.safetensors 等）
ls -lh /mnt/d/LLM_Models/Qwen2.5-7B-Instruct/
ls -lh ~/ai-models/Qwen3.6-35B-A3B-FP8/

确保没有 0 字节文件或缺失的 .safetensors 分片。

第七步：启动 vLLM 推理服务

7.1 启动 Qwen2.5-7B（示例）

python -m vllm.entrypoints.openai.api_server \
    --model /mnt/d/LLM_Models/Qwen2.5-7B-Instruct \
    --served-model-name qwen2.5-7b \
    --host 0.0.0.0 \
    --port 8000 \
    --gpu-memory-utilization 0.85 \
    --dtype float16 \
    --max-model-len 8192

7.2 参数说明

7.3 后台运行（可选）

直接运行会占用终端，关闭即停止。推荐以下方式：

方式 A：nohup

nohup python -m vllm.entrypoints.openai.api_server \
    --model /mnt/d/LLM_Models/Qwen2.5-7B-Instruct \
    --served-model-name qwen2.5-7b \
    --host 0.0.0.0 --port 8000 \
    --gpu-memory-utilization 0.85 \
    --dtype float16 \
    --max-model-len 8192 \
    > ~/vllm-server.log 2>&1 &

# 查看日志
tail -f ~/vllm-server.log

方式 B：systemd 服务（WSL2 需启用 systemd）

# 1. 启用 systemd（/etc/wsl.conf）
sudo tee /etc/wsl.conf > /dev/null <<EOF
[boot]
systemd=true
EOF
# 在 PowerShell 中重启 WSL：wsl --shutdown，再重新打开

# 2. 创建服务文件
sudo tee /etc/systemd/system/vllm.service > /dev/null <<EOF
[Unit]
Description=vLLM OpenAI API Server
After=network.target

[Service]
Type=simple
User=$USER
Environment="PATH=/home/$USER/vllm-env/bin:/usr/bin"
ExecStart=/home/$USER/vllm-env/bin/python -m vllm.entrypoints.openai.api_server \
    --model /mnt/d/LLM_Models/Qwen2.5-7B-Instruct \
    --served-model-name qwen2.5-7b \
    --host 0.0.0.0 --port 8000 \
    --gpu-memory-utilization 0.85 \
    --dtype float16 \
    --max-model-len 8192
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

# 3. 启动并设为开机自启
sudo systemctl daemon-reload
sudo systemctl enable --now vllm
sudo systemctl status vllm

第八步：验证服务

8.1 确认服务启动

终端/日志中出现以下字样即表示就绪：

INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:     Application startup complete.

8.2 测试 API（在 WSL 或 Windows 终端均可）

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen2.5-7b",
    "messages": [
      {"role": "user", "content": "你好，请简单介绍一下你自己"}
    ],
    "max_tokens": 256,
    "temperature": 0.7
  }'

8.3 查看可用模型列表

curl http://localhost:8000/v1/models

8.4 Python 客户端测试

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="EMPTY",  # vLLM 默认无需鉴权
)

resp = client.chat.completions.create(
    model="qwen2.5-7b",
    messages=[{"role": "user", "content": "用一句话解释什么是 Transformer"}],
)
print(resp.choices[0].message.content)

第九步：常见问题排查

附录：常用运维命令速查

# 激活环境
source ~/vllm-env/bin/activate

# 查看 GPU 实时状态
watch -n 1 nvidia-smi

# 查看 vLLM 进程
ps aux | grep vllm

# 停止服务（前台直接 Ctrl+C；后台用 kill）
pkill -f "vllm.entrypoints"

# 更新 vLLM
pip install --upgrade vllm

# 清理 pip 缓存（释放磁盘）
pip cache purge

# WSL 关机（PowerShell）
wsl --shutdown

最后提醒：首次启动 vLLM 时会对模型进行编译/预热，耗时 1~5 分钟属正常现象，请耐心等待 Uvicorn running 出现后再发起请求。生产环境建议配合 Nginx 反向代理、API Key 鉴权（--api-key 参数）及日志轮转使用。

前言

本项目基于若依前后端分离版开发，现需将其改造为不分离版本，即将前端打包产物整合进后端 JAR 包中统一运行。以下是详细的改造步骤。

一、 修改前端项目配置

1. 修改生产环境配置

编辑 ruoyi-ui/.env.production 文件，配置 API 基础路径（二选一）：

# 方式一：本机地址访问（推荐）
VUE_APP_BASE_API = '/'

# 方式二：指定任意地址访问
# VUE_APP_BASE_API = 'http://xxx.xxx.xxx.xxx:8080'

2. 修改路由模式

编辑 ruoyi-ui/src/router/index.js，将路由模式设置为 hash：

export default new Router({
  mode: 'hash', // 必须改为 hash 模式
  scrollBehavior: () => ({ y: 0 }),
  routes: constantRoutes
})

3. 修改注销跳转逻辑

编辑 ruoyi-ui/src/layout/components/Navbar.vue 中的 logout 方法，防止重定向错误：

async logout() {
  this.$confirm('确定注销并退出系统吗？', '提示', {
    confirmButtonText: '确定',
    cancelButtonText: '取消',
    type: 'warning'
  }).then(() => {
    this.$store.dispatch('LogOut').then(() => {
      // 注意：跳转 index 前加 /#/ 防止定向错误
      location.href = '/#/index';
    })
  }).catch(() => {});
}

4. 执行前端打包

在前端项目根目录运行以下命令生成 dist 文件：

npm run build:prod

二、 修改后端项目配置

1. 添加 Thymeleaf 模板引擎配置

编辑 ruoyi-admin/src/main/resources/application.yml：

spring:
  # 模板引擎配置
  thymeleaf:
    mode: HTML
    encoding: utf-8
    cache: false

2. 添加 Thymeleaf 依赖

编辑 ruoyi-admin/pom.xml，引入模板引擎依赖：

<!-- spring-boot-thymeleaf -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-thymeleaf</artifactId>
</dependency>

3. 配置静态资源映射

编辑 ruoyi-framework/src/main/java/com/ruoyi/framework/config/ResourcesConfig.java，在 addResourceHandlers 方法中添加：

/** 前端静态资源配置 */
registry.addResourceHandler("/static/**").addResourceLocations("classpath:/static/");

4. 放行静态资源访问权限

编辑 ruoyi-framework/src/main/java/com/ruoyi/framework/config/SecurityConfig.java，在 configure 方法中添加匿名访问规则：

// 静态资源可匿名访问，主要添加 "/static/**", "/index", "/*.ico"
.antMatchers(HttpMethod.GET, "/", "/*.html", "/**/*.html", "/**/*.css", "/**/*.js", "/profile/**", "/static/**", "/index", "/*.ico").permitAll()

5. 设置首页访问控制器

编辑 SysIndexController.java，配置根路径返回页面：

@RequestMapping("/")
public ModelAndView index() {
    return new ModelAndView("index.html");
}

6. 整合前端静态资源

将前端打包生成的 dist 目录内容复制到后端项目中：

• HTML 文件：放入 ruoyi-admin/src/main/resources/templates/ 目录
• JS/CSS/图片等静态文件：放入 ruoyi-admin/src/main/resources/static/ 目录

注意：如果 templates 或 static 目录不存在，请手动新建。

三、 启动验证

启动后端服务，访问测试地址（例如：http://192.168.164.134:8080/）。

✅ 成功标志：页面正常显示首页并加载出验证码，即表示改造完成。