> 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-tw/zhi-yuan/support-guides/full-project-history-migration.md).

# （v3.5.13 遷移）完整專案歷史遷移

## 完整專案歷史遷移

此 `3.5.x` 社群版的釋出版本包含 [完整專案歷史功能](https://www.overleaf.com/learn/latex/Using_the_History_feature) 這項功能已經在我們的 SaaS 服務中提供， [overleaf.com](http://overleaf.com/)

將您的執行個體升級到 Overleaf CE 之後 `3.5.13`，所有新專案預設都會使用完整專案歷史。現有專案將繼續使用舊版歷史系統，直到它們被遷移為止。

{% hint style="info" %}
如果您升級到 `3.5.13` 並決定降級到較早的版本，那麼您應該從完整的系統備份還原。建立於 `3.5.13` 的專案歷史與較早版本的 Overleaf CE 不相容。
{% endhint %}

新的完整專案歷史為使用者帶來了多項改進：

* 它會追蹤二進位檔案的變更，而這在舊版系統中不受支援。
* 支援標籤版本。
* 整體而言，系統更加穩健，資料遺失的機率更低。

請查看 [完整專案歷史文件](https://www.overleaf.com/learn/latex/Using_the_History_feature) 以取得更多關於完整專案歷史的資訊。

### 遷移現有專案

{% stepper %}
{% step %}

#### 建立備份

建立完整的 [備份](https://docs.overleaf.com/on-premises/maintenance/data-and-backups#performing-a-consistent-backup) ，包含您執行個體的一致快照與 **mongo**, **redis** 以及 **sharelatex** 目錄。
{% endstep %}

{% step %}

#### 更新

將 sharelatex/sharelatex 映像檔的版本更新為 3.5.13。

工具包：使用 `$ bin/upgrade` 腳本將工具包升級到最新版本，並編輯 **config/version** 為 3.5.13。
{% endstep %}

{% step %}

#### 啟動執行個體

理想情況下，您會希望在遷移進行時防止使用者存取您的執行個體，以避免在您需要還原備份時發生資料遺失。請參閱 [離線遷移](https://github.com/overleaf/overleaf/wiki/Full-Project-History-Migration/#offline-migration) 以了解更多關於如何執行此操作的資訊。
{% endstep %}

{% step %}

#### 等待所有服務啟動並執行

等待所有服務啟動並執行（請參見下方指令）

{% code overflow="wrap" %}

```bash
$ bin/docker-compose exec sharelatex /bin/bash -c "curl http://localhost:3000/status"
web sharelatex 已啟動（api）%
```

{% endcode %}
{% endstep %}

{% step %}

#### 執行遷移腳本

{% code overflow="wrap" %}

```bash
# Overleaf 工具包使用者：
$ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; VERBOSE_LOGGING=true node scripts/history/migrate_history.js --force-clean --fix-invalid-characters --convert-large-docs-to-file"

# 舊版 docker-compose.yml 使用者：
$ docker exec sharelatex /bin/bash -c "cd /overleaf/services/web; VERBOSE_LOGGING=true node scripts/history/migrate_history.js --force-clean --fix-invalid-characters --convert-large-docs-to-file"
```

{% endcode %}

`--force-clean` 會清除新系統中部分已遷移的專案歷史資料，這可讓您對先前嘗試失敗的個別專案重新執行遷移；

`--fix-invalid-characters` 會替換新歷史系統不支援的不可列印字元；

`--convert-large-docs-to-file` 會將超過 2MB 可編輯大小門檻的文件轉換為不可編輯的檔案）

輸出應如下所示：

```bash
已遷移專案  :  1
專案總數     :  51
剩餘專案 :  51
要遷移的歷史記錄總數：98
開始遷移...
正在遷移專案：63d29b5772dd80015a81bffe
遷移結果 { upgraded: true, historyType: 'NoneWithoutConversion' }
正在遷移專案：63d29c2e72dd80015a81c0a2
遷移結果 { upgraded: true, historyType: 'NoneWithoutConversion' }

// …

遷移完成
==================
已遷移專案： 51
失敗專案： 0
完成。
```

如果遷移成功，您將得到一個退出碼 `0`，且最後幾行會顯示沒有失敗：

```bash
失敗專案： 0
完成。
```

您可以重新開放使用者存取（請參見下一步）。如果有失敗，請參閱下方的疑難排解章節。如果問題無法立即修復，您仍然可以重新開放網站，而尚未遷移的專案將保留在舊版歷史系統中。
{% endstep %}

{% step %}

#### 重新開放網站

如果您選擇執行離線遷移，那麼您需要重新開放網站。如果您仍然登入，您需要：

1. 點擊 **管理員** 按鈕並選擇 **管理網站**
2. 點擊 **開啟／關閉編輯器** 分頁
3. 點擊 **重新開啟編輯器** 按鈕

如果您已關閉瀏覽器，則需要使用 `$ bin/up`.
{% endstep %}
{% endstepper %}

#### 離線遷移

為了在歷史遷移腳本執行時防止使用者登入，請依照以下步驟操作：

* 使用管理員帳號登入您的 Overleaf 執行個體
* 點擊 **管理員** 按鈕並選擇 **管理網站**
* 點擊 **開啟／關閉編輯器** 分頁
* 點擊 **關閉編輯器** 按鈕
* 點擊 **中斷所有使用者連線** 按鈕

完成後，如果有任何使用者已登入，他們會被重新導向至維護頁面，而任何造訪登入頁面的新使用者將會看到維護頁面，並且 **無法** 登入。

#### 線上遷移

可以在應用程式仍在執行時運行遷移腳本。需要考慮幾點：

* 遷移過程會大量消耗 CPU，當腳本執行時您應監控資源使用情況。
* 在較高的 `--concurrency` 值下，某些服務中的事件迴圈（`track-changes` 尤其是）可能會出現一些阻塞，這會導致使用體驗下降。我們建議先使用預設的 `--concurrency=1` 值。
* 您可以隨時停止腳本。再次啟動時，遷移會從您中斷的地方繼續。這在您偏好於較不忙的時段（例如夜間）執行遷移時很有用。

我們建議在專案數少於 1000 個專案時（`db.projects.count()`）關閉網站並在維護時段離線執行遷移。如果專案數量很多，您可以執行腳本並監控進度，然後根據您的具體情況決定是繼續線上還是離線執行。

#### 清理舊版歷史資料

Server Pro 中新增了一個用於清理舊版歷史資料的腳本 `3.5.6`, `4.0.6` 以及 `4.1.0`.

{% code overflow="wrap" %}

```bash
bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; node scripts/history/clean_sl_history_data.js"
```

{% endcode %}

此腳本可在所有專案都遷移完成後執行。它也可用於在進行線上遷移時釋放一些空間。

{% hint style="info" %}
在 3.5.13 版之前的 Server Pro 中，該腳本會刪除以下內容： `docHistory` 以及 `docHistoryIndex` 集合。MongoDB 在您刪除文件後不會釋放磁碟空間，反而會在未來為同一集合中的文件重複使用該空間。歷史遷移完成後，這些集合將不再有任何寫入，因此磁碟空間會保持未使用狀態。

如果您想再次讓磁碟空間可用，可以升級到 Server Pro 3.5.13（仍使用 3.x 發行版時）或 Server Pro 4.2.5（使用 4.x 發行版時），然後重新執行清理腳本。

Server Pro 中包含的清理腳本，最新的修補版發行 `3.5.x` 以及最新的 `4.x.x` 會在最後一步刪除這些集合。

重新執行清理腳本是安全的。
{% endhint %}

### 疑難排解

我們將在此加入疑難排解建議。請注意，雖然我們通常只為 Server Pro 客戶提供支援，但考量到這項遷移的性質，我們也會盡力支援遇到完整專案歷史遷移特定問題的 CE 客戶。

如果完整專案歷史遷移腳本失敗（即以錯誤結束，或輸出非零數量的失敗專案），請透過電子郵件將以下詳細資訊寄給我們的支援團隊 [support+historymigration@overleaf.com](mailto:support+historymigration@overleaf.com?subject=Full%20project%20history%20migration%20problem\&body=Instance%20Type%3A%20CE%20or%20Server%20Pro%20%28delete%20as%20appropriate%29%0A%0AInstallation%20Type%3A%20Overleaf%20toolkit%20or%20docker-compose.yml%20or%20other%20%28delete%20as%20appropriate%29%0A%0AScript%20output%3A%0A%0Abin%2Fdoctor%20output%20%28if%20using%20toolkit%29%3A%0A)，並詳細說明：

主旨：完整專案歷史遷移問題

* 執行個體類型：CE 或 Server Pro（視情況刪除）
* 安裝類型：Overleaf toolkit 或 `docker-compose.yml` 或其他（視情況刪除）
* 版本：3.5.x（toolkit： `$ cat config/version`)
* 遷移腳本輸出（應位於容器中的 `/overleaf/services/web`)
* 已遷移專案：（依遷移腳本輸出而定）
* 專案總數：（依遷移腳本輸出而定）
* 剩餘專案：（依遷移腳本輸出而定）
* 遷移持續時間：
* `bin/doctor` 輸出（使用 toolkit 時）
* Toolkit 版本： `$ git rev-parse HEAD` （使用 Toolkit 時）

請考慮將 `history-v1`, `project-history` 以及 `track-changes` 服務的日誌檔附加到電子郵件中。您可以在 `/var/log/sharelatex` 中的 `sharelatex` 容器內找到它們，並像這樣匯出：

```bash
$ docker cp sharelatex:/var/log/sharelatex/history-v1.log history-v1.log
$ docker cp sharelatex:/var/log/sharelatex/project-history.log project-history.log
$ docker cp sharelatex:/var/log/sharelatex/track-changes.log track-changes.log
```

在附加之前，請先從日誌檔中遮蔽任何敏感資訊。

#### 尋找損壞的檔案樹

對於具有格式錯誤檔案樹的專案，遷移可能會失敗（例如，檔名為空白）。您可以使用以下方式找出這些問題的清單： `find_malformed_filetrees` 腳本，該腳本會檢查資料庫中的所有專案：

{% code overflow="wrap" %}

```bash
$ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; node scripts/find_malformed_filetrees.js"
錯誤路徑：123456789012345678901234 rootFolder.0.1.2.3
錯誤路徑：123456789012345678901234 rootFolder.0.4.5.6
...
```

{% endcode %}

若要修正無效路徑，請使用 `fix_malformed_filetree` 腳本，對每個錯誤路徑執行一次指令：

{% code overflow="wrap" %}

```bash
$ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; node scripts/fix_malformed_filetree.js 123456789012345678901234 rootFolder.0.1.2.3"
$ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; node scripts/fix_malformed_filetree.js 123456789012345678901234 rootFolder.0.4.5.6"
...
```

{% endcode %}

#### 將專案從完整專案歷史降級為舊版歷史

如果有某個專案已遷移到完整專案歷史，但您想回到舊版歷史，請使用 `downgrade_project` 腳本，如下所示：

{% code overflow="wrap" %}

```bash
$ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; PROJECT_ID=YOUR
```

{% endcode %}


---

# 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-tw/zhi-yuan/support-guides/full-project-history-migration.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.