容器与 WSL 环境成套配置与排查 部分实测

场景

你的 Docker 和 WSL「装了但用不起来」：daemon 连不上、端口冲突、exec 报 TTY、容器访问不了宿主机、WSL 输出乱码、报磁盘满、WSL 里找不到 node。每篇教程各讲一个坑，报错时根本不知道先解决哪个。

本组合包把它们按排查顺序编排成套：先保证 WSL 基础可用（编码/磁盘/运行时）→ 再保证 Docker daemon 可达 → 最后是容器操作层（网络/端口/exec）。与 combo-mirror-setup（镜像配源）互补：那里解决「拉不下来」，这里解决「用不起来」。

组合成员 （2）

# 编码（问题：wsl-pipe-encoding）——现代 WSL 默认 UTF-8 管道，中文直传正常；
  # 旧版 / Windows PowerShell 5.1 出现逐字符空字节/乱码时，改为 Windows Terminal + WSL 内 UTF-8 区域设置：
  sudo locale-gen zh_CN.UTF-8 && sudo update-locale LANG=zh_CN.UTF-8
  # 磁盘（问题：wsl-no-space-left）——vhdx 稀疏化，删除文件自动还空间（WSL 2.4.4+）：
  #   Windows 侧（PowerShell）：wsl --shutdown
  #   wsl --manage <发行版> --set-sparse true
  # 运行时（问题：claude-code-router-2）——WSL 侧装 Node，别依赖 Windows 侧 npm：
  curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && sudo apt-get install -y nodejs

# daemon（问题：docker-daemon-connect）——"Cannot connect to the Docker daemon" 三板斧：
  #   1) Docker Desktop 已启动且开启 WSL 集成（Settings → Resources → WSL integration）
  #   2) 检查 socket：ls -l /mnt/wsl/docker-desktop/shared-sockets/guest-services/docker.proxy.sock
  #   3) 或本机直接跑 Engine：sudo systemctl enable --now docker

# 排查：占用者是不是 docker-proxy，daemon 是不是 /usr/bin/dockerd（旧 daemon 特征）
  ss -ltnp | grep <端口>
  systemctl status docker          # 确认旧 daemon 在自启
  # 处理：停掉并禁用 WSL 内旧 daemon（先确认其名下无在用容器再停）
  systemctl stop docker docker.socket
  systemctl disable docker docker.socket

方案总览

顺序逻辑：环境层 → daemon 层 → 操作层。WSL 基础不好，后面全白搭；daemon 不可达，容器操作层一条都验不了。

快速开始

一键脚本由本文档自动生成（渲染后位于 pages/combos/combo-docker-wsl-env.sh），逐条执行：

bash pages/combos/combo-docker-wsl-env.sh

• 配完你会得到：WSL 基础（编码/磁盘/Node）+ Docker daemon 可达 + 容器操作三条命令模板。
• 预计耗时：10-20 分钟（取决于 WSL 磁盘操作与 Node 安装）。
• 前置条件：Windows 侧 WSL >= 2.4.4（稀疏化命令需要）；Docker >= 20.10（本机实测 29.1.3）。
• 注意：WSL 重启命令会重启所有发行版（影响运行中进程）；daemon 修复可能需重启 Docker Desktop。

想弄明白每一步在干什么、修错了怎么恢复 → 看「逐步教学」。一键脚本出问题 → 按逐步教学手动执行定位。

逐步教学

第 1 步：WSL 基础（编码/磁盘/Node）

WSL 环境层三件事，先确认再往下：

• 乱码（wsl-pipe-encoding）：现代 WSL 默认 UTF-8 管道正常（本环境实测 Windows 侧调用 wsl 输出中文原样无乱码）；旧版 / Windows PowerShell 5.1 出逐字符空字节/乱码时，改 Windows Terminal + WSL 内 UTF-8 区域设置。
• 磁盘满（wsl-no-space-left）：vhdx 稀疏化——删除文件自动还空间（WSL 2.4.4+）。
• WSL 里找不到 node（claude-code-router-2）：npm 装自 Windows 侧，WSL 里 PATH 没有——WSL 侧装 Node。

  # 编码（问题：wsl-pipe-encoding）——现代 WSL 默认 UTF-8 管道，中文直传正常；
  # 旧版 / Windows PowerShell 5.1 出现逐字符空字节/乱码时，改为 Windows Terminal + WSL 内 UTF-8 区域设置：
  sudo locale-gen zh_CN.UTF-8 && sudo update-locale LANG=zh_CN.UTF-8
  # 磁盘（问题：wsl-no-space-left）——vhdx 稀疏化，删除文件自动还空间（WSL 2.4.4+）：
  #   Windows 侧（PowerShell）：wsl --shutdown
  #   wsl --manage <发行版> --set-sparse true
  # 运行时（问题：claude-code-router-2）——WSL 侧装 Node，别依赖 Windows 侧 npm：
  curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && sudo apt-get install -y nodejs
  

预期输出: WSL 侧 node --version 输出版本号（本环境实测 v22.22.1）

装好确认：

• WSL 内 node --version 正常（>= 18）；
• 中文输出无乱码；df -h / 有余量。

卡住怎么办：

• WSL 重启命令会重启所有发行版（影响运行中进程）→ 先保存工作再执行。
• 稀疏化与旧版 WSL 不兼容 → 先升级 WSL。
• Node 安装脚本慢 → 用 npmmirror 二进制镜像或 apt 源替换。

第 2 步：Docker daemon 可达

「Cannot connect to the Docker daemon」三板斧：① Docker Desktop 已启动且开启 WSL 集成（Settings → Resources → WSL integration）；② socket 存在；③ 或本机直接跑 Engine。本环境真实复现过此问题：docker info Server 段报 socket 不存在（Docker Desktop WSL 集成 socket 缺失）；解法需启动 Docker Desktop / 开 WSL 集成（用户环境操作，本环境未实测）。

  # daemon（问题：docker-daemon-connect）——"Cannot connect to the Docker daemon" 三板斧：
  #   1) Docker Desktop 已启动且开启 WSL 集成（Settings → Resources → WSL integration）
  #   2) 检查 socket：ls -l /mnt/wsl/docker-desktop/shared-sockets/guest-services/docker.proxy.sock
  #   3) 或本机直接跑 Engine：sudo systemctl enable --now docker
  

预期输出: docker info 输出 Server 段（含 Containers/Images 信息）

装好确认：

• docker info 有 Server 段（不只 Client 段）；
• docker ps 不再报连接错误。

卡住怎么办：

• socket 不存在 → 启动 Docker Desktop 并确认 WSL 集成开关；或改用 Engine（systemctl）。
• 权限错（/var/run/docker.sock）→ 用户加进 docker 组后重开终端（见下方命令块）。
• 端口被残留旧 dockerd 劫持（verified 2026-08-30，docker-port-already-allocated 变体）：容器内 curl 正常、容器外 localhost:3000 一律 403/连接拒绝，重启 Docker Desktop 依旧——不是容器问题，是 WSL 内残留旧 dockerd（Docker Desktop 升级前的 29.1.3，/usr/bin/dockerd）的 docker-proxy 长期占用 3000 端口，转发到已删除容器的死网络命名空间（杀容器不杀进程）。

  # 排查：占用者是不是 docker-proxy，daemon 是不是 /usr/bin/dockerd（旧 daemon 特征）
  ss -ltnp | grep <端口>
  systemctl status docker          # 确认旧 daemon 在自启
  # 处理：停掉并禁用 WSL 内旧 daemon（先确认其名下无在用容器再停）
  systemctl stop docker docker.socket
  systemctl disable docker docker.socket

预期输出: 占用端口进程消失；容器外 localhost:<端口> 直通 Docker Desktop 引擎容器（Windows/WSL 两侧均 200；2026-08-30 实测）

第 3 步：容器操作层（端口/TTY/宿主机访问）

daemon 可达后，容器操作层三条命令模板按报错逐条排：

# 端口冲突（问题：docker-port-already-allocated）——查占用 + 换端口：
  ss -ltnp | grep <端口>
  docker run -p <新端口>:80 ...
  # exec TTY（问题：docker-exec-tty）——需要交互终端用 -it，纯脚本用 -i（或去掉 -t）：
  docker exec -it <容器> bash      # 交互
  docker exec -i <容器> command    # 脚本/管道
  # 容器访问宿主机（问题：docker-host-access）——Docker 20.10+ 用 host-gateway：
  docker run --add-host=host.docker.internal:host-gateway ...
  

预期输出: 换端口后容器正常启动；exec 不再报 TTY 错；容器内能访问 host.docker.internal

装好确认：

• 端口冲突：查新端口干净 + 容器启动成功；
• TTY：交互/脚本两种形态分别正常；
• 宿主机访问：容器内 curl host.docker.internal:<端口> 通。

卡住怎么办：

• daemon 又不可达 → 回到第 2 步三板斧。
• host-gateway 不生效（Docker < 20.10）→ 升级 Docker；或用宿主机内网 IP 代替。

note: 本层三条未实测（需 daemon 可用后跑真实容器，当前环境 daemon 不可达）；命令为官方标准形态，待有可用环境补测。

装完验收（一步到位）

作用：配完跑下面一条命令块，全绿 = 本组合包就绪；某条失败 → 回「逐步教学」对应步骤定位。

node --version
docker info 2>&1 | grep -A2 '^Server:'
ss -ltnp | grep docker-proxy || echo '无 docker-proxy 残留劫持'
docker ps

预期输出: node >= 18；docker info 出 Server 段；无旧 dockerd docker-proxy 残留（有则走第 2 步劫持排查节）；docker ps 正常。环境层 → daemon 层 → 操作层逐层全绿 = 就绪

注：成员级已实测（WSL 侧 Node v22.22.1、daemon socket 缺失复现、端口劫持实测复现+修复 2026-08-30）；容器操作层命令需 daemon 可用后验证。

日常使用

启动与入口

• WSL：日常直接进发行版使用；编码/磁盘是静态配置。
• Docker：Docker Desktop 常驻或 systemctl 启动；docker info 随时自检。

常用操作

1. 环境自检一条龙：node --version（WSL 侧）+ docker info（Server 段）。
2. 端口冲突排查：查占用命令找占用 → 换端口或停占用者。
3. exec 进容器：交互/脚本两种形态（见第 3 步命令块）。

数据与目录

• WSL：发行版 vhdx 文件（Windows 侧用户数据目录下）。
• Docker：镜像/容器数据由 Docker 管理；daemon 配置 /etc/docker/daemon.json（与 combo-mirror-setup 共享，勿互相覆盖）。

卸载与清理

本组合包是配置与排查方案（WSL/Docker 为系统组件，不卸载）：

# 还原项（按需）：
# 编码：sudo update-locale LANG=C.UTF-8
# Node（WSL 侧）：sudo apt-get remove -y nodejs
# Docker 集成：Docker Desktop 设置里关闭 WSL integration（不卸载）

提示：vhdx 稀疏化后不要手动删 vhdx 文件（数据全在发行版里）。

安装顺序

1. WSL 基础先行：编码（乱码）与磁盘（vhdx 稀疏化）是环境层，先确认；WSL 侧 Node 先装好（npm 来自 Windows 侧是 ccr 等工具在 WSL 里找不到 node 的根因）。
2. Docker daemon 可达：socket 存在 + docker info 出 Server 段，才进入容器操作层。
3. 容器操作层：端口冲突 → exec TTY → 容器访问宿主机，按报错顺序逐条排。

依赖警告

• 冲突：WSL（发行版配置/Windows 侧）与 Docker（daemon/socket）配置面独立，无共享写面 → compatible；与 combo-mirror-setup（daemon.json 镜像）共享 daemon.json 一个文件——先配源再排查，或合并编辑，不要互相覆盖（possible-compatible，构造性判定）。
• 版本：WSL >= 2.4.4（稀疏化）；Docker >= 20.10（host-gateway / registry-mirrors）；Node >= 18（WSL 侧，ccr 运行前提）。
• 环境：WSL 重启命令会重启所有发行版（影响运行中进程）；稀疏化与旧版 WSL 不兼容；daemon 相关修复可能需要重启 Docker Desktop（影响运行中容器）；权限类：systemctl 需 sudo。
• 国内网络：镜像配源见 combo-mirror-setup（docker-hub-pull-fail 已挂那包）；Node 安装脚本走 nodesource 官方，慢时用 npmmirror 二进制镜像或 apt 源替换。

FAQ

1. docker info 只有 Client 段没有 Server 段？ → daemon 不可达，走「第 2 步三板斧」：Docker Desktop 启动 + WSL 集成开启 + socket 检查（本环境真实复现过 socket 缺失）。
2. WSL 里 node: not found 但 Windows 有 node？ → 根因是 npm/node 装自 Windows 侧；在 WSL 侧重装 Node（第 1 步），问题即消失（本环境反证实测）。
3. exec 报 TTY 错？ → 交互用 -it，脚本/管道用 -i（去掉 -t）。
4. 端口冲突怎么办？ → 查占用命令找占用 → 换映射端口。
5. 这套排查实测过吗？ → 部分实测：daemon 问题真实复现（socket 缺失）、乱码场景本环境正常、WSL 侧 Node 反证实测、端口劫持实测复现+修复（2026-08-30）、稀疏化与容器操作层未实测（需用户环境操作/daemon 可用）。
6. 容器内 curl 通、容器外 localhost:3000 全 403/拒连，重启 Docker Desktop 也没用？ → WSL 内残留旧 dockerd 的 docker-proxy 劫持端口（2026-08-30 实测复现+修复）：ss -ltnp 看占用者是否为 /usr/bin/dockerd 的 docker-proxy，是则 systemctl stop/disable docker docker.socket。

验证证据

每份组合包在隔离环境实测（冒烟 + 写面检查），未实测项在文中如实标注；实测日期见下方验证证据。

验证于 2026-08-29 · TTL 到期 —（180 天）

2026-08-29 实测（WSL Ubuntu + Docker 29.1.3）：

• docker-daemon-connect：本环境真实复现——docker info Server 段报 socket 连接失败（Docker Desktop WSL 集成 socket 不存在）。解法未实测（需启动 Docker Desktop / 开启 WSL 集成，属用户环境操作，红线不碰）。
• wsl-pipe-encoding：本环境实测正常——Windows 侧调用 wsl 输出中文原样无乱码（现代 WSL 默认 UTF-8 管道）；乱码场景为旧版 WSL / Windows PowerShell 5.1，解法给出未实测。
• wsl-no-space-left：本环境无复现（df -h / 766G 可用）；稀疏化未实测（需 WSL 重启，红线禁止）。
• claude-code-router-2：本环境 WSL 侧 /usr/bin/node v22.22.1 实测存在——「WSL 里 node: not found」的根因（npm 装自 Windows 侧）在此环境不成立，反证解法：WSL 侧装 Node 后问题消失。
• docker 端口劫持（verified 2026-08-30）：WSL 残留旧 dockerd（29.1.3，/usr/bin/dockerd）docker-proxy 长期占用 3000 端口转发到已删除容器死命名空间——容器内通、容器外 403/拒连；stop+disable 旧 daemon 后 localhost:3000 直通 Docker Desktop 引擎（Windows/WSL 两侧均 200）。证据 实测复现日志（2026-08-30） 第 0 节。
• docker-exec-tty / docker-port-already-allocated / docker-host-access：未实测（需 daemon 可用后跑真实容器，daemon 当前不可达）。

关联问题

• docker-desktop-orphan-socket
• docker-daemon-connect
• wsl-no-space-left