GitLab Git Large File Storage (LFS) の管理

Gitリポジトリのサイズを大きくしたり、パフォーマンスに影響を与えたりすることなく、大きなファイルを保存するには、Git Large File Storage (LFS) を使用します。LFSを有効または無効にしたり、LFSオブジェクトのローカルまたはリモートストレージを設定したり、ストレージタイプ間でオブジェクトを移行することができます。

Git LFSに関するユーザー向けドキュメントは、Git Large File Storageを参照してください。

前提要件:

• ユーザーは、Git LFS clientバージョン1.1.0以降、または1.0.2をインストールする必要があります。

LFSを有効または無効にする

LFSはデフォルトで有効になっています。無効にするには、次の手順に従います:

ローカルストレージパスの変更

Git LFSオブジェクトはサイズが大きくなる可能性があります。デフォルトでは、GitLabがインストールされているサーバーに保存されます。

デフォルトのローカルストレージパスの場所を変更するには、次の手順に従います:

リモートオブジェクトストレージへのLFSオブジェクトの格納

LFSオブジェクトをオブジェクトストレージに格納できます。これにより、ローカルディスクへの読み取りと書き込みを削減し、ディスク容量を大幅に解放できます。

統合されたオブジェクトストレージ設定を使用する必要があります。

オブジェクトストレージに移行する

LFSオブジェクトをローカルストレージからオブジェクトストレージに移行できます。この処理はバックグラウンドで実行され、ダウンタイムは不要です。

1. オブジェクトストレージを設定します。

2. LFSオブジェクトを移行します:

   Linuxパッケージ（Omnibus）

   sudo gitlab-rake gitlab:lfs:migrate

   Docker

   sudo docker exec -t <container name> gitlab-rake gitlab:lfs:migrate

   自己コンパイル（ソース）

   sudo -u git -H bundle exec rake gitlab:lfs:migrate RAILS_ENV=production

3. オプション。SQLコンソールを使用して、進行状況を追跡し、すべてのLFSオブジェクトが正常に移行したことを確認します。

   1. PostgreSQLコンソールを開きます:

      Linuxパッケージ（Omnibus）

      sudo gitlab-psql

      Docker

      sudo docker exec -it <container_name> /bin/bash
      gitlab-psql

      自己コンパイル（ソース）

      sudo -u git -H psql -d gitlabhq_production

   2. 次のSQLクエリを使用して、すべてのLFSファイルをオブジェクトストレージに移行したことを確認します。objectstgの数がtotalと同じである必要があります:

      gitlabhq_production=# SELECT count(*) AS total, sum(case when file_store = '1' then 1 else 0 end) AS filesystem, sum(case when file_store = '2' then 1 else 0 end) AS objectstg FROM lfs_objects;
      
      total | filesystem | objectstg
      ------+------------+-----------
       2409 |          0 |      2409

4. ディスク上のlfs-objectsディレクトリにファイルがないことを確認します:

   Linuxパッケージ（Omnibus）

   sudo find /var/opt/gitlab/gitlab-rails/shared/lfs-objects -type f | grep -v tmp | wc -l

   Docker

   /var/opt/gitlabを/srv/gitlabにマウントしている場合は、次のようになります:

   sudo find /srv/gitlab/gitlab-rails/shared/lfs-objects -type f | grep -v tmp | wc -l

   自己コンパイル（ソース）

   sudo find /home/git/gitlab/shared/lfs-objects -type f | grep -v tmp | wc -l

ローカルストレージへの移行の復元

ローカルストレージに移行して戻すには、次の手順に従います:

ピュアSSH転送プロトコル

git-lfs 3.0.0は、HTTPの代わりにSSHを転送プロトコルとして使用するためのサポートをリリースしました。SSHは、git-lfsコマンドラインツールによって透過的に処理されます。

ピュアSSHプロトコルのサポートが有効になっていて、gitがSSHを使用するように設定されている場合、すべてのLFS操作はSSH経由で行われます。たとえば、Git originがgit@gitlab.com:gitlab-org/gitlab.gitの場合などです。gitとgit-lfsが異なるプロトコルを使用するように設定することはできません。バージョン3.0以降、git-lfsは最初にピュアSSHプロトコルの使用を試み、サポートが有効になっていないか利用できない場合は、HTTPの使用にフォールバックします。

前提要件:

• git-lfsバージョンは、v3.5.1以降である必要があります。

Git LFSがピュアSSHプロトコルを使用するように切り替えるには、次の手順に従います:

ストレージ統計

グループおよびプロジェクトごとのLFSオブジェクトの合計ストレージ使用量は、次の手段で確認できます:

• 管理者エリア
• グループ APIおよびプロジェクト API

関連トピック

• ブログ投稿: Git LFS入門
• ユーザードキュメント: Git Large File Storage（LFS）

トラブルシューティング

見つからないLFSオブジェクト

見つからないLFSオブジェクトに関するエラーは、次のいずれかの状況で発生する可能性があります:

• ディスクからオブジェクトストレージにLFSオブジェクトを移行するときに、次のようなエラーメッセージが表示される:

  ERROR -- : Failed to transfer LFS object
  006622269c61b41bf14a22bbe0e43be3acf86a4a446afb4250c3794ea47541a7
  with error: No such file or directory @ rb_sysopen -
  /var/opt/gitlab/gitlab-rails/shared/lfs-objects/00/66/22269c61b41bf14a22bbe0e43be3acf86a4a446afb4250c3794ea47541a7

  （読みやすくするために改行を追加しました）。

• VERBOSE=1パラメータを指定してLFSオブジェクトの整合性チェックを実行する場合。

データベースには、ディスク上にないLFSオブジェクトのレコードが含まれている可能性があります。データベースエントリは、オブジェクトの新しいコピーがプッシュされるのを防ぐ可能性があります。これらの参照を削除するには、次の手順に従います:

1. Railsコンソールを起動します。

2. Railsコンソールで見つからないとレポートされているオブジェクトをクエリして、ファイルパスを返します:

   lfs_object = LfsObject.find_by(oid: '006622269c61b41bf14a22bbe0e43be3acf86a4a446afb4250c3794ea47541a7')
   lfs_object.file.path

3. ディスクまたはオブジェクトストレージに存在するかどうかを確認します:

   ls -al /var/opt/gitlab/gitlab-rails/shared/lfs-objects/00/66/22269c61b41bf14a22bbe0e43be3acf86a4a446afb4250c3794ea47541a7

4. ファイルが存在しない場合は、Railsコンソールを使用してデータベースレコードを削除します:

   # First delete the parent records and then destroy the record itself
   lfs_object.lfs_objects_projects.destroy_all
   lfs_object.destroy

複数の見つからないLFSオブジェクトを削除する

複数の見つからないLFSオブジェクトへの参照を一度に削除するには、次の手順に従います:

1. GitLab Railsコンソールを使用します。

2. 次のスクリプトを実行します:

   lfs_files_deleted = 0
   LfsObject.find_each do |lfs_file|
     next if lfs_file.file.file.exists?
     lfs_files_deleted += 1
     p "LFS file with ID #{lfs_file.id} and path #{lfs_file.file.path} is missing."
     # lfs_file.lfs_objects_projects.destroy_all     # Uncomment to delete parent records
     # lfs_file.destroy                              # Uncomment to destroy the LFS object reference
   end
   p "Count of identified/destroyed invalid references: #{lfs_files_deleted}"

このスクリプトは、データベース内の見つからないすべてのLFSオブジェクトを識別します。レコードを削除する前に:

• 最初に、検証のため​​に見つからないファイルに関する情報を出力します。
• コメント化された行は、誤った削除を防ぎます。コメントを解除すると、スクリプトは識別されたレコードを削除します。
• スクリプトは、比較のために削除されたレコードの最終カウントを自動的に出力します。

TLS v1.3サーバーでLFSコマンドが失敗する

GitLabを構成してTLS v1.2を無効にし、TLS v1.3接続のみを有効にする場合、LFS操作にはGit LFSクライアントバージョン2.11.0以降が必要です。バージョン2.11.0以前のGit LFSクライアントを使用すると、GitLabに次のエラーが表示されます:

batch response: Post https://username:***@gitlab.example.com/tool/releases.git/info/lfs/objects/batch: remote error: tls: protocol version not supported
error: failed to fetch some objects from 'https://username:[MASKED]@gitlab.example.com/tool/releases.git/info/lfs'

TLS v1.3で構成されたGitLabサーバー上でGitLab CIを使用する場合、含まれているGitLab Runner Helper imageで更新されたGit LFSクライアントバージョンを受信するには、13.2.0以降にGitLab Runnerにアップグレードする必要があります。

インストールされているGit LFSクライアントのバージョンを確認するには、次のコマンドを実行します:

git lfs version

`Connection refused` Connection refusedエラー

LFSオブジェクトをプッシュまたはミラーすると、次のようなエラーが表示される場合:

• dial tcp <IP>:443: connect: connection refused
• Connection refused - connect(2) for \"<target-or-proxy-IP>\" port 443

ファイアウォールまたはプロキシルールが接続を終了している可能性があります。

標準のUnixツールまたは手動のGitプッシュを使用した接続チェックが成功した場合、ルールはリクエストのサイズに関連している可能性があります。

PDFファイルの表示エラー

LFSがオブジェクトストレージで構成され、proxy_downloadがfalseに設定されている場合、WebブラウザーからPDFファイルをプレビューすると、エラーが表示されることがあります:

An error occurred while loading the file. Please try again later.

これは、クロスオリジンリソース共有 (CORS) の制限が原因で発生します: ブラウザがオブジェクトストレージからPDFファイルを読み込むことを試みますが、オブジェクトストレージプロバイダーは、GitLabドメインがオブジェクトストレージドメインと異なるため、リクエストを拒否します。

この問題を解決するには、オブジェクトストレージプロバイダーのCORS設定を構成して、GitLabドメインを許可します。詳細については、次のドキュメントを参照してください:

1. AWS S3
2. Google Cloud Storage
3. Azureストレージ。

Forking in progressメッセージでフォーク操作が停止する

複数のLFSファイルを含むプロジェクトをフォークしている場合、操作がForking in progressメッセージで停止する可能性があります。これが発生した場合は、次の手順に従って問題を診断し、解決してください:

1. 次のエラーメッセージについて、exceptions_json.logファイルを確認してください:

   "error_message": "Unable to fork project 12345 for repository
   @hashed/11/22/encoded-path -> @hashed/33/44/encoded-new-path:
   Source project has too many LFS objects"

   このエラーは、イシュー#476693で説明されているように、LFSファイルのデフォルト制限である100,000に達したことを示しています。

2. GITLAB_LFS_MAX_OID_TO_FETCH変数の値を大きくします:

   1. 設定ファイル/etc/gitlab/gitlab.rbを開きます。

   2. 変数を追加または更新します:

      gitlab_rails['env'] = {
         "GITLAB_LFS_MAX_OID_TO_FETCH" => "NEW_VALUE"
      }

      要件に基づいてNEW_VALUEを数値に置き換えます。

3. 変更を適用します。以下を実行します:

   sudo gitlab-ctl reconfigure

   詳細については、Linuxパッケージインストールの再構成を参照してください。

4. フォーク操作を繰り返します。