> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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** 并运行：

```powershell theme={null}
wsl --install -d Ubuntu
```

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

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

```powershell theme={null}
wsl --update
wsl --version
wsl --list --verbose
```

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

```powershell theme={null}
wsl --set-version Ubuntu 2
```

Docker 需要 WSL **2.1.5 或更高版本**；`wsl --version` 显示的 WSL 软件版本和发行版的 **VERSION 2** 列是两项不同的检查。如果安装失败，请参阅[安装故障排除](https://ayakaleaf-pro.mintlify.site/zh-CN/on-premises/installation/using-docker-compose/windows/troubleshooting.md#wsl-or-docker-reports-that-virtualization-is-unavailable)和 [Microsoft 的安装说明](https://learn.microsoft.com/en-us/windows/wsl/install)；如果 WSL 报告虚拟化不可用，请在 BIOS/UEFI 中启用硬件虚拟化。

**2. 安装并启动 Docker Desktop**

下载适用于你的处理器的 [Docker Desktop for Windows](https://docs.docker.com/desktop/setup/install/windows-install/) 并运行安装程序。如果提供选项，请使用 **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 后端指南](https://docs.docker.com/desktop/features/wsl/)。

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

**3. 在 Ubuntu 中检查 Docker**

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

```bash theme={null}
docker version
docker compose version
docker ps
```

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

如果 `docker` 不可用或无法连接，请在应用 WSL Integration 后重新打开 Ubuntu，并检查 Docker Desktop 是否正在运行。请参阅[故障排除](https://ayakaleaf-pro.mintlify.site/zh-CN/on-premises/installation/using-docker-compose/windows/troubleshooting.md#docker-is-unavailable-in-ubuntu)。

**4. 检查资源和 Docker socket**

检查 Docker 可见的资源：

```bash theme={null}
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 设置](https://learn.microsoft.com/en-us/windows/wsl/wsl-config)进行管理，而不是像 Mac 上那样使用 Docker Desktop 的资源滑块。需要运行 `wsl --shutdown` 的更改会中断所有正在运行的 WSL 发行版和 Docker 工作负载；请在启动实例之前应用这些更改。

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

### 下一步

在 Ubuntu 中 `docker ps` 正常运行后，请继续阅读 [1. 下载 Toolkit](https://ayakaleaf-pro.mintlify.site/zh-CN/on-premises/installation/using-docker-compose/windows/1.-download-the-toolkit.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.