WSL 2 调用宿主机 Docker 配置私有证书

发表于 更新于

在 Windows 开发环境中，WSL 2（Windows Subsystem for Linux 2）与 Docker Desktop 的组合已成为开发者的主流选择——既可以享受 Linux 终端的便捷性，又能依托宿主机 Docker 服务实现容器化开发。但在实际使用中，当需要访问私有镜像仓库或启用宿主机 Docker TLS 验证时，常出现 tls: failed to verify certificate: x509: certificate signed by unknown authority 证书信任错误。本文将详细讲解如何在 WSL 2 中配置私有证书，让 WSL 客户端顺利信任宿主机 Docker 服务端或私有镜像仓库，彻底解决证书验证问题。

一、前置条件：确保 WSL 2 与宿主机 Docker 正常连通

在配置私有证书前，需先确认 WSL 2 能正常调用宿主机 Docker 服务，这是后续证书配置的基础，步骤如下：

  1. 验证 WSL 版本：在 Windows 终端执行 wsl -l -v，确保目标 Linux 发行版（如 Ubuntu）的 VERSION 为 2；若为 1，需执行 wsl --set-version <发行版名称> 2 升级。

  2. 启用 Docker Desktop WSL 集成：打开宿主机 Docker Desktop，进入 Settings → General，勾选 Use the WSL 2 based engine；再进入 Settings → Resources → WSL Integration，启用目标 WSL 发行版的集成功能，点击 Apply & Restart 重启 Docker。

  3. WSL 端安装 Docker 客户端：进入 WSL 终端，执行 sudo apt update && sudo apt install docker.io -y，无需单独启动 Docker 守护进程（daemon），因为 WSL 会复用宿主机 Docker 服务。

  4. 测试连通性：在 WSL 终端执行 docker -H tcp://localhost:2375 ps，若能正常返回宿主机 Docker 容器列表，说明 WSL 与宿主机 Docker 已连通；若提示连接失败，需检查 Docker Desktop 集成配置或 Windows 防火墙是否放行 2375 端口。

注意：WSL 2 访问宿主机文件系统时，推荐使用路径 /run/desktop/mnt/host/c/（替代传统 /mnt/c/），可避免路径访问权限或同步问题，这也是后续证书拷贝的关键路径格式。

二、核心场景：WSL 配置私有证书的两种常用场景

WSL 中调用宿主机 Docker 时，证书信任需求主要分为两种场景：一是信任宿主机 Docker 服务端的 TLS 证书（双向认证场景），二是信任私有镜像仓库（如 Harbor、GitLab Registry）的私有 CA 证书。以下分别给出详细配置步骤，覆盖大多数开发场景。

场景一：WSL 信任宿主机 Docker 服务端证书（mTLS 双向认证）

若宿主机 Docker 启用了 TLS 验证（即通过 --tlsverify 参数启动），WSL 客户端需配置对应的 CA 证书、客户端证书及密钥，才能通过双向认证（mTLS）与宿主机 Docker 服务端通信。

步骤 1：获取宿主机 Docker TLS 证书

宿主机 Docker 的 TLS 证书默认存储在 C:\Users\<你的 Windows 用户名>\.docker\ 目录下，核心文件包括：

  • ca.pem：根 CA 证书（用于验证服务端证书合法性）；

  • cert.pem、key.pem：宿主机 Docker 服务端证书及密钥；

  • client-cert.pem、client-key.pem：客户端证书及密钥（双向认证必需）。

若该目录下无相关证书，需先在宿主机配置 Docker TLS 验证，生成对应证书文件（可参考 Docker 官方文档或联系运维人员获取）。

步骤 2：在 WSL 中创建证书目录

WSL 中 Docker 客户端会从 ~/.docker/certs.d/<宿主机 Docker 地址>:<端口>/ 目录读取证书，需先创建该目录，格式如下：

1
2
# 示例：宿主机 Docker 地址为 192.168.1.100，TLS 端口为 2376（默认 TLS 端口）
mkdir -p ~/.docker/certs.d/192.168.1.100:2376

说明：宿主机 Docker 启用 TLS 后，默认端口为 2376，而非非 TLS 模式的 2375，需确认端口对应正确。

步骤 3：拷贝宿主机证书到 WSL 目录

通过 WSL 访问宿主机证书目录，将所需证书拷贝到上述创建的 WSL 证书目录中，命令如下：

1
2
3
4
5
6
# 拷贝根 CA 证书（必选）
cp /run/desktop/mnt/host/c/Users/<Windows用户名>/.docker/ca.pem ~/.docker/certs.d/192.168.1.100:2376/ca.crt

# 拷贝客户端证书与密钥（双向认证必选）
cp /run/desktop/mnt/host/c/Users/<Windows用户名>/.docker/client-cert.pem ~/.docker/certs.d/192.168.1.100:2376/client.crt
cp /run/desktop/mnt/host/c/Users/<Windows用户名>/.docker/client-key.pem ~/.docker/certs.d/192.168.1.100:2376/client.key

注意：将命令中的 <Windows用户名> 和宿主机 Docker 地址、端口替换为实际信息，若路径错误会导致证书无法被识别。

步骤 4：配置 WSL 环境变量（永久生效）

需在 WSL 中配置环境变量，指定宿主机 Docker 地址、启用 TLS 验证，并指向证书目录，确保每次启动 WSL 终端都能生效。

  1. 编辑环境变量配置文件（根据所使用的 Shell 选择，如 bash 对应 ~/.bashrc，zsh 对应 ~/.zshrc）：
    vim ~/.bashrc

  2. 在文件末尾添加以下配置：
    `# 指向宿主机 Docker 服务地址（TLS 端口 2376）

export DOCKER_HOST=tcp://192.168.1.100:2376

启用 TLS 验证

export DOCKER_TLS_VERIFY=1

指向 WSL 本地证书目录

export DOCKER_CERT_PATH=~/.docker/certs.d/192.168.1.100:2376`

  1. 使配置生效：
    source ~/.bashrc

步骤 5：验证配置

在 WSL 终端执行 docker ps，若能正常返回宿主机 Docker 容器列表，无证书验证错误，说明配置成功；若仍报错，需检查证书路径、环境变量或宿主机 Docker TLS 配置是否正确。

场景二：WSL 信任私有镜像仓库证书

若仅需在 WSL 中通过宿主机 Docker 访问私有镜像仓库（如公司内网 Harbor、自建 GitLab Registry），无需配置宿主机 Docker TLS 验证，只需让 WSL Docker 客户端信任私有仓库的 CA 证书即可，该场景更常见于日常开发。

步骤 1：获取私有仓库 CA 证书

私有仓库的 CA 证书（通常为 ca.crt 或 ca.pem）可从宿主机获取——宿主机 Docker 若已配置信任该私有仓库，证书通常存储在 C:\Users\<Windows用户名>\.docker\certs.d\<仓库域名>:<端口>/ 目录下；若未配置，需联系运维人员获取私有仓库的 CA 证书。

步骤 2：在 WSL 中创建仓库证书目录

与场景一类似，WSL Docker 客户端会根据私有仓库的域名和端口查找证书，需创建对应目录：

1
2
# 示例：私有仓库地址为 registry.example.com，端口为 443（默认 HTTPS 端口）
mkdir -p ~/.docker/certs.d/registry.example.com:443

步骤 3：拷贝 CA 证书到 WSL 目录

将宿主机的私有仓库 CA 证书拷贝到 WSL 对应的证书目录中，命令如下：

1
cp /run/desktop/mnt/host/c/Users/<Windows用户名>/.docker/certs.d/registry.example.com:443/ca.crt ~/.docker/certs.d/registry.example.com:443/

补充：若私有仓库使用自签名证书，且宿主机未配置，可直接将自签名证书拷贝到上述目录，无需额外配置。

步骤 4：验证配置

在 WSL 终端执行 docker login registry.example.com，输入私有仓库的账号密码，若能成功登录，说明证书配置生效；登录成功后，即可正常拉取、推送私有镜像，不再出现 x509 证书错误。

三、常见问题与快速修复方案

配置过程中，可能会遇到证书识别失败、连接超时等问题，以下是高频问题及解决方案，覆盖大部分异常场景：

问题 1：配置后仍报 x509: certificate signed by unknown authority

核心原因：证书路径错误、证书文件损坏，或 WSL 系统未信任该 CA 证书。

解决方案：

  • 检查证书路径是否正确，确保 ca.crt 位于 ~/.docker/certs.d/<地址:端口>/ 目录下，且文件名正确（必须为 ca.crt）；

  • 重启 WSL 终端，或执行 wsl --shutdown 关闭 WSL 后重新进入，刷新证书缓存；

  • 手动更新 WSL 系统证书（可选）：
    sudo cp ~/.docker/certs.d/**/ca.crt /usr/local/share/ca-certificates/ sudo update-ca-certificates
    执行后会提示证书更新信息，忽略“ca-certificates.crt does not contain exactly one certificate”警告，不影响生效。

问题 2：WSL 无法访问宿主机证书路径（权限不足或路径错误）

核心原因：使用了错误的宿主机路径，或 WSL 对宿主机文件系统访问权限不足。

解决方案：

  • 优先使用 /run/desktop/mnt/host/c/ 路径访问 Windows C 盘，替代 /mnt/c/，避免 WSL 2 路径挂载异常；

  • 若提示权限不足，执行 sudo chmod 755 ~/.docker/certs.d/，赋予证书目录可读权限；

  • 确认宿主机证书文件未被隐藏，且 Windows 文件夹共享权限已开启。

问题 3：Docker Desktop 证书自动同步后仍无法生效

核心原因：Docker Desktop 会自动将 Windows ~/.docker/certs.d 同步到 WSL 的 /etc/docker/certs.d，但可能存在同步延迟或权限问题。

解决方案：手动拷贝证书到 WSL 的 ~/.docker/certs.d 目录（按本文场景步骤操作），而非依赖自动同步；同步后重启 Docker Desktop 和 WSL，确保证书生效。

问题 4：WSL 执行 docker 命令提示 connection refused

核心原因：宿主机 Docker 未启动、WSL 集成未启用，或环境变量配置错误。

解决方案：

  • 确认宿主机 Docker Desktop 已启动，且 WSL 集成功能已启用；

  • 检查DOCKER_HOST 环境变量，确保地址和端口与宿主机 Docker 一致；

  • 执行 unset DOCKER_HOST 清除错误环境变量，重新配置后生效。

四、总结与最佳实践

WSL 2 调用宿主机 Docker 配置私有证书，核心是让 WSL Docker 客户端能够识别并信任 CA 证书，不同场景对应不同的配置逻辑，可总结如下：

应用场景 核心操作 关键文件/环境变量
信任宿主机 Docker 服务端（mTLS） 配置客户端证书目录 + 环境变量，启用 TLS 验证 DOCKER_HOST、DOCKER_TLS_VERIFY、DOCKER_CERT_PATH；ca.crt、client.crt、client.key
信任私有镜像仓库 将仓库 CA 证书放入对应域名/端口的证书目录 仓库域名专属目录下的 ca.crt

最佳实践建议

  1. 开发环境优先使用“场景二”配置：若无需宿主机 Docker TLS 验证，仅配置私有仓库证书即可，操作更简洁，避免不必要的复杂配置；

  2. 生产环境推荐“场景一”配置：启用 TLS 双向认证，提升宿主机 Docker 服务的安全性，防止未授权访问；

  3. 证书管理：将私有证书统一存储在宿主机固定目录，WSL 按需拷贝，避免重复创建证书，便于后续维护和更新；

  4. 异常排查：遇到证书问题时，优先检查证书路径、文件名和环境变量，再尝试重启 WSL 和 Docker Desktop，大部分问题可快速解决。

通过本文的配置步骤，可彻底解决 WSL 2 调用宿主机 Docker 时的私有证书信任问题，实现 WSL 与宿主机 Docker 的无缝协同，提升容器化开发效率。若遇到特殊场景（如多仓库证书配置、代理环境下的证书问题），可根据实际需求调整证书目录和配置参数。