docs: 初始装机指南

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

01-hardware-check.md

@@ -0,0 +1,77 @@
+# 01 硬件与基础检查
+
+## 目标
+
+确认你的硬件能跑这套配置 + 基础环境 OK。
+
+## 检查清单
+
+- [ ] RTX 5060 Ti 16GB 已装进主板
+- [ ] 电源线 8pin 接好
+- [ ] 显示器接在显卡 HDMI/DP 上（**不是**主板的核显口）
+- [ ] 主板 BIOS 里 Resizable BAR / Above 4G Decoding 开启（默认开的，没动过就不用管）
+- [ ] Windows 11 已更新到最新版（设置 → Windows 更新 → 检查更新）
+
+## 必备工具（Windows 端先装好）
+
+打开 PowerShell（管理员），跑：
+```powershell
+# 1. WSL2
+wsl --install
+
+# 2. 装完重启后，验证
+wsl --list --verbose
+```
+
+应当看到 `VERSION` 列 = `2`。
+
+## 装 Ubuntu 24.04
+
+```powershell
+wsl --install -d Ubuntu-24.04
+```
+
+第一次进 Ubuntu 会提示设用户名密码（**记好**），完成后会自动回到命令行。
+
+## 回到 WSL2 Ubuntu 终端，更新系统
+
+```bash
+sudo apt update && sudo apt upgrade -y
+sudo apt install -y build-essential git curl wget netcat-openbsd
+```
+
+## 验证硬件识别
+
+**Windows PowerShell**：
+```powershell
+nvidia-smi
+```
+**应当看到**：
+```
++-----------------------------------------+
+| NVIDIA-SMI 610.47 ...  |
+| 0  NVIDIA GeForce RTX 5060 Ti ...  16311MiB |
++-----------------------------------------+
+```
+
+如果**报错 / 没看到卡**：
+- 检查显示器接的是**显卡**不是核显
+- 检查 PCIe 插槽插紧没
+- 主板 BIOS 里把 PEG/PCIe16 优先级设第一
+
+## 验证 WSL2 看得到 GPU
+
+**WSL2 Ubuntu 终端**：
+```bash
+nvidia-smi
+```
+**应当看到同一张 5060 Ti**（同驱动版本 610.47 / 610.43.02 都行）。
+
+如果**看不到 / 报错**：
+- 确认 WSL2 是 v2：`wsl --set-default-version 2`
+- 更新 WSL2 内核（PowerShell 管理员）：`wsl --update`
+- 重启 WSL2：`wsl --shutdown` 然后重新打开终端
+
+## 下一步
+
+✅ 通过后 → [02 Windows 装 Studio 驱动](./02-windows-driver.md)

02-windows-driver.md

@@ -0,0 +1,76 @@
+# 02 Windows 装 Studio 驱动
+
+## 目标
+
+装 NVIDIA Studio 驱动（**不是 Game Ready**）≥ 560.94。
+
+## 为什么必须 Studio 驱动
+
+- Blackwell 架构必需 560.94+，旧驱动点不亮 5060 Ti
+- Studio 驱动针对创作/AI 场景优化（PyTorch/CUDA 兼容性更好）
+- Game Ready 跑游戏稳，跑 AI 可能出幺蛾子
+
+## 下载驱动
+
+打开 https://www.nvidia.cn/Download/index.aspx，按这个选：
+
+| 字段 | 选什么 |
+|------|------|
+| 产品类型 | **GeForce** |
+| 产品系列 | **GeForce RTX 50 Series (Notebooks)** |
+| 产品 | **GeForce RTX 5060 Ti** |
+| 操作系统 | **Windows 11** |
+| 下载类型 | **Studio Driver (SD)** ← 不是 Game Ready |
+| 语言 | 简体中文 |
+
+**版本号要求 ≥ 560.94**。
+
+## 安装步骤
+
+1. 关掉所有程序（浏览器、Steam、OBS 录屏、任何在用显卡的）
+2. 双击下载的 .exe
+3. **如果让你选安装位置**：保持默认
+4. **如果让你选组件**：
+   - ✅ 显卡驱动程序（必选）
+   - ✅ NVIDIA App（如果灰的就跳过，不影响）
+   - ✅ PhysX / HD Audio（默认勾的全留）
+   - **不要取消**任何一项
+5. **关键一步**：进入自定义页面 → 勾上"**执行清洁安装**"（Clean Install）
+6. 点"下一步"等进度条（2-5 分钟）
+7. 装完提示重启 → **完整重启**（开始菜单 → 电源 → 重启，不是关机再开）
+
+## 验证
+
+重启后 PowerShell 跑：
+```powershell
+nvidia-smi
+```
+
+**应当看到**：
+- 驱动版本：`610.47`（或你装的那个版本）
+- 显卡：RTX 5060 Ti
+- CUDA Version：`12.8` 或更高
+- 显存：`16311 MiB`（约 16GB）
+
+## 常见坑
+
+### 看不到卡 / 设备管理器有黄色感叹号
+
+1. 卸载干净再装：设置 → 应用 → 搜 "NVIDIA" → 全部卸载
+2. 用 DDU（Display Driver Uninstaller）安全模式清理
+3. 重装时**勾"执行清洁安装"**
+
+### 安装报错 "找不到兼容的硬件"
+
+主板 BIOS 没识别到 5060 Ti，更新主板 BIOS 到最新。
+
+### 安装报错 "另一个安装正在进行"
+
+杀掉 Windows Installer：
+```powershell
+taskkill /F /IM msiexec.exe
+```
+
+## 下一步
+
+✅ 通过后 → [03 WSL2 + CUDA 12.8](./03-wsl2-ubuntu.md)

03-wsl2-ubuntu.md

@@ -0,0 +1,92 @@
+# 03 WSL2 + CUDA 12.8
+
+## 目标
+
+让 WSL2 Ubuntu 能用 5060 Ti 跑 CUDA 程序。
+
+## ⚠️ 重要：WSL2 不要装 NVIDIA 驱动
+
+WSL2 有个特殊机制——**Windows 装一次驱动，WSL2 共享用**。
+
+| 位置 | 装什么 |
+|------|------|
+| Windows 11 | ✅ NVIDIA Studio 驱动（第二章装的） |
+| WSL2 Ubuntu | ✅ **只装 CUDA Toolkit**（数学库） |
+| WSL2 Ubuntu | ❌ **不装 NVIDIA 驱动**（会和 Windows 驱动打架黑屏） |
+
+## 验证 WSL2 透传
+
+**WSL2 Ubuntu 终端**：
+```bash
+nvidia-smi
+```
+**应当看到**和 Windows 端一样的 5060 Ti（驱动版本号略不同没关系，KMD/UMD 一致即可）。
+
+## 装 CUDA Toolkit 12.8
+
+**WSL2 Ubuntu 终端**（一段一段粘贴跑）：
+
+### 1. 加 NVIDIA 官方 apt 仓库
+
+```bash
+wget https://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/x86_64/cuda-keyring_1.1-1_all.deb
+sudo dpkg -i cuda-keyring_1.1-1_all.deb
+sudo apt update
+```
+
+### 2. 装 CUDA Toolkit（不装驱动）
+
+```bash
+sudo apt install -y cuda-toolkit-12-8
+```
+**等 3-5 分钟**（约 1.5 GB 下载）。
+
+### 3. 加 PATH
+
+```bash
+echo 'export PATH=/usr/local/cuda/bin:$PATH' >> ~/.bashrc
+echo 'export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
+source ~/.bashrc
+```
+
+### 4. 验证
+
+```bash
+nvcc --version
+```
+**应当看到**：
+```
+Cuda compilation tools, release 12.8, V12.8.93
+```
+
+## 装 Python 环境管理器
+
+uv（比 conda 快 10 倍）：
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+source ~/.bashrc
+uv --version
+```
+**应当看到** `uv 0.x.x`（2026 年最新版）。
+
+那个 `mkdir: cannot create directory '/home/xxx/.config/fish': Permission denied` 报错**无关**（你用 bash 不影响）。
+
+## 准备模型目录（用 D 盘）
+
+```bash
+mkdir -p /mnt/d/ollama_models
+mkdir -p /mnt/d/ComfyUI-models/checkpoints
+mkdir -p /mnt/d/ComfyUI-models/vae
+mkdir -p /mnt/d/ComfyUI-models/loras
+mkdir -p /mnt/d/ComfyUI-models/controlnet
+mkdir -p /mnt/d/llm-code
+mkdir -p /mnt/d/img-code
+ls -la /mnt/d/
+```
+
+`System Volume Information: Permission denied` 是 Windows 系统卷，**正常**，不管。
+
+## 下一步
+
+✅ 通过后 → [04 Ollama 装 LLM](./04-ollama-llm.md)

04-ollama-llm.md

@@ -0,0 +1,128 @@
+# 04 Ollama 装 LLM
+
+## 目标
+
+装 Ollama + 拉 qwen2.5:7b 模型 + 跑通对话。
+
+## Ollama 装
+
+### 1. 让 Ollama 把模型存 D 盘
+
+**WSL2 Ubuntu 终端**：
+```bash
+echo 'export OLLAMA_MODELS=/mnt/d/ollama_models' >> ~/.bashrc
+source ~/.bashrc
+```
+
+### 2. 装 zstd（解压用）
+
+```bash
+sudo apt install -y zstd
+```
+
+### 3. 装 Ollama
+
+**WSL2 网络访问国外源（GitHub）通常不通**，所以不要用官方一键脚本。直接下二进制：
+
+**Windows 浏览器**打开下载链接：
+- https://github.com/ollama/ollama/releases/latest
+- 找 `ollama-linux-amd64.tar.zst`（约 1.3 GB）
+- 右键 → 另存为 → `D:\ollama-linux-amd64.tar.zst`
+
+**WSL2 终端解压**：
+```bash
+sudo tar -C /usr --use-compress-program=unzstd -xf /mnt/d/ollama-linux-amd64.tar.zst
+ollama --version
+```
+
+**应当看到** `ollama version 0.x.x`（GitHub 上的最新版）。
+
+**如果 unzstd 报错**，用备用方法：
+```bash
+unzstd -k /mnt/d/ollama-linux-amd64.tar.zst -o /tmp/ollama-linux-amd64.tar
+ls -lh /tmp/ollama-linux-amd64.tar
+sudo tar -C /usr -xf /tmp/ollama-linux-amd64.tar
+ollama --version
+```
+
+### 4. 启服务
+
+```bash
+ollama serve &
+```
+看到 `Listening on 127.0.0.1:11434` 后按回车。
+
+## 拉模型
+
+### 推荐 16G 显存能跑得动的
+
+| 模型 | 大小 | 用途 |
+|------|------|------|
+| `qwen2.5:7b` | 4.5G | 中文对话主力（最舒服）|
+| `qwen2.5:14b` | 9G | 强一点的中文 |
+| `deepseek-r1:14b` | 9G | 推理/代码强 |
+| `qwen2.5-coder:14b` | 9G | 写代码辅助 |
+
+**D 盘预留 50G** 给模型（3-4 个模型）。
+
+### 拉第一个
+
+```bash
+ollama pull qwen2.5:7b
+```
+**等 3-10 分钟**（看网络速度，4.5G）。
+
+### 测试
+
+```bash
+ollama run qwen2.5:7b "用一句话介绍你自己"
+```
+**应当看到中文回复**。输入 `/bye` 退出。
+
+## 常用命令
+
+```bash
+# 列出已下载的模型
+ollama list
+
+# 启服务（开机后或重启后）
+ollama serve &
+
+# 进入对话
+ollama run qwen2.5:7b
+
+# 停止某个模型（释放显存）
+ollama stop qwen2.5:7b
+
+# 删除模型
+ollama rm qwen2.5:7b
+
+# 通过 API 调用（端口 11434）
+curl http://localhost:11434/api/generate -d '{"model":"qwen2.5:7b","prompt":"你好","stream":false}'
+```
+
+## 调出 GUI（可选）
+
+### LM Studio（图形界面）
+
+**WSL2 终端**：
+```bash
+cd ~/
+wget https://releases.lmstudio.ai/linux/x86/0.3.10/LM-Studio-0.3.10-x64.AppImage -O lmstudio.AppImage
+chmod +x lmstudio.AppImage
+./lmstudio.AppImage
+```
+
+## 显存占用参考
+
+| 模型 | 显存 | 速度（7b 量级） |
+|------|------|------|
+| 7b Q4_K | ~5G | 10-20 tokens/s |
+| 14b Q4_K | ~10G | 6-12 tokens/s |
+| 32b Q4_K | ~20G | 2-4 tokens/s（**16G 跑不了**）|
+
+**16G 显存上限**：14b Q4_K 量化的 32B 模型（勉强能跑但慢），再大就跑不动了。
+
+## 下一步
+
+✅ 通过后 → [05 PyTorch 验证](./05-pytorch-verify.md)

05-pytorch-verify.md

@@ -0,0 +1,98 @@
+# 05 PyTorch 验证
+
+## 目标
+
+装 PyTorch 2.7.1 + cu128，验证能调用 5060 Ti。
+
+## 装 venv
+
+**WSL2 Ubuntu 终端**：
+```bash
+cd /mnt/d/llm-code
+uv venv --python 3.11 .venv
+source .venv/bin/activate
+```
+**应当看到**命令行前缀变成 `(.venv) eric@...`。
+
+## 装 PyTorch（用清华源代理，国内最快）
+
+```bash
+uv pip install torch torchvision torchaudio \
+  --index-url https://download.pytorch.org/whl/cu128 \
+  --extra-index-url https://pypi.tuna.tsinghua.edu.cn/simple
+```
+
+| 参数 | 用途 |
+|------|------|
+| `--index-url` | 强制走 PyTorch 官方源（拉 cu128 专用 wheel）|
+| `--extra-index-url` | 补充源，其他依赖走清华（`pypi.tuna.tsinghua.edu.cn`）|
+
+**不要**同时加 `--index-url` 和 `-i`，uv 会报"重复"。
+
+**预计 5-15 分钟**（约 2.5 GB 下载）。
+
+## 验证（关键！）
+
+```bash
+python -c "import torch; print('CUDA:', torch.cuda.is_available(), '| GPU:', torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'NONE')"
+```
+
+**应输出**：
+```
+CUDA: True | GPU: NVIDIA GeForce RTX 5060 Ti
+```
+
+## 跑个真测试（确认能算东西）
+
+```bash
+python -c "
+import torch
+x = torch.randn(1000, 1000, device='cuda')
+y = torch.randn(1000, 1000, device='cuda')
+z = x @ y
+print('矩阵乘法 OK, 形状:', z.shape, '设备:', z.device)
+print('显存占用:', torch.cuda.memory_allocated()/1e9, 'GB')
+"
+```
+
+**应输出**：
+```
+矩阵乘法 OK, 形状: torch.Size([1000, 1000]) 设备: cuda:0
+显存占用: 8.0... GB
+```
+
+## 镜像版本必须匹配
+
+| torch | torchvision | torchaudio |
+|------|------|------|
+| 2.7.0 | 0.22.0 | 2.7.0 |
+| 2.7.1 | 0.22.1 | 2.7.1 |
+| 2.8.0 | 0.23.0 | 2.8.0 |
+
+**不要混搭**（如 torch 2.7.1 + torchvision 0.22.0，会出兼容警告）。
+
+## 常见问题
+
+### 输出 `CUDA: False`
+
+按顺序排查：
+1. `nvidia-smi` 在 WSL2 能不能看到卡
+2. `nvcc --version` 是不是 12.8
+3. 重新装一遍 PyTorch（可能是装时网络断了，下了不完整的 wheel）
+
+### 装时报 `pip` 相关错
+
+```bash
+deactivate
+uv venv --python 3.11 .venv --clear
+source .venv/bin/activate
+# 重装
+```
+
+### 装完 import 报 `libcudart.so not found`
+
+CUDA Toolkit 没装好，回到 [03 WSL2 + CUDA 12.8](./03-wsl2-ubuntu.md) 重新装。
+
+## 下一步
+
+✅ 通过后 → [06 ComfyUI 装出图](./06-comfyui-image.md)

06-comfyui-image.md

@@ -0,0 +1,120 @@
+# 06 ComfyUI 装出图
+
+## 目标
+
+装 ComfyUI + 拉 Flux.1-dev fp8 模型 + 出第一张图。
+
+## 拉 ComfyUI 代码
+
+**WSL2 终端**：
+```bash
+cd /mnt/d/img-code
+git clone https://github.com/comfyanonymous/ComfyUI.git
+cd ComfyUI
+```
+
+## 建独立 venv（和 LLM 那个分开）
+
+```bash
+uv venv --python 3.11 .venv
+source .venv/bin/activate
+```
+
+## 装依赖
+
+```bash
+uv pip install -r requirements.txt
+uv pip install torch torchvision torchaudio \
+  --index-url https://download.pytorch.org/whl/cu128 \
+  --extra-index-url https://pypi.tuna.tsinghua.edu.cn/simple
+```
+
+## 让 ComfyUI 用 D 盘模型
+
+**WSL2 终端**（在 ComfyUI 目录下）：
+```bash
+cat > extra_model_paths.yaml << 'EOF'
+comfyui_models:
+  base_path: /mnt/d/ComfyUI-models
+  checkpoints: checkpoints
+  vae: vae
+  loras: loras
+  controlnet: controlnet
+EOF
+```
+
+**这样配置后**：
+- 你把模型放 `/mnt/d/ComfyUI-models/checkpoints/`
+- ComfyUI 自动找到（不用改代码）
+
+## 验证 PyTorch（同 05 章）
+
+```bash
+python -c "import torch; print(torch.cuda.is_available(), torch.cuda.get_device_name(0))"
+```
+
+## 拉 Flux.1-dev fp8 模型（16G 显存能跑）
+
+**WSL2 终端**：
+```bash
+source .venv/bin/activate
+uv pip install huggingface_hub
+
+python -c "
+from huggingface_hub import hf_hub_download
+import os
+os.makedirs('/mnt/d/ComfyUI-models/checkpoints', exist_ok=True)
+os.makedirs('/mnt/d/ComfyUI-models/vae', exist_ok=True)
+hf_hub_download(repo_id='Comfy-Org/Flux.1-FP8', filename='flux1-dev-fp8.safetensors', local_dir='/mnt/d/ComfyUI-models/checkpoints/')
+hf_hub_download(repo_id='Comfy-Org/Flux.1-FP8', filename='ae.safetensors', local_dir='/mnt/d/ComfyUI-models/vae/')
+print('下载完成')
+"
+```
+
+**等 10-20 分钟**（约 12 GB）。
+
+## 启动 ComfyUI
+
+```bash
+python main.py --listen 0.0.0.0
+```
+
+**看到**：
+```
+To see the GUI go to: http://0.0.0.0:8188
+```
+
+**Windows 浏览器打开**：http://localhost:8188
+
+## 出第一张图
+
+1. 浏览器打开 `http://localhost:8188`
+2. 左键双击空白处 → 搜 "Load Checkpoint" → 选 `flux1-dev-fp8.safetensors`
+3. 加 "CLIP Text Encode" 节点（输入正面提示词）
+4. 加 "Empty Latent Image" 节点（设置 1024x1024）
+5. 加 "KSampler" 节点
+6. 加 "VAE Decode" + "Save Image" 节点
+7. 点 "Queue Prompt" → 等 30-60 秒
+
+**第一次出图会编译 kernel，比较慢**（2-3 分钟），之后每张 5-10 秒。
+
+## 模型推荐
+
+| 模型 | 显存 | 速度 | 质量 |
+|------|------|------|------|
+| Flux.1-dev fp8 | 12G | 中 | ⭐⭐⭐⭐⭐ |
+| SDXL | 7G | 快 | ⭐⭐⭐⭐ |
+| SD 1.5 | 4G | 很快 | ⭐⭐⭐ |
+
+**16G 显存**：
+- Flux.1-dev fp8 刚好
+- SDXL 舒服
+- SD 1.5 跑得飞快
+
+## 关掉 ComfyUI
+
+回到 WSL2 终端，按 `Ctrl+C`。
+
+## 下一步
+
+✅ 通过后 → 装更多模型 / 装 ComfyUI-Manager（一键装插件）/ 学 workflow

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
+```
+
+跑这个能一次性看到所有组件状态。

README.md

@@ -1,3 +1,53 @@
-# gpu-stack-bootstrap
+# GPU Stack Bootstrap
 
-Windows 11 + WSL2 Ubuntu 24.04 + RTX 5060 Ti Blackwell GPU 全栈装机指南（驱动/CUDA/PyTorch/Ollama/ComfyUI）
+> Windows 11 + WSL2 Ubuntu 24.04 + RTX 5060 Ti (Blackwell) 全栈装机指南
+>
+> 目标读者：能看懂命令但没装过 NVIDIA 显卡+WSL2+CUDA 的新人
+
+## 一句话 TL;DR
+
+装 NVIDIA Studio 驱动（Windows）→ 装 CUDA Toolkit 12.8（WSL2）→ 装 PyTorch / Ollama / ComfyUI
+→ 验证 `nvidia-smi` 看到 5060 Ti → 完事。
+
+## 当前进度
+
+| 章节 | 状态 | 验证方式 |
+|------|------|------|
+| [01 硬件与基础检查](./01-hardware-check.md) | ✅ 已跑通 | 装好显卡，nvidia-smi 能看到 |
+| [02 Windows 装 Studio 驱动](./02-windows-driver.md) | ✅ 已跑通 | nvidia-smi 看到 5060 Ti + 610.47 |
+| [03 WSL2 + CUDA 12.8](./03-wsl2-ubuntu.md) | ✅ 已跑通 | nvcc --version 显示 12.8 |
+| [04 Ollama 装 LLM](./04-ollama-llm.md) | ✅ 已跑通 | qwen2.5:7b 聊天正常 |
+| [05 PyTorch 验证](./05-pytorch-verify.md) | ⏳ 待补 | 看到 `CUDA: True \| 5060 Ti` |
+| [06 ComfyUI 装出图](./06-comfyui-image.md) | ⏳ 待补 | 浏览器开 8188 出图 |
+| [90 排错手册](./90-troubleshoot.md) | ✅ 已有 | 镜像源 / zstd / WSL2 透传失败 |
+
+## 硬件清单
+
+- **GPU**: NVIDIA GeForce RTX 5060 Ti (16 GB, Blackwell 架构, sm_120)
+- **CPU**: AMD Ryzen 7 8845HS (实测)
+- **OS**: Windows 11 + WSL2 Ubuntu 24.04 LTS
+- **内存**: 32GB 起步
+
+## 关键硬规则
+
+1. **驱动必须 ≥ 560.94**（Blackwell 必需，5060 Ti 在 560.94 之前根本点不亮）
+2. **WSL2 Ubuntu 内不能装 NVIDIA 驱动**（会和 Windows 驱动打架黑屏）—— 只装 CUDA Toolkit
+3. **CUDA Toolkit 必须 ≥ 12.6**（Blackwell 必需，13.x 主流 wheel 还没出）
+4. **PyTorch wheel 必须 `+cu128`**（不是 cu118/cu121/cu124，老版本不支持 Blackwell）
+5. **模型放 D 盘**（`/mnt/d/`），系统盘别占满
+
+## 推荐阅读顺序
+
+1. 先看 [01 硬件与基础检查](./01-hardware-check.md) —— 确认你电脑符合
+2. 严格按 02 → 03 → 04 跑，每步都看验证输出
+3. 卡住先查 [90 排错手册](./90-troubleshoot.md)
+4. 跑通后看 05 / 06 装实际工作负载
+
+## 备份仓库
+
+- **Gitea (主)**: https://git.errlens.top/hwd32/gpu-stack-bootstrap
+- **GitCode (异地备份)**: https://gitcode.com/tupingr/gpu-stack-bootstrap
+
+## 贡献
+
+踩坑了补 [90 排错手册](./90-troubleshoot.md) 或直接提 PR。