跳轉到主要內容
沙箱編譯在開發環境中的運作方式與正式環境映像檔略有不同。開發環境已經設定好沙箱編譯;本頁說明相關設定以及需要注意的三件事:
  • 檔案權限問題
  • history-v1 與 filestore 之間的磁碟區共用
  • 子目錄問題

啟用沙箱編譯

沙箱編譯預設為開啟。develop/docker-compose.yml 為 clsi 設定了 SANDBOXED_COMPILES=true,其餘設定位於 develop/dev.env:
develop/dev.env
clsi 不會自行拉取映像檔,因此請用 docker pull ghcr.io/ayaka-notes/texlive-full:2026.1(以及 :2025.1)拉取一次映像檔。 LaTeX 在兄弟容器中以 TEXLIVE_IMAGE_USER 身分執行。在開發環境中該使用者是 tex,這也是 clsi 的預設值(services/clsi/config/settings.defaults.cjs:154)。正式環境映像檔在 SANDBOXED_COMPILES_SIBLING_CONTAINERS=true 時改用 www-data(server-ce/config/env.sh:15-21),因為在那裡檔案由 Overleaf 容器的 www-data 使用者建立。
請不要使用你自行建置的映像檔,否則可能會遇到一連串錯誤。

修正檔案權限

clsi 容器以 root 身分啟動,將 compiles、output 和 cache 資料夾交給 node 使用者(uid 1000),然後以 node 身分執行 clsi(services/clsi/entrypoint.sh)。因此主機上的 develop/compiles 屬於 uid 1000,與開發環境中 tex 的 uid 相同(請參閱 develop/pandoc/Dockerfile 中的註解)。使用上述設定,開發環境不需修改任何權限即可編譯。 如果改為設定 TEXLIVE_IMAGE_USER=root,root(uid 0)沒有寫入 compiles 子資料夾的權限。這種情況下,請將 compiles 的所屬群組設為 root 並授予寫入權限,同時設定 setgid,讓新建立的子資料夾繼承該所屬關係:
bash
詳細說明請參閱 services/clsi/README.md。

history-v1 與 filestore 之間的磁碟區共用

本節和下一節的設定已包含在 develop/docker-compose.yml 和 develop/dev.env 中。只有在 develop/dev.rc 中設定 S3_ENABLED=false 時才有作用。使用預設的 S3_ENABLED=true 時,filestore 和 history-v1 會改為將這些檔案儲存在 RustFS 儲存桶中(develop/s3/docker-compose.yml)。
預設情況下,filestore 在 Overleaf 中扮演 S3 與其他服務之間的橋樑。然而在 Overleaf CE 或 Server Pro 中,所有檔案預設都儲存在本機。因此,Overleaf 採用了一個相當巧妙的方法。
server-ce/config/settings.js
同時,data/history 也被歷史服務使用。如此一來,不同的微服務就可以共用同一份資料。這就是 develop 中的 filestore 服務掛載 history-v1 的 history-v1-buckets 磁碟區的原因。沒有它,clsi 將無法從 filestore 服務拉取 blob 檔案。
develop/docker-compose.yml
filestore 透過 dev.env 中的以下設定找到儲存桶:
develop/dev.env

使用子目錄

filestore 總是以子目錄方式讀取歷史 blob(services/filestore/app/js/KeyBuilder.js:58、:70)。正式環境映像檔為 history-v1 開啟了 useSubdirectories(server-ce/config/production.json),但 history-v1 的預設設定沒有開啟,所以在開發環境中 history-v1 會把所有資料扁平化儲存。因此 dev.env 為 history-v1 設定了 NODE_CONFIG:
develop/dev.env
如果沒有它,history-v1 會這樣儲存 project_blobs 檔案:
將 useSubdirectories 設為 true 後,這些名稱中的 _ 會變成 /,因此每個 blob 都會儲存在子資料夾中。
最後修改於 2026年11月20日