> ## 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 充当 S3 与 Overleaf 中其他服务之间的桥梁。然而在 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.