> 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/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。

Toolkit：使用 `$ bin/upgrade` 腳本將 toolkit 升級至最新版本，並編輯 **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 Toolkit 使用者：
$ 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://ayakaleaf-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.