> ## 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. # （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](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/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` にアップグレードした後で以前のバージョンにダウングレードしたくなった場合は、システム全体のバックアップから復元する必要があります。 ### 移行手順 **mongo**、**redis**、**sharelatex** の各ディレクトリの整合性のあるスナップショットを含め、インスタンスの完全な[バックアップ](https://docs.overleaf.com/on-premises/maintenance/data-and-backups#performing-a-consistent-backup)を作成します。 Toolkit： `$ bin/upgrade` スクリプトを使用して **toolkit** を最新バージョンにアップグレードします。確認を求められたら、**Upgrade** image? のプロンプトには同意**せず**、代わりに **config/version** ファイルを手動で編集して値を `5.5.7` に設定します。 従来の docker-compose.yml： `sharelatex` サービスのバージョンを `5.5.7` に更新します。 ```bash wrap theme={null} # 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" ``` 出力例： ```text theme={null} 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). ``` ```bash wrap theme={null} # 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`）まで、フラッシュを繰り返します。 ```text theme={null} found projects {"project_ids":0,"limit":100000,"ts":"2025-09-01T10:35:33.353Z"} total {"succeededProjects":0,"failedProjects":0} ``` "failedProjects" がゼロでない場合は、サポートに連絡し、バイナリファイルの移行を続行しないでください。 Toolkit：`config/variables.env` で `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` を設定します。 従来の docker-compose.yml：`sharelatex` サービスの `environment` セクションで `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '1'` を設定します。 Toolkit：`bin/up -d` 従来の docker-compose.yml：`docker compose up -d` ブラウザの Overleaf エディターでプロジェクトを開き、画像などのバイナリファイルを選択します。 ```bash wrap theme={null} # 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** コンテナの外部に[ログを永続化](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/logging#persisting-logs)している場合は、出力されるログファイルを書き込めるように、ログディレクトリの所有者が `www-data` ユーザー（uid=33）に設定されていることを確認してください。 出力は次のようになります。 ```bash theme={null} 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` が返され、最後の行に失敗がないことが示されます。 ```bash theme={null} Done. ``` ログファイルは次のようになります（スクリプトが出力したパスを使用してください）。 ```bash wrap theme={null} $ 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} ``` Toolkit：`bin/stop sharelatex` 従来の docker-compose.yml：`docker compose stop sharelatex` これで古いファイルをセカンダリストレージに移動できます。後で問題が発生した場合に備えて、しばらくはファイルを保持しておくことをおすすめします。 ```bash wrap theme={null} # 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. ``` Toolkit：`config/variables.env` で `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` を設定します。 従来の docker-compose.yml：`sharelatex` サービスの `environment` セクションで `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '2'` を設定します。 Toolkit：`bin/up -d` 従来の docker-compose.yml：`docker compose up -d` ブラウザの 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 以外が出力された場合）は、次の詳細をメール [support+filestoremigration@overleaf.com](mailto:support+filestoremigration@overleaf.com?subject=Binary%20file%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) でサポートチームにお送りください。 件名：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` にあり、次のようにしてエクスポートできます。 ```bash theme={null} $ docker cp sharelatex:/var/log/overleaf/filestore.log . # replace with the timestamp as printed by the script $ docker cp sharelatex:/var/log/overleaf/file-migration-.log . ``` 添付する前に、ログファイルから機密情報を削除してください。 #### 見つからないファイル 古いバージョンの Server Pro/CE では、ユーザーのアップロードが完了する前にファイルツリーのエントリが作成されていたため、アップロードが失敗するとファイルが見つからない状態になることがありました。すべてのファイルツリーを処理する際に、こうしたケースがいくつかエラーとして報告されることがあります。 見つからないファイルの数が少ない場合は、これらのケースを手動で確認し、ブラウザのエディターから削除することを検討してください。 見つからないファイルの数が多い場合は、サポートへの連絡をご検討ください。上記のメールテンプレートを参照してください。 #### 壊れたファイルツリーを見つける ファイルツリーが不正な形式になっているプロジェクト（たとえばファイル名が空の場合）では、移行が失敗することがあります。データベース内のすべてのプロジェクトをチェックする `find_malformed_filetrees` スクリプトを使って、こうした問題の一覧を取得できます。 ```bash wrap theme={null} $ 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 回ずつ実行します。 ```bash wrap theme={null} $ 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" ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.