更高的安全性
由於許多 LaTeX 文件在 PDF 編譯過程中需要(或具備)執行任意 shell 指令的能力,因此 Sandboxed Compiles 是 Ayakaleaf Pro 建議採用的方式。如果您使用 Sandboxed Compiles,每次編譯都會在獨立的 Docker 容器中執行,該容器權限受限、不與任何其他使用者或專案共用,且無法存取主機網路等外部資源。更簡便的套件管理
為了避免手動安裝套件,我們建議啟用 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 套件子集,很可能會導致使用者遇到缺少套件的錯誤,尤其是在嘗試使用預先建置的範本時。
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 映像檔
中國大陸的使用者可以從 請勿在 Toolkit 的環境設定中使用
ghcr.nju.edu.cn 鏡像拉取映像檔以加快下載速度,然後以其 ghcr.io 名稱為映像檔加上標籤:ghcr.nju.edu.cn:請在其中保留 ghcr.io 名稱。若要避免 bin/up 再次從 ghcr.io 拉取映像檔,請在 config/overleaf.rc 中設定 SIBLING_CONTAINERS_PULL=false。若要透過鏡像讓映像檔保持最新,請參閱自動更新 TeX Live Full 映像檔。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.1ghcr.io/ayaka-notes/texlive-full:2024.1ghcr.io/ayaka-notes/texlive-full:2023.1ghcr.io/ayaka-notes/texlive-full:2022.1ghcr.io/ayaka-notes/texlive-full:2021.1ghcr.io/ayaka-notes/texlive-full:2020.1
可以使用其他映像檔登錄庫嗎?
有些人可能會想,能否將 ghcr.io 替換為其他鏡像站,或將 texlive 改用 Docker Hub 上的其他映像檔?
不,我們不建議這麼做,因為設定相對複雜。如果您是從鏡像站下載,可以將映像檔重新命名為 ghcr.io/ayaka-notes/texlive-full。
但如果您確實想使用自己的映像檔登錄庫,請加入:
config/variables.env
your-repo 中,例如:
hub.your.com/your-repo/texlive-full:2025.1hub.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,並將這兩個變數都改成新的映像檔名稱,卻無法運作:在記錄中,我看到以下內容:
看起來由於某些技術限制,如果您只設定了單一 Docker TeXLive 映像檔,例如variables.env中更新的設定並未生效。編譯仍然嘗試執行texlive/texlive:latest-full映像檔,而不是新的映像檔。 我試過重新開機、刪除容器後重新執行,但問題依舊。 有什麼解決辦法嗎?
texlive-fullA:latest
texlive-fullB:latest。這時,您會發現使用者無法編譯任何專案。
除錯與回報
執行以下指令,從 Toolkit 檢查 clsi 記錄:問與答
沙箱容器、編譯檔案與 TeX Live 映像檔會自動移除嗎?
沙箱容器、編譯檔案與 TeX Live 映像檔會自動移除嗎?
回答:容器與編譯檔案會在一段延遲後自動移除;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>將其刪除。
專案可以讀取主機或 NAS 目錄中的檔案嗎?
專案可以讀取主機或 NAS 目錄中的檔案嗎?
回答:不可以。每個編譯容器只會在
/compile 掛載其所屬專案的編譯目錄,且沒有網路連線,也沒有任何設定可將其他主機目錄掛載到容器中。請改為將專案所需的檔案上傳至專案。是否有 TeX Live basic 映像檔?該如何設定?
是否有 TeX Live basic 映像檔?該如何設定?
回答:有。
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 本身執行的時間。
