> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

## 完整專案歷史遷移

Community Edition 的 `3.5.x` 版本納入了[完整專案歷史功能](https://www.overleaf.com/learn/latex/Using_the_History_feature)，此功能已在我們的 SaaS 服務 [overleaf.com](http://overleaf.com/) 中提供。

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

<Info>
  如果您升級至 `3.5.13` 後決定降級至較早的版本，則應從完整的系統備份進行還原。在 `3.5.13` 中建立之專案的歷史與較早版本的 Overleaf CE 不相容。
</Info>

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

* 能追蹤二進位檔案的變更，這是舊版系統所不支援的。
* 支援標籤版本。
* 系統整體更加穩健，資料遺失的機率更低。

如需更多關於完整專案歷史的資訊，請參閱[完整專案歷史文件](https://www.overleaf.com/learn/latex/Using_the_History_feature)。

### 遷移現有專案

<Steps>
  <Step title="建立備份">
    為您的執行個體建立完整[備份](https://docs.overleaf.com/on-premises/maintenance/data-and-backups#performing-a-consistent-backup)，其中須包含 **mongo**、**redis** 與 **sharelatex** 目錄的一致性快照。
  </Step>

  <Step title="更新">
    將 sharelatex/sharelatex 映像檔版本更新至 3.5.13。

    Toolkit：使用 `$ bin/upgrade` 指令碼將 Toolkit 升級至最新版本，並將 **config/version** 編輯為 3.5.13。
  </Step>

  <Step title="啟動執行個體">
    理想情況下，您會希望在遷移進行期間阻止使用者存取您的執行個體，以避免在需要還原備份時發生資料遺失。如何進行請參閱[離線遷移](https://github.com/overleaf/overleaf/wiki/Full-Project-History-Migration/#offline-migration)。
  </Step>

  <Step title="等待所有服務啟動並執行">
    等待所有服務啟動並執行（請參閱下方指令）

    ```bash wrap theme={null}
    $ bin/docker-compose exec sharelatex /bin/bash -c "curl http://localhost:3000/status"
    web sharelatex is alive (api)%
    ```
  </Step>

  <Step title="執行遷移指令碼">
    ```bash wrap theme={null}
    # Overleaf Toolkit users:
    $ 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"

    # legacy docker-compose.yml users:
    $ 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"
    ```

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

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

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

    輸出應如下所示：

    ```bash theme={null}
    Migrated Projects  :  1
    Total Projects     :  51
    Remaining Projects :  51
    Total history records to migrate: 98
    Starting migration...
    Migrating project: 63d29b5772dd80015a81bffe
    migration result { upgraded: true, historyType: 'NoneWithoutConversion' }
    Migrating project: 63d29c2e72dd80015a81c0a2
    migration result { upgraded: true, historyType: 'NoneWithoutConversion' }

    // …

    Migration complete
    ==================
    Projects migrated:  51
    Projects failed:  0
    Done.
    ```

    如果遷移成功，您會得到結束代碼 `0`，且最後幾行會顯示沒有失敗：

    ```bash theme={null}
    Projects failed:  0
    Done.
    ```

    您可以重新開放使用者存取（請參閱下一步）。如果有失敗的情況，請參閱下方的疑難排解章節。即使問題未能立即修正，您仍可重新開放網站，未遷移的專案會繼續使用舊版歷史系統。
  </Step>

  <Step title="重新開放網站">
    如果您選擇進行離線遷移，則需要重新開放網站。如果您仍處於登入狀態，需要：

    1. 點選 **Admin** 按鈕並選擇 **Manage Site**
    2. 點選 **Open/Close Editor** 分頁
    3. 點選 **Reopen Editor** 按鈕

    如果您已關閉瀏覽器，則需要使用 `$ bin/up` 重新啟動網站。
  </Step>
</Steps>

#### 離線遷移

若要在歷史遷移指令碼執行期間阻止使用者登入，請依照以下步驟進行：

* 使用管理員帳號登入您的 Overleaf 執行個體
* 點選 **Admin** 按鈕並選擇 **Manage Site**
* 點選 **Open/Close Editor** 分頁
* 點選 **Close Editor** 按鈕
* 點選 **Disconnect all users** 按鈕

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

#### 線上遷移

您可以在應用程式仍在執行時執行遷移指令碼。但有幾點需要注意：

* 遷移過程會大量使用 CPU，在指令碼執行期間您應監控資源使用情況。
* 若 `--concurrency` 值設得較高，部分服務（特別是 `track-changes`）的事件迴圈可能會發生阻塞，導致使用者體驗下降。我們建議從預設的 `--concurrency=1` 值開始。
* 您可以隨時停止指令碼。再次啟動時，遷移會從您中斷的地方繼續進行。如果您偏好在較不繁忙的時段（例如夜間）執行遷移，這會很有幫助。

當您的專案數量少於 1000 個（`db.projects.count()`）時，我們建議關閉網站，並在維護時段內以離線方式執行遷移。如果專案數量很多，您可以先執行指令碼並監控其進度，再根據您的具體情況決定繼續以線上或離線方式執行。

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

Server Pro `3.5.6`、`4.0.6` 與 `4.1.0` 新增了用於清除舊版歷史資料的指令碼。

```bash wrap theme={null}
bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; node scripts/history/clean_sl_history_data.js"
```

此指令碼可以在所有專案完成遷移後執行，也可以在進行線上遷移時用來釋放部分空間。

<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` 版本所附的清除指令碼，會在最後一步刪除這些集合。

  重新執行清除指令碼是安全的。
</Info>

### 疑難排解

我們會在此新增疑難排解建議。請注意，雖然我們通常只為 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) 將以下詳細資訊傳送給我們的支援團隊，內容包括：

主旨：Full project history migration problem

* 執行個體類型：CE 或 Server Pro（請刪除不適用者）
* 安裝類型：Overleaf toolkit、`docker-compose.yml` 或其他（請刪除不適用者）
* 版本：3.5.x（toolkit：`$ cat config/version`）
* 遷移指令碼輸出（應位於容器中的 `/overleaf/services/web` 下）
* Migrated Projects：（依遷移指令碼輸出）
* Total Projects：（依遷移指令碼輸出）
* Remaining Projects：（依遷移指令碼輸出）
* 遷移所花費的時間：
* `bin/doctor` 輸出（使用 toolkit 時）
* Toolkit 版本：`$ git rev-parse HEAD`（使用 Toolkit 時）

建議您在電子郵件中附上 `history-v1`、`project-history` 與 `track-changes` 服務的日誌檔。您可以在 `sharelatex` 容器內的 `/var/log/sharelatex` 找到這些檔案，並以如下方式匯出：

```bash theme={null}
$ 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` 指令碼檢查資料庫中的所有專案，列出這些問題：

```bash wrap theme={null}
$ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; node scripts/find_malformed_filetrees.js"
BAD PATH: 123456789012345678901234 rootFolder.0.1.2.3
BAD PATH: 123456789012345678901234 rootFolder.0.4.5.6
...
```

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

```bash wrap theme={null}
$ 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"
...
```

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

如果有專案已遷移至完整專案歷史，但您想回到舊版歷史，請依照以下方式使用 `downgrade_project` 指令碼：

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.