更高的安全性
沙盒编译是 Ayakaleaf Pro 的推荐方式,因为许多 LaTeX 文档在 PDF 编译过程中需要或能够执行任意 shell 命令。如果使用沙盒编译,每次编译都会在一个独立的、能力受限的 Docker 容器中运行,该容器不与任何其他用户或项目共享,也无法访问主机网络等外部资源。更便捷的宏包管理
为了避免手动安装宏包,我们建议启用沙盒编译。这是 Ayakaleaf Pro 中的一项可配置设置,它能让你的用户在自己的本地部署中使用与 overleaf.com 相同的 TeX Live 环境。沙盒编译所使用的 TeX Live 镜像包含最常用的宏包和字体,并已针对我们的模板库进行测试,可确保与本地项目的最大兼容性。 启用沙盒编译后,你可以配置用户在项目中可选择的 TeX Live 版本,并为新项目设置默认的 TeX Live 镜像版本。如果你尝试在不使用沙盒编译的情况下运行 Ayakaleaf Pro,你的实例将默认使用基础方案(basic scheme)版本的 TeX Live 进行编译。这个基础版本很轻量,仅包含非常有限的 LaTeX 宏包子集,很可能会导致用户遇到缺少宏包的错误,尤其是在尝试使用预置模板时。
沙盒编译要求
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 镜像
中国大陆用户可以从 不要在 Toolkit 的环境变量设置中使用
ghcr.nju.edu.cn 镜像站拉取镜像以加快下载速度,然后为其打上对应的 ghcr.io 名称标签:ghcr.nju.edu.cn:请在其中保留 ghcr.io 名称。若要阻止 bin/up 再次从 ghcr.io 拉取镜像,请在 config/overleaf.rc 中设置 SIBLING_CONTAINERS_PULL=false。若要通过镜像站保持镜像为最新版本,请参阅自动更新 TeX Live Full 镜像。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.1ghcr.io/ayaka-notes/texlive-full:2024.1ghcr.io/ayaka-notes/texlive-full:2023.1ghcr.io/ayaka-notes/texlive-full:2022.1ghcr.io/ayaka-notes/texlive-full:2021.1ghcr.io/ayaka-notes/texlive-full:2020.1
能否使用其他镜像仓库
有些人可能会想,能否将 ghcr.io 替换为其他镜像站点,或者将 texlive 切换为 Docker Hub 上的其他镜像?
不,我们不建议这样做,因为配置相对复杂。如果你是从镜像站点下载的,可以将镜像重命名为 ghcr.io/ayaka-notes/texlive-full。
但是,如果你确实想使用自己的镜像仓库,请添加:
config/variables.env
your-repo 中,例如
hub.your.com/your-repo/texlive-full:2025.1hub.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,并将这两个变量都改为新镜像名称后,却无法正常工作:在日志中,我看到以下内容:
看起来由于一些技术限制,如果你只设置了单个 Docker TeXLive 镜像,例如variables.env中更新后的设置没有生效。编译仍然尝试运行texlive/texlive:latest-full镜像,而不是新镜像。 我尝试过重启、删除容器后重新运行,但问题依旧。 有什么解决办法吗?
texlive-fullA:latest
texlive-fullB:latest。此时,你会发现用户无法编译所有项目。
调试与报告
运行以下命令,通过 Toolkit 查看 clsi 日志:Q&A
沙盒容器、编译文件和 TeX Live 镜像会被自动删除吗?
沙盒容器、编译文件和 TeX Live 镜像会被自动删除吗?
回答:容器和编译文件会在一段时间后被删除;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>将其删除。
项目可以读取宿主机或 NAS 目录中的文件吗?
项目可以读取宿主机或 NAS 目录中的文件吗?
回答:不可以。每个编译容器只挂载其所属项目的编译目录(位于
/compile),并且没有网络,也没有任何设置可以将宿主机的其他目录挂载到其中。请改为将项目所需的文件上传到项目中。是否有 TeX Live basic 镜像?如何配置?
是否有 TeX Live basic 镜像?如何配置?
回答:有。
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 运行本身的耗时。
