docs: 初始装机指南

包含 6 章步骤 + 排错手册：
- 01 硬件与基础检查
- 02 Windows 装 Studio 驱动
- 03 WSL2 + CUDA 12.8
- 04 Ollama 装 LLM
- 05 PyTorch 验证（待补，依赖实机跑通）
- 06 ComfyUI 装出图（待补，依赖实机跑通）
- 90 排错手册

90-troubleshoot.md

@@ -0,0 +1,175 @@
+# 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：换国内镜像源**
+
+```bash
+# 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）：
+```bash
+# 临时
+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"
+
+```bash
+sudo apt install -y zstd
+```
+然后重装。
+
+### WSL2 透传不到 GPU
+
+按顺序排查：
+
+```bash
+# 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](./03-wsl2-ubuntu.md) 重新加 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 章](./03-wsl2-ubuntu.md)。
+
+### PyTorch 输出 `CUDA: False`
+
+```bash
+# 排查
+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)
+
+```bash
+# 关掉其他模型
+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
+# PowerShell 管理员
+wsl --shutdown
+wsl --update
+wsl --unregister Ubuntu-24.04   # 注意：会删 Ubuntu 内所有数据
+wsl --install -d Ubuntu-24.04
+```
+
+## 工具脚本
+
+### 一键检查所有验证
+
+```bash
+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
+```
+
+跑这个能一次性看到所有组件状态。