> For the complete documentation index, see [llms.txt](https://ayakaleaf-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://ayakaleaf-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: resource busy or locked, unlink '/var/lib/overleaf/data/compiles/62f3d57bef7cf9005c364e75-62f3d57bef7cf9005c364e7a/.nfs573663533034825247625441'
```

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

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

{% code title="的临时磁盘的配置摘录" %}

```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` 命令输出一份日志副本。

如果您看到这一行 `Fatal: Can't initialize Background Jobs`，完整输出大致如下：

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

```
1:M 11 Feb 2024 15:19:22.609 # Server initialized
1:M 11 Feb 2024 15:19:22.609 # Fatal: Can't initialize Background Jobs.
1:C 11 Feb 2024 15:19:26.055 # oO0OoO0OoO0Oo Redis is starting 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.