gpu-stack-bootstrap/90-troubleshoot.md

90 排错手册

网络问题（最常见）

WSL2 拉不到国外源（GitHub / PyPI）

症状：

• curl 返回 9-14 字节（HTML 错误页）
• git clone 慢到 0 KB/s 或报 early EOF
• apt update 卡住

解法 A：用 Windows 浏览器下载，WSL2 拿本地文件

1. Windows 浏览器下到 D:\xxx
2. WSL2 读：/mnt/d/xxx

解法 B：换国内镜像源

# pip 走清华
uv pip install xxx --extra-index-url https://pypi.tuna.tsinghua.edu.cn/simple

# Hugging Face 走镜像
export HF_ENDPOINT=https://hf-mirror.com

# apt 走阿里云
sudo sed -i 's/archive.ubuntu.com/mirrors.aliyun.com/g' /etc/apt/sources.list
sudo apt update

解法 C：让 WSL2 走 Windows 代理

如果 Windows 上有 clash/v2ray（默认端口 7890）：

# 临时
export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890

# 永久
echo 'export http_proxy=http://127.0.0.1:7890' >> ~/.bashrc
echo 'export https_proxy=http://127.0.0.1:7890' >> ~/.bashrc

安装问题

Ollama 装时报 "zstd not found"

sudo apt install -y zstd

然后重装。

WSL2 透传不到 GPU

按顺序排查：

# 1. 确认 WSL2 版本
wsl --list --verbose
# VERSION 列必须 = 2

# 2. 更新 WSL2 内核（PowerShell 管理员）
wsl --update

# 3. 重启 WSL2（PowerShell）
wsl --shutdown
# 重新打开 Ubuntu 终端

# 4. 在 Ubuntu 内验证
nvidia-smi

如果还不行：

• 确认 Windows 端 nvidia-smi 能看到 5060 Ti
• 重新启动整个 WSL2 服务（services.msc → LxssManager → 重启）

nvidia-smi 在 Ubuntu 报错 "command not found"

说明 PATH 没设对。回到 03 章 WSL2 + CUDA 12.8 重新加 PATH。

uv pip install 报 "the argument --index-url cannot be used multiple times"

去掉 -i 或不要同时加两个 --index-url。uv 用 --index-url（PyTorch 专有源）+ --extra-index-url（清华源）的组合方式，不能两个 --index-url。

PyTorch 装完 import 报 libcudart.so not found

CUDA Toolkit 没装好，重装 03 章。

PyTorch 输出 CUDA: False

# 排查
python -c "import torch; print(torch.version.cuda)"
# 应输出 12.8

ls /usr/local/cuda/lib64/libcudart.so*
# 应有文件存在

性能问题

Ollama 跑模型慢（< 5 tokens/s）

• 检查是不是量化版本太重（如 32B 跑 16G 显存必慢）
• 关掉其他吃 GPU 的程序（nvidia-smi 看 GPU-Util）
• 试试更小的模型（7b 替代 14b）

ComfyUI 出图慢

• 第一次出图编译 kernel，慢 2-3 分钟（正常）
• 之后每张 5-10 秒是 Flux.1-dev fp8 正常速度
• 调小分辨率（512x512 → 1024x1024 慢 4 倍）

显存问题

跑 14B 模型 OOM (Out of Memory)

# 关掉其他模型
ollama stop qwen2.5:7b

# 用更小的量化版本
ollama pull qwen2.5:7b

ComfyUI 出图 OOM

1. 调小图片尺寸（1024 → 768）
2. 启用 FP8 attention
3. 关掉 ControlNet / LoRA

黑屏 / 驱动冲突

千万别在 WSL2 装 NVIDIA 驱动

会和 Windows 驱动打架 → 整个系统黑屏。如果已经装了：

1. 重启进 Windows 安全模式
2. 用 DDU 卸载
3. 正常启动

重装 WSL2 内核

# PowerShell 管理员
wsl --shutdown
wsl --update
wsl --unregister Ubuntu-24.04   # 注意：会删 Ubuntu 内所有数据
wsl --install -d Ubuntu-24.04

工具脚本

一键检查所有验证

cat > /tmp/check.sh << 'EOF'
echo "=== nvidia-smi ==="
nvidia-smi
echo ""
echo "=== nvcc ==="
nvcc --version
echo ""
echo "=== ollama ==="
ollama --version
ollama list
echo ""
echo "=== PyTorch ==="
source /mnt/d/llm-code/.venv/bin/activate
python -c "import torch; print('CUDA:', torch.cuda.is_available(), '| GPU:', torch.cuda.get_device_name(0))"
EOF
chmod +x /tmp/check.sh
bash /tmp/check.sh

跑这个能一次性看到所有组件状态。