# wsl

**Repository Path**: dis-acme/wsl

## Basic Information

- **Project Name**: wsl
- **Description**: windows wsl 相关操作文档
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-03
- **Last Updated**: 2026-11-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WSL 文档索引

> **更新时间**: 2026-11-13
> **目录**: `D:\WSL\doc\`

---

## 目录结构

```
D:\WSL\doc\
├── README.md                  ← 本索引
├── tools\                     可直接使用的脚本
│   └── setup-vnc-portforward.ps1   VNC 端口转发一键配置
├── wsl\                       WSL 基础与网络
│   ├── 01-操作手册.md
│   ├── 02-SSH外部访问配置.md
│   └── 03-多实例部署实战.md
├── desktop\                   桌面环境（TigerVNC + XFCE）
│   ├── 01-桌面应用故障排查与修复.md
│   ├── 02-浏览器与Trae登录故障排查.md
│   ├── 03-IDEA与GoLand故障排查.md
│   ├── 04-Flameshot截图工具.md
│   └── 05-u-xf-soldier升级TigerVNC.md
└── k8s\                       Kubernetes（k3s 单节点集群）
    ├── README.md              k8s 专题索引 + 环境快照
    ├── 01-环境与安装.md
    ├── 02-方案选型对比.md
    ├── 03-日常使用手册.md
    ├── 04-故障排查手册.md
    ├── 05-真实迁移案例.md
    └── 06-Dashboard管理界面.md
```

**命名约定**：`NN-主题.md`（两位序号 + 短横线 + 中文主题），序号在各自目录内从 01 递增。

---

## 文档清单

### wsl\ —— WSL 基础与网络

| 编号 | 文档 | 内容 | 更新日期 |
|------|--------|------|---------|
| wsl/01 | [操作手册](./wsl/01-操作手册.md) | WSL 基础操作、发行版管理、性能配置、常用命令 | 2026-10-10 |
| wsl/02 | [SSH外部访问配置](./wsl/02-SSH外部访问配置.md) | 多发行版 SSH 配置、端口规划、Windows 端口转发、VNC 端口转发（第 7 节） | 2026-11-10 |
| wsl/03 | [多实例部署实战](./wsl/03-多实例部署实战.md) | 模板化部署方法论、4 个真问题（msi/被墙/DEB822/xrdp）、实例名前缀 | 2026-11-10 |

### desktop\ —— 桌面环境

| 编号 | 文档 | 内容 | 更新日期 |
|------|--------|------|---------|
| desktop/01 | [桌面应用故障排查与修复](./desktop/01-桌面应用故障排查与修复.md) | **主文档**：8 类桌面故障的完整排查与修复 + VNC 自启动服务文件附录 | 2026-11-10 |
| desktop/02 | [浏览器与Trae登录故障排查](./desktop/02-浏览器与Trae登录故障排查.md) | 浏览器默认设置、Trae 登录、firefox-esr/PPA pin 部署 | 2026-11-10 |
| desktop/03 | [IDEA与GoLand故障排查](./desktop/03-IDEA与GoLand故障排查.md) | **IDEA/GoLand 专项**：Markdown 白屏、TRAE 插件、钥匙包弹窗 | 2026-10-21 |
| desktop/04 | [Flameshot截图工具](./desktop/04-Flameshot截图工具.md) | Flameshot 截图：安装、使用、自启动、与 Windows 剪贴板互通 | 2026-10-22 |
| desktop/05 | [u-xf-soldier升级TigerVNC](./desktop/05-u-xf-soldier升级TigerVNC.md) | **升级记录**：u-xf-soldier 桌面 Xvfb+x11vnc → TigerVNC，中文剪贴板保持方案 | 2026-11-02 |

### k8s\ —— Kubernetes

| 编号 | 文档 | 内容 | 更新日期 |
|------|--------|------|---------|
| k8s/01 | [环境与安装](./k8s/01-环境与安装.md) | clean.tar 恢复实例、k3s 安装、SSH 2219、端口转发、脚本清单 | 2026-11-03 |
| k8s/02 | [方案选型对比](./k8s/02-方案选型对比.md) | k3s / kind / minikube / microk8s / kubeadm 功能与资源对比 | 2026-11-03 |
| k8s/03 | [日常使用手册](./k8s/03-日常使用手册.md) | kubectl 速查、demo 部署、访问方式、自带组件用法 | 2026-11-03 |
| k8s/04 | [故障排查手册](./k8s/04-故障排查手册.md) | 5 个真实案例（双节点、localhost 不通、IP 漂移等）+ 诊断命令集 | 2026-11-03 |
| k8s/05 | [真实迁移案例](./k8s/05-真实迁移案例.md) | RAGFlow 依赖栈 compose → k3s 完整迁移：3 个硬约束、映射表、5 个坑、执行记录 | 2026-11-09 |
| k8s/06 | [Dashboard管理界面](./k8s/06-Dashboard管理界面.md) | Kubernetes Dashboard 一键部署、Token 登录、镜像兜底、2 个坑、维护命令 | 2026-11-13 |

---

## 快速导航

### 我想...

| 需求 | 看哪篇 |
|------|--------|
| 装个新发行版、配内存、改 DNS | [wsl/01](./wsl/01-操作手册.md) |
| 从另一台机器 SSH 登录 WSL | [wsl/02](./wsl/02-SSH外部访问配置.md) |
| **批量建实例 / 用模板开新实例** | **[wsl/03](./wsl/03-多实例部署实战.md)** |
| 多实例终端分不清自己在哪个实例 | [wsl/03](./wsl/03-多实例部署实战.md) 第 3 节 |
| **VNC 连桌面（localhost 固定地址）** | **[wsl/02](./wsl/02-SSH外部访问配置.md) 第 7 节** + [tools/setup-vnc-portforward.ps1](./tools/setup-vnc-portforward.ps1) |
| **Chrome/应用上不了网** | **[desktop/01](./desktop/01-桌面应用故障排查与修复.md) 第 3 节** |
| **点登录拉不起浏览器（Trae/GoLand）** | **[desktop/01](./desktop/01-桌面应用故障排查与修复.md) 第 4 节** |
| **VNC 重启后黑屏** | **[desktop/01](./desktop/01-桌面应用故障排查与修复.md) 第 5 节** |
| **打开大应用就卡死** | **[desktop/01](./desktop/01-桌面应用故障排查与修复.md) 第 6 节** |
| **桌面图标启动的应用缺环境变量** | **[desktop/01](./desktop/01-桌面应用故障排查与修复.md) 第 7 节** |
| snap 应用报 cannot open display | [desktop/01](./desktop/01-桌面应用故障排查与修复.md) 第 8 节 |
| 重启后没有中文输入法 | [desktop/01](./desktop/01-桌面应用故障排查与修复.md) 第 9 节 |
| 剪贴板不互通 Windows | [desktop/01](./desktop/01-桌面应用故障排查与修复.md) 第 10 节 |
| 找现成的修复脚本 | [desktop/01](./desktop/01-桌面应用故障排查与修复.md) 第 11 节 |
| 设置默认浏览器 | [desktop/01](./desktop/01-桌面应用故障排查与修复.md) 第 12.2 节 / [desktop/02](./desktop/02-浏览器与Trae登录故障排查.md) |
| **IDEA/GoLand Markdown 白屏** | **[desktop/03](./desktop/03-IDEA与GoLand故障排查.md) 第 3-4 节** |
| **IDEA 的 TRAE 插件报 Missing JCEF** | **[desktop/03](./desktop/03-IDEA与GoLand故障排查.md) 第 7.1 节** |
| **启动时弹 Unlock Keyring 密码框** | **[desktop/03](./desktop/03-IDEA与GoLand故障排查.md) 第 4.1 节** |
| **IDEA 体检** | `~/local/bin/idea-health-check.sh` |
| **WSL 里截图（Flameshot）** | [desktop/04](./desktop/04-Flameshot截图工具.md) |
| **截图图片传到 Windows** | [desktop/04](./desktop/04-Flameshot截图工具.md) 第 6 节 |
| **托盘没有火焰图标** | [desktop/04](./desktop/04-Flameshot截图工具.md) 第 7.1 节 |
| **VNC 卡顿/拖影、观感差（u-xf-soldier）** | [desktop/05](./desktop/05-u-xf-soldier升级TigerVNC.md) |
| **装 k3s / 从零恢复 WSL 实例** | **[k8s/01](./k8s/01-环境与安装.md)** |
| **选哪种 k8s 发行版** | [k8s/02](./k8s/02-方案选型对比.md) |
| **日常 kubectl / 跑个 demo** | [k8s/03](./k8s/03-日常使用手册.md) |
| **k8s 出问题排查** | [k8s/04](./k8s/04-故障排查手册.md) |
| **把 compose 服务搬上 k8s** | [k8s/05](./k8s/05-真实迁移案例.md) |
| **用图形界面看集群（Dashboard）** | **[k8s/06](./k8s/06-Dashboard管理界面.md)** |
| 备份 WSL 实例 | `D:\WSL\backup\备份说明.txt` |

---

## 当前环境速查

```
发行版      desktop1(:1, VNC 5901, SSH 2222)
            desktop2(:2, VNC 5902, SSH 2223)
            k3s(SSH 2219, k3s v1.36.5 单节点集群)
SSH 连接    ssh -p 2223 inho@127.0.0.1     ← 用回环，不受 IP 变动影响
            ssh -p 2219 inho@127.0.0.1     ← k3s 实例
用户        inho (uid=1001)
共享 IP     172.29.248.225（所有发行版共享）
桌面环境    TigerVNC + XFCE
```

**关键提醒**：
- `wsl.exe` 在本机被安全策略拦截，无法从 AI 侧直接调用
- 需sudo 的操作必须手动执行（AI 侧 `sudo -n` 不可用）
- 桌面应用请用 `chrome-safe` / `trae-safe` 启动，不要点桌面图标
- WSL2 的 localhost 转发不覆盖 NodePort/hostPort，k8s 服务访问方式见 [k8s/03](./k8s/03-日常使用手册.md)

---

## 核心认知（避免重复踩坑）

1. **WSLg 把 `/tmp/.X11-unix` 挂成只读** → snap 应用无法工作
2. **GUI/systemd 启动不读 shell 配置** → 环境变量要靠启动器注入
3. **Electron 日志会骗人**（`openBrowser success` 不代表成功）
4. **xdotool 本机未安装**，不要用它做诊断判断
5. **Chrome 会卡在 Google 后台服务** → 需 `--disable-background-networking`
6. **VNC 是软件渲染** → Electron 应用需 `--disable-gpu` + 降分辨率
7. **WSL 启动会重置主机名** → 须在 `/etc/wsl.conf` 写 `[network] hostname=...`（k8s 实例踩过坑，见 [k8s/04](./k8s/04-故障排查手册.md)）
8. **WSL 全实例共享 IP 和端口表** → 端口必须一个实例一个（SSH 2222/2223/2219、VNC 5901/5902、k8s NodePort 都因此规划），新建实例先查端口冲突（见 [wsl/03](./wsl/03-多实例部署实战.md)）