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

​

完整專案歷史遷移

Community Edition 的 3.5.x 版本納入了完整專案歷史功能，此功能已在我們的 SaaS 服務 overleaf.com 中提供。

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

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

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

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

如需更多關於完整專案歷史的資訊，請參閱完整專案歷史文件。

​

遷移現有專案

1. 建立備份

   為您的執行個體建立完整備份，其中須包含 mongo、redis 與 sharelatex 目錄的一致性快照。

2. 更新

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

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

3. 啟動執行個體

   理想情況下，您會希望在遷移進行期間阻止使用者存取您的執行個體，以避免在需要還原備份時發生資料遺失。如何進行請參閱離線遷移。

4. 等待所有服務啟動並執行

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

   $ bin/docker-compose exec sharelatex /bin/bash -c "curl http://localhost:3000/status"
   web sharelatex is alive (api)%
   
5. 執行遷移指令碼

   # 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 可編輯大小上限的文件轉換為不可編輯的檔案）

   輸出應如下所示：

   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，且最後幾行會顯示沒有失敗：

   Projects failed:  0
   Done.
   

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

6. 重新開放網站

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

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

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

​

離線遷移

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

• 使用管理員帳號登入您的 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 新增了用於清除舊版歷史資料的指令碼。

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

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

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

重新執行清除指令碼是安全的。

​

疑難排解

我們會在此新增疑難排解建議。請注意，雖然我們通常只為 Server Pro 客戶提供支援，但考量到此遷移的性質，我們也會盡力協助遇到完整專案歷史遷移相關問題的 CE 使用者。

如果完整專案歷史遷移指令碼失敗（亦即以錯誤結束，或顯示失敗專案數不為零），請透過電子郵件 [e-mail] 將以下詳細資訊傳送給我們的支援團隊，內容包括：

主旨：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 找到這些檔案，並以如下方式匯出：

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

$ 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 指令碼，針對每個錯誤路徑各執行一次指令：

$ 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 指令碼：

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