Overleaf CLSI 在 Linux 主机上 LaTeX 编译无法写入 compiles 目录的权限问题怎么排查【免费下载链接】overleafA web-based collaborative LaTeX editor项目地址: https://gitcode.com/GitHub_Trending/ov/overleaf在 Linux 主机上用 Docker 独立部署 Overleaf 的 CLSI 服务Common LaTeX Service Interface负责编译 LaTeX 文档时你可能会遇到这样一个问题CLSI 能正常启动但编译时 LaTeX 无法往主机的compiles目录写入内容导致编译失败。这个问题的根源是宿主机目录属主与容器内用户的 uid 不匹配本文依据 services/clsi/README.md 中的“Important note for Linux users”一节说明如何确认根因、修改目录权限并验证编译恢复。适用前提本排查路径对应文档中描述的独立部署形态CLSI 以 Docker 容器运行且设置了SANDBOXED_COMPILEStrue实际编译由 CLSI 拉起的 sibling containers 完成主机的compiles目录挂载进容器例如 README 示例中的-v $PWD/compiles:/overleaf/services/clsi/compiles对应环境变量SANDBOXED_COMPILES_HOST_DIR_COMPILESLaTeX 编译的工作目录TEXLIVE_IMAGE_USER控制 sibling container 中运行 LaTeX 的用户文档示例将其设为root。完整的独立部署命令构建镜像、拉取 TeX Live 镜像、docker run启动见 services/clsi/README.md 的 Installation 一节。从 Dockerfile 也能看到容器内compiles目录的属主是nodechown node:node cache compiles output见 services/clsi/Dockerfile。问题根因文档给出的解释链条如下排查时按此顺序核对CLSI 内的 Node 应用以用户node运行其 uid 为1000。因此挂载到容器里的compiles目录在宿主机上被创建为 uid、gid 均为1000的目录。如果你的宿主机上恰好也有一个 uid/gid 为1000的用户或组该用户/组就会成为compiles目录的属主。LaTeX 在 sibling containers 中以TEXLIVE_IMAGE_USER指定的用户运行。文档示例中该值设为rootuid0而 uid0对属主为1000:1000、且没有组写权限的compiles目录没有写权限无法写入compiles下的子目录。文档指出这是 Docker 在 Linux 上处理挂载目录属主的方式带来的结果可参考其提到的上游 moby issue并非 CLSI 代码缺陷。第一步确认 compiles 目录的属主在主机的compiles目录所在位置执行ls -lnd compiles文档给出的示例输出示例结果drwxr-xr-x 2 1000 1000 4096 Mar 19 12:41 compiles如果输出与示例一致——属主为1000:1000且组和其他用户只有读和进入权限drwxr-xr-x——再结合启动容器时TEXLIVE_IMAGE_USER的取值即可确认根因运行 LaTeX 的用户如 uid0的root没有权限向compiles的子目录写入。第二步修改 compiles 目录权限文档提供两种方案二选一即可。两组命令都需要sudo作用对象是宿主机上的compiles目录及其内容递归修改属主、为组增加写权限并在目录上设置 setgid 位使新创建的子目录继承该组属主。方案一把 root 组设为组属主文档标注的 quick fixsudo chown -R 1000:root compiles sudo chmod -R gw compiles sudo chmod gs compilessetgidgs的作用是让之后新建的子目录也继承root组的属主避免下次编译时新目录再次出现属主不一致。方案二创建 overleaf 组并让相关用户加入如果宿主机上没有 uid 为1000的用户需要先创建一个文档中的命令带# If required注释表示仅在该用户不存在时才需要执行sudo useradd --uid 1000 host-node-user # If required sudo groupadd overleaf sudo usermod -a -G overleaf root sudo usermod -a -G overleaf $(id -nu 1000) sudo chown -R 1000:overleaf compiles sudo chmod -R gw compiles sudo chmod gs compiles副作用说明这条路径会创建新组overleaf、修改root用户和 uid1000用户的组成员关系必要时还会新建host-node-user用户比方案一对宿主机的改动更大两种方案都不影响 CLSI 容器本身的运行。验证重新发起一次编译请求权限修改完成后按文档 API 一节的方式向 CLSI 发一个编译请求验证。把下面这段 JSON 存为data.json内容取自文档示例已按文档要求去掉注释{ compile: { options: { compiler: lualatex, timeout: 40 }, rootResourcePath: main.tex, resources: [ { path: main.tex, content: \\documentclass{article}\n\\begin{document}\nHello World\n\\end{document} } ] } }然后发送请求。文档说明 URL 中的 project-id 可以是任意值例如用my-test-projectcurl -X POST -H Content-Type: application/json -d data.json http://localhost:3013/project/my-test-project/compile文档给出的示例响应示例结果{ compile: { status: success, outputFiles: [ { type: pdf, url: http://localhost:3013/project/project-id/output/output.pdf }, { type: log, url: http://localhost:3013/project/project-id/output/output.log } ] } }响应中compile.status为success且返回了 pdf、log 的下载地址说明 LaTeX 已成功写入编译产物。边界与限制文档中根因分析和两组修复命令都针对“LaTeX 以rootuid0运行、compiles目录属主为1000:1000”这一组合TEXLIVE_IMAGE_USER的默认值是tex如果你改用了别的编译用户文档未覆盖该情况不能直接套用上述结论。该权限问题是 Docker 在 Linux 上挂载目录属主机制的固有表现文档指向了上游 moby issue修改权限是文档给出的处理方式而非升级 CLSI 可解决的 bug。本文只涉及SANDBOXED_COMPILEStrue的独立部署形态develop/docker-compose.yml 中的开发环境使用SANDBOXED_COMPILESfalse且clsi容器以user: root运行属主模型不同不适用本文的排查结论。【免费下载链接】overleafA web-based collaborative LaTeX editor项目地址: https://gitcode.com/GitHub_Trending/ov/overleaf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考