안녕하세요! 시스템컨설턴트그룹 28기 인프라 담당 양현준입니다.
오늘은 MinIO를 다루면서 겪은 일과 다량의 파일을 효율적으로 MinIO에 업로드하는 방법에 대해 정리했습니다.
MinIO란?
MinIO는 고성능 오픈소스 오브젝트 스토리지로 Amazon S3와 호환되는 API를 제공하는 오브젝트 스토리지입니다.
소스코드가 AGPLv3 라이선스 하에 공개되어 있는 오픈소스 소프트웨어입니다.
MinIO Object Browser
MinIO는 관리자 홈페이지(Object Browser)를 제공합니다.
이를 통해 손쉽게 MinIO 클러스터를 관리하고, 오브젝트 브라우저 기능을 통해 클러스터에 파일을 업로드하고 다운로드 받을 수 있습니다.
파일 마이그레이션을 하는 이유
저희 단체에서 기존에 운영하던 애플리케이션이 있습니다. 이는 로컬 파일시스템을 이용해서 사용자로부터 받은 파일을 로컬에 저장하고 이를 서빙하도록 코드가 작성되어 있었습니다.
하지만 점차 컨테이너 기반으로 인프라 및 모든 애플리케이션을 운영하기로 결정함에 따라서 해당 애플리케이션도 MinIO 오브젝트 스토리지를 적극적으로 이용할 수 있게끔 마이그레이션하고, 파일들을 MinIO에 업로드해야 했습니다.
파일들은 모두 합해 약 35GiB 정도 되었고, 파일의 수는 약 17,000개 정도 되었습니다.
* 마이그레이션과 관련한 내용은 여기에서 확인하실 수 있습니다.
Web UI를 통한 첫번째 시도
먼저 마이그레이션한 애플리케이션의 QA 진행을 위해 1차로 파일들을 업로드해야 했습니다.
처음에는 MinIO에서 제공되는 Object Browser를 이용해 파일을 업로드 하려고 했습니다.
파일을 전부 선택해서 업로드하는데, 업로드가 하나하나 되면서 매우 느리게 진행되었습니다.
모든 파일을 업로드하니 약 2시간이 지나있었습니다.
원인 분석
원인을 파악하기 위해 Claude에게 물어봤습니다.
이번에 파일 업로드에 사용한크롬 브라우저는 HTTP/1.1 프로토콜 기준으로 도메인당 최대 6개의 HTTP 요청을 처리한다고 합니다.
약 17,000개의 파일을 업로드하니 그만큼 각 파일별로 HTTP POST(PUT) 요청이 발생하게 됩니다.
MinIO 관리자 페이지는 각 파일을 PutObject API로 파일을 전송합니다.
17,000번의 독립적인 요청으로 인해 그만큼의 TCP 핸드셰이크와 HTTP 오버헤드가 발생하게 되는 것입니다.
파일 중 약 15,000개가 개별 용량이 100MB가 안되는 작은 파일이기에 오버헤드 비율이 더 높아질 수 밖에 없었습니다.
또한 파일을 로컬 컴퓨터에서 브라우저로 메모리에 올리기에 메모리 사용량도 크게 늘었을 것입니다.
이것은 명백한 제 실수이긴 합니다만, 작업할 때 유선랜을 사용하지 않고 무선랜을 사용해 네트워크 레이턴시가 더 심하게 발생했을 수 있습니다.
파일 업로드의 대안, Rclone
Rclone은 Go 언어로 만든 클라우드 스토리지 특화 업로드 및 다운로드 프로그램입니다.
Rclone의 성능을 볼 수 있는 극단적인 사례가 하나 있습니다.
각 대학교에서 제공하는 구글 드라이브는 Google Workspace for Education 서비스로부터 제공이 되는데, 2018년에는 해당 약관에 대역폭에 대한 제한이 없었다고 합니다.
이를 파악한 캘리포니아 대학교의 한 학생이 rclone을 이용해 무려 총 128TB의 파일들을 구글 드라이브에 400MB/s (MB/s입니다. Mbps가 아니에요.) 가 넘어가는 속도로 업로드를 시도한 사례가 있었습니다.
아무튼, MinIO는 Amazon S3와 호환되는 API를 제공하기 때문에 rclone에서 S3를 Storage로 지정하여 바로 연결할 수 있습니다.
Rclone 설치 및 설정
Rclone을 설치하는 방법은 간단합니다.
curl https://rclone.org/install.sh | sudo bash
위 명령어를 통해 간단하게 rclone을 설치할 수 있습니다.
rclone config
n) New remote
name> minio
Storage> s3
provider> Minio
env_auth> false
access_key_id> YOUR_ACCESS_KEY
secret_access_key> YOUR_SECRET_KEY
region> us-east-1
endpoint> http://MINIO_HOST:9000
location_constraint>
acl>
설정 명령어를 통해 S3 스토리지, minio provider를 지정하여 세팅할 수 있습니다.
마지막으로 아래 명령어를 통해 버킷 목록이 나오면 정상적으로 연결된 것이라고 할 수 있겠습니다.
rclone lsd minio:
Rclone 파일 업로드 및 검증
파일 업로드는 rclone copy 명령어를 이용해 진행할 수 있습니다.
저의 경우에는 아래처럼 사용했습니다.
rclone copy ./webdata minio:mybucket/webdata \
--progress \
--fast-list \
--transfers 8 \
--checkers 16 \
--retries 10 \
--low-level-retries 20 \
--s3-upload-concurrency 4 \
--check-first \
progress 옵션은 실시간 전송 현황을 콘솔에 표시합니다.
fast-list 옵션은 메모리를 더 사용하는 대신 목록 조회시 API 호출을 줄여 속도를 향상시킵니다.
transfer 옵션은 동시에 전송할 파일의 개수입니다.
checker 옵션은 전송 전 파일 비교를 수행하는 병렬 스레드의 수입니다.
retries 옵션은 전체 작업 실패시 재시도 횟수입니다.
low-level-retries 옵션은 개별 HTTP 요청 실패시 저수준 재시도 횟수입니다.
s3-upload-concurrency 옵션은 단일 파일의 멀티파트 업로드 내 병렬 청크 수입니다. 대용량 파일에 효과적이라고 합니다.
check-first는 전송 시작 전 모든 파일 체크를 먼저 완료한 뒤에 업로드를 시작하는 옵션입니다.
업로드가 완료되면 아래 명령어를 통해 누락된 파일 또는 손상된 파일이 있는지 추가로 검증할 수 있습니다.
rclone check ./webdata minio:mybucket/webdata --one-way --fast-list
결과
Rclone을 이용해 병렬처리를 잘 활용하여 파일을 업로드했더니, 35GiB 파일을 모두 업로드하는데 약 10분 정도가 소요되었습니다. 웹 콘솔에 모두 반영되는데까지는 약 5분정도 추가로 더 걸렸습니다.
Rclone을 이용한 덕분에 매우 큰 시간단축을 이뤘습니다.
실제로 파일을 이전하는 문제 때문에 서비스를 이전하는 총 다운타임을 4-5시간 정도로 잡았는데 실제 작업시간은 1시간 밖에 걸리지 않았습니다.
마무리
이번에 SCG에서 팀블로그를 개설하면서 저는 처음 여기에 글을 쓰게 되었는데요. 잘 읽으셨을지 모르겠네요.
모쪼록 도움이 되었길 바랍니다.
인프라나 백엔드, 기타 잡다한 이야기에 관심있으시다면 제 개인 블로그에도 한번 놀러와주세요. 감사합니다!
'Infra' 카테고리의 다른 글
| 웍실 네트워크 개편 (1) | 2026.04.03 |
|---|