跳转到主要内容
如果你使用的是较早的版本,请在路径名中使用 sharelatex 代替 overleaf。
在 Overleaf 容器中挂载 NFS 文件系统在技术上是可行的,但不推荐这样做,因为它可能导致各种性能错误。编译时常见的一个错误是:
我们尤其不建议将基于 NFS 的文件系统用于临时数据,例如存放编译数据的目录。对于以下目录,我们建议使用本地临时磁盘,最好是本地 SSD。对于基于 docker-compose 的部署,我们建议直接覆盖来自 NFS 的绑定挂载,这样可以避免修改应用中的路径。下面是一个 docker-compose 配置片段示例,其中使用了挂载在 /scratch 的临时磁盘:
docker-compose excerpt
更新后无需将任何现有文件从 NFS 迁移到新位置。LaTeX 编译器会在再次完整编译时重新创建所有文件。更多详情请参阅:https://docs.overleaf.com/on-premises/support/troubleshooting#running-overleaf-with-an-nfs-filesystem
如果你在 Windows 或 macOS 上运行 Overleaf,mongo 服务可能无法重新启动,并出现以下错误:
Example error
当 MongoDB 数据是从不提供其所需语义的文件系统(例如 Windows 挂载的目录)绑定挂载而来时,就可能出现此错误。对于使用 WSL 2 的 Windows,请将 Toolkit 放在 Ubuntu 的 Linux 主目录下,并使用默认的绑定挂载。请参阅该平台指南中的 MongoDB 检查。对于需要 Docker 管理存储的新安装,以下覆盖配置使用了命名卷(请参阅 MongoDB 镜像存储指南)。在现有安装上,更改挂载不会迁移数据:请在切换之前备份并恢复数据库/缓存,否则服务将看到空卷。请将以下内容添加到 config/docker-compose.override.yml,并与任何现有配置合并:
config/docker-compose.override.yml
更多信息请参阅:https://docs.overleaf.com/on-premises/support/troubleshooting#running-overleaf-on-windows-or-macos-results-in-the-mongoservice-not-starting
使用 docker logs redis 命令输出一份日志。如果你看到 Fatal: Can't initialize Background Jobs 这一行,完整输出大致如下:
Redis log example
这可能与当前使用的 Docker 版本有关。更新到 >= 20.10.10 的版本应该可以解决此问题。更多信息请参阅 Redis 上游 issue:https://github.com/redis/redis/issues/12362参考:https://docs.overleaf.com/on-premises/support/troubleshooting#upgrading-to-redis-6.2-results-in-a-restart-loop
由于所有编译都在同一个 sharelatex 容器中进行,Community Edition 默认禁用了 \write18 命令;这是更安全的默认设置。如果你希望为 pdflatex 启用它,请在项目根目录下创建一个 latexmkrc 文件,内容如下:
latexmkrc
然后尝试重新编译。参考:https://docs.overleaf.com/on-premises/support/troubleshooting#please-verify-that-you-have-enabled-system-calls.-for-pdflatex-this-is-pdflatex-shell-escape
这些错误表示 mongo 容器不断崩溃并重启。bin/up 会先启动 MongoDB,然后在其中运行一条命令,而该命令会在容器重启期间失败。bin/docker-compose ps 会显示 mongo 服务处于 Restarting 状态。要找出真正的原因,请查看 MongoDB 日志:
常见原因包括:
  • CPU 不支持 AVX。在 x86-64 上,MongoDB 5.0 及更高版本需要 AVX,日志中会显示 MongoDB 5.0+ requires a CPU with AVX support。在虚拟机中,请将 CPU 类型设置为 host,以便透传 AVX。
  • Linux 内核版本为 6.19 至 7.0.13。MongoDB 拒绝在这些内核上启动。有关解决方法,请参阅软件要求。
  • 数据由较旧版本的 MongoDB 创建。MongoDB 8.0 无法直接打开 4.4 或 5.0 的数据。请一次升级一个主版本,参见更新 MongoDB。
这在 Ayakaleaf Pro 中是预期行为,可以忽略。当 OVERLEAF_IS_SERVER_PRO 不为 true 时会输出此消息,而 Ayakaleaf Pro 镜像正是这种情况。Ayakaleaf Pro 不需要此变量,因此请保持其未设置。
在 Overleaf 启动之前,容器会运行启动检查,其中任何一项失败时容器都会退出。Toolkit 以 restart: always 方式运行该容器,因此 Docker 会再次启动它,而同一项检查又会再次失败。启动输出中会指出失败的检查项:
常见原因包括:
  • Missing required secrets:在 config/variables.env 中设置 OVERLEAF_INVITE_TOKEN_SECRET,请参阅环境变量。
  • ShareLaTeX to Overleaf rebranding:配置中仍在使用 SHARELATEX_ 变量或路径;请按照消息提示将其重命名。
  • Checking can connect to mongo and redis 之后出现错误:Overleaf 无法连接到 MongoDB 或 Redis。请检查 bin/logs mongo 和 bin/logs redis。
排除原因后,运行 bin/up -d。
每次启动时,容器会依次运行其启动脚本,日志会以 *** Running /etc/my_init.d/<script>... 的形式列出每个脚本。910_initiate_doc_version_recovery 仅在曾经运行过 Overleaf 5.0.1 的实例上才有工作要做。在其他任何实例上,它会输出 No recovery of doc versions needed.,然后继续启动。其输出也会写入 OVERLEAF_DATA_PATH 中的 data/history/doc-version-recovery.log。退出代码以及 bin/docker-compose logs --tail=100 sharelatex 的末尾内容可以说明发生了什么:
  • 退出代码 2,且日志以 *** Init system aborted. 结尾:容器被停止了,例如通过 bin/stop、docker stop 或在 bin/up 中按 Ctrl+C。最后一行 Running 中的脚本只是当时正在运行的脚本,它并没有失败。请使用 bin/up -d 再次启动容器,并让启动过程完成。
  • 退出代码 1,且日志显示 *** /etc/my_init.d/<script> failed with status <n>:该脚本失败了,其错误信息就在上面几行。如果 910_initiate_doc_version_recovery 失败并显示 Detected unflushed changes while recovering doc versions,说明该实例运行过 5.0.1 且仍有未刷新的编辑;请按照官方的 Doc version recovery 指南操作。
当你的账户已登录但无权打开该页面时,就会显示此页面,例如由非管理员账户打开管理页面,或打开未与你共享的项目。要打开管理页面,请使用管理员账户登录。现有管理员可以将其他账户设为管理员,你也可以使用 create-user --admin 命令创建一个管理员账户,请参阅用户管理。在开发环境(develop/)中,管理页面还需要在 develop/dev.env 中设置 ADMIN_PRIVILEGE_AVAILABLE=true;Ayakaleaf Pro 镜像已默认设置该项。
最后修改于 2026年11月8日