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

# 設定沙箱編譯

若要在開發環境中設定沙箱編譯，開發環境與正式環境之間有些許差異。你需要注意以下 3 件事：

* 檔案權限問題
* history-v1 與 filestore 之間的磁碟區共用
* 子目錄問題

### 啟用沙箱編譯

這裡只需要像在 Overleaf CE 中一樣啟用沙箱編譯即可，唯一需要注意的是使用者設定。這裡我們將其設為 root。

在正式環境中，我們使用 www-data 作為 Overleaf 容器與 TeX 編譯容器之間的共用使用者。然而在開發環境中，容器內的預設使用者是 node，且沒有 www-data 使用者可供對應，因此我們改用 root 作為替代做法。

<Warning>
  請不要使用你自行建置的映像檔，否則可能會遇到一連串錯誤。
</Warning>

```dotenv wrap theme={null}
#################
#   Sandbox     #
#################
SANDBOXED_COMPILES=true
TEXLIVE_IMAGE_USER=root
ALL_TEX_LIVE_DOCKER_IMAGES=ghcr.io/ayaka-notes/texlive-full:2025.1, ghcr.io/ayaka-notes/texlive-full:2024.1
ALL_TEX_LIVE_DOCKER_IMAGE_NAMES=Texlive 2025, Texlive 2024
TEX_LIVE_DOCKER_IMAGE=ghcr.io/ayaka-notes/texlive-full:2025.1
```

### 修正檔案權限

LaTeX 會以 `TEXLIVE_IMAGE_USER` 環境變數所指定的使用者身分在同層容器中執行。在上述範例中，此值設為 `root`，其 uid 為 `0`。這會與上述權限產生衝突，因為 root 使用者沒有寫入 `compiles` 子資料夾的權限。

一個快速的修正方式是將 `compiles` 的群組擁有權交給 `root` 群組並授予讀寫權限，同時設定 `setgid`，讓新的子資料夾也繼承此擁有權：

```bash title="bash" theme={null}
sudo chown -R 1000:root compiles
sudo chmod -R g+w compiles
sudo chmod g+s compiles
```

詳細說明請參閱 `services/clsi/README.md`。

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

預設情況下，filestore 在 Overleaf 中扮演 S3 與其他服務之間的橋樑。然而在 Overleaf CE 或 Server Pro 中，所有檔案預設都儲存在本機。因此，Overleaf 採用了一個相當巧妙的方法。

```javascript title="server-ce/config/settings.js" wrap theme={null}
switch (process.env.OVERLEAF_FILESTORE_BACKEND) {
  case 's3':
    // s3 case...
  default:
    settings.filestore = {
      backend: 'fs',
      stores: {
        template_files: Path.join(DATA_DIR, 'template_files'),

        // NOTE: The below paths are hard-coded in server-ce/config/production.json, so hard code them here as well.
        // We can use DATA_DIR after switching history-v1 from 'config' to '@overleaf/settings'.
        project_blobs:
          process.env.OVERLEAF_HISTORY_PROJECT_BLOBS_BUCKET ||
          '/var/lib/overleaf/data/history/overleaf-project-blobs',
        global_blobs:
          process.env.OVERLEAF_HISTORY_BLOBS_BUCKET ||
          '/var/lib/overleaf/data/history/overleaf-global-blobs',
      },
    }
}
```

同時，`data/history` 也會被 history 服務使用。如此一來，不同的微服務便能共用相同的資料。你需要在開發環境中將 `history-v1-buckets` 這個磁碟區加入 filestore 服務，否則 **clsi 將無法從 filestore 服務拉取 blob 檔案**。

```yml title="develop/docker-compose.yml" wrap theme={null}
  filestore:
    build:
      context: ..
      dockerfile: services/filestore/Dockerfile
    env_file:
      - dev.env
#    environment:
#      - ENABLE_CONVERSIONS=true
    volumes:
      - filestore-public-files:/overleaf/services/filestore/public_files
      - filestore-template-files:/overleaf/services/filestore/template_files
      - filestore-uploads:/overleaf/services/filestore/uploads
      - history-v1-buckets:/buckets
```

此外，你還需要在 `dev.env` 設定中加入 BUCKET 名稱：

```dotenv title="develop/dev.env" theme={null}
OVERLEAF_EDITOR_PROJECT_BLOBS_BUCKET='/buckets/project_blobs'
OVERLEAF_EDITOR_BLOBS_BUCKET='/buckets/blobs'
```

### 使用子目錄

Filestore 預設將 useSubdirectories 設為 true，但在開發環境中，history v1 會<strong>將所有資料扁平化</strong>，進而造成衝突。若要修正此問題，你需要加入以下設定：

```dotenv title="develop/dev.env" theme={null}
OVERLEAF_EDITOR_PROJECT_BLOBS_BUCKET='/buckets/project_blobs'
OVERLEAF_EDITOR_BLOBS_BUCKET='/buckets/blobs'
NODE_CONFIG='{"persistor":{"useSubdirectories":true}}'
```

在 history v1 中，所有 `project_blobs` 檔案原本是這樣儲存的：

```bash wrap theme={null}
node@43eb5dac5b1b:/buckets/project_blobs$ ls
169_609_71360f687c431b9796_5b_889ef3cf71c83a4c027c4e4dc3d1a106b27809  
94e_655_88cb5cc77ab70c9796_a0_e21c740cf81e868f158e30e88985b5ea1d6c19
169_609_71360f687c431b9796_a0_e21c740cf81e868f158e30e88985b5ea1d6c19
94e_655_88cb5cc77ab70c9796_fd_3c0326302e49486d3ea86c833edf9b88320c41
169_609_71360f687c431b9796_fd_3c0326302e49486d3ea86c833edf9b88320c41 

```

你需要將 useSubdirectories 設為 `true`，改用子目錄模式。此時，blob 中原本的 `_` 會被替換為 `/`。


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