0. 安装 WSL 2 和 Docker Desktop

安装 WSL 2 和 Ubuntu，然后在 Windows 上将 Ubuntu 连接到 Docker Desktop。

Ayakaleaf Pro 使用 Linux 容器。在 Windows 上，请安装使用 WSL 2 后端的 Docker Desktop，并在 Ubuntu 中运行 Toolkit 脚本。

WSL 2 提供 Linux 内核。Docker Desktop 在其自己的 docker-desktop 环境中管理 Docker 引擎；启用 WSL Integration 后，Ubuntu 中的 Docker CLI 就可以与该引擎通信。随后 Toolkit 会以容器形式启动应用程序、MongoDB 和 Redis。启用沙盒编译后，应用程序会使用引擎的 Docker socket 为每次编译启动一个单独的 TeX Live 容器。你无需在 Windows 上安装 MongoDB、Redis 或 TeX Live。

1. 安装 WSL 2 和 Ubuntu

   在 Windows 中以管理员身份打开 PowerShell 并运行：

   wsl --install -d Ubuntu
   

   如果系统提示，请重启 Windows。从开始菜单打开 Ubuntu，并创建 Linux 用户名和密码。这是在 Ubuntu 中使用 sudo 的账户，与你的 Windows 登录账户相互独立。

   回到 PowerShell，更新 WSL 并检查发行版：

   wsl --update
   wsl --version
   wsl --list --verbose
   

   Ubuntu 所在行必须显示 VERSION 2。如果显示为 1，请使用列表中该发行版的确切名称：

   wsl --set-version Ubuntu 2
   

   Docker 需要 WSL 2.1.5 或更高版本；wsl --version 显示的 WSL 软件版本和发行版的 VERSION 2 列是两项不同的检查。如果安装失败，请参阅安装故障排除和 Microsoft 的安装说明；如果 WSL 报告虚拟化不可用，请在 BIOS/UEFI 中启用硬件虚拟化。

2. 安装并启动 Docker Desktop

   下载适用于你的处理器的 Docker Desktop for Windows 并运行安装程序。如果提供选项，请使用 WSL 2 后端。从 Windows 开始菜单打开 Docker Desktop，并等待引擎启动。

   在 Docker Desktop 的 Settings → General 中，如果显示了 Use WSL 2 based engine 选项，请启用它。在 Settings → Resources → WSL Integration 下，为 Ubuntu 启用集成，然后选择 Apply 或 Apply & restart。如果 Ubuntu 不是你的默认发行版，请显式打开它自己的开关。

   如果缺少 WSL Integration，请检查 Docker Desktop 是否正在使用 Linux containers。请参阅 Docker 的 WSL 2 后端指南。

   本指南请使用 Docker Desktop 的集成。使用 apt install docker.io 安装第二个 Docker Engine 或在 Ubuntu 中启动 dockerd，会形成一套独立的环境并可能导致冲突。如果你已经在 Ubuntu 中使用某个 Engine，请在切换之前遵循 Docker 的迁移指南；保留现有的应用程序数据和备份。

3. 在 Ubuntu 中检查 Docker

   打开 Ubuntu 终端。在其中运行以下命令，不要使用 sudo：

   docker version
   docker compose version
   docker ps
   

   docker version 必须同时显示 Client 和 Server。在新安装中，容器列表为空是正常的。仅运行 docker --version 并不能证明引擎正在运行。

   如果 docker 不可用或无法连接，请在应用 WSL Integration 后重新打开 Ubuntu，并检查 Docker Desktop 是否正在运行。请参阅故障排除。

4. 检查资源和 Docker socket

   检查 Docker 可见的资源：

   docker info --format 'CPUs={{.NCPU}} Memory={{.MemTotal}} Kernel={{.KernelVersion}}'
   df -h "$HOME"
   ls -l /var/run/docker.sock
   

   对于小型本地实例，为 Docker 提供 4 个 CPU 和 8 GB 内存只是一个建议的起点，而不是经过测量的最低要求。也要为 Windows 保留足够的内存。使用 WSL 2 后端时，资源限制通过 WSL 设置进行管理，而不是像 Mac 上那样使用 Docker Desktop 的资源滑块。需要运行 wsl --shutdown 的更改会中断所有正在运行的 WSL 发行版和 Docker 工作负载；请在启动实例之前应用这些更改。

   在 Toolkit 配置中保留 DOCKER_SOCKET_PATH=/var/run/docker.sock。应用程序需要这个引擎 socket 来进行沙盒编译。不要为了修复连接错误而将其权限改为 777；请改为恢复 Docker Desktop 的集成。

​

下一步

在 Ubuntu 中 docker ps 正常运行后，请继续阅读 1. 下载 Toolkit。