WSL 2 上的 Docker 远程容器入门

本分步指南将帮助你开始使用远程容器进行开发,方法是 使用 WSL 2 设置适用于 Windows 的 Docker Desktop (适用于 Linux 的 Windows 子系统,版本 2)。

适用于 Windows 的 Docker Desktop 提供用于生成、传送和运行 dockerized 应用的开发环境。 通过启用基于 WSL 2 的引擎,可以在同一台计算机上运行 Docker Desktop 中的 Linux 和 Windows 容器。 (Docker Desktop 免费供个人使用,小型企业,有关 Pro、Team 或 Business 定价的信息,请参阅 Docker 站点常见问题解答)。

注释

建议使用 Docker Desktop,因为它 与适用于 Linux 的 Windows 和 Windows 子系统集成。 但是,虽然 Docker Desktop 支持同时运行 Linux 和 Windows 容器,但 不能 同时运行这两个容器。 若要同时运行 Linux 和 Windows 容器,需要在 WSL 中安装和运行单独的 Docker 实例。 如果需要同时运行容器,或者只想直接在 Linux 分发版中安装容器引擎,请遵循该容器服务的 Linux 安装说明,例如在 Ubuntu 上安装 Docker 引擎安装 Podman 以运行 Linux 容器

Docker 容器概述

Docker 是一种工具,用于使用容器创建、部署和运行应用程序。 使用容器,开发人员可以使用它所需的所有部件(库、框架、依赖项等)打包应用,并将其作为一个包交付。 使用容器可确保无论运行应用的任何自定义设置或以前安装的库都运行相同,而该库可能与用于编写和测试应用代码的计算机不同。 这样,开发人员就可以专注于编写代码,而无需担心代码将运行的系统。

Docker 容器类似于虚拟机,但不创建整个虚拟作系统。 相反,Docker 使应用能够使用与运行它的系统相同的 Linux 内核。 这允许应用包仅下载主计算机上尚未存在的部件,减少包大小并提高性能。

容器能够保持持续可用性的一个重要原因是通过使用 Docker 容器与 Kubernetes 这样的工具配合使用。 这样,就可以在不同时间创建应用容器的多个版本。 无需关闭整个系统进行更新或维护,而是可以即时替换每个容器(及其特定的微服务)。 可以使用所有的更新内容准备新容器,为生产环境配置容器,并在容器准备就绪后只需指向新的容器。 还可以使用容器存档您的应用的不同版本,并根据需要将其作为安全的备份回退运行。

若要了解详细信息,请查看 Docker 容器简介

先决条件

  • WSL 版本 1.1.3.0 或更高版本。
  • Windows 11 64 位:家庭版或专业版 21H2 或更高版本,或企业版或教育版 21H2 或更高版本。
  • Windows 10 64 位(推荐):家庭版或专业版 22H2(内部版本 19045)或更高版本,或者企业版或教育版 22H2(内部版本 19045)或更高版本。 (最低):家庭版或专业版 21H2(内部版本 19044)或更高版本,或企业版或教育版 21H2(内部版本 19044)或更高版本。 更新 Windows
  • 具有 二级地址转换(SLAT)的 64 位处理器。
  • 4GB 系统 RAM。
  • 在 BIOS 中启用硬件虚拟化。
  • 安装 WSL 并为在 WSL 2 中运行的 Linux 分发设置用户名和密码
  • 安装 Visual Studio Code(可选)。 这将提供最佳体验,包括能够在远程 Docker 容器内编码和调试并连接到 Linux 分发版。
  • 安装 Windows 终端(可选)。 这将提供最佳体验,包括在同一接口中自定义和打开多个终端(包括 Ubuntu、Debian、PowerShell、Azure CLI 或喜欢使用的任何终端)。
  • 在 Docker 中心注册 Docker ID(可选)。
  • 有关使用条款的更新,请参阅 Docker Desktop 许可协议

有关详细信息,请参阅 在 Windows 上安装 Docker Desktop 的 Docker 文档系统要求

若要了解如何在 Windows Server 上安装 Docker,请参阅 入门:为容器准备 Windows

注释

WSL 可以在 WSL 版本 1 或 WSL 2 模式下运行分发版。 可以通过打开 PowerShell 并输入: wsl -l -v来检查此项。 确保你的发行版设置为使用 WSL 2,然后输入:wsl --set-version <distro> 2。 替换为 <distro> 发行版名称(例如 Ubuntu 18.04)。

在 WSL 版本 1 中,由于 Windows 和 Linux 之间存在根本差异,Docker 引擎无法直接在 WSL 内部运行,因此 Docker 团队使用 Hyper-V VM 和 LinuxKit 开发了替代解决方案。 但是,由于 WSL 2 现在在具有完整系统调用容量的 Linux 内核上运行,因此 Docker 可以在 WSL 2 中完全运行。 这意味着 Linux 容器可以在不仿真的情况下本机运行,从而提高 Windows 和 Linux 工具之间的性能和互作性。

安装 Docker Desktop

使用适用于 Windows 的 Docker Desktop 支持的 WSL 2 后端,可以在基于 Linux 的开发环境中工作并生成基于 Linux 的容器,同时使用 Visual Studio Code 进行代码编辑和调试,并在 Windows 上的 Microsoft Edge 浏览器中运行容器。

若要安装 Docker(安装 WSL 后):

  1. 下载 Docker Desktop 并按照安装说明进行作。

  2. 安装后,从 Windows“开始”菜单启动 Docker Desktop,然后从任务栏的隐藏图标菜单中选择 Docker 图标。 右键单击图标以显示 Docker 命令菜单,然后选择“设置”。 Docker Desktop 仪表板图标

  3. 确保在“设置>”中选中“使用基于 WSL 2 的引擎”。 Docker Desktop 常规设置

  4. 通过转到 “设置>资源>WSL 集成”,从要启用 Docker 集成的已安装 WSL 2 分发版中进行选择。 Docker Desktop 资源设置

  5. 要确认 Docker 是否已安装,请打开 WSL 发行版(如 Ubuntu),并输入以下命令以显示版本及内部版本号:docker --version

  6. 使用以下方法测试安装是否正常工作:运行简单的内置 Docker 映像: docker run hello-world

小窍门

下面是一些有用的 Docker 命令,需要了解:

  • 通过输入以下命令列出 Docker CLI 中可用的命令: docker
  • 使用以下命令列出特定命令的信息: docker <COMMAND> --help
  • 列出您计算机上的 Docker 镜像(此时仅有 hello-world 镜像):docker image ls --all
  • 列出计算机上的容器,其中包含: docker container ls --alldocker ps -a (如果没有 -a 显示所有标志,将仅显示正在运行的容器)
  • 列出有关 Docker 安装的系统范围信息,包括 WSL 2 上下文中可用的资源(CPU 和内存)和统计信息,以及: docker info

使用 VS Code 在远程容器中开发

若要开始使用 Docker 和 WSL 2 开发应用,我们建议使用 VS Code 以及 WSL、开发容器和 Docker 扩展。

  • 安装 VS Code WSL 扩展。 此扩展使你能够打开在 VS Code 中的 WSL 上运行的 Linux 项目(无需担心路径问题、二进制兼容性或其他跨 OS 挑战)。

  • 安装 VS Code 开发容器扩展。 通过此扩展,可以在容器内打开项目文件夹或存储库,利用 Visual Studio Code 的完整功能集在容器中执行开发工作。

  • 安装 VS Code Docker 扩展。 此扩展添加了从 VS Code 内部生成、管理和部署容器化应用程序的功能。 (需要开发容器扩展才能实际使用容器作为开发环境。

让我们使用 Docker 为现有应用项目创建开发容器。

  1. 在本示例中,我将使用 Python 开发环境中 Django 的 Hello World 教程 中的源代码来设置文档。如果希望使用自己的项目源代码,可以跳过此步骤。 若要从 GitHub 下载 HelloWorld-Django Web 应用,请打开 WSL 终端(例如 Ubuntu),然后输入: git clone https://github.com/mattwojo/helloworld-django.git

    注释

    始终将代码存储在正在使用的工具所在的同一文件系统中。 这将导致文件访问性能更快。 在此示例中,我们使用 Linux 发行版(Ubuntu),并希望将项目文件存储在 WSL 文件系统 \\wsl\上。 使用 WSL 中的 Linux 工具访问这些文件时,在 Windows 文件系统上存储项目文件会显著降低速度。

  2. 在 WSL 终端中,切换到此项目的源代码目录:

    cd helloworld-django
    
  3. 输入以下命令,打开在本地 WSL 扩展服务器上运行的 VS Code 中的项目:

    code .
    

    通过检查 VS Code 实例左下角的绿色远程指示器,确认已连接到 WSL Linux 发行版。

    VS Code WSL 远程指示器

  4. 在 VS Code 命令面板(Ctrl + Shift + P)中,输入:开发者容器:重新以容器方式打开,因为我们使用 WSL 扩展已经打开了该文件夹。 或者,使用 开发容器:在容器中打开文件夹... 使用本地 \\wsl$ 共享(从 Windows 端)选择 WSL 文件夹。 有关更多详细信息,请参阅 Visual Studio Code 快速入门:在容器中打开现有文件夹 。 如果这些命令在开始键入时未显示,请检查以确保已安装上面链接的开发容器扩展。

    VS Code 开发容器命令

  5. 选择要容器化的项目文件夹。 在本例中,这是 \\wsl\Ubuntu-20.04\home\mattwojo\repos\helloworld-django\

    VS Code 开发容器文件夹

  6. 将显示容器定义列表,因为项目文件夹(存储库)中尚没有开发容器配置。 显示的容器配置定义列表根据项目类型进行筛选。 对于 Django 项目,我将选择 Python 3。

    VS Code 开发容器配置定义

  7. VS Code 的新实例将打开,开始生成新映像,生成完成后,将启动容器。 你将看到一个新的.devcontainer文件夹,其中包含容器配置信息,位于Dockerfiledevcontainer.json文件中。

    VS Code .devcontainer 文件夹

  8. 若要确认项目仍连接到 WSL 和容器中,请打开 VS Code 集成终端(Ctrl + Shift + ~)。 输入以下代码检查作系统: uname 和 Python 版本: python3 --version。 可以看到,uname 显示为“Linux”,这意味着你仍然连接到 WSL 2 引擎,而 Python 版本号将根据容器配置而定,并可能与您在 WSL 发行版上安装的 Python 版本不同。

  9. 若要使用 Visual Studio Code 在容器内运行和调试应用,请先打开 “运行 ”菜单(Ctrl+Shift+D 或选择最左侧菜单栏上的选项卡)。 然后选择“ 运行”和“调试 ”以选择最适合你的项目的配置(在本示例中,这是“Django”)。 这将在launch.json项目的文件夹中创建一个.vscode文件,其中包含有关如何运行应用的说明。

    VS Code 运行调试配置

  10. 在 VS Code 内部,选择“ 运行>开始调试 ”(或只按 F5 键)。 这将在 VS Code 中打开一个终端。你应该看到如下所示的结果:“开发服务器正在 http://127.0.0.1:8000/ 启动。使用 CONTROL-C 退出服务器。” 按住 Control 键并选择显示的地址,以在默认 Web 浏览器中打开应用程序,并查看项目在其容器中运行。

    在 Docker 容器中运行的 VS Code

现在,你已使用由 WSL 2 后端提供支持的 Docker Desktop 成功配置远程开发容器,可以使用 VS Code 编写代码、生成、运行、部署或调试!

故障排除

WSL docker 上下文已弃用

如果使用的是适用于 WSL 的 Docker 早期技术预览版,则可能具有一个名为“wsl”的 Docker 上下文,该上下文现已弃用,不再使用。 可以使用以下命令进行检查: docker context ls 可以删除此“wsl”上下文以避免命令错误: docker context rm wsl 因为你想要对 Windows 和 WSL2 使用默认上下文。

可能会在已弃用的 wsl 上下文中遇到的错误包括:docker wsl open //./pipe/docker_wsl: The system cannot find the file specified.error during connect: Get http://%2F%2F.%2Fpipe%2Fdocker_wsl/v1.40/images/json?all=1: open //./pipe/docker_wsl: The system cannot find the file specified.

有关此问题的详细信息,请参阅 如何在 Windows 10 上的 Windows System for Linux(WSL2)中设置 Docker

查找 docker 映像存储文件夹时遇到问题

Docker 创建两个发行版文件夹来存储数据:

  • \wsl$\docker-desktop
  • \wsl$\docker-desktop-data

可以通过打开 WSL Linux 分发版并输入: explorer.exe . 在 Windows 文件资源管理器中查看文件夹来查找这些文件夹。 输入:\\wsl\<distro name>\mnt\wsl 其中 <distro name> 替换为你分发版的名称(例如,Ubuntu-20.04)来查看这些文件夹。

在 WSL 中查找 Docker 存储位置的详细信息,请参阅 WSL 存储库 或此 StackOverflow 文章中的此问题。

有关 WSL 中常规故障排除问题的更多帮助,请参阅 故障排除 文档。

其他资源