> ## 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，然後將 Ubuntu 連接至 Windows 上的 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-TW/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-TW/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 的整合。

### 下一步

當 `docker ps` 在 Ubuntu 中可以運作後，請繼續進行 [1. 下載 Toolkit](https://ayakaleaf-pro.mintlify.site/zh-TW/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.