> 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-tw/zhi-yuan/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 的 bind mount，這樣可避免變更應用程式中的路徑。以下是一個 `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 %}

為了避免這個錯誤，資料需要儲存在 volume 中，而不是 bind mount 的目錄（請參閱 `mongo` 映像文件說明以獲得更多詳情：<https://github.com/docker-library/docs/blob/master/mongo/content.md#where-to-store-data）。若要將資料儲存在掛載於> MongoDB 和 Redis 容器中的 Docker volumes 內，請將下列內容加入 `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 # oO0OoO0OoO0OoO Redis 正在啟動 oO0OoO0OoO0OoO
```

{% 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` 指令在 Community Edition 中預設為停用，因為所有編譯都會在同一個 `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://ayakaleaf-pro.ayaka.space/on-premises/zh-tw/zhi-yuan/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.