• 推奨
• 背景情報
• ファイルを保存する場所
• ダイレクトアップロードの実装
  • Workhorseルーティングルールの追加
  • 事前承認エンドポイントの追加
• アップロードの処理
• CarrierWaveアップローダー
  • オプションのアップローダの動作
  • CarrierWaveストレージエンジン
  • CarrierWaveファイルのライフサイクル
• GitLabによるCarrierWaveの修正
  • ストレージエンジン間でのデータのマイグレーション
  • Workhorse 経由での直接アップロード
• テーブル
  • フィーチャーバケットの詳細
  • CarrierWaveインテグレーション

アップロードガイド新規アップロードの追加

推奨

• アップローダを作成する際は、そのアップローダを AttachmentUploader
• アップローダをこのドキュメントのテーブルに追加します。
• 新しいオブジェクトストレージのバケットを追加しないでください。
• 直接アップロードの実装
• アップロードを処理する必要がある場合は、その処理場所を決定します。

背景情報

• CarrierWave アップローダ
• GitLabによるCarrierWaveの修正

ファイルを保存する場所

CarrierWave Uploader は、ファイルの保存場所を決定します。新しいアップローダクラスを作成する際、新機能のファイルをどこに保存するかを決定します。

まず最初に、新しいUploaderクラスが必要かどうかを自問してください。異なるマウントポイントや異なるモデルに同じUploaderクラスを使用しても問題ありません。

もし独自のUploaderクラスが必要であれば、AttachmentUploaderのサブクラスにしてください。 その後、そのクラスから保存場所とディレクトリスキームを継承します。ディレクトリスキームは次のとおりです：

File.join(model.class.underscore, mounted_as.to_s, model.id.to_s)

GitLabのコードベースを見回すと、独自の保存場所を持つUploaderがたくさんあります。オブジェクトストレージの場合、これは Uploaders が独自のバケットを持つことを意味します。私たちは現在、以下の理由から、 新しいバケットを追加することを推奨していません：

• 新しいバケットを使うと、GDK、Omnibus GitLab、CNGのダウンストリームを変更する必要があるため、開発時間が長くなります。
• 新しいバケットを使うと、GitLab.comインフラストラクチャの変更が必要になり、新機能のロールアウトが遅くなります。
• 新しいバケットを使うことで、セルフマネジメントのGitLabインストールでの新機能の導入が遅くなります：ローカルのGitLab管理者が新しいバケットを設定するまで、人々はあなたの新機能を使い始めることができません。

既存のバケットを使うことで、このような余分な作業や摩擦を避けることができます。AttachmentUploader が使っているGitlab.config.uploads ストレージロケーションは、すでに設定されていることが保証されています。

ダイレクトアップロードの実装

以下では、ダイレクトアップロードの実装方法について説明します。

ダイレクトアップロードの使用は常に必要というわけではありませんが、通常は良いアイデアです。アップロードの頻度が低く、アップロードの回数が少ない機能でない限り、ダイレクトアップロードを実装することをお勧めします。アップロードの頻度が低くて少ない機能の例としては、プロジェクトのアバターがあります。アバターはめったに変更されませんし、アプリケーションはアバターのサイズに厳しい制限を課しています。

アップロードの頻度が少なく、かつ、アップロードのサイズが小さくない機能を扱う場合、ダイレクトアップロードのサポートを実装しないことは、技術的負債を背負うことを意味します。少なくとも、後で直接アップロードのサポートを追加_できる_ようにするべきです。

ダイレクトアップロードをサポートするには、2つのことが必要です：

1. Railsの事前承認エンドポイント
2. Workhorseのルーティングルール

Workhorseはあなたのアップロードをどこに保存すればいいのかわかりません。それを知るために事前承認要求を行います。また、どこで事前承認リクエストを行うかどうかもわかりません。そのためにはルーティングルールが必要です。

Workhorseが以前は別のプロジェクトであったことを覚えている人へのメモです：これらの2つのステップを別々のマージリクエストに分ける必要はもうありません。実際、1つのマージリクエストで両方を行う方が簡単でしょう。

Workhorseルーティングルールの追加

ルーティングルールはworkhorse/internal/upstream/routes.goで定義されます。ルーティングルールの構成は以下の通りです：

• HTTP 動詞 (通常は “POST” または “PUT”)
• パスの正規表現
• アップロードタイプ：MIMEマルチパートまたは “フルリクエストボディ”
• オプションで、以下のような HTTP ヘッダをマッチさせることもできます。Content-Type

使用例：

u.route("PUT", apiProjectPattern+`packages/nuget/`, mimeMultipartUploader),

workhorse/upload_test.goの TestAcceleratedUpload 、ルーティングルールのテストを追加してください。

また、新機能のアップロードリクエストを実行したときに、Workhorseが事前承認リクエストを行っていることを手動で確認してください。これはRailsのアクセスログを見ることで確認できます。ルーティングルールにミスがあったとしても、ハードエラーにはならないため、これは必要なことです。

事前承認エンドポイントの追加

ここでは3つのケースを区別します：Railsコントローラ、Grape APIエンドポイント、GraphQLリソースです。

悪いニュースから始めると、GraphQLの直接アップロードは現在サポートされていません。WorkhorseがGraphQLクエリを解析しないからです。イシュー#280819も参照してください。代わりにGrape経由でファイルアップロードを受け付けることを検討してください。

Grapeの事前承認エンドポイントについては、/authorize ルートを実装した既存の例を探してください。その一例がPOST:id/uploads/authorize エンドポイントです。この特定の例はFileUploaderを使用しており、アップロードはそのUploaderクラスの保存場所（バケット）に保存されることを意味します。

Railsエンドポイントでは、WorkhorseAuthorizationを使用できます。

アップロードの処理

機能によっては、アップロードされたファイルからメタデータを抽出するなど、アップロードを処理する必要があります。これを実装する方法はいくつかあります。主な選択肢は、_どこで_処理を実装するか、または「誰が処理するか」です。

Railsでの処理は魅力的に見えますが、直接アップロードできないため、スケーリングの問題につながりがちです。その場合、Workhorseでの処理で機能を再構築することを余儀なくされます。そのため、機能の要件が許すのであれば、Sidekiqで処理を行うことが、複雑さとスケーリング能力の間で良いバランスを取ることになります。

CarrierWaveアップローダー

GitLabでは、CarrierWaveの修正版を使ってアップロードを管理しています。以下では、CarrierWave の使い方とその修正方法を説明します。

CarrierWave の中心となる概念はUploaderクラスです。Uploaderはファイルの保存場所を定義し、オプションでバリデーションと処理ロジックを含みます。Uploaderを使用するには、ActiveRecordモデルのテキストカラムに関連付ける必要があります。これは「マウント」と呼ばれ、カラムはmountpoint と呼ばれます。例えば

class Project < ApplicationRecord
  mount_uploader :avatar, AttachmentUploader
end

tanuki.png というアバターをアップロードする場合、CarrierWave はプロジェクトのprojects.avatar カラムに文字列tanuki.png を格納し、AttachmentUploader クラスに設定データとディレクトリスキーマを格納します。たとえば、プロジェクト ID が 123 の場合、実際のファイルは/var/opt/gitlab/gitlab-rails/uploads/-/system/project/avatar/123/tanuki.pngにあります。ディレクトリ/var/opt/gitlab/gitlab-rails/uploads/-/system/project/avatar/123/ は、設定 (/var/opt/gitlab/gitlab-rails/uploads)、モデル名 (project)、モデル ID (123)、およびマウントポイント (avatar) などを使用してアップローダによって選択されます。

アップローダは、アップロードの個々の保存ディレクトリを決定します。モデルのmountpoint 列にはファイル名が含まれています。

CarrierWaveはファイルハンドルオブジェクトをオペレーションするゲッターとセッターをモデルに定義しているため、mountpoint 列に直接アクセスすることはありません。

オプションのアップローダの動作

アップロード先のディレクトリを決定する以外にも、CarrierWave Uploaderはコールバックを介していくつかの動作を実装することができます。これらの振る舞いのすべてが GitLab で使えるわけではありません。特に、現在のところ CarrierWave のversion メカニズムを使うことはできません。できることは次のとおりです：

• ファイル名の検証
• 直接アップロードとは互換性がありません：画像のリサイズなど、ファイル内容の1回限りの前処理
• 直接アップロードとは互換性がありません：静止時の暗号化

画像のリサイズや暗号化などのCarrierWaveの前処理には、アップロードされたファイルへのローカルアクセスが必要です。このため、Rubyから処理済みファイルをアップロードする必要があります。これは、Rubyでアップロードを_行わない_ダイレクトアップロードに反します。前処理ビヘイビアを持つアップローダで直接アップロードを使用する場合、前処理ビヘイビアは無言でスキップされます。

CarrierWaveストレージエンジン

CarrierWaveには2つのストレージエンジンがあります：

GitLabは設定によってこれらの両方のエンジンを使用します。

CarrierWaveでストレージエンジンを選択する一般的な方法は、Uploader.storage クラスメソッドを使うことです。GitLabではこれを行わず、Uploader#storage をオーバーライドしています。これにより、ファイルごとにストレージエンジンを変えることができます。

CarrierWaveファイルのライフサイクル

アップローダーは、通常のストレージとキャッシュストレージの2つのストレージ領域に関連付けられています。それぞれに独自のストレージ・エンジンがあります。マウントポイントセッター (project.avatar = File.open('/tmp/tanuki.png')) にファイルを割り当てる場合、cache! メソッドを介して、副作用としてキャッシュストレージにファイルをコピー/移動する必要があります。ファイルを永続化するには、何らかの方法でstore! メソッドを store!呼び出す必要があります。これは、store! ActiveRecordコールバックを経由するか、 store!Uploaderインスタンスで呼び出すことで行われます。

通常、cache! やstore! とやり取りする必要はありませんが、GitLab CarrierWave の変更をデバッグする必要がある場合は、これらのメソッドが存在し、常に呼び出されることを知っておくと便利です。具体的には、CarrierWave の前処理動作 (process など) はbefore :cache フックとして実装されており、直接アップロードする場合はこれらのフックは無視され実行されないことを知っておくとよいでしょう。

直接アップロードでは、すべてのCarrierWavebefore :cache フックをスキップします。

GitLabによるCarrierWaveの修正

GitLabはCarrierWaveの改良版を使って様々なことを可能にしています。

ストレージエンジン間でのデータのマイグレーション

app/uploaders/object_storage.rbには、ローカルストレージとオブジェクトストレージの間でユーザーデータをマイグレーションするコードがあります。このコードが存在するのは、長い間 GitLab.com が NFS 経由でローカルストレージにアップロードを保存していたからです。これが変わったのは、インフラのマイグレーションの一環としてアップロードをオブジェクトストレージに移さなければならなくなったからです。

これが、CarrierWavestorage が GitLab のアップロードごとに異なる理由であり、uploads.store やci_job_artifacts.file_store のようなデータベースカラムがある理由です。

Workhorse 経由での直接アップロード

Workhorseの直接アップロードは、RubyのCPU時間をかけずに大きなアップロードを受け付ける仕組みです。WorkhorseはGoで書かれており、goroutineはRubyスレッドよりもはるかにリソースフットプリントが小さいです。

直接アップロードは以下のように動作します。

1. Workhorseはユーザーのアップロードリクエストを受け付けます。
2. WorkhorseがRailsでリクエストを事前認証し、一時的なアップロード場所を受け取ります。
3. Workhorseは一時的なアップロード先へのユーザーのリクエストにファイルアップロードを保存します。
4. WorkhorseはリクエストをRailsに伝えます。
5. Railsがリモートコピーオペレーションをイシューし、アップロードされたファイルを一時的な場所から最終的な場所にコピーします。
6. Railsが一時的なアップロードを削除します。
7. Railsがタイムアウトした場合に備えて、Workhorseは2回目の一時アップロードを削除します。

通常、cache! はCarrierWave::SanitizedFile のインスタンスを返し、store! はFog を使ってそのファイルをアップロードします。

オブジェクトストレージの場合、GitLab特有の修正により、一時的な場所から最終的な場所へのコピーはRailsがCarrierWaveを欺くことで実装されます。CarrierWaveがcache! 、一時ファイルを指すCarrierWave::Storage::Fog::File ファイルハンドルを返します。store! 、CarrierWaveはこのファイルを目的の場所にコピーします。

テーブル

Scalability::Frameworksチームは、オブジェクトストレージとアップロードをより使いやすく、より堅牢なものにしています。アップローダーを追加または変更する場合は、このテーブルも更新していただけると助かります。これは、アップローダがどこでどのように使用されているかの概要を把握するのに役立ちます。

フィーチャーバケットの詳細

CarrierWaveインテグレーション