docs(docker-management): 补充 WSL 网络代理诊断

Author: mudssky

ai/skills/dev/docker-management/SKILL.md

@@ -26,11 +26,16 @@ description: 管理 Docker 运行方案的选型、配置、迁移与日常运
 - 选型对比：读 `references/runtime-options.md`。
 - Windows 安装、方案 C 配置、Docker Desktop 迁移：读 `references/platforms/windows.md`。
 - WSL2 `.wslconfig` / `/etc/wsl.conf` 模板：读 `references/wsl2-config-templates.md`。
+- WSL2 mirrored / NAT 网络代理、Docker daemon 拉取代理排障：读 `references/wsl-network-proxy.md`。
 - 迁移策略、要不要备份、备份/恢复命令：读 `references/migration-strategy.md`。
 - 日常运维：读 `references/daily-ops.md`。
 - 命令与 compose 工作流：读 `references/commands.md`。
 - 故障排查：读 `references/troubleshooting.md`。
 
+## 可复用脚本
+
+- WSL2 Docker 代理诊断：优先运行 `scripts/Test-WslDockerProxy.ps1`，再根据输出决定是否修改 daemon proxy、代理软件监听或防火墙。
+
 ## 安全护栏
 
 迁移、卸载 Docker Desktop、删除容器、清理卷、执行 `prune`、注销 WSL 发行版、覆盖 `.wslconfig` / `/etc/wsl.conf` 都是高风险操作。执行前先确认：

ai/skills/dev/docker-management/references/daily-ops.md

@@ -113,6 +113,8 @@ docker volume prune
 
 代理分三层处理：当前 shell、Docker daemon 拉取镜像、新建容器运行环境。不要假设项目内存在代理脚本；直接写入对应层的标准配置。
 
+Windows + WSL2 的 mirrored / NAT 代理地址选择、`host.docker.internal`、`/etc/resolv.conf` 和 `docker pull unexpected EOF` 排查见 `wsl-network-proxy.md`。
+
 当前 shell 临时代理：
 
 ```bash
@@ -169,7 +171,7 @@ cat >~/.docker/config.json <<'EOF'
 EOF
 ```
 
-在 WSL mirrored 网络中，优先使用 `127.0.0.1:<port>` 或显式 `PROXY_DEFAULT_HOST/PORT`，不要再依赖解析 `/etc/resolv.conf` 的旧 NAT 主机 IP 方案。
+在 WSL mirrored 网络中，优先使用 `127.0.0.1:<port>` 或 `host.docker.internal:<port>`，不要写死局域网 IP。只有回退到 NAT 模式时，才使用 `/etc/resolv.conf` 的 `nameserver` 地址。
 
 ## 数据卷习惯
 

ai/skills/dev/docker-management/references/platforms/windows.md

@@ -132,7 +132,7 @@ volumes:
 
 ### 5. 代理与端口策略
 
-代理配置不要依赖某个项目里的脚本。需要代理时，直接按当前环境写入 shell 环境变量、Docker daemon systemd drop-in 或 Docker CLI 容器代理配置。
+代理配置不要依赖某个项目里的脚本。需要代理时，直接按当前环境写入 shell 环境变量、Docker daemon systemd drop-in 或 Docker CLI 容器代理配置。WSL2 mirrored / NAT 的代理地址选择和排障细节见 `../wsl-network-proxy.md`。
 
 当前 shell 临时代理：
 
@@ -174,7 +174,7 @@ cat >~/.docker/config.json <<'EOF'
 EOF
 ```
 
-WSL mirrored 网络中，优先使用 `127.0.0.1:<port>` 访问 Windows 侧代理。旧式解析 `/etc/resolv.conf` nameserver 的代理脚本只适合早期 NAT 模式，不再作为默认方案。
+WSL mirrored 网络中，优先使用 `127.0.0.1:<port>` 或 `host.docker.internal:<port>` 访问 Windows 侧代理。旧式解析 `/etc/resolv.conf` nameserver 的代理脚本只适合 NAT 模式，不再作为默认方案。
 
 本机开发服务默认把端口绑定到 `127.0.0.1`：
 

ai/skills/dev/docker-management/references/troubleshooting.md

@@ -52,6 +52,7 @@ systemctl show --property=Environment docker
 - 当前 shell 需要代理时执行 `proxy on`。
 - Docker daemon 拉取需要代理时执行 `proxy docker on`，该命令会重启 Docker。
 - 新建容器内部需要代理时执行 `proxy container on`。
+- Windows + WSL2 场景先按 `wsl-network-proxy.md` 区分 mirrored / NAT、shell 代理和 Docker daemon 代理。`curl -x ...` 能通不代表 `docker pull` 已经走代理。
 
 ## 端口无法访问或被占用
 
@@ -141,3 +142,4 @@ autoProxy=true
 - 修改 `.wslconfig` 后必须 `wsl --shutdown`。
 - mirrored 模式对入站访问可能需要 Hyper-V 防火墙规则。
 - 只做本机开发时，不要为了局域网访问放宽防火墙；优先保持容器端口绑定到 `127.0.0.1`。
+- 代理问题优先测试 `127.0.0.1:<port>` 和 `host.docker.internal:<port>`；只有 NAT 模式才使用 `/etc/resolv.conf` 的 `nameserver` 地址。完整流程见 `wsl-network-proxy.md`。

ai/skills/dev/docker-management/references/wsl-network-proxy.md

@@ -0,0 +1,188 @@
+# WSL2 网络与代理
+
+## 目录
+
+- [推荐判断](#推荐判断)
+- [Mirrored 模式](#mirrored-模式)
+- [NAT 模式](#nat-模式)
+- [Docker daemon 代理](#docker-daemon-代理)
+- [排查命令](#排查命令)
+- [常见结论](#常见结论)
+
+## 推荐判断
+
+优先使用新版 WSL 的 mirrored 网络；不能使用或行为异常时，再回退到 NAT 模式的 Windows 宿主机地址。
+
+| 场景 | 代理地址优先级 | 说明 |
+|---|---|---|
+| mirrored 网络 | `127.0.0.1:<port>`，其次 `host.docker.internal:<port>` | 不写死局域网 IP；换 Wi-Fi、路由器或 VPN 时更稳 |
+| NAT 网络 | `/etc/resolv.conf` 里的 `nameserver:<port>` | 该地址通常是 WSL 访问 Windows 宿主机的网关 |
+| Docker daemon 拉取镜像 | 写 systemd drop-in，不只写 shell env | `docker pull` 由 dockerd 发起，不继承普通 shell 的临时代理 |
+| 容器内访问外网 | 写 `~/.docker/config.json` 或 compose `environment` | 只影响新建容器，不影响 daemon 拉镜像 |
+
+Windows 代理软件必须真实监听 WSL 可达地址。若只监听 `127.0.0.1`，mirrored 下通常可用；NAT 下通常需要开启 `Allow LAN` / `允许局域网连接`，并确认 Windows 防火墙允许专用网络入站。
+
+## Mirrored 模式
+
+确认 WSL 版本和配置：
+
+```powershell
+wsl --version
+wsl --status
+Get-Content "$env:USERPROFILE\.wslconfig"
+```
+
+推荐 `.wslconfig` 关键项：
+
+```ini
+[wsl2]
+networkingMode=mirrored
+dnsTunneling=true
+autoProxy=true
+firewall=true
+localhostForwarding=true
+```
+
+修改后必须重启 WSL：
+
+```powershell
+wsl --shutdown
+```
+
+代理测试：
+
+```bash
+curl -x http://127.0.0.1:7890 https://registry-1.docker.io/v2/ -I
+curl -x http://host.docker.internal:7890 https://registry-1.docker.io/v2/ -I
+```
+
+`HTTP/2 401` 或 `401 Unauthorized` 是 Docker Registry 未带 token 时的正常探活结果，说明代理链路能访问 registry。
+
+`autoProxy=true` 依赖 Windows 系统代理配置；代理软件开着但 Windows 系统代理关闭时，WSL 不一定会自动注入 `HTTP_PROXY` / `HTTPS_PROXY`。
+
+## NAT 模式
+
+传统 NAT 模式中，WSL 内的 `127.0.0.1` 是 WSL 自己，不是 Windows。通过 `/etc/resolv.conf` 获取 Windows 宿主机地址：
+
+```bash
+WIN_HOST="$(awk '/nameserver/ {print $2; exit}' /etc/resolv.conf)"
+echo "$WIN_HOST"
+curl -x "http://${WIN_HOST}:7890" https://registry-1.docker.io/v2/ -I
+```
+
+NAT 模式通常要求代理软件开启：
+
+```yaml
+allow-lan: true
+bind-address: "*"
+mixed-port: 7890
+```
+
+不同代理软件名称不同，重点是代理端口要监听 Windows 的非 loopback 地址，且防火墙允许 WSL 访问。
+
+## Docker daemon 代理
+
+当前 shell 的代理只影响当前进程：
+
+```bash
+export http_proxy="http://127.0.0.1:7890"
+export https_proxy="$http_proxy"
+export HTTP_PROXY="$http_proxy"
+export HTTPS_PROXY="$http_proxy"
+```
+
+Docker daemon 拉取镜像必须写 systemd drop-in：
+
+```bash
+sudo mkdir -p /etc/systemd/system/docker.service.d
+sudo tee /etc/systemd/system/docker.service.d/http-proxy.conf >/dev/null <<'EOF'
+[Service]
+Environment="HTTP_PROXY=http://127.0.0.1:7890"
+Environment="HTTPS_PROXY=http://127.0.0.1:7890"
+Environment="NO_PROXY=localhost,127.0.0.1,::1,192.168.0.0/16,10.0.0.0/8,172.16.0.0/12,.ts.net,100.64.0.0/10"
+EOF
+sudo systemctl daemon-reload
+sudo systemctl restart docker
+```
+
+验证 daemon 是否读到代理：
+
+```bash
+systemctl show --property=Environment docker
+docker info | sed -n '/HTTP Proxy/,+4p'
+docker pull hello-world:latest
+```
+
+若 mirrored 模式下 `127.0.0.1` 不通但 `host.docker.internal` 通，可以把 drop-in 中的代理地址改成 `http://host.docker.internal:<port>`。不要写死 `192.168.x.x`，除非只是临时排障。
+
+新建容器默认代理写入 Docker CLI 配置：
+
+```bash
+mkdir -p ~/.docker
+cat >~/.docker/config.json <<'EOF'
+{
+  "proxies": {
+    "default": {
+      "httpProxy": "http://127.0.0.1:7890",
+      "httpsProxy": "http://127.0.0.1:7890",
+      "noProxy": "localhost,127.0.0.1,::1"
+    }
+  }
+}
+EOF
+```
+
+这只影响之后创建的容器，不会修复 `docker pull`。
+
+## 排查命令
+
+优先使用 skill 自带脚本，避免 PowerShell 与 bash 嵌套引号导致误判：
+
+```powershell
+.\scripts\Test-WslDockerProxy.ps1 -Distro Ubuntu -HttpPort 7890
+.\scripts\Test-WslDockerProxy.ps1 -Distro Ubuntu -HttpPort 7890 -TestDockerPull
+```
+
+脚本默认只诊断，不修改配置。`-TestDockerPull` 会额外执行 `docker pull hello-world:latest` 和 `docker run --rm hello-world`。
+
+Windows 侧检查代理监听地址：
+
+```powershell
+Get-NetTCPConnection -LocalPort 7890 -ErrorAction SilentlyContinue |
+  Select-Object LocalAddress,LocalPort,State,OwningProcess
+```
+
+WSL 侧检查名称解析和端口：
+
+```bash
+getent hosts host.docker.internal || true
+for hp in 127.0.0.1:7890 host.docker.internal:7890; do
+  h="${hp%:*}"
+  p="${hp##*:}"
+  printf '%s ' "$hp"
+  timeout 3 bash -lc "</dev/tcp/$h/$p" >/dev/null 2>&1 && echo ok || echo fail
+done
+```
+
+区分 shell 代理和 daemon 代理：
+
+```bash
+env | grep -i proxy
+systemctl show --property=Environment docker
+docker info | sed -n '/HTTP Proxy/,+4p'
+```
+
+查看 Docker 拉取错误：
+
+```bash
+docker --debug pull hello-world:latest
+journalctl -u docker --since '10 minutes ago' --no-pager -l
+```
+
+## 常见结论
+
+- `curl -x ... https://registry-1.docker.io/v2/` 能返回 401，只说明当前 shell 代理可用；`docker pull` 仍需要 daemon 代理。
+- `docker info` 显示了 HTTP Proxy，但仍出现 `unexpected EOF`，通常是代理软件、规则、TLS 中间链路或 Registry 规则问题；继续用 `journalctl -u docker` 和代理客户端日志定位。
+- mirrored 模式下可能出现 `localhostForwarding ignored` 提示，这是因为 mirrored 网络已有自己的 localhost 行为，不代表代理一定不可用。
+- `external-controller` 不是代理端口，不要把它写进 `HTTP_PROXY`。
+- 本机开发默认避免把数据库、Portainer 等服务暴露到局域网；端口绑定优先使用 `127.0.0.1:hostPort:containerPort`。