沙箱编译

Overleaf Pro 提供在受保护的沙箱环境中运行编译以满足企业安全需求的选项。它通过在每个项目自己的受保护 Docker 环境中运行来实现这一点。

改进的安全性

由于许多 LaTeX 文档在 PDF 编译过程中需要/具有执行任意 shell 命令的能力，Sandboxed Compiles（沙箱编译）是 Server Pro 推荐的做法。如果您使用 Sandboxed Compiles，每次编译都会在单独的 Docker 容器中运行，具有受限的能力，不与任何其他用户或项目共享，并且无法访问主机网络等外部资源。

如果您尝试在没有 沙箱编译 的情况下运行 Overleaf Pro，则编译会与其他并发编译一起在主 Docker 容器内运行，用户在运行 LaTeX 编译时对 sharelatex 容器资源（文件系统、网络和环境变量）具有完全的读写访问权限。

更简单的软件包管理

为了避免手动安装软件包，我们建议启用 Sandboxed Compiles。这是在 Server Pro 内可以配置的设置，能为您的用户提供与 overleaf.com 上相同的 TeX Live 环境，但运行在您自己的本地部署中。Sandboxed Compiles 使用的 TeX Live 镜像包含在我们的示例模板库中测试过的最受欢迎的软件包和字体，确保与本地项目的最大兼容性。

启用 Sandboxed Compiles 允许您配置用户在其项目中可以选择哪些 TeX Live 版本，并为新项目设置默认的 TeX Live 镜像版本。

如果您尝试在没有 Sandboxed Compiles 的情况下运行 Overleaf Pro，您的实例将默认使用一个基础版本的 TeX Live 进行编译。该基础版本体积轻量，仅包含非常有限的 LaTeX 软件包子集，极可能导致用户出现缺少软件包的错误，尤其是在他们尝试使用预构建模板时。

由于 Overleaf Pro 的架构支持离线工作，因此没有自动化方式将 overleaf.com 的示例模板集成到您的本地安装中；不过，可以按模板逐个手动完成。有关此过程的更多信息，请参阅我们有关从 overleaf.com 传输模板的指南： TEMPLATE_ALL_DESCRIPTION=Browse a collection of all available LaTeX templates, categorized by document type, style, and purpose..

Sandboxed Compiles 要求 sharelatex 容器能够访问主机上的 Docker socket（通过绑定挂载），以便它可以管理这些兄弟编译容器。

工作原理

当启用 Sandboxed Compiles 时，Docker socket 会从主机挂载到 sharelatex 容器中，以便容器内的编译器服务可以在主机上创建新的 Docker 容器。然后，对于每个项目中每次编译运行，LaTeX 编译服务（CLSI）将执行以下操作：

• 将项目文件写出到 OVERLEAF_DATA_PATH.

• 中的某个位置 使用挂载的 Docker socket 创建一个新的 texlive

• 容器用于本次编译运行。 使用挂载的 Docker socket 创建一个新的 让 OVERLEAF_DATA_PATH.

• 容器从 使用挂载的 Docker socket 创建一个新的 下的位置读取项目数据并在该

容器内编译该项目。

启用 Sandboxed Compiles

对于 Toolkit 用户 要启用沙箱编译（也称为兄弟容器），请在:

overleaf-toolkit/config/overleaf.rc

文件中设置以下配置选项：
config/overleaf.rc

SERVER_PRO=true

SIBLING_CONTAINERS_ENABLED=true 5.0.3 对于 Docker Compose 用户 从 Overleaf CE/Server Pro 开始， 环境变量已从 SHARELATEX_*.

重新命名为 OVERLEAF_* 如果您使用的是 4.x 版本（或更早），请确保相应地为变量添加前缀（例如使用 SHARELATEX_MONGO_URL).

而不是
OVERLEAF_MONGO_URL
    版本: '2'
        #...
        services:
            sharelatex:
            volumes:
        - /data/overleaf_data:/var/lib/overleaf
            #...
            - /var/run/docker.sock:/var/run/docker.sock
            environment:
            DOCKER_RUNNER: "true"
            #...
        #...

SANDBOXED_COMPILES: "true"

SANDBOXED_COMPILES_HOST_DIR: "/data/overleaf_data/data/compiles" 更改 TexLive 镜像 对于中国大陆用户，您可以使用

ghcr.nju.edu.cn

• 来加速下载。 Overleaf Pro 使用三个环境变量来决定 Sandboxed Compiles 使用哪些 TeX Live 镜像： TEX_LIVE_DOCKER_IMAGE （必需），.

• 用于编译新项目的默认 TeX Live 镜像。此镜像必须包含在 Overleaf Pro 使用三个环境变量来决定 Sandboxed Compiles 使用哪些 TeX Live 镜像： ALL_TEX_LIVE_DOCKER_IMAGES

• （必需）， Overleaf Pro 使用三个环境变量来决定 Sandboxed Compiles 使用哪些 TeX Live 镜像： ALL_TEX_LIVE_DOCKER_IMAGE_NAMES 用于前端选项的镜像友好名称的逗号分隔列表。 要使用的 TeX Live 镜像的逗号分隔列表。如果使用 Overleaf Toolkit 来部署，这些镜像将被下载或更新。要跳过下载，请在 overleaf-toolkit/config/overleaf.rc.

中设置 SIBLING_CONTAINERS_PULL=false 当使用 （必需），.

bin/up

命令启动您的 Overleaf Pro 实例时，Toolkit 将自动拉取

中列出的所有镜像。
下面是一个示例，我们将新项目默认设置为使用 TeX Live 2025，同时保留 2024 供现有项目使用。
config/variables.env

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 2024TEX_LIVE_DOCKER_IMAGE=ghcr.io/ayaka-notes/texlive-full:2025.1 沙箱编译

强烈建议至少设置

两个 texlive-full 镜像 来加速下载。 。有关详细原因，请参见 （必需），:

• 可用的 TeX Live 镜像 这些是一系列为 Overleaf 专门优化的 TeX Live 镜像，也可以添加到 和 ghcr.io/ayaka-notes/texlive-full:2025.1

• （也可使用

• latest

• 标签）

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

替换为其他镜像站点，或者从 Docker Hub 切换到其他 texlive 镜像？

命令启动您的 Overleaf Pro 实例时，Toolkit 将自动拉取

不，我们不推荐这样做，因为配置相对复杂。如果您从镜像站点下载，您可以将镜像重命名为

ghcr.io/ayaka-notes/texlive-full 但是，如果您真的想使用您自己的镜像仓库，请添加：IMAGE_ROOT=hub.your.com/your-repo

• 然后，您需要确保 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
  if (process.env.SANDBOXED_COMPILES === 'true') {
  // 如果未提供，则设置默认的 image root

  let imageRootPath = process.env.IMAGE_ROOT || "ghcr.io/ayaka-notes";
  // [
  // 将 imageRoot 导出到 Settings
  Settings.imageRoot = imageRootPath
  // ]
  // allowedImageNames 应该是：
    //  { imageName: "texlive-2023:latest", imageDesc: "TeX Live 2023" },
      //  { imageName: "texlive-2022:latest", imageDesc: "TeX Live 2022" },
      Settings.allowedImageNames = parseTextExtensions(process.env.ALL_TEX_LIVE_DOCKER_IMAGES)
        .map((texImage, index) => ({
    }))
  
  imageName: texImage.split("/")[texImage.split("/").length - 1],
  imageDesc: parseTextExtensions(process.env.ALL_TEX_LIVE_DOCKER_IMAGE_NAMES)[index]

  || texImage.split(':')[1],
  // 最终，imageName 将与 imageRoot 组合，形成完整的镜像路径
    // 完整名称将类似于：ghcr.io/ayaka-notes/texlive-2023:latest
  }

  // 如果未提供，则设置默认的镜像名称
  if(!process.env.TEX_LIVE_DOCKER_IMAGE) {
  process.env.TEX_LIVE_DOCKER_IMAGE = imageRootPath + "/" + Settings.allowedImageNames[0].imageName
}

// 将 currentImageName 导出到 Settings

// 这是新创建项目的镜像名称 Settings.currentImageName = process.env.TEX_LIVE_DOCKER_IMAGE已知问题 使用:

6.0.1-ext-v3.3
时，我在

variables.env 中有以下设置：TEX_LIVE_DOCKER_IMAGE=texlive/texlive:latest-full ALL_TEX_LIVE_DOCKER_IMAGES=texlive/texlive:latest-full 这在

texlive/texlive:latest-full
下工作正常。然而，我拉取了另一个 texlive 镜像

danteev/texlive:2025-10-15

并将这两个变量都更改为该新镜像名称，但它不起作用： 

TEX_LIVE_DOCKER_IMAGE=danteev/texlive:2025-10-15 使用 ALL_TEX_LIVE_DOCKER_IMAGES=danteev/texlive:2025-10-15 中有以下设置： 在日志中，我看到以下内容：

{"name":"clsi","level":50,"err":{"message":"(HTTP code 404) no such container - No such image: texlive/texlive:latest-full ","name":"Error","stack":"Error: (HTTP code 404) no such container - No such image: texlive/texlive:latest-full ...

看起来在

中更新的设置没有生效。编译仍然尝试运行 镜像，而不是新的镜像。

我尝试过重启、删除容器并重新运行，但问题依旧。
有什么解决办法吗？
由于某些技术限制，如果您只设置了单个 Docker TeXLive 镜像，例如

texlive-fullA:latest ALL_TEX_LIVE_DOCKER_IMAGES=texlive/texliveA:latest-fullALL_TEX_LIVE_DOCKER_IMAGE_NAMES=TeXLiveA

我尝试过重启、删除容器并重新运行，但问题依旧。
有什么解决办法吗？
由于某些技术限制，如果您只设置了单个 Docker TeXLive 镜像，例如

TEX_LIVE_DOCKER_IMAGE=texlive/texliveA:latest-full 在运行一段时间的 Overleaf 实例后，您可能想将 TeXLive 镜像修改为.

texlive-fullB:latest

。然后，您会发现用户无法编译所有项目。 这是因为每个项目中用于沙箱编译的 TeXLive-Full 镜像名称会被保存在数据库中。 只有当用户切换其项目的 TeXLive 版本，例如从 2024 切换到 2025 时，数据库中的镜像名称才会被更改。

当 CLSI 编译一个项目时，它会使用数据库中找到的容器镜像名称直接编译该项目。

如果您仅提供一个 Docker 镜像，用户将无法修改用于编译项目的镜像。在这种情况下，您需要编写脚本以

手动修改数据库中所有用户项目的 TeXLive 镜像（在 mongoDB 中）。