AWS S3를 활용한 파이썬(FastAPI) 이미지 업로드 API 구현

AWS S3를 활용한 파이썬(FastAPI) 이미지 업로드 API 구현

서비스에 '유저 프로필 사진'이나 '프로젝트 포트폴리오 이미지'를 업로드하는 기능은 필수적입니다. 하지만 이미지를 백엔드 서버에 직접 저장하는 것은 서버 용량 부족과 속도 저하의 주범입니다. 이를 해결하기 위해 글로벌 스탠다드로 쓰이는 AWS S3(Simple Storage Service) 연동법을 알아봅니다.

1. 왜 클라우드 스토리지(S3)를 사용해야 할까?

웹 서버(EC2)는 연산을 처리하는 두뇌 역할을 해야지, 짐을 쌓아두는 창고 역할을 해서는 안 됩니다. S3는 무한대에 가까운 용량을 제공하며, 데이터가 유실될 확률이 극히 적은 완벽한 '클라우드 창고'입니다. 데이터베이스에는 이미지가 저장된 'URL 주소(텍스트)'만 저장하고, 실제 파일은 S3로 보내는 것이 정석입니다.

2. Boto3: 파이썬에서 AWS를 조종하는 리모컨

파이썬 서버에서 AWS S3와 통신하기 위해서는 AWS가 공식 지원하는 boto3 라이브러리를 사용해야 합니다. 먼저 AWS IAM에서 S3 접근 권한이 있는 Access Key와 Secret Key를 발급받아야 합니다.

3. FastAPI 파일 업로드 로직 구현

클라이언트로부터 이미지를 받아 AWS S3에 다이렉트로 업로드하고, 저장된 이미지의 URL을 반환하는 API 엔드포인트 예시입니다.

from fastapi import FastAPI, UploadFile, File
import boto3
import uuid

app = FastAPI()

# S3 클라이언트 설정 (보안을 위해 환경변수로 관리해야 함)
s3_client = boto3.client(
    's3',
    aws_access_key_id='YOUR_ACCESS_KEY',
    aws_secret_access_key='YOUR_SECRET_KEY',
    region_name='ap-northeast-2'
)
BUCKET_NAME = 'my-dev-match-bucket'

@app.post("/upload/profile/")
async def upload_profile_image(file: UploadFile = File(...)):
    # 파일명 중복 방지를 위해 UUID 생성
    file_extension = file.filename.split(".")[-1]
    new_file_name = f"{uuid.uuid4()}.{file_extension}"
    
    # S3에 파일 업로드
    s3_client.upload_fileobj(
        file.file, 
        BUCKET_NAME, 
        new_file_name,
        ExtraArgs={"ContentType": file.content_type}
    )
    
    # S3에 저장된 이미지의 공개 URL 생성
    image_url = f"https://{BUCKET_NAME}.s3.ap-northeast-2.amazonaws.com/{new_file_name}"
    
    return {"message": "업로드 성공", "image_url": image_url}

4. 마무리

이 구조를 마스터하면 이미지뿐만 아니라 PDF, 동영상 등 어떤 포맷의 파일이든 무제한으로 다룰 수 있는 확장성 높은 백엔드를 갖추게 됩니다. 다음은 이렇게 만든 서버를 세상에 배포하는 방법을 알아보겠습니다.