（v3.5.13 移行）完全なプロジェクト履歴の移行

​

完全なプロジェクト履歴の移行

Community Edition の 3.5.x リリースには、SaaS サービスである overleaf.com で既に提供されている完全なプロジェクト履歴（Full Project History）機能が含まれています。

インスタンスを 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）でイベントループがブロックされ、UX が低下する可能性があります。デフォルトの --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 のお客様にも、できる限りサポートを提供します。

完全なプロジェクト履歴の移行スクリプトが失敗した場合（つまり、エラーで終了した場合や、失敗したプロジェクト数として 0 以外の値が出力された場合）は、以下の詳細をメール [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 スクリプトを使用し、不正なパスごとにコマンドを 1 回ずつ実行します：

$ 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