跳转到主要内容
Ayakaleaf Pro 提供了在安全沙盒环境中运行编译的选项,以满足企业级安全需求。它通过在各自独立的安全 Docker 环境中运行每个项目来实现这一点。

更高的安全性

沙盒编译是 Ayakaleaf Pro 的推荐方式,因为许多 LaTeX 文档在 PDF 编译过程中需要或能够执行任意 shell 命令。如果使用沙盒编译,每次编译都会在一个独立的、能力受限的 Docker 容器中运行,该容器不与任何其他用户或项目共享,也无法访问主机网络等外部资源。
如果你尝试在不使用沙盒编译的情况下运行 Ayakaleaf Pro,编译将与其他并发编译一起在主 Docker 容器内运行,并且用户在运行 LaTeX 编译时对 sharelatex 容器的资源(文件系统、网络和环境变量)拥有完全的读写权限。

更便捷的宏包管理

为了避免手动安装宏包,我们建议启用沙盒编译。这是 Ayakaleaf Pro 中的一项可配置设置,它能让你的用户在自己的本地部署中使用与 overleaf.com 相同的 TeX Live 环境。沙盒编译所使用的 TeX Live 镜像包含最常用的宏包和字体,并已针对我们的模板库进行测试,可确保与本地项目的最大兼容性。 启用沙盒编译后,你可以配置用户在项目中可选择的 TeX Live 版本,并为新项目设置默认的 TeX Live 镜像版本。
如果你尝试在不使用沙盒编译的情况下运行 Ayakaleaf Pro,你的实例将默认使用基础方案(basic scheme)版本的 TeX Live 进行编译。这个基础版本很轻量,仅包含非常有限的 LaTeX 宏包子集,很可能会导致用户遇到缺少宏包的错误,尤其是在尝试使用预置模板时。
由于 Ayakaleaf Pro 被设计为可离线运行,因此没有自动化的方式将 overleaf.com 模板库集成到你的本地部署中;不过,可以按模板逐个手动完成此操作。有关具体做法的更多信息,请查看我们的从 overleaf.com 迁移模板指南:#transferring-templates-from-overleaf.com。
沙盒编译要求 sharelatex 容器能够(通过绑定挂载)访问主机上的 Docker socket,以便管理这些同级编译容器。

工作原理

启用沙盒编译后,Docker socket 将从主机挂载到 sharelatex 容器中,使容器内的编译服务能够在主机上创建新的 Docker 容器。然后,对于每个项目的每次编译运行,LaTeX 编译服务(CLSI)将执行以下操作:
  • 将项目文件写出到 OVERLEAF_DATA_PATH 内的某个位置。
  • 使用挂载的 Docker socket 为本次编译创建一个新的 texlive 容器。
  • 让 texlive 容器从 OVERLEAF_DATA_PATH 下的该位置读取项目数据。
  • 在 texlive 容器内编译项目。

启用沙盒编译

适用于 Toolkit 用户

要启用沙盒编译(也称为同级容器,Sibling containers),请在 overleaf-toolkit/config/overleaf.rc 中设置以下配置选项:
config/overleaf.rc
要禁用它们,请设置 SIBLING_CONTAINERS_ENABLED=false 并运行 bin/up。之后编译将在 sharelatex 容器内使用其基础 TeX Live 运行。

适用于 Docker Compose 用户

设置 TexLive 镜像

中国大陆用户可以从 ghcr.nju.edu.cn 镜像站拉取镜像以加快下载速度,然后为其打上对应的 ghcr.io 名称标签:
不要在 Toolkit 的环境变量设置中使用 ghcr.nju.edu.cn:请在其中保留 ghcr.io 名称。若要阻止 bin/up 再次从 ghcr.io 拉取镜像,请在 config/overleaf.rc 中设置 SIBLING_CONTAINERS_PULL=false。若要通过镜像站保持镜像为最新版本,请参阅自动更新 TeX Live Full 镜像。
Ayakaleaf Pro 使用三个环境变量来确定沙盒编译所使用的 TeX Live 镜像:
  • 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.1
  • 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 替换为其他镜像站点,或者将 texlive 切换为 Docker Hub 上的其他镜像?
不,我们不建议这样做,因为配置相对复杂。如果你是从镜像站点下载的,可以将镜像重命名为 ghcr.io/ayaka-notes/texlive-full。 但是,如果你确实想使用自己的镜像仓库,请添加:
config/variables.env
然后,你需要确保所有 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

自动同步 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,并将这两个变量都改为新镜像名称后,却无法正常工作:
在日志中,我看到以下内容:
看起来 variables.env 中更新后的设置没有生效。编译仍然尝试运行 texlive/texlive:latest-full 镜像,而不是新镜像。 我尝试过重启、删除容器后重新运行,但问题依旧。 有什么解决办法吗?
由于一些技术限制,如果你只设置了单个 Docker TeXLive 镜像,例如 texlive-fullA:latest
并且在运行 Overleaf 实例一段时间后,你可能想将 TeXLive 镜像修改为 texlive-fullB:latest。此时,你会发现用户无法编译所有项目。
这是因为每个项目所使用的 TeXLive-Full 镜像(用于沙盒编译)名称是持久化保存在数据库中的。只有当用户切换其项目的 TeXLive 版本(例如从 2024 切换到 2025)时,数据库中的镜像名称才会改变。 CLSI 编译项目时,会直接使用数据库中记录的容器镜像名称来编译项目。 如果你只提供一个 Docker 镜像,用户将无法修改用于编译项目的镜像。在这种情况下,你需要编写脚本,手动修改 MongoDB 中所有用户项目的 TeXLive 镜像。

调试与报告

运行以下命令,通过 Toolkit 查看 clsi 日志:
如果你在使用 TeX Live 镜像编译时遇到任何问题,请在此提交 issue: https://github.com/ayaka-notes/texlive-full/issues/new?template=texlive-image-bug.yml 为了帮助我们复现和排查问题,我们可能会请你将项目上传到 Overleaf。随后我们将拉取该项目,并通过 GitHub Action 运行编译测试。

Q&A

回答:容器和编译文件会在一段时间后被删除;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> 将其删除。
无需手动删除这些容器。
回答:不可以。每个编译容器只挂载其所属项目的编译目录(位于 /compile),并且没有网络,也没有任何设置可以将宿主机的其他目录挂载到其中。请改为将项目所需的文件上传到项目中。
回答:有。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 运行本身的耗时。
最后修改于 2026年11月13日