跳轉到主要內容
Ayakaleaf Pro 提供在安全沙箱環境中執行編譯的選項,以滿足企業級的安全需求。其做法是讓每個專案都在各自獨立且安全的 Docker 環境中執行。

更高的安全性

由於許多 LaTeX 文件在 PDF 編譯過程中需要(或具備)執行任意 shell 指令的能力,因此 Sandboxed Compiles 是 Ayakaleaf Pro 建議採用的方式。如果您使用 Sandboxed Compiles,每次編譯都會在獨立的 Docker 容器中執行,該容器權限受限、不與任何其他使用者或專案共用,且無法存取主機網路等外部資源。
如果您嘗試在未啟用 Sandboxed Compiles 的情況下執行 Ayakaleaf Pro,編譯將會與其他同時進行的編譯一起在主要 Docker 容器內執行,且使用者在執行 LaTeX 編譯時,對 sharelatex 容器的資源(檔案系統、網路與環境變數)擁有完整的讀寫權限。

更簡便的套件管理

為了避免手動安裝套件,我們建議啟用 Sandboxed Compiles。這是 Ayakaleaf Pro 中的一項可設定選項,能讓您的使用者在您自己的地端安裝中,使用與 overleaf.com 相同的 TeX Live 環境。Sandboxed Compiles 所使用的 TeX Live 映像檔包含最熱門的套件與字型,並已針對我們的範本庫進行測試,確保與地端專案有最高的相容性。 啟用 Sandboxed Compiles 後,您可以設定使用者在專案中可選擇的 TeX Live 版本,並為新專案設定預設的 TeX Live 映像檔版本。
如果您嘗試在未啟用 Sandboxed Compiles 的情況下執行 Ayakaleaf Pro,您的執行個體將預設使用 basic scheme 版本的 TeX Live 進行編譯。這個基本版本相當輕量,只包含非常有限的 LaTeX 套件子集,很可能會導致使用者遇到缺少套件的錯誤,尤其是在嘗試使用預先建置的範本時。
由於 Ayakaleaf Pro 的架構設計為可離線運作,因此沒有自動化的方式能將 overleaf.com 範本庫中的範本整合到您的地端安裝中;不過,您可以逐一手動匯入範本。如需了解其運作方式,請參閱我們從 overleaf.com 轉移範本的指南:#transferring-templates-from-overleaf.com。
Sandboxed Compiles 需要 sharelatex 容器能(透過綁定掛載)存取主機上的 Docker socket,以便管理這些同層級的編譯容器。

運作方式

啟用 Sandboxed Compiles 後,Docker socket 會從主機掛載到 sharelatex 容器中,讓容器內的編譯服務能在主機上建立新的 Docker 容器。接著,每個專案每次執行編譯時,LaTeX 編譯服務(CLSI)都會執行以下動作:
  • 將專案檔案寫入 OVERLEAF_DATA_PATH 內的某個位置。
  • 使用掛載的 Docker socket 為此次編譯建立新的 texlive 容器。
  • 讓 texlive 容器從 OVERLEAF_DATA_PATH 下的位置讀取專案資料。
  • 在 texlive 容器內編譯專案。

啟用 Sandboxed Compiles

Toolkit 使用者

要啟用沙箱編譯(也稱為 Sibling containers),請在 overleaf-toolkit/config/overleaf.rc 中設定以下選項:
config/overleaf.rc
若要停用,請設定 SIBLING_CONTAINERS_ENABLED=false 並執行 bin/up。之後編譯會在 sharelatex 容器內使用其基本的 TeX Live 執行。

Docker Compose 使用者

設定 TeX Live 映像檔

中國大陸的使用者可以從 ghcr.nju.edu.cn 鏡像拉取映像檔以加快下載速度,然後以其 ghcr.io 名稱為映像檔加上標籤:
請勿在 Toolkit 的環境設定中使用 ghcr.nju.edu.cn:請在其中保留 ghcr.io 名稱。若要避免 bin/up 再次從 ghcr.io 拉取映像檔,請在 config/overleaf.rc 中設定 SIBLING_CONTAINERS_PULL=false。若要透過鏡像讓映像檔保持最新,請參閱自動更新 TeX Live Full 映像檔。
Ayakaleaf Pro 使用三個環境變數來決定 Sandboxed Compiles 要使用哪些 TeX Live 映像檔:
  • TEX_LIVE_DOCKER_IMAGE (選填),新專案所使用的 TeX Live 映像檔。它必須是 ALL_TEX_LIVE_DOCKER_IMAGES 中的映像檔之一。若未設定,新專案會使用 ALL_TEX_LIVE_DOCKER_IMAGES 中的第一個映像檔。
  • ALL_TEX_LIVE_DOCKER_IMAGE_NAMES (選填),以逗號分隔、依相同順序排列的映像檔名稱清單,顯示於編譯器設定中。若未設定,或清單比映像檔清單短,映像檔會以其標籤顯示,例如 2026.1。
  • ALL_TEX_LIVE_DOCKER_IMAGES (必填),以逗號分隔的 TeX Live 映像檔清單。若使用 Overleaf Toolkit 部署,這些映像檔將會被下載或更新。若要略過下載,請在 config/overleaf.rc 中設定 SIBLING_CONTAINERS_PULL=false。
使用 bin/up 指令啟動 Ayakaleaf Pro 執行個體時,Toolkit 會自動拉取 ALL_TEX_LIVE_DOCKER_IMAGES 中列出的所有映像檔。 以下範例中,新專案預設使用 TeX Live 2026,舊專案則繼續使用 2025。
以下設定會安裝 2025 到 2026 年的所有完整 TeX Live Docker 映像檔。使用此設定前,建議至少準備 64 GB 的可用儲存空間。
config/variables.env
強烈建議至少設定 2 個 texlive-full 映像檔。詳細原因請參閱 #known-issues

可用的 TeX Live 映像檔

以下是一系列專為 Overleaf 最佳化的 TeX Live 映像檔,可加入 TEX_LIVE_DOCKER_IMAGE 與 ALL_TEX_LIVE_DOCKER_IMAGES:
  • ghcr.io/ayaka-notes/texlive-full:2026.1(亦即 latest 標籤)
  • ghcr.io/ayaka-notes/texlive-full:2025.1
  • ghcr.io/ayaka-notes/texlive-full:2024.1
  • ghcr.io/ayaka-notes/texlive-full:2023.1
  • ghcr.io/ayaka-notes/texlive-full:2022.1
  • ghcr.io/ayaka-notes/texlive-full:2021.1
  • ghcr.io/ayaka-notes/texlive-full:2020.1
映像檔的標籤必須遵循嚴格的格式(適用的正規表示式為 ^[0-9]+.[0-9]+,其中第一個數字決定 TeX Live 年份,第二個數字則為修補版本)。

可以使用其他映像檔登錄庫嗎?

有些人可能會想,能否將 ghcr.io 替換為其他鏡像站,或將 texlive 改用 Docker Hub 上的其他映像檔?
不,我們不建議這麼做,因為設定相對複雜。如果您是從鏡像站下載,可以將映像檔重新命名為 ghcr.io/ayaka-notes/texlive-full。 但如果您確實想使用自己的映像檔登錄庫,請加入:
config/variables.env
接著,您需要確保所有 texlive 映像檔都位於 your-repo 中,例如:
  • hub.your.com/your-repo/texlive-full:2025.1
  • hub.your.com/your-repo/texlive-full:2024.1
詳細資訊請閱讀以下原始碼,了解我們如何解析您的環境變數:
sandboxed-compiles/index.mjs

自動同步 TeX Live 映像檔

為了避免每次都要手動執行 bin/up 更新執行個體,您可以將 TeX Live 映像檔的更新自動化。請參閱 updating-tex-live-full-images-automatically.md。

已知問題

以下是來自 Overleaf 社群的真實案例:
我使用 6.0.1-ext-v3.3,在 variables.env 中有以下設定:
使用 texlive/texlive:latest-full 時一切正常。然而,我拉取了另一個 texlive 映像檔 danteev/texlive:2025-10-15,並將這兩個變數都改成新的映像檔名稱,卻無法運作:
在記錄中,我看到以下內容:
看起來 variables.env 中更新的設定並未生效。編譯仍然嘗試執行 texlive/texlive:latest-full 映像檔,而不是新的映像檔。 我試過重新開機、刪除容器後重新執行,但問題依舊。 有什麼解決辦法嗎?
由於某些技術限制,如果您只設定了單一 Docker TeXLive 映像檔,例如 texlive-fullA:latest
在 Overleaf 執行個體運作一段時間後,您可能想將 TeXLive 映像檔改為 texlive-fullB:latest。這時,您會發現使用者無法編譯任何專案。
這是因為每個專案所使用的 TeXLive-Full 映像檔名稱(用於沙箱編譯)會持久保存在資料庫中。只有當使用者切換專案的 TeXLive 版本時(例如從 2024 切換到 2025),資料庫中的映像檔名稱才會變更。 CLSI 編譯專案時,會直接使用在資料庫中找到的容器映像檔名稱來編譯專案。 如果您只提供一個 Docker 映像檔,使用者將無法變更用來編譯專案的映像檔。在這種情況下,您需要撰寫腳本,在 MongoDB 中為所有使用者專案手動修改 TeXLive 映像檔。

除錯與回報

執行以下指令,從 Toolkit 檢查 clsi 記錄:
如果您在使用 TeX Live 映像檔編譯時遇到任何問題,請在此提交 issue: https://github.com/ayaka-notes/texlive-full/issues/new?template=texlive-image-bug.yml 為了協助我們重現並排除問題,我們可能會請您將專案上傳到 Overleaf。接著我們會拉取該專案,並透過 GitHub Action 執行編譯測試。

問與答

回答:容器與編譯檔案會在一段延遲後自動移除;TeX Live 映像檔則不會。
  • 編譯容器(project-<project id>-<hash>)會在同一專案的多次編譯之間重複使用,因此編譯後仍會保留。系統每小時會執行一次檢查,移除存在超過一小時、且其專案在過去一小時內未曾編譯的容器。容器通常會在最後一次編譯後一到兩小時內被移除。重新啟動 Overleaf 不會移除它們,而是由下一次每小時檢查移除。
  • 字數統計、SyncTeX 與轉換容器會在完成後立即移除。
  • 編譯檔案(data/overleaf/data/compiles 與 output)會在專案一天未使用後移除,每 10 分鐘檢查一次。當磁碟空間不足時,此期間會逐步縮短,最短為半天。
  • TeX Live 映像檔永遠不會被移除,因為每次編譯都需要它們。從 ALL_TEX_LIVE_DOCKER_IMAGES 中移除映像檔後,若要釋放空間,請使用 docker image rm <image> 將其刪除。
無需手動刪除這些容器。
回答:不可以。每個編譯容器只會在 /compile 掛載其所屬專案的編譯目錄,且沒有網路連線,也沒有任何設定可將其他主機目錄掛載到容器中。請改為將專案所需的檔案上傳至專案。
回答:有。ghcr.io/ayaka-notes/texlive-basic:<year>.1(2020.1 至 2026.1)包含 TeX Live basic 方案,以及 latexmk、xetex 與 fontspec 等少數套件,但不含完整的字型集。它比 texlive-full 小得多,但使用其他套件的專案會出現缺少套件的錯誤。以 TeX Live 2025 basic 為例:
config/variables.env
ghcr.io/ayaka-notes/texlive-full:base 並不是 basic 映像檔:它不包含 TeX Live,因此無法編譯。
回答:編輯器不會顯示這項資訊,而 clsi 記錄檔也只會在 debug 層級記錄它。不過每個編譯請求都會回傳這項資訊:開啟瀏覽器的開發者工具,前往 Network 分頁,重新編譯,然後選取 compile 請求。其 JSON 回應中有以毫秒為單位的 timings,其中 compileE2E 是編譯服務中整個編譯的時間,而 compile 則是 LaTeX 本身執行的時間。
最後修改於 2026年11月13日