> ## Documentation Index
> Fetch the complete documentation index at: https://felimet-hub.jmcores.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Docker 效能設定（WSL 2 後端與 daemon）

> WSL 2 後端怎麼分配 CPU 與記憶體（.wslconfig）、WSL 整合指令、Docker 資料存哪，以及 daemon.json 引擎設定。

`Docker` `WSL 2` `設定`

這是 Windows 上最容易設錯的地方：**WSL 2 後端下，Docker 的 CPU 與記憶體不在 Docker Desktop 的 GUI 設**，而是由 WSL 2 整個虛擬機的設定檔控制。

## 連接到 WSL 2 後端

1. Docker Desktop → Settings → General → 勾選 **Use the WSL 2 based engine**。
2. Settings → Resources → **WSL Integration** → 開啟要讓 `docker` 指令可用的發行版（如 Ubuntu）→ Apply & Restart。

開啟整合後，在那個發行版的 Linux 終端機就能直接用 `docker`。

<Note>
  只有 **Hyper-V 後端**（或 macOS / Linux）才在 Docker Desktop 的 Settings → Resources → Advanced 直接設 CPU / 記憶體 / swap。WSL 2 後端走下面的 `.wslconfig`。
</Note>

## 分配效能（`.wslconfig`）

CPU / 記憶體 / swap 在 `%UserProfile%\.wslconfig` 的 `[wsl2]` 區段設（檔案不存在就自己建）。**`[wsl2]` 區段標頭不可省略**，否則設定不生效：

```ini theme={null}
# 路徑：C:\Users\<你的使用者名稱>\.wslconfig
[wsl2]
memory=8GB       # WSL 2 虛擬機記憶體上限（預設為實體記憶體的 50%）
processors=4     # 可用的虛擬處理器數（預設等於邏輯處理器數）
swap=8GB         # swap 大小（設 0 關閉）
# swapfile=C:\\WSL\\wsl-swap.vhdx   # swap 檔位置（預設 %Temp%\swap.vhdx）

[experimental]
autoMemoryReclaim=dropCache   # 自動釋放閒置記憶體
sparseVhd=true                # 新 VHD 自動稀疏化，省磁碟實際佔用
```

改完要重啟 WSL 才生效：

```powershell theme={null}
wsl --shutdown          # 關閉所有 WSL 發行版（約等 8 秒完全停止）
wsl --list --running    # 確認沒有發行版還在跑
wsl -d Ubuntu           # 重新啟動，設定即套用
```

## WSL 整合常用指令

```powershell theme={null}
wsl -l -v                       # 列出發行版、WSL 版本（1 或 2）與狀態
wsl --set-default-version 2     # 新裝的發行版預設用 WSL 2
wsl --set-version Ubuntu 2      # 把現有發行版轉成 WSL 2
wsl --update                    # 更新 WSL 核心
wsl --shutdown                  # 關閉所有 WSL（套用 .wslconfig 必經步驟）
wsl --terminate Ubuntu          # 只關特定發行版，保留其他在跑的
wsl --status                    # 看 WSL 版本與核心資訊
```

## Docker 資料存哪、怎麼看大小

WSL 2 後端下，Docker 的映像層、容器、volume 資料都在 **`docker-desktop-data`** 這個 WSL 發行版的虛擬磁碟（VHDX）裡，預設位置：

```
C:\Users\<UserName>\AppData\Local\Docker\wsl\
```

```powershell theme={null}
wsl -l -v        # 會看到 docker-desktop 與 docker-desktop-data 兩個發行版
```

```
  NAME                   STATE       VERSION
* Ubuntu                 Running     2
  docker-desktop         Stopped     2
  docker-desktop-data    Stopped     2
```

`docker-desktop-data` 的 VHDX 就是磁碟占用來源。它**動態擴展但不會自動縮回**，檔案總管看不到實際占用，要用指令查：

```powershell theme={null}
Get-ChildItem "$env:LOCALAPPDATA\Docker\wsl" -Recurse -File |
  Select-Object Name, @{N='Size(MB)';E={[math]::Round($_.Length/1MB,1)}}
```

要回收空間靠 [清理指令](/notes/docker/guide/cli/)（`docker system prune`）。要搬移 VHDX 位置：Docker Desktop → Settings → Resources → Advanced → **Disk image location**。

## daemon.json（Docker 引擎設定）

要調 registry mirror、日誌輪替、預設 runtime 等引擎層設定，改 daemon 設定檔。**Docker Desktop 上不直接編輯檔案**，而是 Settings → Docker Engine 的 JSON 編輯器；Linux 原生安裝才是 `/etc/docker/daemon.json`。

```json theme={null}
{
  "log-driver": "json-file",
  "log-opts": { "max-size": "10m", "max-file": "3" },
  "registry-mirrors": ["https://mirror.example.com"],
  "default-runtime": "runc",
  "live-restore": true
}
```

常用鍵：`log-opts` 限制單一容器日誌大小與檔數（避免日誌塞爆磁碟，值得預設加）、`registry-mirrors` 加速 pull、`data-root` 改資料根目錄、`live-restore` 讓 daemon 重啟時容器不中斷。

## 接下來

* [資料落點](/notes/docker/guide/storage/)：volume 與 bind mount 在 WSL 2 的效能差異。
* [Docker CLI 指令](/notes/docker/guide/cli/)：清理指令回收 VHDX 空間。

官方參考：[docs.docker.com/desktop/features/wsl](https://docs.docker.com/desktop/features/wsl/)、[learn.microsoft.com/windows/wsl/wsl-config](https://learn.microsoft.com/windows/wsl/wsl-config)