GPUStack Windows（WSL2）部署指南

GPUStack v2 以高性能推理与生产级稳定性为核心演进方向，对整体架构进行了全面重构，实现了组件间的灵活解耦，并对多推理引擎和异构算力进行了深度优化，充分释放推理引擎在吞吐、延迟与并发方面的性能潜力。

基于这一架构设计，GPUStack v2 聚焦 Linux 原生环境，以充分利用其在生态和 AI 基础设施领域的成熟优势。

对于 Windows 用户，推荐通过 WSL2（Windows Subsystem for Linux）运行 GPUStack v2，在 Windows 上构建与 Linux 生产环境高度一致的 AI 运行环境，完整体验 v2 带来的性能优化与架构优势。

整篇稍长，可先看以下总结的六点，有问题再细看全文：

驱动安装：在 Windows 主机安装 NVIDIA 驱动，不要在 WSL 内部安装。
CUDA 环境：无需 CUDA Toolkit（Windows/WSL 均不需要）。
容器环境：请在 WSL 内部安装原生 Docker Engine，不要使用 Docker Desktop。
（可选）局域网访问 ：若需局域网访问 Server，可在 "WSL Settings" 中将网络模式配置为 Mirrored。
环境检测 ：运行环境检测时，请使用默认用户，不要使用 root 用户（nvidia-smi 在 WSL 中的非标准路径中，此路径不在 root 用户下的环境变量中）。
IP 配置 ：Worker IP 填写 WSL 的具体 IP，使用 127.0.0.1 可能存在问题。

下面将详细介绍如何在 WSL 环境中配置 NVIDIA GPU 并部署 GPUStack。

1. 实验环境

本文基于以下实验环境编写，但适用于大多数支持 WSL 的 Windows 10/11 系统。

操作系统：Windows 11
硬件：GeForce RTX 4090D
虚拟化：需在 BIOS/UEFI 中开启虚拟化支持

2. 关键架构说明

相关参考文档：

Microsoft WSL 官方文档（GPU 支持）：https://learn.microsoft.com/en-us/windows/wsl/tutorials/gpu-compute
NVIDIA CUDA on WSL 用户指南：https://docs.nvidia.com/cuda/wsl-user-guide/index.html

在 WSL 中部署 GPUStack 有两点需要注意：

2.1 驱动安装

在 Windows 系统中安装 NVIDIA 显卡驱动，不要在 WSL 中安装。WSL 内部会自动通过 Passthrough 机制调用宿主机的驱动，在 WSL Linux 发行版中重复安装 NVIDIA 驱动或 CUDA Toolkit 可能会破坏现有环境。

2.2 容器运行时

请使用原生 Docker Engine，不要使用 Docker Desktop 集成。Docker Desktop 的网络模型与标准 Docker Engine 不同，会导致 GPUStack 组件间通信失败。

如果已经安装 Docker Desktop，请在 Docker Desktop 设置中关闭对目标子系统的集成。参考配置如图所示：

3. 环境准备步骤

步骤 1：安装 NVIDIA 驱动（Windows 端）

前往 NVIDIA 官方驱动下载页面，根据显卡型号下载并安装Windows 版本的最新驱动程序。

下载地址：https://www.nvidia.com/en-us/drivers/

步骤 2：安装或更新 WSL（Windows 端）

以管理员身份打开 PowerShell 或命令提示符，执行以下命令安装或更新 WSL：

powershell 复制代码

# 安装 WSL（默认安装 Ubuntu）
wsl --install

# 或者更新 WSL 至最新内核
wsl --update

注意：首次安装 WSL 后，系统可能要求重启计算机。
详细步骤参考：https://learn.microsoft.com/en-us/windows/wsl/install

步骤 3：安装 Docker Engine（WSL 端）

进入 WSL Linux 终端，按照 Docker 官方文档安装 Docker Engine。

官方文档：https://docs.docker.com/engine/install/ubuntu/

步骤 4：安装 NVIDIA Container Toolkit（WSL 端）

官方文档：https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html

安装完成后，需要执行如下配置命令：

bash 复制代码

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

4.（可选）局域网访问配置

默认情况下，WSL 使用 NAT 模式，这意味着局域网内的其他设备无法直接访问 WSL 中运行的服务（如 GPUStack Server）。

若需在局域网访问，请使用 "WSL Settings" 工具配置 WSL 网络模式为 "Mirrored"，如下图所示

关于 WSL 网络模式的详细信息，请查看微软官方文档：https://learn.microsoft.com/en-us/windows/wsl/networking

5. 部署 GPUStack Server

环境准备就绪后，WSL 即可被视为一个标准的 Linux 环境。

请参考 GPUStack 官方文档进行安装：https://docs.gpustack.ai/latest/installation/installation/

6. 添加 Worker 时的注意事项

在 GPUStack UI 界面中按照引导添加 Worker 时，请务必注意以下两点：

6.1 使用默认用户执行脚本

在执行添加 Worker 的验证脚本时，请使用 WSL 的默认用户执行，不要使用 root 用户。

原因：在 WSL 中，nvidia-smi 命令的路径可能未包含在 root 用户的环境变量中，而默认用户可以直接调用。若使用 root 执行，即使环境配置正确，GPU 检测也会失败。

6.2 正确填写 Worker IP

在配置 Worker IP 地址时，请填写 WSL 的实际 IP 地址（例如 172.x.x.x），可使用 ip addr 命令查看。

使用 127.0.0.1 可能导致添加 Worker 失败。

7. 常见问题与注意事项

重启生效：安装 Windows 显卡驱动和 WSL 后通常需要重启 Windows 系统；安装 NVIDIA Container Toolkit 后需重启 WSL 中的 Docker 服务。
WSL 局限性：尽管 NVIDIA 对 WSL 的支持已非常完善，但仍有极少数特定场景可能存在兼容性差异。如遇未知错误，建议搜索 "WSL + [具体错误信息]" 获取解决方案。
组件角色：本指南主要解决 GPU 算力供给（Worker）的问题。对于 GPUStack Server（管理端），由于其主要通过网络通信，对 GPU 依赖较小，部署位置相对灵活，但在 WSL 中统一部署管理更为方便。

官网文档：https://docs.gpustack.ai/

GPUStack v2 FAQ：https://p0p8qa0c0s.feishu.cn/wiki/U3rfw356JitxN3kQeyOcrabInAg

欢迎加入社区群交流

如果二维码失效，大家可前往 GPUStack 项目获取最新入群二维码 https://github.com/gpustack/gpustack/blob/main/docs/assets/wechat-group-qrcode.jpg