Flask 대용량 업로드, 청크 업로드, 재개 업로드 구현 가이드

🔗 Flask에서 대용량 업로드의 기본 구조

웹 애플리케이션에서 몇 MB 이하의 작은 파일은 단일 요청으로 업로드해도 문제가 없지만, 수백 MB에서 수 GB에 이르는 대용량 파일은 안정성을 보장하기 어렵습니다.
특히 Flask와 같은 WSGI 기반 프레임워크에서는 요청이 완료될 때까지 메모리에 데이터를 유지하는 경우가 많아 서버 부하로 이어질 수 있습니다.
따라서 처음 설계 단계부터 대용량 파일 업로드를 별도의 구조로 다뤄야 합니다.

가장 기본적인 방식은 업로드 요청을 받으면 서버가 임시 디렉토리에 파일을 저장하고, 이후 작업(예: DB 연동, S3 업로드, 후처리 등)을 수행하는 것입니다.
하지만 대용량 업로드에서는 네트워크 오류, 연결 끊김, 브라우저 제한으로 인해 전체 전송이 실패하는 경우가 많습니다.
이를 대비하기 위해 업로드 과정을 작은 단위로 나누어 관리하는 접근이 필수입니다.

📌 Flask 기본 업로드 방식의 한계

Flask에서 흔히 사용하는 request.files['file'] 방식은 간단하지만, 모든 데이터를 메모리 혹은 임시 파일에 담기 때문에 큰 용량에서는 문제가 발생합니다.
예를 들어 2GB 동영상을 업로드하면 WSGI 서버가 이를 모두 처리해야 하므로 메모리 부족이나 요청 타임아웃이 발생할 수 있습니다.

📌 대용량 업로드 안정화를 위한 구조 설계

안정적인 대용량 업로드를 위해 고려해야 할 핵심 구조는 다음과 같습니다.

• 📂파일을 청크 단위로 분할하여 업로드
• 🗄️서버는 청크를 임시 저장소에 기록하고 메타데이터(DB/Redis)에 상태 저장
• 🔄네트워크 오류 발생 시 중단 지점부터 재개할 수 있도록 설계
• ☁️최종적으로는 AWS S3 같은 외부 스토리지로 옮겨 서비스 부하 분산

from flask import Flask, request

app = Flask(__name__)

@app.route('/upload', methods=['POST'])
def upload_file():
    file = request.files['file']
    file.save(f"./uploads/{file.filename}")
    return "uploaded"

위 코드는 가장 기본적인 업로드 예시이지만, 실제 서비스에서는 청크 분할 업로드, 재개 기능을 더해야 안정적인 환경을 만들 수 있습니다.

🛠️ 청크 업로드 API 설계와 FormData 활용

청크 업로드는 대용량 파일을 일정 크기의 블록으로 나눠 순차적으로 전송하고, 서버가 이를 안전하게 이어 붙이는 방식입니다.
네트워크 오류가 발생해도 이미 도착한 블록은 유지되므로 신뢰성이 높아집니다.
API는 보통 업로드 초기화, 청크 전송, 상태 조회, 완료 확정, 중단 취소의 다섯 동작으로 구성합니다.
클라이언트는 FormData나 Content-Range 헤더를 사용해 각 청크의 메타데이터를 함께 전송하고, 서버는 업로드 ID를 키로 진행 상황을 기록합니다.

📌 필수 엔드포인트 설계

📌 Flask 서버 예시 코드

from flask import Flask, request, jsonify
import os, uuid, pathlib

app = Flask(__name__)
BASE = pathlib.Path("./uploads")
BASE.mkdir(exist_ok=True)

INMEM = {}  # 업로드 메타데이터: {upload_id: {"filename":..., "size":..., "received": set(), "chunks": int}}

@app.post("/upload/init")
def init_upload():
    data = request.get_json()
    upload_id = uuid.uuid4().hex
    chunks = int((data["size"] + data["chunkSize"] - 1) // data["chunkSize"])
    INMEM[upload_id] = {"filename": data["filename"], "size": data["size"], "received": set(), "chunks": chunks}
    (BASE / upload_id).mkdir(exist_ok=True)
    return jsonify({"uploadId": upload_id, "chunks": chunks})

@app.put("/upload/chunk")
def put_chunk():
    upload_id = request.headers.get("X-Upload-Id")
    index = int(request.headers.get("X-Chunk-Index"))
    if upload_id not in INMEM:
        return ("unknown upload", 404)
    chunk_path = BASE / upload_id / f"{index}.part"
    with open(chunk_path, "wb") as f:
        f.write(request.get_data())
    INMEM[upload_id]["received"].add(index)
    return ("ok", 200)

@app.get("/upload/status")
def status():
    upload_id = request.args.get("id")
    if upload_id not in INMEM:
        return ("unknown upload", 404)
    return jsonify(sorted(list(INMEM[upload_id]["received"])))

@app.post("/upload/complete")
def complete():
    upload_id = request.get_json().get("id")
    meta = INMEM.get(upload_id)
    if not meta:
        return ("unknown upload", 404)
    if len(meta["received"]) != meta["chunks"]:
        return ("incomplete", 409)
    final = BASE / meta["filename"]
    with open(final, "wb") as out:
        for i in range(meta["chunks"]):
            with open(BASE / upload_id / f"{i}.part", "rb") as part:
                out.write(part.read())
    return jsonify({"savedAs": str(final)})

📌 브라우저 FormData 업로더

브라우저에서는 Blob.slice를 이용해 파일을 일정 크기로 나누고, 각 청크를 FormData 또는 바이트 바디로 전송합니다.
FormData는 추가 메타데이터를 함께 보내기 쉬워 디버깅에 유리합니다.
헤더에는 업로드 ID, 청크 인덱스, 전체 청크 수를 넣어 서버의 상태 갱신을 돕습니다.

async function uploadFile(file, chunkSize = 5 * 1024 * 1024) {
  const initRes = await fetch("/upload/init", {
    method: "POST",
    headers: {"Content-Type": "application/json"},
    body: JSON.stringify({ filename: file.name, size: file.size, chunkSize })
  });
  const { uploadId, chunks } = await initRes.json();

  for (let i = 0; i < chunks; i++) {
    const start = i * chunkSize;
    const end = Math.min(file.size, start + chunkSize);
    const blob = file.slice(start, end);

    const res = await fetch("/upload/chunk", {
      method: "PUT",
      headers: { "X-Upload-Id": uploadId, "X-Chunk-Index": String(i) },
      body: blob
    });

    if (!res.ok) {
      // 실패 시 상태 조회 후 누락된 청크만 재전송
      const st = await fetch(`/upload/status?id=${uploadId}`).then(r => r.json());
      i = Math.min(...Array.from(Array(chunks).keys()).filter(x => !st.includes(x))) - 1;
    }
  }

  await fetch("/upload/complete", { method: "POST", headers: {"Content-Type":"application/json"}, body: JSON.stringify({ id: uploadId }) });
}

📌 메타데이터와 헤더 규칙

X-Upload-Id는 업로드 세션을 식별하고, X-Chunk-Index는 0부터 시작하는 정수로 지정합니다.
옵션으로 Content-Range를 사용해 바이트 범위를 표기하면 서버가 교차 검증할 수 있습니다.
파일 전체 해시와 청크별 해시를 별도로 두면 무결성 검사가 쉬워집니다.

• 🧩청크 크기 권장: 5MB ~ 16MB 범위에서 네트워크 품질에 맞게 조절
• 🔁멱등성 보장: 동일 청크 재전송 시 덮어쓰기 허용
• 🧮서버는 총 청크 수와 마지막 청크 길이 검증
• 🔐업로드 ID에 대한 인증·인가 필수 적용

⚙️ 업로드 재개 프로토콜과 서버 상태 저장

대용량 업로드에서 가장 중요한 기능 중 하나는 재개(resume) 기능입니다.
업로드가 중단되면 처음부터 다시 시작하는 대신, 이미 전송된 청크는 그대로 유지하고 누락된 부분만 보충하는 방식으로 안정성과 효율성을 확보할 수 있습니다.
이를 위해 서버와 클라이언트 간에 명확한 프로토콜을 정의해야 합니다.

📌 서버 상태 저장 방식

서버는 각 업로드 세션의 상태를 기록해야 합니다.
기본적으로는 업로드 ID와 함께 다음 정보를 저장합니다.

• 📂파일명과 총 크기
• 📊총 청크 수와 도착한 청크 인덱스
• ⏱️업로드 시작 시각과 마지막 갱신 시각
• 🔐사용자 인증 정보와 권한

이 데이터는 Redis 같은 인메모리 저장소나 관계형 데이터베이스에 보관할 수 있습니다.
특히 Redis를 사용하면 빠른 읽기/쓰기와 TTL(만료 시간)을 활용할 수 있어 일시적인 업로드 세션 관리에 적합합니다.

📌 재개 프로토콜 흐름

재개 업로드는 보통 다음과 같은 흐름으로 동작합니다.

1. 클라이언트가 업로드 ID를 지정하여 서버에 상태를 조회합니다.
2. 서버는 이미 도착한 청크 인덱스 목록을 반환합니다.
3. 클라이언트는 누락된 청크만 선별해 전송합니다.
4. 모든 청크가 도착하면 서버는 파일을 병합하고 무결성을 검증합니다.

💬 재개 업로드를 제대로 지원하려면 클라이언트와 서버가 동일한 청크 크기와 순서를 공유해야 하며, 중간에 규칙이 달라지면 업로드 실패로 이어집니다.

📌 Flask 재개 처리 코드 예시

@app.get("/upload/resume")
def resume():
    upload_id = request.args.get("id")
    if upload_id not in INMEM:
        return ("unknown upload", 404)
    return jsonify({
        "received": sorted(list(INMEM[upload_id]["received"])),
        "totalChunks": INMEM[upload_id]["chunks"]
    })

클라이언트는 이 API를 주기적으로 호출해 업로드 현황을 확인하고, 누락된 청크만 다시 보낼 수 있습니다.
이때 서버는 멱등성을 보장하기 위해 이미 도착한 청크를 덮어써도 문제없도록 설계하는 것이 안전합니다.

📌 실패 복구 전략

네트워크 오류나 브라우저 종료 같은 예외 상황에서는 클라이언트가 업로드 ID를 기억해두는 것이 중요합니다.
쿠키나 로컬스토리지를 이용해 ID를 보관하면 페이지를 새로 열어도 이어서 업로드할 수 있습니다.
또한 서버 측에서는 일정 시간 동안 도착하지 않은 세션을 자동으로 정리하는 기능을 둬야 자원 낭비를 방지할 수 있습니다.

🔌 Nginx WSGI S3 등 실무 환경 설정 체크리스트

대용량·청크·재개 업로드는 코드만으로 완성되지 않습니다.
프록시 서버, WSGI 런타임, 객체 스토리지의 설정이 맞물려야 병목과 타임아웃을 피하고 안정성을 확보할 수 있습니다.
여기서는 Nginx 프록시, Gunicorn 같은 WSGI 서버, 그리고 AWS S3 멀티파트 업로드 구성 시 확인해야 할 핵심 포인트를 체크리스트와 예시 설정으로 정리합니다.
각 항목은 독립적으로 적용 가능하며, 서비스 특성에 맞게 수치 값을 조정하는 것을 권장합니다.

📌 Nginx 리버스 프록시 권장 설정

프론트 프록시는 클라이언트와 WSGI 사이에서 첫 번째 완충 역할을 합니다.
대용량 업로드에서는 요청 버퍼링과 본문 크기 제한, 타임아웃 값이 특히 중요합니다.

server {
  client_max_body_size 0;                    # 업로드 크기 제한 해제(또는 충분히 크게)
  proxy_request_buffering off;               # 청크 스트리밍에 유리
  proxy_buffering off;                       # 대기 지연 최소화
  proxy_read_timeout 600s;                   # 네트워크 품질에 따라 상향
  proxy_send_timeout 600s;

  location / {
    proxy_pass http://127.0.0.1:8000;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
  }
}

📌 Gunicorn WSGI 런타임 튜닝

WSGI 서버는 동시성 모델과 타임아웃 전략을 통해 업로드 중인 워커가 장시간 블로킹되지 않도록 구성합니다.
CPU 코어 수, 예상 동시 업로드 수, I/O 패턴을 고려해 워커·스레드를 조합하세요.

# 예: I/O 중심 워크로드용 gunicorn 명령
gunicorn app:app \
  --bind 127.0.0.1:8000 \
  --workers 4 \                 # 코어 수 기준
  --threads 4 \                 # I/O 대기 완충
  --timeout 600 \               # 업로드 지연 대비
  --graceful-timeout 30 \
  --keep-alive 75

• 🧵스레드 수는 과도하게 높이지 말고, uploads/sec 모니터링으로 점진 조정
• 🧯워크 커넥션 고갈 방지: 프런트(Nginx)의 keepalive와 백엔드 타임아웃 균형화
• 📈프로메테우스/로깅으로 요청 시간 분포와 업로드 실패율 추적

📌 AWS S3 멀티파트 업로드 체크포인트

S3를 최종 저장소로 사용할 경우 서버에서 머지하지 않고, 클라이언트가 바로 S3에 올리도록 사전 서명 URL과 멀티파트 업로드를 조합하면 백엔드 부하를 크게 줄일 수 있습니다.

# Flask에서 사전 서명 URL 발급 예시
import boto3, os
s3 = boto3.client("s3")

@app.post("/s3/presign")
def presign():
    data = request.get_json()
    return {
      "url": s3.generate_presigned_url(
         ClientMethod="put_object",
         Params={"Bucket": os.environ["BUCKET"], "Key": data["key"]},
         ExpiresIn=600,
         HttpMethod="PUT"
      )
    }

📌 운영 자동화와 스토리지 정리

임시 청크와 미완료 세션은 디스크를 빠르게 소모합니다.
주기 배치로 만료된 업로드 ID를 정리하고, 파일 머지 완료 후에는 임시 파트를 즉시 삭제합니다.
로그에는 업로드 ID, 사용자, 파일 해시, 청크 범위를 남겨 추적 가능한 상태를 유지하세요.

• 🚦Nginx: client_max_body_size, proxy_request_buffering, 타임아웃 재확인
• 🧪대역폭·지연 혼합 조건에서 대용량 파일로 스트레스 테스트
• 🗂️임시 디렉터리 파티션 용량, inode 모니터링
• 🔐사전 서명 URL 범위 최소화, 업로드 ID에 사용자 바인딩
• 🧹미완료 세션 TTL 설정과 주기적 가비지 컬렉션

💡 무결성 검증 속도 최적화 보안 베스트 프랙티스

대용량 업로드가 끝났다고 해서 바로 안전하다고 볼 수는 없습니다.
파일이 손상되거나 악성 코드가 포함될 수 있기 때문에 반드시 무결성 검증과 보안 점검을 거쳐야 합니다.
또한 업로드 처리 속도를 최적화하지 않으면 서버 리소스가 과도하게 소모될 수 있습니다.
이 단계에서는 성능과 보안을 동시에 확보하기 위한 실무 팁을 정리합니다.

📌 파일 무결성 검증

업로드된 파일이 원본과 동일한지 확인하려면 해시 검증을 수행해야 합니다.
대표적으로 SHA-256이나 MD5 해시를 사용합니다.
클라이언트가 전체 파일 해시와 청크별 해시를 미리 계산해 서버에 전달하면, 서버는 저장된 데이터와 대조하여 손상 여부를 판단할 수 있습니다.

import hashlib

def sha256sum(path):
    h = hashlib.sha256()
    with open(path, "rb") as f:
        for chunk in iter(lambda: f.read(8192), b""):
            h.update(chunk)
    return h.hexdigest()

📌 성능 최적화 전략

대용량 업로드는 디스크 I/O와 CPU 연산을 동시에 소모하기 때문에 효율적인 자원 활용이 필요합니다.

• 📂스트리밍 방식으로 파일을 읽고 해시를 계산해 메모리 사용량 최소화
• ⚡멀티스레드/멀티프로세스로 청크 해시를 병렬 계산
• 🗄️임시 저장소를 SSD로 설정해 I/O 병목 최소화
• 📡업로드 중간 상태를 주기적으로 Redis에 기록해 장애 복구 속도 향상

📌 보안 베스트 프랙티스

업로드 과정에서 보안을 강화하려면 아래 항목들을 반드시 확인해야 합니다.

• 🔐인증·인가를 거친 사용자만 업로드 가능
• 🧹미완료 업로드 세션을 주기적으로 정리해 자원 낭비 방지
• 🦠바이러스 및 악성 코드 스캔 자동화 도입
• 🚫허용 확장자와 MIME 타입을 화이트리스트 방식으로 제한
• 🛡️업로드 파일은 즉시 격리 디렉토리에 보관하고 승인 후에만 서비스와 연동

❓ 자주 묻는 질문 (FAQ)