> ## 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.

# 沙箱編譯（Sandboxed Compiles）

> 在 Kubernetes 叢集的節點上，於 TeX Live 容器中編譯 LaTeX。

編譯由每個 Ayakaleaf Pro Pod 內的 **clsi** 服務執行。啟用沙箱編譯後，clsi 會要求 Pod 所在**節點的 Docker Engine** 為每次編譯啟動一個 TeX Live 容器，並以該節點上的路徑將專案目錄交給它。沙箱的運作方式與可用的映像檔，請參閱[沙箱編譯](https://ayakaleaf-pro.mintlify.site/zh-TW/on-premises/configuration/overleaf-toolkit/sandboxed-compiles.md)。

| | |
| - | - |
| 服務 | clsi（編譯）、web（編譯器設定中的映像檔清單），位於每個 Ayakaleaf Pro Pod 中 |
| 節點 | Docker Engine 與 `ALL_TEX_LIVE_DOCKER_IMAGES` 中的每個映像檔，位於每個可執行 Ayakaleaf Pro 的節點上 |
| Pod 掛載 | `/var/run/docker.sock`，以及作為 `hostPath` 磁碟區的編譯、輸出與快取目錄 |
| 定期工作 | clsi 會刪除一天內未使用的編譯目錄，並每小時從節點的 Docker 中移除舊的 TeX Live 容器 |

### 設定

安裝過程已設定好一切：節點上的 Docker 與映像檔見 [0. 準備節點](https://ayakaleaf-pro.mintlify.site/zh-TW/on-premises/installation/using-kubernetes/0.-prepare-the-nodes.md)，設定見 [4. 個人化您的執行個體](https://ayakaleaf-pro.mintlify.site/zh-TW/on-premises/installation/using-kubernetes/4.-personalizing-your-instance.md)，磁碟區則見 [5. 部署 Ayakaleaf Pro](https://ayakaleaf-pro.mintlify.site/zh-TW/on-premises/installation/using-kubernetes/5.-deploy-ayakaleaf-pro.md)。所有設定都位於 ConfigMap 中：

| 變數 | 值 |
| - | - |
| `SANDBOXED_COMPILES`、`SANDBOXED_COMPILES_SIBLING_CONTAINERS`、`DOCKER_RUNNER` | `"true"` |
| `SANDBOXED_COMPILES_HOST_DIR_COMPILES` | 掛載於 `/var/lib/overleaf/data/compiles` 之磁碟區在節點上的路徑 |
| `SANDBOXED_COMPILES_HOST_DIR_OUTPUT` | 掛載於 `/var/lib/overleaf/data/output` 之磁碟區在節點上的路徑 |
| `SANDBOXED_COMPILES_HOST_DIR_CACHE` | 掛載於 `/var/lib/overleaf/data/cache` 之磁碟區在節點上的路徑 |
| `ALL_TEX_LIVE_DOCKER_IMAGES`、`ALL_TEX_LIVE_DOCKER_IMAGE_NAMES`、`TEX_LIVE_DOCKER_IMAGE` | 映像檔，與 Toolkit 相同 |

### 新增 TeX Live 版本

**1. 在每個節點上拉取映像檔**

```bash theme={null}
# on each node that can run Ayakaleaf Pro
sudo docker pull ghcr.io/ayaka-notes/texlive-full:2025.1
```

Toolkit 會自行拉取映像檔；在 Kubernetes 上則沒有任何元件會代勞。請拉取到 **Docker** 中，而不是使用 `crictl`：clsi 是向 Docker 要求映像檔。若節點上缺少所用的映像檔，編譯就會失敗。

**2. 在 ConfigMap 中列出並重新啟動**

```yaml theme={null}
  ALL_TEX_LIVE_DOCKER_IMAGES: ghcr.io/ayaka-notes/texlive-full:2026.1,ghcr.io/ayaka-notes/texlive-full:2025.1
  ALL_TEX_LIVE_DOCKER_IMAGE_NAMES: TeX Live 2026,TeX Live 2025
  TEX_LIVE_DOCKER_IMAGE: ghcr.io/ayaka-notes/texlive-full:2026.1
```

```bash theme={null}
kubectl apply -f 30-config.yaml
kubectl -n overleaf rollout restart deployment/overleaf     # or statefulset/overleaf
```

之後才加入叢集的節點，必須先具備 Docker 與所有映像檔，Ayakaleaf Pro 才能在其上執行。若並非每個節點都符合條件，請為這類節點加上標籤，並使用 `nodeSelector` 讓 Ayakaleaf Pro 只在這些節點上執行。

### 多個副本

每個副本都在自己的節點上編譯，並將編譯輸出保存在該處，因此使用者必須停留在執行編譯的副本上，這點由負載平衡器的黏性 Cookie 確保。切勿在同一個節點上執行兩個副本：它們會共用該節點的編譯目錄。[水平擴展](https://ayakaleaf-pro.mintlify.site/zh-TW/on-premises/configuration/kubernetes/horizontal-scaling.md)的設定以 `podAntiAffinity` 防止這種情況。

TeX Live 容器在 Pod 旁邊執行，不受 Pod 的記憶體限制約束，也不在排程器的視野內。請在節點上為它們保留可用記憶體，請參閱 [0. 準備節點](https://ayakaleaf-pro.mintlify.site/zh-TW/on-premises/installation/using-kubernetes/0.-prepare-the-nodes.md)。

### 在 Kubernetes 上的測試

在 Kubernetes 1.37 上以三個副本置於 HAProxy 之後（每個節點一個），並在每個節點的 Docker 中拉取 TeX Live 2026 與 2025，沙箱編譯的端對端測試全數通過（7 個案例）：新專案可編譯為 PDF、編譯器設定提供兩個映像檔並可在其間切換、使用 fontspec 的 XeLaTeX、LaTeX 錯誤及修正後重新編譯、停止執行中的編譯，以及雙向的 SyncTeX。在 12 位使用者同時編譯 600 頁文件的負載測試中，每個節點執行 4 次編譯，請參閱[預期效能](https://ayakaleaf-pro.mintlify.site/zh-TW/on-premises/configuration/kubernetes/horizontal-scaling.md#what-to-expect)。


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