リポジトリのストレージ

プラン: Free、Premium、Ultimate
提供形態: GitLab Self-Managed

GitLabは、リポジトリのストレージにリポジトリを保存します。リポジトリのストレージは次のいずれかです:

Gitalyノードを指すgitaly_addressで設定された物理ストレージ。
Gitaly Cluster (Praefect)にリポジトリを保存する仮想ストレージ。

リポジトリのストレージは、リポジトリが保存されているディレクトリを直接指すpathとして設定できます。しかし、リポジトリを含むディレクトリへGitLabが直接アクセスする方法は非推奨となりました。物理ストレージまたは仮想ストレージを介してリポジトリにアクセスするようにGitLabを設定する必要があります。

詳細:

Gitalyの設定については、Gitalyを設定するを参照してください。
Gitaly Cluster (Praefect)のConfigure Gitaly Cluster (Praefect)（Gitaly Cluster (Praefect)の構成）を参照してください。

ハッシュ化されたストレージ

ハッシュ化されたストレージは、プロジェクトのIDのハッシュに基づいて、プロジェクトをディスク上の場所に保存します。これにより、フォルダー構造が不変になり、URLからディスク構造への状態の同期が不要になります。つまり、グループ、ユーザー、またはプロジェクトの名前を変更した場合は、次のようになります:

必要な処理はデータベーストランザクションのみです。
即座に反映されます。

また、ハッシュは、リポジトリをディスク上でより均等に分散させる効果もあります。トップレベルディレクトリに含まれるフォルダーの数は、トップレベルのネームスペースの総数よりも少なくなります。

ハッシュ形式は、SHA256(project.id)で計算された、SHA256の16進数表現に基づいています。トップレベルのフォルダーは、ハッシュの最初の2文字を使用し、その下に次の2文字を使用した別のフォルダーが続きます。どちらも特別な@hashedフォルダーに保存されるため、既存のレガシーストレージプロジェクトとの共存が可能です。次に例を示します:

# Project's repository:
"@hashed/#{hash[0..1]}/#{hash[2..3]}/#{hash}.git"

# Wiki's repository:
"@hashed/#{hash[0..1]}/#{hash[2..3]}/#{hash}.wiki.git"

ハッシュ化されたストレージパスを変換する

Gitリポジトリに関する問題のトラブルシューティング、フックの追加、その他のタスクでは、人間が読めるプロジェクト名とハッシュ化されたストレージパスの間で変換が必要になります。次の変換が可能です:

プロジェクト名からハッシュ化されたパス

管理者は次のいずれかを使用して、プロジェクト名またはIDからプロジェクトのハッシュ化されたパスを調べることができます:

管理者エリア。
Railsコンソール。

管理者エリアでプロジェクトのハッシュ化されたパスを調べるには、次の手順に従います:

左側のサイドバーの下部で、管理者を選択します。新しいナビゲーションをオンにしている場合は、左側のサイドバーの下部にあるアバターを選択し、管理者を選択します。
概要 > プロジェクトを選択し、プロジェクトを選択します。
Relative path（相対パス）フィールドを探します。値は次のようになります:
```
"@hashed/b1/7e/b17ef6d19c7a5b1ee83b907c595526dcb1eb06db8227d650d5dda0a9f4ce8cd9.git"
```

Railsコンソールを使用してプロジェクトのハッシュ化されたパスを調べるには、次の手順に従います:

Railsコンソールを起動します。
次の例のようなコマンドを実行します（プロジェクトのIDまたは名前のいずれかを使用します）:
```
Project.find(16).disk_path
Project.find_by_full_path('group/project').disk_path
```

ハッシュ化されたパスからプロジェクト名

管理者は次のいずれかを使用して、ハッシュ化された相対パスからプロジェクト名を検索できます:

Railsコンソール。
*.gitディレクトリ内のconfigファイル。

Railsコンソールを使用してプロジェクト名を調べるには、次の手順に従います:

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

次の例のようなコマンドを実行します:

ProjectRepository.find_by(disk_path: '@hashed/b1/7e/b17ef6d19c7a5b1ee83b907c595526dcb1eb06db8227d650d5dda0a9f4ce8cd9').project

このコマンド内の引用符で囲まれた文字列は、GitLabサーバーで確認できるディレクトリツリーです。たとえば、デフォルトのLinuxパッケージインストールでは/var/opt/gitlab/git-data/repositories/@hashed/b1/7e/b17ef6d19c7a5b1ee83b907c595526dcb1eb06db8227d650d5dda0a9f4ce8cd9.gitのようになり、このディレクトリ名の末尾から.gitを除きます。

出力には、プロジェクトIDとプロジェクト名が含まれます。次に例を示します:

=> #<Project id:16 it/supportteam/ticketsystem>

ハッシュ化されたパスからプロジェクトのフルパスへの変換

Railsコンソールを使用してプロジェクトのフルパスを調べるには、次の手順に従います:

Railsコンソールを起動します。
次の例のようなコマンドを実行します:
```
ProjectRepository.find_by(disk_path: '@hashed/b1/7e/b17ef6d19c7a5b1ee83b907c595526dcb1eb06db8227d650d5dda0a9f4ce8cd9').project.full_path
```
このコマンド内の引用符で囲まれた文字列は、GitLabサーバー上にあるディレクトリツリーです。たとえば、デフォルトのLinuxパッケージインストールでは/var/opt/gitlab/git-data/repositories/@hashed/b1/7e/b17ef6d19c7a5b1ee83b907c595526dcb1eb06db8227d650d5dda0a9f4ce8cd9.gitのようになり、このディレクトリ名の末尾から.gitを除きます。

この出力には、プロジェクトのフルパスが含まれています。次に例を示します:

=> "it/supportteam/ticketsystem"

ハッシュ化されたオブジェクトプール

オブジェクトプールは、公開および内部プロジェクトのフォークを重複排除するために使用されるリポジトリで、元のプロジェクトのオブジェクトが含まれています。objects/info/alternatesを使用すると、元のプロジェクトとそのフォークは、共有オブジェクトに対してこのオブジェクトプールを使用します。詳細については、GitLab開発ドキュメントのGitオブジェクト重複排除の情報を参照してください。

オブジェクトは、元のプロジェクトでハウスキーピングが実行されたときに、元のプロジェクトからオブジェクトプールに移動されます。オブジェクトプールリポジトリは、@hashedではなく@poolsというディレクトリ内に、通常のリポジトリと同様に保存されます。

# object pool paths
"@pools/#{hash[0..1]}/#{hash[2..3]}/#{hash}.git"

@poolsディレクトリに保存されているオブジェクトプールリポジトリでは、git pruneまたはgit gcを実行しないでください。これらの操作を行うと、オブジェクトプールに依存している通常のリポジトリでデータが失われる可能性があります。

ハッシュ化されたオブジェクトプールストレージパスを変換する

Railsコンソールを使用してプロジェクトのオブジェクトプールを調べるには、次の手順に従います:

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

次の例のようなコマンドを実行します:

project_id = 1
pool_repository = Project.find(project_id).pool_repository
pool_repository = Project.find_by_full_path('group/project').pool_repository

# Get more details about the pool repository
pool_repository.source_project
pool_repository.member_projects
pool_repository.shard
pool_repository.disk_path

グループWikiストレージ

@hashedディレクトリに保存されているプロジェクトWikiとは異なり、グループWikiは@groupsというディレクトリに保存されます。プロジェクトWikiと同様に、グループWikiはハッシュ化されたストレージのフォルダー規則に従いますが、プロジェクトIDではなくグループIDのハッシュを使用します。

次に例を示します:

# group wiki paths
"@groups/#{hash[0..1]}/#{hash[2..3]}/#{hash}.wiki.git"

Gitaly Cluster (Praefect)ストレージ

Gitalyクラスター（Praefect）を使用している場合、Praefectがリポジトリストレージの場所を管理します。Praefectがリポジトリに使用する内部パスは、ハッシュ化されたパスとは異なります。詳細については、Praefectによって生成されるレプリカパスを参照してください。

リポジトリのファイルアーカイブキャッシュ

ユーザーは、次のいずれかを使用して、.zipや.tar.gzなどの形式でリポジトリのアーカイブをダウンロードできます:

GitLab UI。
リポジトリAPI。

GitLabは、このアーカイブをGitLabサーバー上のディレクトリのキャッシュに保存します。

Sidekiqで実行されているバックグラウンドジョブが、このディレクトリから古くなったアーカイブを定期的にクリーンアップします。このため、このディレクトリにはSidekiqサービスとGitLab Workhorseサービスの両方からアクセスできる必要があります。GitLab Workhorseが使用しているディレクトリにSidekiqがアクセスできない場合、そのディレクトリを含むディスクがいっぱいになるおそれがあります。

SidekiqとGitLab Workhorseに共有マウントを使用させたくない場合は、代わりに、このディレクトリからファイルを削除する個別のcronジョブを設定することもできます。

ファイルアーカイブキャッシュのデフォルトのディレクトリは、/var/opt/gitlab/gitlab-rails/shared/cache/archiveです。これは、/etc/gitlab/gitlab.rbのgitlab_rails['gitlab_repository_downloads_path']設定で変更できます。

キャッシュを無効にするには、次の手順に従います:

Pumaを実行しているすべてのノードで、環境変数WORKHORSE_ARCHIVE_CACHE_DISABLEDを設定します:
```
sudo -e /etc/gitlab/gitlab.rb
```
```
gitlab_rails['env'] = { 'WORKHORSE_ARCHIVE_CACHE_DISABLED' => '1' }
```
変更を有効にするため、更新されたノードを再設定します:
```
sudo gitlab-ctl reconfigure
```

Helmチャートは、キャッシュを/srv/gitlab/shared/cache/archiveに保存します。このディレクトリの設定は変更できません。

キャッシュを無効にするには、--set gitlab.webservice.extraEnv.WORKHORSE_ARCHIVE_CACHE_DISABLED="1"を使用するか、valuesファイルで次のように指定します:

gitlab:
  webservice:
    extraEnv:
      WORKHORSE_ARCHIVE_CACHE_DISABLED: "1"

オブジェクトストレージのサポート

次の表は、各ストレージタイプで保存可能なオブジェクトを示しています:

保存可能なオブジェクト	ハッシュ化されたストレージ	S3互換
リポジトリ	はい	–
添付ファイル	はい	–
アバター	いいえ	–
Pages	いいえ	–
Dockerレジストリ	いいえ	–
CI/CDジョブログ	いいえ	–
CI/CDアーティファクト	いいえ	はい
CI/CDキャッシュ	いいえ	はい
LFSオブジェクト	類似の仕組みで対応	はい
リポジトリプール	はい	–

S3互換のエンドポイントに保存されたファイルは、#{namespace}/#{project_name}というプレフィックスが付加されていない限り、ハッシュ化されたストレージと同じメリットを得られます。これは、CI/CDキャッシュやLFSオブジェクトに当てはまります。

アバター

各ファイルは、データベースで割り当てられたidに対応するディレクトリに保存されます。ユーザーアバターの場合、ファイル名は常にavatar.pngです。アバターが置き換えられると、Uploadモデルが破棄され、別のidを持つ新しいモデルが作成されます。

CI/CDアーティファクト

CI/CDアーティファクトはS3互換です。

LFSオブジェクト

GitLabにおけるLFSオブジェクトは、Gitの実装に従って、2文字と2階層のフォルダーを使用する類似のストレージパターンで保存されます:

"shared/lfs-objects/#{oid[0..1}/#{oid[2..3]}/#{oid[4..-1]}"

# Based on object `oid`: `8909029eb962194cfb326259411b22ae3f4a814b5be4f80651735aeef9f3229c`, path will be:
"shared/lfs-objects/89/09/029eb962194cfb326259411b22ae3f4a814b5be4f80651735aeef9f3229c"

LFSオブジェクトもS3互換です。

新しいリポジトリの保存先を設定する

複数のリポジトリのストレージを設定した後、新しいリポジトリの保存先を選択できます:

左側のサイドバーの下部で、管理者を選択します。新しいナビゲーションをオンにしている場合は、左側のサイドバーの下部にあるアバターを選択し、管理者を選択します。
設定 > リポジトリを選択します。
リポジトリのストレージを展開します。
新しいリポジトリのためのストレージノードフィールドに値を入力します。
変更を保存を選択します。

各リポジトリのストレージパスには、0 - 100のウェイトを割り当てることができます。新しいプロジェクトを作成すると、これらのウェイトに基づいて、リポジトリが作成されるストレージの場所が決まります。

あるリポジトリのストレージパスのウェイトが他のリポジトリのストレージパスに比べて高いほど、そのストレージが選択される頻度も高くなります（(storage weight) / (sum of all weights) * 100 = chance %）。

デフォルトでは、リポジトリのウェイトがまだ設定されていない場合は、以下のとおりです:

defaultのウェイトは100です。
その他すべてのストレージのウェイトは0です。

すべてのストレージのウェイトが0の場合（たとえば、defaultが存在しない場合）、GitLabは設定に関係なく、またdefaultが存在するかにかかわらず、新しいリポジトリをdefaultに作成しようとします。詳細については、トラッキングイシューを参照してください。

リポジトリを移動する

リポジトリを別のリポジトリストレージ（たとえば、defaultからstorage2）に移行するには、Gitaly Cluster（Praefect）への移行と同じプロセスを使用します。