Zettelkasten

multipart upload는 안정적으로 큰 파일을 전송할 수 있게 도와준다

·수정 2026.10.14·수정 3회

요약

  • 안정적으로 큰 크기의 파일을 전송하는 방법에는 multipart가 사용된다.
  • S3에서는 파일을 5MiB~5GiB 파트로 나눠 올리고, Complete 요청 때 S3가 파트 번호 순으로 이어 붙인다. 끊기면 실패한 파트만 다시 올린다.
  • boto3 upload_file·upload_fileobj는 8MiB가 넘으면 알아서 multipart로 올린다. 직접 짤 일은 스트림을 받으며 올리거나 브라우저가 S3로 바로 올릴 때 정도다.
  • 끝내지 않은 업로드의 파트도 Complete나 Abort 전까지 저장 요금이 나가므로 AbortIncompleteMultipartUpload 수명 주기 규칙을 같이 건다.

본문

  • 멀티파트 업로드는 큰 파일을 여러 작은 조각으로 나눠서 서버에 업로드하는 방식으로 마지막에 서버가 조각을 합쳐서 원래의 하나의 객체로 만드는 개념
  • 필요성
    1. 단일 PUT 한계 회피
      • 스토리지 서비스들은 단일 업로드 요청에 크기 제한이 있음
    2. 전송 안정성
      • 한번에 100GB 업로드 하다가 끊기면 처음부터 다시 업로드해야함
      • 멀티 파트는 특정 파트만 업로드 해도됨
    3. 병렬 업로드
      • 동시에 여러 파트 업로드 가능해서 속도 향상됨
  • 동작 과정
    • Initiate 업로드 시작: 서버에서 uploadId를 발급함
    • Upload Parts: 파일을 5MiB ~ 5GiB 조각으로 나눠 업로드 (마지막 파트만 5MiB보다 작아도 됨)
      • 파트마다 응답으로 오는 ETag를 파트 번호와 함께 직접 기록해 둬야 함. Complete 요청을 ListParts 결과로 만들지 말라고 AWS 문서가 따로 경고함
    • Complete: 모든 파트 올렸어라고 요청 -> 서버에서 파트를 합쳐 최종 파일을 완성함
      • 요청에 uploadId와 (파트 번호, ETag) 목록을 같이 보냄
    • Abort: 실패하면 uploadId로 중단 요청 -> 올라간 파트를 지움
      • Initiate에는 만료가 없어서 Complete나 Abort를 안 하면 파트가 계속 남음
      • 진행 중인 파트 업로드가 다 끝난 뒤에 Abort해야 파트가 남지 않음

S3 한도

  • 파트 번호 1~10,000, 즉 파트는 최대 10,000개
  • 파트 크기 5MiB~5GiB, 마지막 파트는 하한 없음
  • 객체 하나 최대 48.8TiB
  • AWS 문서는 100MB 이상이면 multipart를 쓰라고 권함
  • 파트 크기와 개수 한도가 같이 묶여 있음. 직접 나눌 때 8MiB 파트면 10,000개 × 8MiB ≈ 78GiB까지만 올라가므로, 큰 파일은 파트 크기를 키워야 함

적용 방법 (boto3 기준)

  1. 서버에서 파일을 올릴 때: upload_file·upload_fileobj가 TransferConfig 기준으로 자동으로 나눠 올림
    • 기본값: multipart_threshold 8MiB, multipart_chunksize 8MiB, max_concurrency 10
    • put_object는 PutObject 한 번으로 올리므로 나누지 않음. 큰 파일을 put_object로 올리고 있다면 upload_file로 바꾸는 것만으로 적용됨
    from boto3.s3.transfer import TransferConfig
    
    config = TransferConfig(
        multipart_threshold=100 * 1024 * 1024,  # 이 크기부터 multipart
        multipart_chunksize=16 * 1024 * 1024,   # 파트 크기
    )
    s3.upload_file("big.mp4", bucket, key, Config=config)
    
    • Node는 @aws-sdk/lib-storage의 Upload가 같은 일을 함. 기본 partSize 5MiB, queueSize 4이고, 실패하면 기본으로 AbortMultipartUpload를 호출함(leavePartsOnError: false)
  2. 직접 제어할 때 (스트림을 받으며 올리기, 이어 올리기): create_multipart_upload → upload_part 반복 → complete_multipart_upload. 예외가 나면 abort_multipart_upload
  3. 브라우저나 앱이 S3로 바로 올릴 때
    • 서버가 create_multipart_upload로 uploadId를 받고, 파트마다 generate_presigned_url("upload_part", Params={Bucket, Key, UploadId, PartNumber})로 URL을 만들어 줌
    • 클라이언트가 각 URL에 PUT하고 응답 헤더의 ETag를 모아 보내면 서버가 Complete를 호출함
    • 브라우저에서 올리면 ETag는 CORS 기본 노출 헤더가 아니라서, 버킷 CORS 설정의 ExposeHeaders에 ETag를 넣어야 JS가 읽을 수 있음
    • 서버는 서명만 하고 데이터는 서버를 거치지 않음. Valet Key 패턴과 같은 구조

같이 챙길 것

  • 끝내지 않은 업로드 정리
    • Initiate 후 Complete나 Abort 전까지 파트의 저장·요청 요금이 나감. 앱이 중간에 죽으면 Abort도 못 하므로 버킷에 수명 주기 규칙을 걸어 둠
    • 이 규칙으로 파트를 지울 때 조기 삭제 요금은 없음
    {"Rules": [{"ID": "abort-incomplete-mpu", "Status": "Enabled", "Filter": {"Prefix": ""},
                "AbortIncompleteMultipartUpload": {"DaysAfterInitiation": 7}}]}
    
    aws s3api put-bucket-lifecycle-configuration --bucket <버킷> --lifecycle-configuration file://lifecycle.json
  • 요청 수
    • Create 1번 + 파트 수만큼 UploadPart + Complete 1번이 모두 요청으로 과금됨. 100GB를 100MB 파트로 올리면 1,002번
    • 작은 파일까지 multipart로 쪼개면 요청비만 늘어나므로, threshold를 실제 파일 크기 분포에 맞춤

관련 노트

참고