跳转到主要内容
沙箱编译在开发环境中的工作方式与生产镜像略有不同。开发环境已经配置好了沙箱编译;本页说明相关设置以及需要注意的三件事:
  • 文件权限问题
  • history-v1 与 filestore 之间的卷共享
  • 子目录问题

启用沙盒编译

沙箱编译默认开启。develop/docker-compose.yml 为 clsi 设置了 SANDBOXED_COMPILES=true,其余设置位于 develop/dev.env:
develop/dev.env
clsi 不会自行拉取镜像,因此请用 docker pull ghcr.io/ayaka-notes/texlive-full:2026.1(以及 :2025.1)拉取一次镜像。 LaTeX 在兄弟容器中以 TEXLIVE_IMAGE_USER 身份运行。在开发环境中该用户是 tex,这也是 clsi 的默认值(services/clsi/config/settings.defaults.cjs:154)。生产镜像在 SANDBOXED_COMPILES_SIBLING_CONTAINERS=true 时改用 www-data(server-ce/config/env.sh:15-21),因为在那里文件由 Overleaf 容器的 www-data 用户创建。
请不要使用你自行构建的镜像,否则可能会遇到一系列错误。

修复文件权限

clsi 容器以 root 身份启动,将 compiles、output 和 cache 文件夹交给 node 用户(uid 1000),然后以 node 身份运行 clsi(services/clsi/entrypoint.sh)。因此主机上的 develop/compiles 属于 uid 1000,与开发环境中 tex 的 uid 相同(参见 develop/pandoc/Dockerfile 中的注释)。使用上述设置,开发环境无需修改任何权限即可编译。 如果改为设置 TEXLIVE_IMAGE_USER=root,root(uid 0)没有写入 compiles 子文件夹的权限。这种情况下,请将 compiles 的所属组设为 root 并授予写权限,同时设置 setgid,使新建的子文件夹继承该所属关系:
bash
详细文档请参阅 services/clsi/README.md。

history-v1 与 filestore 之间的卷共享

本节和下一节的设置已包含在 develop/docker-compose.yml 和 develop/dev.env 中。只有在 develop/dev.rc 中设置 S3_ENABLED=false 时它们才起作用。使用默认的 S3_ENABLED=true 时,filestore 和 history-v1 会改为将这些文件保存在 RustFS 存储桶中(develop/s3/docker-compose.yml)。
默认情况下,filestore 充当 S3 与 Overleaf 中其他服务之间的桥梁。然而在 Overleaf CE 或 Server Pro 中,所有文件默认都存储在本地。因此,Overleaf 引入了一种非常取巧的方法。
server-ce/config/settings.js
同时,data/history 也被历史服务使用。这样,不同的微服务就可以共享同一份数据。这就是 develop 中的 filestore 服务挂载 history-v1 的 history-v1-buckets 卷的原因。没有它,clsi 将无法从 filestore 服务拉取 blob 文件。
develop/docker-compose.yml
filestore 通过 dev.env 中的以下设置找到存储桶:
develop/dev.env

使用子目录

filestore 总是以子目录方式读取历史 blob(services/filestore/app/js/KeyBuilder.js:58、:70)。生产镜像为 history-v1 开启了 useSubdirectories(server-ce/config/production.json),但 history-v1 的默认配置没有开启,所以在开发环境中 history-v1 会把所有数据扁平化存储。因此 dev.env 为 history-v1 设置了 NODE_CONFIG:
develop/dev.env
如果没有它,history-v1 会这样存储 project_blobs 文件:
将 useSubdirectories 设为 true 后,这些名称中的 _ 会变成 /,因此每个 blob 都存储在子文件夹中。
最后修改于 2026年11月20日