GitLab Git ラージファイルストレージ(LFS) 管理

このページには、セルフマネージドGitLabインスタンスでのGit LFSの設定に関する情報が含まれています。Git LFSについてのユーザードキュメントは、Git Large File Storageをご覧ください。

前提条件：

LFSの有効化・無効化

LFSはデフォルトで有効になっています。無効にするには

Linux package (Omnibus)

  1. /etc/gitlab/gitlab.rb を編集します：

    # Change to true to enable lfs - enabled by default if not defined
gitlab_rails['lfs_enabled'] = false

  2. ファイルを保存して GitLab を再設定してください：

    sudo gitlab-ctl reconfigure
Helm chart (Kubernetes)

  1. Helm の値をエクスポートします：

    helm get values gitlab > gitlab_values.yaml

  2. gitlab_values.yaml を編集します：

    global:
  appConfig:
    lfs:
      enabled: false

  3. ファイルを保存して、新しい値を適用します：

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
Docker

  1. docker-compose.yml を編集します：

    version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['lfs_enabled'] = false

  2. ファイルを保存して GitLab を再起動します：

    docker compose up -d
Self-compiled (source)

  1. /home/git/gitlab/config/gitlab.yml を編集します：

    production: &base
  lfs:
    enabled: false

  2. ファイルを保存して GitLab を再起動します：

    # For systems running systemd
sudo systemctl restart gitlab.target
   
# For systems running SysV init
sudo service gitlab restart

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

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

note
Dockerインストールの場合は、データがマウントされるパスを変更できます。Helmチャートでは、オブジェクトストレージを使用してください。

デフォルトのローカルストレージのパスの場所を変更するには

Linux package (Omnibus)

  1. /etc/gitlab/gitlab.rb を編集します：

    # /var/opt/gitlab/gitlab-rails/shared/lfs-objects by default.
gitlab_rails['lfs_storage_path'] = "/mnt/storage/lfs-objects"

  2. ファイルを保存して GitLab を再設定してください：

    sudo gitlab-ctl reconfigure
Self-compiled (source)

  1. /home/git/gitlab/config/gitlab.yml を編集します：

    # /home/git/gitlab/shared/lfs-objects by default.
production: &base
  lfs:
    storage_path: /mnt/storage/lfs-objects

  2. ファイルを保存して GitLab を再起動します：

    # For systems running systemd
sudo systemctl restart gitlab.target
   
# For systems running SysV init
sudo service gitlab restart

LFS オブジェクトをリモートオブジェクトストレージに保存する方法

LFSオブジェクトをリモートオブジェクトストレージに格納することができます。これにより、ローカルディスクへの読み書きを減らし、ディスクスペースを大幅に解放できます。

GitLab 13.2以降では、連結オブジェクトストレージの設定を使用する必要があります。

オブジェクトストレージへのマイグレーション

LFSオブジェクトをローカルストレージからオブジェクトストレージにマイグレーションできます。処理はバックグラウンドで行われるため、ダウンタイムは必要ありません。

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

  2. LFS オブジェクトをマイグレーションします：

    Linux package (Omnibus)
    sudo gitlab-rake gitlab:lfs:migrate
    Docker
    sudo docker exec -t <container name> gitlab-rake gitlab:lfs:migrate
    Self-compiled (source)
    sudo -u git -H bundle exec rake gitlab:lfs:migrate RAILS_ENV=production
  3. オプション。PostgreSQLコンソールを使用して、進行状況を追跡し、すべてのジョブのLFSオブジェクトが正常にマイグレーションされたことを確認します。

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

      Linux package (Omnibus)
      sudo gitlab-psql
      Docker
      sudo docker exec -it <container_name> /bin/bash
gitlab-psql
      Self-compiled (source)
      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 package (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
    Self-compiled (source)
    sudo find /home/git/gitlab/shared/lfs-objects -type f | grep -v tmp | wc -l

ローカルストレージへのマイグレーション

note
Helmチャートでは、オブジェクトストレージを使用する必要があります。

ローカルストレージにマイグレーションを戻すには：

Linux package (Omnibus)

  1. LFS オブジェクトをマイグレーションします：

    sudo gitlab-rake gitlab:lfs:migrate_to_local

  2. /etc/gitlab/gitlab.rb を編集し、LFS オブジェクトのオブジェクトストレージを無効にします：

    gitlab_rails['object_store']['objects']['lfs']['enabled'] = false

  3. ファイルを保存して GitLab を再設定してください：

    sudo gitlab-ctl reconfigure
Docker

  1. LFS オブジェクトをマイグレーションします：

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

  2. docker-compose.yml を編集し、LFS オブジェクトのオブジェクトストレージを無効にします：

    version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['object_store']['objects']['lfs']['enabled'] = false

  3. ファイルを保存して GitLab を再起動します：

    docker compose up -d
Self-compiled (source)

  1. LFS オブジェクトをマイグレーションします：

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

  2. /home/git/gitlab/config/gitlab.yml を編集し、LFS オブジェクトのオブジェクトストレージを無効にします：

    production: &base
  object_store:
    objects:
      lfs:
        enabled: false

  3. ファイルを保存して GitLab を再起動します：

    # For systems running systemd
sudo systemctl restart gitlab.target
   
# For systems running SysV init
sudo service gitlab restart

ストレージの統計

グループとプロジェクトの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 コマンドが TLS v1.3 サーバで失敗します。

TLS v1.2を無効にし、TLS v1.3接続のみを有効にするようにGitLabを設定した場合、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イメージ経由で更新されたGit LFSクライアントのバージョンを受け取るには、GitLab Runner13.2.0以降にアップグレードする必要があります。

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

git lfs version

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.

これは、Cross-Origin Resource Sharing(CORS) の制限により発生します。ブラウザはオブジェクトストレージからPDFをロードしようとしますが、GitLabドメインとオブジェクトストレージドメインが異なるため、オブジェクトストレージプロバイダがリクエストを拒否します。

このイシューを解決するには、オブジェクトストレージプロバイダのCORS設定をGitLabドメインを許可するように設定してください。詳しくは以下のドキュメントをご覧ください：

  1. AWS S3
  2. Googleクラウドストレージ
  3. Azure Storage。

既知の制限

  • Git LFS クライアントのバージョン 1.1.0 以降、または 1.0.2 とのみ互換性があります。
  • ストレージ統計は、各 LFS オブジェクトをリンクしているプロジェクトごとに数えます。