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，然後執行：

   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 的整合。

​

下一步

當 docker ps 在 Ubuntu 中可以運作後，請繼續進行 1. 下載 Toolkit。