（v5.5.7 移行）バイナリファイルの移行

​

バイナリファイルの移行

Server Pro と Community Edition の次期メジャーバージョン 6.0 では、バイナリファイルのストレージ使用量が半分に削減されます。バージョン 5.5.7 にはオンライン移行が含まれており、アップグレードの一環としてダウンタイムを最小限に抑えられます。

Server Pro 4.x 以降、バイナリファイルは「filestore」のアクティブファイルストレージと完全なプロジェクト履歴システムの 2 か所に重複して保存されています。今後は、各ファイルのコピーは 1 つだけ、完全なプロジェクト履歴システムに保存されるようになります。

統合ストレージシステムへの移行は 2 つの要素で構成されます。移行のフェーズを制御する新しいフラグと、すべてのアクティブなプロジェクトおよびソフト削除されたプロジェクトを処理するスクリプトです。

フェーズ：

• OVERLEAF_FILESTORE_MIGRATION_LEVEL=0（デフォルト）：ファイルは filestore から読み取られ、filestore に書き込まれます。履歴へのファイルの書き込みは非同期で行われます。
• OVERLEAF_FILESTORE_MIGRATION_LEVEL=1：ファイルは履歴から読み取られ（filestore へのフォールバックあり）、filestore と履歴の両方に書き込まれます。OVERLEAF_FILESTORE_MIGRATION_LEVEL=0 へのダウングレードが可能です。
• OVERLEAF_FILESTORE_MIGRATION_LEVEL=2：ファイルの読み書きは履歴のみに対して行われます。「オフライン」で実施した場合を除き、OVERLEAF_FILESTORE_MIGRATION_LEVEL=1 へのダウングレードはできません。

データを S3 に保存し、filestore（OVERLEAF_FILESTORE_S3_ACCESS_KEY_ID）と履歴（OVERLEAF_HISTORY_S3_ACCESS_KEY_ID）で別々のサービスアカウントを使用している場合は、filestore ユーザーに blob 用の履歴バケット OVERLEAF_HISTORY_PROJECT_BLOBS_BUCKET への読み取りアクセス権を付与してください。今後は、filestore サービスがコンパイラーサービスからの読み取りに応答するようになります。

バイナリファイルの移行は、まず本番以外の環境/サンドボックス環境で実施することを強くおすすめします。

標準の Server Pro ライセンスでは、本番環境に加えて本番以外の環境/サンドボックス環境でもアプリケーションを 1 つ実行できます。テスト用に本番以外の環境を用意することを強くおすすめします。

Server Pro/CE バージョン 6.0 にアップグレードした後で以前のバージョンにダウングレードしたくなった場合は、システム全体のバックアップから復元する必要があります。

​

移行手順

1. バックアップを作成する

   mongo、redis、sharelatex の各ディレクトリの整合性のあるスナップショットを含め、インスタンスの完全なバックアップを作成します。

2. アップデートする

   Toolkit： $ bin/upgrade スクリプトを使用して toolkit を最新バージョンにアップグレードします。確認を求められたら、Upgrade image? のプロンプトには同意せず、代わりに config/version ファイルを手動で編集して値を 5.5.7 に設定します。

   従来の docker-compose.yml： sharelatex サービスのバージョンを 5.5.7 に更新します。

3. 影響を受けるプロジェクト数を見積もる

   # Overleaf Toolkit users:
   $ bin/docker-compose exec sharelatex /bin/bash -c "source /etc/overleaf/env.sh && source /etc/container_environment.sh && cd /overleaf/services/history-v1 && /sbin/setuser www-data node storage/scripts/back_fill_file_hash.mjs --report"
   
   # Legacy docker-compose.yml users:
   $ docker compose exec sharelatex /bin/bash -c "source /etc/overleaf/env.sh && source /etc/container_environment.sh && cd /overleaf/services/history-v1 && /sbin/setuser www-data node storage/scripts/back_fill_file_hash.mjs --report"
   

   出力例：

   Current status:
   - Total number of projects: 10
   - Total number of deleted projects: 5
   Sampling 1000 projects to estimate progress...
   Sampled stats for projects:
   - Sampled projects: 9 (90% of all projects)
   - Sampled projects with all hashes present: 5
   - Percentage of projects that need back-filling hashes: 44% (estimated)
   - Sampled projects have 11 files that need to be checked against the full project history system.
   - Sampled projects have 3 files that need to be uploaded to the full project history system (estimating 27% of all files).
   Sampled stats for deleted projects:
   - Sampled deleted projects: 4 (80% of all deleted projects)
   - Sampled deleted projects with all hashes present: 3
   - Percentage of deleted projects that need back-filling hashes: 25% (estimated)
   - Sampled deleted projects have 2 files that need to be checked against the full project history system.
   - Sampled deleted projects have 1 files that need to be uploaded to the full project history system (estimating 50% of all files).
   
4. プロジェクト履歴キューをフラッシュする

   # Overleaf Toolkit users:
   $ bin/docker-compose exec sharelatex /overleaf/bin/flush-history-queues
   
   # Legacy docker-compose.yml users:
   $ docker compose exec sharelatex /overleaf/bin/flush-history-queues
   

   すべてのプロジェクトがフラッシュされる（"project_ids":0）まで、フラッシュを繰り返します。

   found projects {"project_ids":0,"limit":100000,"ts":"2025-09-01T10:35:33.353Z"}
   total {"succeededProjects":0,"failedProjects":0}
   

   “failedProjects” がゼロでない場合は、サポートに連絡し、バイナリファイルの移行を続行しないでください。

5. 移行フェーズを 1 に進める

   Toolkit：config/variables.env で OVERLEAF_FILESTORE_MIGRATION_LEVEL=1 を設定します。

   従来の docker-compose.yml：sharelatex サービスの environment セクションで OVERLEAF_FILESTORE_MIGRATION_LEVEL: '1' を設定します。

6. 設定の変更を適用してインスタンスを起動する

   Toolkit：bin/up -d

   従来の docker-compose.yml：docker compose up -d

7. バイナリファイルへのアクセスを確認する

   ブラウザの Overleaf エディターでプロジェクトを開き、画像などのバイナリファイルを選択します。

8. 移行スクリプトを実行する

   # Overleaf Toolkit users:
   $ bin/docker-compose exec sharelatex /bin/bash -c "source /etc/overleaf/env.sh && source /etc/container_environment.sh && cd /overleaf/services/history-v1 && /sbin/setuser www-data node storage/scripts/back_fill_file_hash.mjs --all"
   
   # Legacy docker-compose.yml users:
   $ docker compose exec sharelatex /bin/bash -c "source /etc/overleaf/env.sh && source /etc/container_environment.sh && cd /overleaf/services/history-v1 && /sbin/setuser www-data node storage/scripts/back_fill_file_hash.mjs --all"
   

   sharelatex コンテナの外部にログを永続化している場合は、出力されるログファイルを書き込めるように、ログディレクトリの所有者が www-data ユーザー（uid=33）に設定されていることを確認してください。

   出力は次のようになります。

   Set UV_THREADPOOL_SIZE=16
   {"name":"default","hostname":"c25e9faaeb53","pid":971,"level":30,"backend":"fs","msg":"Loading backend","time":"2025-07-25T15:00:58.166Z","v":0}
   Writing logs into /var/log/overleaf/file-migration-2025-07-25T15_00_58_199Z.log
   Starting project file backup...
   Loaded global blobs: 0
   Processing non-deleted projects...
   Processed 1 projects, elapsed time 0s
   Done updating live projects
   Processing deleted projects...
   The collection deletedProjects appears to be empty.
   
   Done updating deleted projects
   Done.
   
   

   移行が成功すると、終了コード 0 が返され、最後の行に失敗がないことが示されます。

   Done.
   

   ログファイルは次のようになります（スクリプトが出力したパスを使用してください）。

   $ docker cp sharelatex:/var/log/overleaf/file-migration-2025-07-25T15_00_58_199Z.log .
   $ cat file-migration-2025-07-25T15_00_58_199Z.log
   {"name":"file-migration","hostname":"c25e9faaeb53","pid":971,"level":30,"end":"68839a8f577b9f009d947b27 (2025-07-25T14:54:07.000Z)","msg":"actually completed batch","time":"2025-07-25T15:00:58.379Z","v":0}
   {"name":"file-migration","hostname":"c25e9faaeb53","pid":971,"level":30,"time":"2025-07-25T15:00:58.383Z","LOGGING_IDENTIFIER":"4effa2000000000000000000","projects":1,"blobs":6,"filesWithHash":5,"filesWithoutHash":2,"filesDuplicated":0,"filesRetries":0,"filesFailed":0,"fileTreeUpdated":0,"badFileTrees":0,"globalBlobsCount":0,"globalBlobsEgress":0,"projectDeleted":0,"projectHardDeleted":0,"fileHardDeleted":0,"mongoUpdates":1,"readFromGCSCount":7,"readFromGCSIngress":28532,"writeToGCSCount":5,"writeToGCSEgress":300,"readFromGCSThroughputMiBPerSecond":0.14925639825786063,"eventLoop":{"idle":48.277844,"active":381.53244699971054,"utilization":0.8876763888372498},"diff":{"eventLoop":{"idle":48.223536,"active":134.04030200059555,"utilization":0.7354190687027976},"projects":1,"blobs":6,"filesWithHash":5,"filesWithoutHash":2,"filesDuplicated":0,"filesRetries":0,"filesFailed":0,"fileTreeUpdated":0,"badFileTrees":0,"globalBlobsCount":0,"globalBlobsEgress":0,"projectDeleted":0,"projectHardDeleted":0,"fileHardDeleted":0,"mongoUpdates":1,"readFromGCSCount":7,"readFromGCSIngress":28532,"writeToGCSCount":5,"writeToGCSEgress":300,"readFromGCSThroughputMiBPerSecond":0.14925639825786063},"deferredBatches":[],"msg":"file-migration stats","v":0}
   
9. インスタンスを停止する

   Toolkit：bin/stop sharelatex

   従来の docker-compose.yml：docker compose stop sharelatex

10. 古いファイルをアプリケーションからアクセスできないようにする

    これで古いファイルをセカンダリストレージに移動できます。後で問題が発生した場合に備えて、しばらくはファイルを保持しておくことをおすすめします。

    # Toolkit users:
    $ bin/docker-compose run --rm --entrypoint mv sharelatex --no-clobber --verbose /var/lib/overleaf/data/user_files /var/lib/overleaf/data/old_user_files
    
    # Legacy docker-compose.yml users:
    # We are assuming that you are using the default bind-mount in /var/lib/overleaf
    $ docker compose run --rm --entrypoint mv sharelatex --no-clobber --verbose /var/lib/overleaf/data/user_files /var/lib/overleaf/data/old_user_files
    # In case you are using selective bind-mounts, you can simply remove the bind-mount for /var/lib/overleaf/data/user_files inside the container.
    
11. 移行フェーズを 2 に進める

    Toolkit：config/variables.env で OVERLEAF_FILESTORE_MIGRATION_LEVEL=2 を設定します。

    従来の docker-compose.yml：sharelatex サービスの environment セクションで OVERLEAF_FILESTORE_MIGRATION_LEVEL: '2' を設定します。

12. 設定の変更を適用してインスタンスを起動する

    Toolkit：bin/up -d

    従来の docker-compose.yml：docker compose up -d

13. バイナリファイルへのアクセスを確認する

    ブラウザの Overleaf エディターでプロジェクトを開き、画像などのバイナリファイルを選択します。

​

オフライン移行

バイナリファイル移行スクリプトの実行中にユーザーがログインできないようにしたい場合は、次の手順に従ってください。

• 管理者アカウントで Overleaf インスタンスにログインします
• Admin ボタンをクリックし、Manage Site を選択します
• Open/Close Editor タブをクリックします
• Close Editor ボタンをクリックします
• Disconnect all users ボタンをクリックします

これを行うと、ログイン中のユーザーはメンテナンスページにリダイレクトされ、新たにログインページにアクセスしたユーザーにもメンテナンスページが表示され、ログインできなくなります。

インスタンスを再起動した場合は、これらの手順を繰り返す必要があります。サイトを再開するには、インスタンスを再起動するだけです。

​

オンライン移行

アプリケーションを稼働させたまま移行スクリプトを実行することも可能です。ただし、いくつか考慮すべき点があります。

• 移行処理は IO 負荷が高いため、スクリプトの実行中はリソース使用状況を監視してください。
• 処理の並行度が高いと、filestore サービスのイベントループがブロックされることがあり、ユーザー体験の低下につながります。まずはデフォルト値の --concurrency=10 と --concurrent-batches=1 で始めることをおすすめします。
• スクリプトはいつでも停止できます。再開すると、以前のプロジェクトを検証し、すでに処理済みのファイルはスキップします。これは、移行を比較的空いている時間帯（夜間など）に実行したい場合に便利です。

プロジェクト数が 1000 未満の場合（--report を付けて移行スクリプトを実行したときの出力を参照）は、メンテナンス時間帯にサイトを閉鎖してオフラインで移行を実行することをおすすめします。プロジェクト数が多い場合は、スクリプトを実行して進捗を監視し、状況に応じてオンラインで続けるかオフラインで続けるかを判断してください。

​

旧バイナリファイルデータのクリーンアップ

移行が完了し、プロジェクトが引き続きすべてのファイルにアクセスできることを確認したら、/var/lib/overleaf/data/user_files にある古いファイルストレージを削除できます。これらのファイルはしばらく保持しておくことを強くおすすめします。まずフォルダー名を変更して、アプリケーションからアクセスできないようにしておくとよいでしょう。

​

トラブルシューティング

ここにはトラブルシューティングのアドバイスを追加していく予定です。通常、サポートは Server Pro のお客様にのみ提供していますが、この移行の性質上、バイナリファイルの移行に特有の問題が発生した CE のお客様についても、できる限りサポートいたします。

バイナリファイル移行スクリプトが失敗した場合（つまり、エラーで終了した場合や、失敗したプロジェクトの数として 0 以外が出力された場合）は、次の詳細をメール [e-mail] でサポートチームにお送りください。

件名：Binary file migration problem

本文：

• インスタンスの種類：CE または Server Pro（該当しないものを削除）
• インストールの種類：Overleaf toolkit、docker-compose.yml、その他（該当しないものを削除）
• バージョン：5.5.x（toolkit の場合：$ cat config/version）
• 移行スクリプトの出力（コンテナ内の /var/log/overleaf にあるはずです）
• レポート：（--report を付けて移行スクリプトを実行）
• 処理済みプロジェクト：（スクリプトの最後の実行時点）
• 移行にかかった時間：
• bin/doctor の出力（toolkit を使用している場合）
• Toolkit のバージョン：$ git rev-parse HEAD（Toolkit を使用している場合）

filestore サービスのログファイルもメールに添付することをご検討ください。ログは sharelatex コンテナ内の /var/log/overleaf/filestore.log にあり、次のようにしてエクスポートできます。

$ docker cp sharelatex:/var/log/overleaf/filestore.log .
# replace <timestamp> with the timestamp as printed by the script
$ docker cp sharelatex:/var/log/overleaf/file-migration-<timestamp>.log .

添付する前に、ログファイルから機密情報を削除してください。

​

見つからないファイル

古いバージョンの Server Pro/CE では、ユーザーのアップロードが完了する前にファイルツリーのエントリが作成されていたため、アップロードが失敗するとファイルが見つからない状態になることがありました。すべてのファイルツリーを処理する際に、こうしたケースがいくつかエラーとして報告されることがあります。

見つからないファイルの数が少ない場合は、これらのケースを手動で確認し、ブラウザのエディターから削除することを検討してください。

見つからないファイルの数が多い場合は、サポートへの連絡をご検討ください。上記のメールテンプレートを参照してください。

​

壊れたファイルツリーを見つける

ファイルツリーが不正な形式になっているプロジェクト（たとえばファイル名が空の場合）では、移行が失敗することがあります。データベース内のすべてのプロジェクトをチェックする find_malformed_filetrees スクリプトを使って、こうした問題の一覧を取得できます。

$ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web && /sbin/setuser www-data node scripts/find_malformed_filetrees.mjs > /tmp/malformed-file-trees.json"

不正なパスを修正するには、fix_malformed_filetree スクリプトを使用し、不正なパスごとにコマンドを 1 回ずつ実行します。

$ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web && /sbin/setuser www-data node scripts/fix_malformed_filetree.mjs --logs=/tmp/malformed-file-trees.json"