> For the complete documentation index, see [llms.txt](https://overleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://overleaf-pro.ayaka.space/on-premises/zh-cn/zhi-chi/troubleshooting.md).

# 故障排除

{% hint style="info" %}
如果你使用的是较早版本，请使用 `sharelatex` 而不是 `Overleaf` 在路径名中。
{% endhint %}

<details>

<summary>在 NFS 文件系统上运行 Overleaf</summary>

在 Overleaf 容器中挂载 NFS 文件系统在技术上是可行的，但不建议这样做，因为这可能会导致不同类型的性能错误。

编译过程中常见的一个错误是：

```
EBUSY: 资源忙或已锁定，unlink '/var/lib/overleaf/data/compiles/62f3d57bef7cf9005c364e75-62f3d57bef7cf9005c364e7a/.nfs573663533034825247625441'
```

特别是，我们建议不要为临时数据使用以 NFS 为后端的文件系统，例如用于编译数据的目录。我们建议对以下目录使用本地临时磁盘，最好是本地 SSD。

对于 `docker-compose` 的设置，我们建议直接覆盖来自 NFS 的绑定挂载，这样可以避免更改应用程序中的路径。下面是一个 `docker-compose` 使用挂载在 `/scratch`:

{% code title="docker-compose 片段" %}

```yaml
services:
  sharelatex:
    environment:
      SANDBOXED_COMPILES_HOST_DIR: /scratch/compiles/
    volumes:
      - nfs:/var/lib/overleaf/data
      - /scratch/cache/:/var/lib/overleaf/data/cache
      - /scratch/compiles/:/var/lib/overleaf/data/compiles
      - /scratch/output/:/var/lib/overleaf/data/output
      - /scratch/tmp/:/var/lib/overleaf/tmp
```

{% endcode %}

更新后，无需将任何现有文件从 NFS 迁移到新的位置。LaTeX 编译器可以在再次完整编译时重新生成所有文件。

更多详情请参见：<https://docs.overleaf.com/on-premises/support/troubleshooting#running-overleaf-with-an-nfs-filesystem>

</details>

<details>

<summary>在 Windows 或 macOS 上运行 Overleaf 会导致 `mongo` 服务无法启动</summary>

如果你在 Windows 或 macOS 上运行 Overleaf， `mongo` 该服务可能无法重启，并出现错误：

{% code title="错误示例" %}

```
在任何兼容性版本下都无法启动 WiredTiger。
原因：1：不允许的操作
```

{% endcode %}

为避免此错误，数据需要存储在卷中，而不是绑定挂载的目录中（详情请参见 `mongo` 镜像文档：<https://github.com/docker-library/docs/blob/master/mongo/content.md#where-to-store-data）。要将数据存储在挂载到> MongoDB 和 Redis 容器中的 Docker 卷内，请将以下内容添加到 `config/docker-compose.override.yml` （如果该文件尚不存在，请创建它）：

{% code title="config/docker-compose.override.yml" %}

```yaml
volumes:
  mongo-data:
  redis-data:

services:
  mongo:
    volumes:
      - mongo-data:/data/db

  redis:
    volumes:
      - redis-data:/data
```

{% endcode %}

更多信息请参见：<https://docs.overleaf.com/on-premises/support/troubleshooting#running-overleaf-on-windows-or-macos-results-in-the-mongoservice-not-starting>

</details>

<details>

<summary>升级到 Redis 6.2 会导致重启循环</summary>

使用 `docker logs redis` 命令输出一份日志副本。

如果你看到这一行 `致命错误：无法初始化后台作业`，完整输出将如下所示：

{% code title="Redis 日志示例" %}

```
1:M 11 Feb 2024 15:19:22.609 # 服务器已初始化
1:M 11 Feb 2024 15:19:22.609 # 致命错误：无法初始化后台作业。
1:C 11 Feb 2024 15:19:26.055 # oO0OoO0OoO0Oo Redis 正在启动 oO0OoO0OoO0Oo
```

{% endcode %}

这可能与当前使用的 Docker 版本有关。更新到 >= 20.10.10 的版本应可解决此问题。

更多信息请参见 Redis 上游问题：<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>

</details>

<details>

<summary>模板画廊预览/缩略图图片方向错误</summary>

有时，Server Pro 生成的预览/缩略图图片可能会以错误的方向创建，并且需要手动干预来修正。这些图片存储在 `/var/lib/overleaf/data/template_files/` (>= 5.0.3) 和 `/var/lib/sharelatex/data/template_files/` （更早版本）。

我们建议在进行任何更改之前先备份此文件夹。

你需要对每个受影响的模板执行以下步骤：

查找模板 ID：进入你实例的模板画廊 (/templates/all)，打开一个受影响的模板，并从 URL 中复制 ID（例如：<https://your-instance-url/templates/6645d346c224815e9460a695）。运行修正命令：在> Docker 主机上运行以下命令（将模板 ID 替换为你复制的 ID，并在适当时更新路径）：docker exec sharelatex /bin/bash -c "mogrify -rotate 90 /var/lib/overleaf/data/template\_files/6645d346c224815e9460a695\_\*{thumbnail,preview}"

参考：<https://docs.overleaf.com/on-premises/support/troubleshooting#incorrect-orientation-of-template-gallery-preview-thumbnail-images>

</details>

<details>

<summary>请确认你已启用系统调用。对于 pdflatex，这指的是 'pdflatex -shell-escape'。</summary>

该 `\write18` 命令在社区版中默认被禁用，因为所有编译都在同一个 `sharelatex` 容器中进行；这是更安全的默认设置。

如果你希望为 pdflatex 启用它，请在项目根目录下创建一个 `latexmkrc` 文件，内容如下：

{% code title="latexmkrc" %}

```perl
$pdflatex = 'pdflatex --shell-escape';
```

{% endcode %}

然后尝试重新编译。

参考：<https://docs.overleaf.com/on-premises/support/troubleshooting#please-verify-that-you-have-enabled-system-calls.-for-pdflatex-this-is-pdflatex-shell-escape>

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://overleaf-pro.ayaka.space/on-premises/zh-cn/zhi-chi/troubleshooting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.