agent combo: 容器与 WSL 环境成套配置与排查

Metadata

id	`combo-docker-wsl-env`	recorded	2026-08-29
members	2	status	partial

install script ↓

Members (2)

tool role version install guide

tool	role	version	install	guide
`WSL`	基础环境配置目标	`WSL >= 2.4.4（wsl --manage <发行版> --set-sparse true 需要 2.4.4+，WSL 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	—
`Docker Engine`	容器运行时配置目标	`>= 20.10（registry-mirrors / host-gateway 长期支持；本机实测 29.1.3）`	`# 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`	—

WSL

基础环境配置目标

WSL >= 2.4.4（wsl --manage <发行版> --set-sparse true 需要 2.4.4+，WSL 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

—

Docker Engine

容器运行时配置目标

>= 20.10（registry-mirrors / host-gateway 长期支持；本机实测 29.1.3）

# 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

—

Install order

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

Dependency warnings

冲突：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 源替换。

Linked problems

Evidence

Evidence details kept locally (2026-08-29)