업로드 개발 지침

업로드는 많은 GitLab 기능의 필수적인 부분입니다. GitLab이 업로드를 어떻게 처리하는지 이해하려면 이 페이지에서 파일을 저장소 목적지로 전송하는 핵심 메커니즘을 개요합니다.

GitLab 업로드는 기능별로 구성됩니다. 업로드를 포함하는 모든 기능은 동일한 구성 옵션을 제공하지만 서로 독립적으로 구성할 수 있습니다. 예를 들어 Git LFS 업로드는 CI/CD 빌드 아티팩트 업로드와 독립적으로 구성될 수 있지만 둘 다 동일한 설정 키 세트를 제공합니다. 이러한 설정은 업로드가 어떻게 처리되는지를 규제하며 성능과 확장성에 큰 영향을 미칠 수 있습니다.

이 페이지에서는 이러한 파일 처리 결정에 중요한 업로드 설정을 요약합니다. 그런 다음 이후 섹션에서 각 메커니즘에 대해 자세히 설명합니다.

업로드 설정이 업로드 흐름을 제어하는 방법

개별 업로드 전략을 자세히 살펴보기 전에, 이러한 전략에 대응되는 업로드 설정의 고수준 분석을 살펴보겠습니다.

업로드 설정 자체는 업로드 관리에서 문서화되어 있습니다. 여기에서는 이러한 설정이 GitLab 업로드 로직의 내부를 어떻게 제어하는지에 중점을 둡니다. 최상위 수준에서 업로드된 파일에 대한 두 가지 목적지를 구분합니다.

로컬 저장소 - 파일이 웹 서버 노드에 연결된 볼륨에 저장됩니다.
오브젝트 저장소 - 파일은 원격 오브젝트 스토어 버킷에 저장됩니다.

이 표에서 x.y.z는 gitlab.yml을 통해 취해진 경로를 지정합니다.

설정	값	동작
`<기능>.object_store.enabled`	`false`	파일이 `<기능>.storage_path`에 로컬로 저장됨
`<기능>.object_store.enabled`	`true`	파일이 `<기능>.object_store.remote_directory`에 원격으로 저장됨

오브젝트 저장소를 사용할 때, 관리자는 해당 파일이 해당 버킷으로 이동하는 방법을 제어할 수 있습니다. 이 이동은 다음 중 하나의 방법으로 발생할 수 있습니다.

레일즈 컨트롤러 업로드.
직접 업로드.

개별 Sidekiq 워커는 또한 오브젝트 저장소에 파일을 저장할 수 있으며, 이는 여기에서 다루지 않습니다.

마지막으로, Workhorse는 대부분의 사용자가 시작한 업로드를 Ruby 및 레일즈의 느린 작업을 유지하기 위한 업로드 버퍼링 메커니즘을 사용합니다. 이 메커니즘은 Workhorse 지원 업로드에서 설명되어 있으며, 이전에 논의한 대부분과 서로 직교적으로 실행됩니다.

이제 각 경우를 자세히 살펴봅니다.

로컬 저장소

로컬 저장소는 업로드가 이동할 수 있는 가장 간단한 경로입니다. 이것은 GitLab이 초기에 업로드를 처리하는 방식이었습니다. 레일즈 애플리케이션에서 storage_path에 액세스할 수 있는 저장소 볼륨(디스크 또는 네트워크 연결 저장소와 같은)이 가정됩니다. 이 파일 경로는 레일즈 루트 디렉토리를 기준으로 상대적이며 기능별로 구성 가능합니다.

클라이언트가 파일 업로드를 보내면, Workhorse는 먼저 파일을 디스크로 버퍼링하고 이는 Workhorse 지원 업로드에서 더 자세히 설명되어 있는 메커니즘입니다. 요청이 레일즈 애플리케이션에 도달하면 파일이 이미 로컬 저장소에 존재하므로 레일즈는 단순히 지정된 디렉터리로 이동시켜 트랜잭션을 완료합니다.

로컬 저장소는 클라우드 네이티브 GitLab (CNG) 설치에서 사용할 수 없습니다. 따라서 GitLab SaaS에는 사용되지 않습니다.

오브젝트 저장소

수평으로 확장 가능한 저장소를 제공하기 위해 Amazon AWS, Google Cloud Storage(GCS), Azure Cloud Storage 등과 같은 오브젝트 스토어 공급 업체를 사용해야 합니다.

오브젝트 저장소 사용은 두 가지 주요 이점을 제공합니다.

더 많은 저장 용량 추가의 용이성: 클라우드 공급 업체는 이를 자동으로 수행합니다.
GitLab 설치의 수평 스케일링 활성화: 여러 GitLab 응용 프로그램 서버가 동일한 데이터에 액세스할 수 있습니다.

GitLab SaaS를 포함한 CNG 설치는 항상 오브젝트 저장소(GitLab SaaS의 경우 GCS)를 사용합니다.

원격 오브젝트 저장소로 업로드하는 한 가지 문제는 GitLab에서 객체 저장소 제공 업체로 HTTP 요청이 포함된다는 것입니다. 위에서 언급한 것처럼, 이러한 HTTP 요청이 보내지는 방법에는 세 가지 다른 전략이 있습니다.

레일즈 컨트롤러 업로드.
직접 업로드.
Workhorse 지원 업로드.

레일즈 컨트롤러 업로드

직접 업로드를 사용할 수 없을 때, 레일즈는 컨트롤러 create 액션의 일부로 파일을 오브젝트 저장소로 업로드합니다. 담당하는 컨트롤러는 업로드된 파일의 종류에 따라 다릅니다.

레일즈 컨트롤러 업로드는 로컬 저장소에 파일을 업로드 하면서 크게 다르지 않습니다. 주요 차이점은 레일즈가 객체 저장소로 HTTP 요청을 보내야 한다는 것입니다. 이는 CarrierWave Fog를 통해 수행됩니다.

로컬 저장소와 마찬가지로, 이 전략은 Ruby 및 레일즈의 일부 비용이 많이 드는 I/O 작업을 Workhorse 지원을 통해 이동시킴으로써 이점을 얻습니다. 직접 업로드가 HTTP PUT 요청도 Puma 외부에 유지하기 때문에 더 나은 역할을 합니다.

이 전략은 60초의 요청 타임아웃 시 Puma에 따라 작은 파일 업로드에 적합합니다.

직접 업로드

직접 업로드는 GitLab SaaS와 같이 CNG 설치에 큰 크기(gigabyte) 파일을 객체 저장소로 이동하는 권장 방법입니다.

직접 업로드가 활성화되면 Workhorse는 다음을 수행합니다.

요청을 레일즈로 승인.
객체 저장소 자체와 연결을 설정하여 파일을 임시 위치로 전송합니다.
전송이 완료되면 Workhorse는 레일즈로 요청을 완료합니다.
객체 저장소의 임시 파일을 삭제함으로써 업로드를 완료합니다.

이 전략은 Workhorse 지원 업로드의 다른 형태입니다. 이는 Workhorse 및 Puma 양쪽에서 액세스할 수 있는 공유 저장소에 의존하지 않습니다.

기존의 업로드 전략 중에서 직접 업로드가 큰 크기(gigabyte) 파일을 처리하는 데 가장 적합합니다.

디스크 버퍼링 업로드

direct_upload가 오브젝트 저장소 설정 내에서 비활성화되어 있는 경우, 직접 업로드는 _디스크 버퍼링 업로드_로 대체됩니다. /authorize 호출에 대한 응답에는 파일 시스템 경로만 포함됩니다.

sequenceDiagram participant c as Client participant w as Workhorse participant r as Rails participant os as Object Storage activate c c ->>+w: POST /some/url/upload w ->>+r: POST /some/url/upload/authorize Note over w,r: 이 요청에는 비어있는 본문이 있습니다 r-->>-w: 사전 서명된 OS URL w->>+os: PUT 파일 Note over w,os: 파일은 임시 위치에 저장됩니다. 레일즈가 대상을 선택함 os-->>-w: 요청 결과 w->>+r: POST /some/url/upload Note over w,r: 파일이 그 경로로 교체되었으며<br>기타 메타데이터가 함께 있습니다 r->>+os: 객체를 최종 위치로 이동합니다 os-->>-r: 요청 결과 opt 비동기 처리가 필요한 경우 r->>+redis: 작업 예약 redis-->>-r: 작업이 예약됨 end r-->>-c: 요청 결과 deactivate c w->>-w: 정리 opt 비동기 처리가 필요한 경우 activate sidekiq sidekiq->>+redis: 작업 검색 redis-->>-sidekiq: 작업 sidekiq->>+os: 객체 가져오기 os-->>-sidekiq: 파일 sidekiq->>sidekiq: 파일 처리 deactivate sidekiq end

Workhorse 지원 업로드

대부분의 업로드는 어떤 방식으로든 Workhorse의 지원을 받습니다.

종종, Workhorse는 업로드를 임시 파일로 버퍼링합니다. Workhorse는 임시 파일의 이름과 위치를 Puma에게 알리기 위해 요청에 메타데이터를 추가합니다. 이는 Workhorse와 Puma 간에 공유된 임시 저장소가 필요합니다. 모든 GitLab 설치(포함하여 CNG)에는 이러한 공유 임시 저장소가 있습니다.
Workhorse는 때로 파일을 사전 처리합니다. 예를 들어 CI 아티팩트 업로드의 경우, Workhorse는 ZIP 파일의 내용에 대한 별도의 색인을 만듭니다. Workhorse에서 이 작업을 수행함으로써 Puma 요청 제한 시간을 우회합니다. Sidekiq 백그라운드 처리와 비교했을 때, 이 방법은 사용자가 GitLab이 파일을 수락했지만 아직 처리하지 않은 중간 상태를 보지 않아도 된다는 장점이 있습니다.
직접 업로드로, Workhorse는 파일을 사전 처리하고 객체 저장소에 업로드할 수 있습니다. 대용량 파일을 객체 저장소에 업로드하는 데는 시간이 걸리는데, 이를 Workhorse에서 처리함으로써 Puma 요청 제한 시간을 피할 수 있습니다.

업로드에 대한 자세한 정보는 Workhorse 핸들러를 참조하세요.