> For the complete documentation index, see [llms.txt](https://ayakaleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ayakaleaf-pro.ayaka.space/on-premises/ja/sapto/support-guides/v5.5.7-migration-binary-files-migration.md).

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

## バイナリファイルの移行

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

Server Pro `4.x`では、バイナリファイルは 2 か所に保存されています。アクティブファイルのストレージである「filestore」と、完全なプロジェクト履歴システムです。今後は、各ファイルの単一コピーのみが完全なプロジェクト履歴システムに保存されます。

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

フェーズ:

* `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` （デフォルト）では、ファイルは 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`）：blob 用の履歴バケットへの読み取りアクセス権を filestore ユーザーに付与してください `OVERLEAF_HISTORY_PROJECT_BLOBS_BUCKET` 。今後は filestore サービスが compiler サービスからの読み取りを処理します。

{% hint style="warning" %}
バイナリファイルの移行は、本番環境ではなく非本番／サンドボックス環境で最初に実施することを強く推奨します。
{% endhint %}

{% hint style="success" %}
標準の Server Pro ライセンスでは、本番環境に加えて非本番／サンドボックス環境でアプリケーションを実行できます。テスト用に非本番環境を用意することを強く推奨します。
{% endhint %}

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

### 移行手順

{% stepper %}
{% step %}

#### バックアップを作成する

完全な [バックアップ](https://docs.overleaf.com/on-premises/maintenance/data-and-backups#performing-a-consistent-backup) 一貫したスナップショットを含むインスタンスの **mongo**, **redis** および **sharelatex** ディレクトリ。
{% endstep %}

{% step %}

#### 更新

**ツールキット:** 次を使用してください: `$ bin/upgrade` を最新バージョンにアップグレードするスクリプト **ツールキット** にします。求められたら、 **しないでください** プロンプトを確認 **アップグレード** image? — 代わりに、手動で **config/version** ファイルを編集して値を `5.5.7`.

**旧式の docker-compose.yml:** 次のバージョンを更新します： `sharelatex` サービスを `5.5.7`.
{% endstep %}

{% step %}

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

{% code overflow="wrap" %}

```bash
# Overleaf Toolkit ユーザー：
$ 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"

# 旧式の docker-compose.yml ユーザー向け:
$ 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"
```

{% endcode %}

出力例:

{% code fullWidth="false" %}

```
現在の状態:
- プロジェクト総数: 10
- 削除済みプロジェクト総数: 5
進捗を見積もるために 1000 件のプロジェクトをサンプリングしています...
プロジェクトのサンプル統計:
- サンプリングしたプロジェクト: 9（全プロジェクトの 90%）
- すべてのハッシュが存在するサンプリング済みプロジェクト: 5
- ハッシュのバックフィルが必要なプロジェクトの割合: 44%（推定）
- サンプリング済みプロジェクトには、完全なプロジェクト履歴システムで確認する必要があるファイルが 11 個あります。
- サンプリング済みプロジェクトには、完全なプロジェクト履歴システムにアップロードする必要があるファイルが 3 個あります（全ファイルの 27% と推定）。
削除済みプロジェクトのサンプル統計:
- サンプリングした削除済みプロジェクト: 4（削除済みプロジェクト全体の 80%）
- すべてのハッシュが存在するサンプリング済み削除済みプロジェクト: 3
- ハッシュのバックフィルが必要な削除済みプロジェクトの割合: 25%（推定）
- サンプリング済み削除済みプロジェクトには、完全なプロジェクト履歴システムで確認する必要があるファイルが 2 個あります。
- サンプリング済み削除済みプロジェクトには、完全なプロジェクト履歴システムにアップロードする必要があるファイルが 1 個あります（全ファイルの 50% と推定）。
```

{% endcode %}
{% endstep %}

{% step %}

#### プロジェクト履歴キューをフラッシュする

{% code overflow="wrap" %}

```bash
# Overleaf Toolkit ユーザー：
$ bin/docker-compose exec sharelatex /overleaf/bin/flush-history-queues

# 旧式の docker-compose.yml ユーザー向け:
$ docker compose exec sharelatex /overleaf/bin/flush-history-queues
```

{% endcode %}

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

```
検出されたプロジェクト {"project_ids":0,"limit":100000,"ts":"2025-09-01T10:35:33.353Z"}
合計 {"succeededProjects":0,"failedProjects":0}
```

{% hint style="danger" %}
「failedProjects」が 0 でない場合は、サポートに連絡し、バイナリファイルの移行を続行しないでください。
{% endhint %}
{% endstep %}

{% step %}

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

ツールキット: 設定 `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` を `config/variables.env`.

旧式の docker-compose.yml: 設定 `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '1'` の `環境` セクションの `sharelatex` サービス。
{% endstep %}

{% step %}

#### 構成変更を適用してインスタンスを起動する

ツールキット: `bin/up -d`

旧式の docker-compose.yml: `docker compose up -d`
{% endstep %}

{% step %}

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

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

{% step %}

#### 移行スクリプトを実行する

{% code overflow="wrap" %}

```bash
# Overleaf Toolkit ユーザー：
$ 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"

# 旧式の docker-compose.yml ユーザー向け:
$ 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"
```

{% endcode %}

{% hint style="danger" %}
もしログ [ファイルを保存しているなら](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/logging#persisting-logs) コンテナの外に **sharelatex** 、logs ディレクトリの所有者が `www-data` ユーザー（uid=33）に設定されていることを確認してください。そうすることで、出力されたログファイルを書き込めます。
{% endhint %}

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

```bash
UV_THREADPOOL_SIZE=16 を設定する
{"name":"default","hostname":"c25e9faaeb53","pid":971,"level":30,"backend":"fs","msg":"バックエンドを読み込み中","time":"2025-07-25T15:00:58.166Z","v":0}
ログを /var/log/overleaf/file-migration-2025-07-25T15_00_58_199Z.log に書き込んでいます
プロジェクトファイルのバックアップを開始しています...
グローバル blob を読み込みました: 0
削除されていないプロジェクトを処理中...
1 件のプロジェクトを処理しました、経過時間 0 秒
ライブプロジェクトの更新を完了しました
削除済みプロジェクトを処理中...
deletedProjects コレクションは空のようです。

削除済みプロジェクトの更新を完了しました
完了。

```

移行が成功すると、終了コードは `0`となり、最後の行に失敗なしが示されます：

```bash
完了。
```

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

{% code overflow="wrap" %}

```bash
$ 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":"実際にバッチを完了しました","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 統計","v":0}
```

{% endcode %}
{% endstep %}

{% step %}

#### インスタンスを停止する

ツールキット: `bin/stop sharelatex`

旧式の docker-compose.yml: `docker compose stop sharelatex`
{% endstep %}

{% step %}

#### 古いファイルをアプリケーションからアクセス不可にする

これで古いファイルを二次ストレージに移動できます。後で問題が発生した場合に備えて、しばらくファイルを残しておくことをお勧めします。

{% code overflow="wrap" %}

```bash
# Toolkit ユーザー向け:
$ bin/docker-compose run --rm --entrypoint mv sharelatex --no-clobber --verbose /var/lib/overleaf/data/user_files /var/lib/overleaf/data/old_user_files

# 旧式の docker-compose.yml ユーザー向け:
# /var/lib/overleaf のデフォルトの bind-mount を使用していると想定しています
$ docker compose run --rm --entrypoint mv sharelatex --no-clobber --verbose /var/lib/overleaf/data/user_files /var/lib/overleaf/data/old_user_files
# 選択的 bind-mount を使用している場合は、コンテナ内の /var/lib/overleaf/data/user_files の bind-mount を単純に削除できます。
```

{% endcode %}
{% endstep %}

{% step %}

#### 移行フェーズを 2 に進める

ツールキット: 設定 `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` を `config/variables.env`.

旧式の docker-compose.yml: 設定 `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '2'` の `環境` セクションの `sharelatex` サービス。
{% endstep %}

{% step %}

#### 構成変更を適用してインスタンスを起動する

ツールキット: `bin/up -d`

旧式の docker-compose.yml: `docker compose up -d`
{% endstep %}

{% step %}

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

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

#### オフライン移行

バイナリファイル移行スクリプトの実行中にユーザーのログインを防ぎたい場合は、次の手順に従ってください:

* 管理者アカウントで Overleaf インスタンスにログインします
* クリックしてください **管理者** ボタンを押して、次を選択します **サイトを管理**
* クリックしてください **エディタを開く/閉じる** タブ
* クリックしてください **エディタを閉じる** ボタン
* クリックしてください **すべてのユーザーを切断** ボタン

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

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

#### オンライン移行

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

* 移行プロセスは 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)、以下の内容を記載してください：

件名: バイナリファイル移行の問題

本文:

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

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

```bash
$ docker cp sharelatex:/var/log/overleaf/filestore.log .
# <timestamp> はスクリプトに表示されたタイムスタンプに置き換えてください
$ docker cp sharelatex:/var/log/overleaf/file-migration-<timestamp>.log .
```

添付する前に、ログファイル内の機密情報を必ずマスキングしてください。

#### 不足しているファイル

古いバージョンの Server Pro/CE では、ユーザーのアップロード完了前に file-tree エントリが作成されることがあり、アップロードが失敗するとファイルが欠落しているように見える原因になります。すべての file-tree を処理するときに、これらのケースの一部がエラーとして報告されることがあります。

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

不足ファイル数が多い場合は、上記のメールテンプレートを参照してサポートに連絡することを検討してください。

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

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

{% code overflow="wrap" %}

```bash
$ 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"
```

{% endcode %}

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

{% code overflow="wrap" %}

```bash
$ 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"
```

{% endcode %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ayakaleaf-pro.ayaka.space/on-premises/ja/sapto/support-guides/v5.5.7-migration-binary-files-migration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.