서버 비용 폭탄 막는 Flutter S3 파일 업로드 실전 가이드 (Pre-signed URL, Lambda, IAM, CORS 총정리)

오늘날의 모바일 애플리케이션은 단순히 정보를 소비하는 창구를 넘어 사용자가 적극적으로 콘텐츠를 생산하고 공유하는 플랫폼으로 진화했습니다. 인스타그램의 사진과 릴스, 유튜브의 동영상, 중고 거래 앱의 상품 이미지, 클라우드 드라이브의 문서 파일까지, 성공적인 서비스의 이면에는 사용자가 생성한 수많은 파일을 안정적으로 처리하는 기술이 자리 잡고 있습니다. 하지만 늘어나는 사용자만큼, 혹은 그 이상으로 빠르게 증가하는 파일 데이터는 개발자와 인프라 담당자에게 커다란 숙제를 안겨줍니다. 바로 '서버 부하'와 '비용' 문제입니다.

만약 여러분의 Flutter 앱이 사용자가 업로드하는 파일을 애플리케이션 서버를 통해 S3와 같은 스토리지로 전달하는 전통적인 방식을 사용하고 있다면, 서비스가 성장할수록 서버는 점점 더 느려지고 네트워크 비용은 눈덩이처럼 불어나는 '비용 폭탄'을 맞이할 위험이 큽니다. 사용자는 느린 업로드 속도에 불만을 느끼고, 회사는 불필요한 인프라 비용으로 골머리를 앓게 됩니다.

이 글에서는 이러한 문제를 근본적으로 해결하고, 여러분의 Flutter 앱을 한 단계 더 높은 수준의 아키텍처로 끌어올릴 수 있는 'AWS S3로 직접 파일 업로드' 방식을 심도 있게 다룹니다. 특히, 서버리스의 꽃이라 불리는 API Gateway와 Lambda를 활용하여 보안과 효율성을 모두 잡는 Pre-signed URL(미리 서명된 URL) 생성부터, 많은 개발자들이 함정에 빠지는 IAM 권한 문제와 CORS 설정까지, 실전에서 마주할 수 있는 모든 과정을 총정리하여 상세히 안내합니다. 이 가이드를 끝까지 따라오시면, 서버 부하와 비용 걱정 없이 확장 가능한 파일 업로드 시스템을 구축할 수 있는 튼튼한 기반을 다지게 될 것입니다.

왜 파일 업로드는 서버를 우회해야 하는가? (전통 방식의 치명적 단점)

현대적인 접근법을 이해하기 전에, 왜 기존 방식이 더 이상 유효하지 않은지 명확히 짚고 넘어갈 필요가 있습니다. 전통적인 파일 업로드 아키텍처는 다음과 같은 흐름을 가집니다.

[전통 방식] Flutter App → Application Server (e.g., EC2) → AWS S3

1. 데이터 수신: Flutter 클라이언트가 이미지나 동영상 파일을 HTTP 요청의 Body에 담아 우리가 운영하는 애플리케이션 서버(예: AWS EC2, Spring Boot, NestJS 서버 등)로 전송합니다.
2. 서버 처리: 서버는 이 거대한 파일 데이터를 네트워크 소켓으로부터 모두 읽어들여 메모리나 임시 디스크 공간에 저장합니다.
3. 데이터 재전송: 서버는 AWS SDK를 사용하여 방금 받은 파일 데이터를 다시 AWS S3 버킷으로 업로드합니다.

이 방식은 논리적으로 단순하고 구현이 직관적이라는 장점이 있지만, 서비스 규모가 커지면 다음과 같은 심각한 문제들을 야기합니다.

1. 서버 부하 및 성능 저하

이 아키텍처의 가장 큰 문제는 모든 파일 데이터가 애플리케이션 서버를 '경유'한다는 점입니다. 서버는 파일 업로드를 처리하는 동안 CPU, 메모리, 네트워크 대역폭 등 핵심 자원을 소모합니다. 작은 텍스트 데이터가 아닌 수십, 수백 메가바이트(MB)에 달하는 파일들이 동시에 업로드된다고 상상해보십시오. 서버는 본연의 비즈니스 로직(게시글 처리, 사용자 인증 등)을 처리할 자원을 파일 전송에 빼앗기게 되어 전체 서비스의 응답 속도가 현저히 느려집니다. 이는 마치 작은 동네 우체국이 거대 물류창고로 들어갈 모든 소포를 일일이 받아서 다시 포장해 보내는 것과 같은 비효율입니다.

2. 불필요한 네트워크 비용 발생

클라우드 환경, 특히 AWS에서 비용을 결정하는 중요한 요소 중 하나는 '데이터 전송(Data Transfer)' 비용입니다. 일반적으로 클라우드 서비스로 데이터가 들어오는 '인바운드(Inbound)' 트래픽은 무료이거나 매우 저렴합니다. 하지만 서비스에서 데이터가 밖으로 나가는 '아웃바운드(Outbound)' 트래픽에는 상당한 비용이 부과됩니다.

• (1단계) 클라이언트 → 서버: 이 구간은 서버의 '인바운드' 트래픽입니다. (비용 낮음)
• (2단계) 서버 → S3: 이 구간은 서버의 '아웃바운드' 트래픽입니다. (비용 발생!)

사용자가 1GB 파일을 업로드하면, 우리 서버는 1GB의 아웃바운드 트래픽을 S3로 보내는 데 사용합니다. 이 데이터는 어차피 S3로 가야 할 데이터인데, 굳이 우리 서버를 거치면서 불필요한 통행료를 지불하는 셈입니다. 사용자가 많아지고 파일 크기가 커질수록 이 비용은 무시할 수 없는 수준으로 증가합니다.

3. 복잡한 확장성 문제

파일 업로드 요청이 급증하면 어떻게 해야 할까요? 전통적인 방식에서는 파일 처리 부담을 견디지 못하는 애플리케이션 서버 자체를 증설(Scale-out)해야 합니다. 이는 단순히 서버 대수만 늘리는 것이 아니라 로드 밸런서 설정, 세션 관리, 데이터 동기화 등 전체 아키텍처의 복잡도를 높이는 결과를 초래합니다. 단지 파일 업로드 기능 하나 때문에 전체 시스템이 무거워지고 관리 포인트가 늘어나는 것입니다.

이러한 문제들을 해결하기 위한 현대적인 해답이 바로 클라이언트에서 S3로 직접 업로드하는 방식입니다. 파일 데이터는 더 이상 우리 서버를 괴롭히지 않고 클라이언트에서 S3로 직행합니다. 우리 서버는 단지 "이 사용자는 파일을 업로드할 자격이 있다"는 것을 증명하는 가벼운 '허가증'만 발급해주는 역할로 바뀌게 됩니다.

[현대 방식] Flutter App ↗ (2. 파일 업로드) ↗ S3
Flutter App ↔ (1. 업로드 허가 요청/응답) ↔ Application Server

이 구조를 통해 서버 부하와 네트워크 비용을 90% 이상 절감하고, 파일 업로드 트래픽이 아무리 늘어나도 애플리케이션 서버는 영향을 받지 않는 탄력적인 시스템을 구축할 수 있습니다. 그리고 이 구조의 핵심 열쇠가 바로 'Pre-signed URL'입니다.

보안과 효율의 교차점, Pre-signed URL의 모든 것

클라이언트가 S3에 직접 파일을 업로드하게 하려면, S3는 "이 요청이 신뢰할 수 있는 사용자의 요청인지"를 확인해야 합니다. 이를 위해 AWS 자격 증명(Access Key ID와 Secret Access Key)이 필요합니다. 하지만 이 자격 증명을 Flutter 앱 코드 안에 하드코딩하는 것은 금고 열쇠를 금고 문에 붙여놓는 것과 같은, 절대 해서는 안 될 최악의 보안 실수입니다. 앱이 디컴파일되면 자격 증명이 그대로 노출되어 해커가 우리의 S3 버킷에 무제한으로 접근해 데이터를 훔치거나 삭제하고, 심지어 암호화폐 채굴과 같은 악의적인 용도로 사용하여 상상조차 하기 힘든 '요금 폭탄'을 안겨줄 수 있습니다.

Pre-signed URL(미리 서명된 URL)은 이 딜레마를 우아하게 해결합니다. 그 원리는 다음과 같습니다.

1. [1단계: 허가 요청] Flutter 앱이 파일 업로드를 시작하기 전에, 우리 서버(API)에 "profile-images/user-123.jpg 라는 이름으로 파일을 올리고 싶으니, 임시 업로드 허가증을 발급해주세요." 라고 요청합니다.
2. [2단계: 검증 및 생성] 서버는 이 요청을 보낸 사용자가 로그인된 정식 사용자인지, 프로필 이미지를 업로드할 권한이 있는지 등을 먼저 확인합니다. 모든 검증을 통과하면, 서버만이 안전하게 보관하고 있는 AWS 자격 증명을 사용하여 아주 제한적인 권한을 가진 특별한 URL을 생성합니다. 이 URL에는 다음과 같은 정보가 암호화된 서명과 함께 포함됩니다.
   • 누가(Who): 이 URL을 생성한 주체(서버의 AWS 자격 증명)
   • 무엇을(What): profile-images/user-123.jpg 라는 특정 객체(파일)
   • 어떤 작업을(Action): 객체를 생성하는 작업(PUT 요청)
   • 언제까지(When): 앞으로 5분(300초) 동안만 유효함
3. [3단계: 허가증 반환] 서버는 이렇게 생성된, 유효 시간이 짧고 특정 작업만 허용하는 Pre-signed URL을 Flutter 앱에게 응답으로 전달합니다.
4. [4단계: 직접 업로드] Flutter 앱은 이 URL을 목적지로 삼아 HTTP PUT 요청을 보냅니다. 요청의 본문(Body)에는 실제 이미지 파일 데이터를 담습니다. S3는 이 요청을 받고 URL에 포함된 서명과 각종 파라미터를 검증합니다. 서명이 유효하고, 유효 시간 이내이며, 지정된 작업(PUT)과 객체 키가 일치하면 요청을 승인하고 파일을 안전하게 저장합니다.

이 방식의 핵심은, Flutter 앱은 단 한 번도 강력한 AWS 자격 증명에 직접 접근하지 않는다는 것입니다. 앱이 갖는 것은 오직 짧은 시간 동안 특정 파일 하나를 올리는 데만 사용할 수 있는 일회용 티켓뿐입니다. 설령 이 URL이 중간에 탈취되더라도 유효 시간이 지나면 쓸모가 없어지며, 해커는 이 URL을 가지고 파일을 삭제하거나 다른 파일을 읽는 등의 다른 작업을 절대 수행할 수 없습니다.

실전 아키텍처 설계: Flutter, API Gateway, Lambda, S3 조합

이제 우리가 구축할 전체 시스템의 청사진을 그려보겠습니다. 우리는 이 효율적인 아키텍처를 서버리스(Serverless) 구성 요소들을 활용해 더욱 강력하고 비용 효율적으로 만들 것입니다.

Flutter App <--> AWS API Gateway <--> AWS Lambda <--> AWS S3

• Flutter App: 사용자에게 파일 선택 UI를 제공하고, 업로드 버튼을 누르면 API Gateway를 통해 Lambda 함수를 호출하여 Pre-signed URL을 요청합니다. URL을 받으면 해당 URL로 파일 데이터를 직접 S3에 전송하는 역할을 담당합니다.
• AWS API Gateway: Flutter 앱으로부터의 HTTP 요청을 안전하게 받아 처리하는 '관문'입니다. /presigned-url과 같은 특정 엔드포인트로 들어온 요청을 뒤에 있는 Lambda 함수로 전달(trigger)하는 역할을 합니다. 인증, 요청량 제어(Throttling) 등 다양한 부가 기능을 제공합니다.
• AWS Lambda: Pre-signed URL을 생성하는 핵심 로직을 수행하는 '두뇌'입니다. Node.js, Python, Go 등 선호하는 언어로 코드를 작성할 수 있으며, 요청이 있을 때만 실행되고 실행된 시간만큼만 비용을 지불하므로 매우 경제적입니다. URL 생성과 같은 가벼운 작업에 최적화되어 있습니다.
• AWS S3 (Simple Storage Service): 최종적으로 파일이 저장되는 안전하고 내구성이 뛰어난 '저장고'입니다. 거의 무한에 가까운 확장성을 제공하여 파일 수나 용량에 대한 걱정 없이 사용할 수 있습니다.

1단계: S3 버킷 생성 및 CORS 설정 (가장 흔한 함정)

코드를 작성하기에 앞서, 파일이 저장될 S3 버킷을 준비하고 가장 중요한 설정 중 하나인 CORS를 구성해야 합니다. 많은 개발자들이 이 단계를 놓쳐 원인 모를 오류에 시달리곤 합니다.

1. AWS Management Console에 로그인하여 S3 서비스로 이동합니다.
2. '버킷 만들기'를 클릭하고, 전역적으로 고유한 버킷 이름을 입력합니다 (예: my-flutter-uploads-2023). 리전은 사용자와 가까운 곳(예: ap-northeast-2, 서울)을 선택합니다.
3. '모든 퍼블릭 액세스 차단' 설정을 그대로 유지합니다. Pre-signed URL을 사용할 것이므로 버킷 자체를 공개할 필요가 전혀 없습니다. 이것이 보안의 기본입니다.
4. 버킷 생성을 완료한 후, 생성된 버킷의 '권한' 탭으로 이동합니다.
5. 아래로 스크롤하여 '교차 출처 리소스 공유(CORS)' 섹션을 찾고 '편집' 버튼을 클릭합니다.

이제 여기에 CORS 정책을 입력해야 합니다. 왜 CORS 설정이 필요할까요? 웹 브라우저와 최신 앱 프레임워크는 '동일 출처 정책(Same-Origin Policy)'이라는 보안 규칙을 따릅니다. 이는 악성 스크립트가 다른 웹사이트의 리소스를 마음대로 가져오지 못하게 막는 중요한 장치입니다. 우리의 Flutter 앱(또는 웹)은 우리 서버(API Gateway 도메인)와 통신하지만, 파일을 업로드할 때는 전혀 다른 도메인인 S3(s3.ap-northeast-2.amazonaws.com)로 직접 요청을 보내야 합니다. S3 서버가 "다른 출처(도메인)에서 온 이 요청을 허용하겠다"고 명시적으로 알려주지 않으면, 클라이언트는 보안 위협으로 간주하고 요청을 차단해 버립니다. 이것이 CORS 오류의 정체입니다.

따라서 S3 버킷에 다음과 같은 CORS 규칙을 추가하여, 우리 앱이 파일을 올리는 PUT 요청을 보낼 수 있도록 허용해주어야 합니다.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": "*",
            "Action": "s3:GetObject",
            "Resource": "arn:aws:s3:::버킷이름/*"
        }
    ]
}

CORS 설정 편집창에 아래 JSON 코드를 붙여넣습니다. 이 설정은 모든 도메인(*)에서 오는 PUT, POST, DELETE 요청을 허용합니다. 프로덕션 환경에서는 <AllowedOrigin>을 * 대신 여러분의 웹사이트 도메인이나 특정 출처로 제한하는 것이 더 안전합니다.

<CORSConfiguration>
 <CORSRule>
   <AllowedOrigin>*</AllowedOrigin>
   <AllowedMethod>PUT</AllowedMethod>
   <AllowedMethod>POST</AllowedMethod>
   <AllowedMethod>DELETE</AllowedMethod>
   <AllowedHeader>*</AllowedHeader>
   <MaxAgeSeconds>3000</MaxAgeSeconds>
 </CORSRule>
</CORSConfiguration>

이 설정을 저장하면 S3 버킷 준비는 완료됩니다. 이 단계를 건너뛰면 Flutter 클라이언트에서 S3로 파일을 업로드할 때 네트워크 오류 또는 CORS 관련 오류가 발생하니 반드시 확인해야 합니다.

2단계: Pre-signed URL 생성 Lambda 함수 작성 (Node.js & Python)

이제 Pre-signed URL을 생성하는 서버리스 함수를 작성할 차례입니다. AWS Lambda에서 가장 널리 쓰이는 Node.js와 Python 두 가지 버전의 예시를 모두 살펴보겠습니다.

Node.js (AWS SDK v3) 예시

최신 AWS SDK v3는 모듈식으로 설계되어 필요한 패키지만 가져올 수 있어 더 효율적입니다. Lambda 함수를 생성하고 런타임을 Node.js 18.x 이상으로 설정한 후 다음 코드를 입력합니다.

// 필요한 AWS SDK v3 모듈과 uuid 패키지를 import 합니다.
import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
import { v4 as uuidv4 } from 'uuid';

// S3 클라이언트 인스턴스를 생성합니다. Lambda 실행 환경의 리전을 자동으로 사용합니다.
// 명시적으로 지정하려면 { region: "ap-northeast-2" } 와 같이 설정합니다.
const s3Client = new S3Client({});

// 환경 변수나 코드 내에서 S3 버킷 이름을 정의합니다.
const BUCKET_NAME = process.env.BUCKET_NAME || "your-s3-bucket-name";

export const handler = async (event) => {
    console.log("Received event:", JSON.stringify(event, null, 2));

    // 클라이언트에서 파일 이름과 타입을 받을 수 있습니다. (API Gateway 설정 필요)
    // const queryStringParameters = event.queryStringParameters || {};
    // const fileName = queryStringParameters.fileName;
    // const fileType = queryStringParameters.fileType;

    // 여기서는 간단히 UUID를 사용하여 고유한 파일 키를 생성합니다.
    // 'uploads/' 라는 prefix를 붙여 폴더처럼 관리할 수 있습니다.
    // 실제 앱에서는 user-id 등을 조합하여 더 체계적으로 관리하는 것이 좋습니다.
    // ex: `uploads/${userId}/${uuidv4()}.jpg`
    const fileKey = `uploads/${uuidv4()}.jpg`;

    // Pre-signed URL 생성을 위한 명령(Command) 객체를 생성합니다.
    // 어떤 버킷에(Bucket), 어떤 이름으로(Key) 저장할지를 지정합니다.
    const command = new PutObjectCommand({
        Bucket: BUCKET_NAME,
        Key: fileKey,
        // ContentType: fileType, // 클라이언트에서 받은 파일 타입을 지정해주면 더 좋습니다.
    });

    try {
        // getSignedUrl 함수를 사용하여 URL을 생성합니다.
        // 유효 시간을 300초 (5분)으로 설정합니다. 이 시간 내에 업로드가 완료되어야 합니다.
        const signedUrl = await getSignedUrl(s3Client, command, { expiresIn: 300 });

        console.log("Successfully created pre-signed URL:", signedUrl);

        // 클라이언트에게 성공 응답을 반환합니다.
        // CORS를 위해 Access-Control-Allow-Origin 헤더를 포함하는 것이 안전합니다.
        return {
            statusCode: 200,
            headers: {
                "Access-Control-Allow-Origin": "*",
                "Access-Control-Allow-Headers": "Content-Type",
                "Access-Control-Allow-Methods": "GET,PUT"
            },
            body: JSON.stringify({
                uploadURL: signedUrl,
                key: fileKey, // 클라이언트가 업로드 성공 후 파일 키를 알 수 있도록 전달합니다.
            }),
        };
    } catch (error) {
        console.error("Error creating pre-signed URL", error);
        return {
            statusCode: 500,
            body: JSON.stringify({ message: "Error creating pre-signed URL", error: error.message }),
        };
    }
};

코드를 배포하기 전에 `uuid` 패키지를 Lambda 계층(Layer)으로 추가하거나, 배포 패키지에 함께 포함시켜야 합니다.

Python (Boto3) 예시

Python을 선호하는 개발자를 위해 Boto3 라이브러리를 사용한 예시입니다. 런타임을 Python 3.9 이상으로 설정합니다.

import boto3
import uuid
import json
import os
from botocore.exceptions import ClientError
import logging

# 로거 설정
logger = logging.getLogger()
logger.setLevel(logging.INFO)

# S3 클라이언트 생성
s3_client = boto3.client('s3', region_name=os.environ.get('AWS_REGION', 'ap-northeast-2'))

# 환경 변수에서 버킷 이름 가져오기
BUCKET_NAME = os.environ.get('BUCKET_NAME', 'your-s3-bucket-name')

def handler(event, context):
    logger.info(f"Received event: {json.dumps(event)}")
    
    # 고유한 파일 키 생성
    # ex: uploads/a1b2c3d4-e5f6-7890-1234-56789abcdef0.jpg
    file_key = f"uploads/{uuid.uuid4()}.jpg"
    
    # Pre-signed URL을 생성할 때 파일의 Content-Type을 지정할 수 있습니다.
    # 클라이언트가 이 타입으로 업로드해야 합니다.
    # content_type = "image/jpeg" 
    
    try:
        # Boto3의 generate_presigned_url 함수 사용
        presigned_url = s3_client.generate_presigned_url(
            'put_object',
            Params={
                'Bucket': BUCKET_NAME,
                'Key': file_key,
                # 'ContentType': content_type
            },
            ExpiresIn=300  # URL 유효 시간 (초)
        )
        
        logger.info(f"Successfully created pre-signed URL for key: {file_key}")
        
        # 클라이언트에 성공 응답 반환
        return {
            'statusCode': 200,
            'headers': {
                'Access-Control-Allow-Origin': '*',
                'Access-Control-Allow-Headers': 'Content-Type',
                'Access-Control-Allow-Methods': 'GET,PUT'
            },
            'body': json.dumps({
                'uploadURL': presigned_url,
                'key': file_key
            })
        }
        
    except ClientError as e:
        logger.error(f"Error generating pre-signed URL: {e}")
        return {
            'statusCode': 500,
            'body': json.dumps({'message': 'Could not generate pre-signed URL'})
        }

두 코드 모두 동일한 역할을 수행합니다. 팀의 기술 스택에 맞는 언어를 선택하면 됩니다.

3단계: API Gateway 설정 및 Lambda 연동

이제 Flutter 앱이 호출할 수 있는 HTTP 엔드포인트를 만들 차례입니다.

1. AWS Console에서 API Gateway 서비스로 이동합니다.
2. 다양한 API 타입 중 'HTTP API'의 '구축'을 선택합니다. HTTP API는 REST API보다 더 간단하고 저렴하여 이런 용도에 적합합니다.
3. '통합' 단계에서 '통합 추가'를 클릭합니다.
   • 통합 대상: Lambda
   • Lambda 함수: 위에서 생성한 Lambda 함수 (예: presigned-url-generator-nodejs)를 선택합니다.
4. API 이름을 지정하고(예: FileUploadAPI) 다음으로 넘어갑니다.
5. '경로 구성' 단계에서 '경로 만들기'를 클릭합니다.
   • 메서드: GET
   • 경로: /presigned-url (또는 원하는 경로)
   • 통합 대상: 방금 생성한 Lambda 통합을 선택합니다.
6. 나머지 설정은 기본값으로 두고 API를 생성합니다.
7. 생성이 완료되면 대시보드에서 '호출 URL'을 확인할 수 있습니다. 이 URL이 바로 Flutter 앱에서 API를 호출할 때 사용할 엔드포인트입니다. (예: https://abcdef123.execute-api.ap-northeast-2.amazonaws.com/presigned-url)
8. 마지막으로, 왼쪽 메뉴에서 'CORS'를 선택하고, '액세스 제어 허용 출처'에 *를 입력하고 필요한 헤더(Content-Type 등)와 메서드(GET)를 허용하도록 설정합니다. 이는 S3의 CORS와는 별개로, API Gateway 자체에 대한 CORS 설정입니다.

4단계: IAM 역할, 'Cold Start 실패' 미스터리의 진실

이제 아키텍처의 모든 조각이 맞춰진 것처럼 보입니다. 하지만 이 상태에서 테스트를 해보면 많은 개발자들이 기묘한 문제에 부딪힙니다. 바로 "한동안 앱을 사용하지 않다가 파일 업로드를 시도하면 첫 번째 시도가 실패하고, 곧바로 다시 시도하면 성공하는 현상"입니다.

이 문제의 원인으로 Lambda의 '콜드 스타트(Cold Start)'가 흔히 지목됩니다. 콜드 스타트는 오랫동안 호출되지 않은 Lambda 함수가 다시 호출될 때 실행 환경을 새로 준비하는 과정에서 발생하는 지연 시간입니다. 개발자들은 이 지연 시간 때문에 타임아웃이 발생한다고 추측하고, 첫 요청은 무시하거나 더미 요청을 보내 함수를 '깨우는(warm-up)' 등의 임시방편을 사용하곤 합니다. 하지만 이것은 문제의 현상일 뿐, 근본적인 원인이 아닙니다.

이 문제의 진짜 원인은 99%의 경우 Lambda 함수에 부여된 'IAM 실행 역할(Execution Role)'의 권한 부족입니다.

Lambda 함수가 S3와 같은 다른 AWS 서비스와 상호작용하려면, 반드시 IAM 역할을 통해 명시적인 권한을 부여받아야 합니다. getSignedUrl 이나 generate_presigned_url 함수는 단순히 URL 문자열을 만드는 마법이 아닙니다. 이 함수는 내부적으로 다음과 같이 동작합니다.

"지금 이 코드를 실행하고 있는 주체(Lambda의 실행 역할)의 권한을 빌려서, 'S3 버킷에 객체를 쓰는(PutObject) 행위'를 할 수 있는 임시 URL을 만들려고 합니다. 과연 이 실행 역할은 정말로 해당 S3 버킷에 PutObject를 할 권한을 가지고 있나요?"

만약 Lambda의 실행 역할에 s3:PutObject 권한이 없다면, AWS SDK는 유효하지 않은 서명을 가진 URL을 생성하거나 아예 생성에 실패합니다. 콜드 스타트 시에 이 문제가 두드러지는 이유는, 초기화 과정에서 이 권한 확인을 포함한 모든 절차가 처음부터 실행되면서 권한 부족 문제가 수면 위로 드러나기 때문입니다.

따라서, 이 미스터리를 해결하는 올바른 방법은 Lambda 함수의 실행 역할에 S3 버킷에 대한 정확한 권한을 부여하는 것입니다.

올바른 IAM 정책 설정하기

1. AWS Console에서 IAM 서비스로 이동합니다.
2. 왼쪽 메뉴에서 '역할'을 선택하고, API Gateway와 연동된 Lambda 함수가 사용하는 역할을 찾습니다. (보통 함수이름-role-xxxxxx 와 같은 이름입니다.)
3. 해당 역할을 클릭하고 '권한' 탭에서 '권한 추가' > '인라인 정책 생성'을 선택합니다.
4. JSON 편집기를 선택하고, 다음 정책을 붙여넣습니다. 이것이 바로 '최소 권한의 원칙'을 따르는 가장 안전하고 권장되는 정책입니다.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:PutObject"
            ],
            "Resource": [
                "arn:aws:s3:::your-s3-bucket-name/*"
            ]
        }
    ]
}

• Effect: "Allow": 이 작업을 허용합니다.
• Action: "s3:PutObject": S3에 객체를 생성(업로드)하는 작업만 정확히 지정합니다.
• Resource: "arn:aws:s3:::your-s3-bucket-name/*": 위 작업을 어느 자원에 대해 허용할지 지정합니다. your-s3-bucket-name을 여러분의 버킷 이름으로 바꾸고, /*를 붙여 버킷 안의 모든 객체(파일)에 대해 적용한다는 의미입니다.

정책 이름을 지정하고(예: AllowS3PutObjectPolicy) 정책을 생성하면 모든 설정이 끝납니다. 이제 Lambda 함수는 콜드 스타트 여부와 관계없이 첫 번째 요청부터 항상 유효한 Pre-signed URL을 성공적으로 생성할 것입니다.

주의: 간혹 인터넷 예제에서 "Action": "s3:*" 와 같이 와일드카드를 사용한 정책을 볼 수 있습니다. 이는 해당 버킷에 대한 모든 작업(읽기, 쓰기, 삭제, 권한 변경 등)을 허용하는 매우 강력한 권한입니다. Lambda 함수 코드에 보안 취약점이 있을 경우, 버킷의 모든 데이터가 유출되거나 삭제될 수 있는 심각한 위험을 초래하므로 절대 프로덕션 환경에서 사용해서는 안 됩니다.

5단계: Flutter 클라이언트 최종 구현 코드

이제 모든 백엔드 준비가 끝났습니다. Flutter 앱에서 이 시스템을 사용하는 코드를 작성해 보겠습니다. `http` 패키지와 `image_picker` 패키지가 `pubspec.yaml`에 추가되어 있다고 가정합니다.

import 'dart:io';
import 'package:flutter/material.dart';
import 'package:http/http.dart' as http;
import 'package:image_picker/image_picker.dart';
import 'dart:convert';

class S3UploaderScreen extends StatefulWidget {
  const S3UploaderScreen({super.key});

  @override
  State<S3UploaderScreen> createState() => _S3UploaderScreenState();
}

class _S3UploaderScreenState extends State<S3UploaderScreen> {
  // 3단계에서 확인한 API Gateway의 호출 URL을 입력합니다.
  final String presignedUrlApiEndpoint = 'YOUR_API_GATEWAY_ENDPOINT_URL/presigned-url';

  File? _selectedImage;
  final ImagePicker _picker = ImagePicker();
  String _statusMessage = '이미지를 선택하여 업로드를 시작하세요.';
  bool _isUploading = false;
  String? _uploadedFileKey;

  Future<void> _pickImageFromGallery() async {
    final XFile? pickedFile = await _picker.pickImage(source: ImageSource.gallery);
    if (pickedFile != null) {
      setState(() {
        _selectedImage = File(pickedFile.path);
        _statusMessage = '이미지가 선택되었습니다. 업로드 버튼을 누르세요.';
        _uploadedFileKey = null;
      });
    }
  }

  Future<void> _uploadImageToS3() async {
    if (_selectedImage == null) {
      setState(() => _statusMessage = '업로드할 이미지를 먼저 선택해주세요.');
      return;
    }
    if (_isUploading) return;

    setState(() {
      _isUploading = true;
      _statusMessage = '업로드 준비 중... Pre-signed URL 요청...';
    });

    try {
      // 1단계: 서버(Lambda)에 Pre-signed URL 요청
      final getUrlResponse = await http.get(Uri.parse(presignedUrlApiEndpoint));

      if (getUrlResponse.statusCode != 200) {
        throw Exception('Pre-signed URL을 받아오는데 실패했습니다. 상태 코드: ${getUrlResponse.statusCode}');
      }

      final responseData = json.decode(getUrlResponse.body);
      final String uploadUrl = responseData['uploadURL'];
      final String fileKey = responseData['key'];

      setState(() => _statusMessage = '파일 업로드 중...');

      // 2단계: 받은 URL로 파일 업로드 (HTTP PUT 요청)
      final fileBytes = await _selectedImage!.readAsBytes();
      final uploadResponse = await http.put(
        Uri.parse(uploadUrl),
        headers: {
          // 업로드하는 파일의 MIME 타입에 맞게 설정해야 합니다.
          // Lambda에서 ContentType을 지정했다면 반드시 일치시켜야 합니다.
          'Content-Type': 'image/jpeg',
        },
        body: fileBytes,
      );

      if (uploadResponse.statusCode == 200) {
        setState(() {
          _statusMessage = '업로드 성공!';
          _uploadedFileKey = fileKey; // 업로드된 파일의 S3 키 저장
        });
        print('업로드 성공. S3 객체 키: $fileKey');
        // 이제 이 fileKey를 여러분의 애플리케이션 서버로 보내
        // 데이터베이스에 저장하는 등의 후속 작업을 할 수 있습니다.

      } else {
        throw Exception('S3 업로드 실패: ${uploadResponse.statusCode}, 응답: ${uploadResponse.body}');
      }
    } catch (e) {
      setState(() => _statusMessage = '오류 발생: $e');
      print('오류: $e');
    } finally {
      setState(() => _isUploading = false);
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Flutter S3 Direct Uploader')),
      body: Padding(
        padding: const EdgeInsets.all(16.0),
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          crossAxisAlignment: CrossAxisAlignment.stretch,
          children: [
            Container(
              height: 250,
              decoration: BoxDecoration(
                color: Colors.grey[200],
                border: Border.all(color: Colors.grey.shade400),
                borderRadius: BorderRadius.circular(12),
              ),
              child: _selectedImage != null
                  ? ClipRRect(
                      borderRadius: BorderRadius.circular(12),
                      child: Image.file(_selectedImage!, fit: BoxFit.cover),
                    )
                  : const Center(child: Text('선택된 이미지가 없습니다.')),
            ),
            const SizedBox(height: 20),
            Text(
              _statusMessage,
              textAlign: TextAlign.center,
              style: const TextStyle(fontSize: 16, fontWeight: FontWeight.w500),
            ),
            if (_uploadedFileKey != null)
              Padding(
                padding: const EdgeInsets.symmetric(vertical: 8.0),
                child: SelectableText(
                  'S3 Key: $_uploadedFileKey',
                  textAlign: TextAlign.center,
                  style: TextStyle(color: Colors.green[700], fontSize: 12),
                ),
              ),
            const SizedBox(height: 20),
            ElevatedButton.icon(
              icon: const Icon(Icons.photo_library),
              onPressed: _pickImageFromGallery,
              label: const Text('갤러리에서 이미지 선택'),
            ),
            const SizedBox(height: 10),
            ElevatedButton.icon(
              icon: _isUploading
                  ? const SizedBox(width: 20, height: 20, child: CircularProgressIndicator(color: Colors.white, strokeWidth: 3,))
                  : const Icon(Icons.cloud_upload),
              onPressed: _uploadImageToS3,
              label: Text(_isUploading ? '업로드 중...' : 'S3로 업로드'),
              style: ElevatedButton.styleFrom(
                backgroundColor: _isUploading ? Colors.grey : Colors.blue,
              ),
            ),
          ],
        ),
      ),
    );
  }
}

이 코드는 이미지 선택부터 Pre-signed URL 요청, 그리고 S3로의 최종 업로드까지 전체 과정을 명확하게 보여줍니다. 특히 업로드 성공 후 반환받은 `fileKey`를 애플리케이션의 데이터베이스에 저장하면, 해당 파일을 사용자 프로필이나 게시물과 연결하여 관리할 수 있습니다.

총정리: 안정적인 파일 업로드 시스템을 위한 최종 체크리스트

Flutter와 AWS 서버리스 기술을 활용한 현대적인 파일 업로드 시스템 구축 여정을 마무리하며, 성공적인 구현을 위해 반드시 확인해야 할 핵심 사항들을 체크리스트 형태로 정리했습니다. 프로젝트 진행 시 이 목록을 꼭 확인해보세요.

• [✅] S3 버킷 설정: 버킷이 생성되었고, '모든 퍼블릭 액세스 차단'이 활성화되어 있는가?
• [✅] S3 CORS 정책: S3 버킷의 '권한' 탭에 클라이언트의 PUT 요청을 허용하는 CORS 규칙이 올바르게 설정되었는가? (가장 흔한 실패 원인 중 하나!)
• [✅] Lambda 실행 역할(IAM): Lambda 함수의 실행 역할에 s3:PutObject 권한을 부여하는 IAM 정책이 정확하게 연결되었는가? ('Cold Start 실패' 문제의 핵심 해결책)
• [✅] API Gateway 설정: HTTP API가 생성되고, GET /presigned-url과 같은 경로가 Lambda 함수와 올바르게 통합되었는가? API Gateway 자체의 CORS 설정도 확인했는가?
• [✅] Flutter 클라이언트 구현: 클라이언트 코드가 (1) GET으로 API Gateway에 URL을 요청하고, (2) 반환된 URL을 사용하여 PUT으로 S3에 직접 파일을 업로드하는 2단계 프로세스를 따르는가? PUT 요청 시 Content-Type 헤더를 정확히 포함하고 있는가?
• [✅] 파일 키 관리: S3에 저장될 파일의 키(이름)가 UUID 등을 통해 고유하게 생성되어 파일 덮어쓰기 충돌을 방지하는가?
• [✅] 후속 처리 연동: 파일 업로드 성공 후 Lambda로부터 반환된 파일 키(key)를 받아, 애플리케이션의 데이터베이스에 저장하는 로직이 준비되었는가?

이 가이드에서 제시한 아키텍처와 원칙, 그리고 코드를 통해 여러분은 더 이상 파일 업로드로 인한 서버 걱정 없이, 사용자의 콘텐츠 생산을 마음껏 지원하는 안정적이고 확장성 높은 Flutter 애플리케이션을 만들 수 있을 것입니다. 이는 단순한 기능 구현을 넘어, 비즈니스의 성장에 따라 유연하게 대처할 수 있는 강력한 기술적 자산을 확보하는 길입니다.

Continue Reading →

AWS Lambda 파일 업로드, API Gateway 연동 시 겪는 문제와 해결법 총정리 (S3 연동 포함)

서버리스 아키텍처, 특히 AWS Lambda를 사용하여 웹 애플리케이션을 구축할 때 가장 흔하게 부딪히는 난관 중 하나는 바로 '파일 업로드' 기능 구현입니다. 단순히 텍스트 데이터만 주고받는 API와 달리, 이미지, 동영상, 문서 등 바이너리 데이터가 포함된 multipart/form-data 형식의 요청을 처리하는 것은 생각보다 까다롭습니다. 많은 개발자들이 API Gateway와 Lambda를 연동하는 과정에서 수많은 시행착오를 겪으며 시간을 허비하곤 합니다.

이 글의 목표는 명확합니다. AWS API Gateway와 Node.js 기반의 Lambda 함수를 사용하여 텍스트 필드와 파일을 함께 업로드할 때 발생하는 일반적인 문제점들을 진단하고, 이를 해결하는 가장 확실하고 안정적인 방법을 단계별로 제시하는 것입니다. 단순히 '이렇게 하세요'라는 지침을 넘어, 왜 특정 설정이 필요하고, 어떤 라이브러리를 사용해야 하며, 실제 운영 환경을 고려하여 최종적으로 파일을 Amazon S3에 저장하는 전체 과정을 완벽하게 다룰 것입니다. 더 이상 모호한 문서와 파편화된 정보 속에서 헤매지 않도록, 이 가이드가 여러분의 든든한 나침반이 되어 드릴 것입니다.

1. 왜 서버리스 파일 업로드는 복잡한가? 근본적인 원인 이해하기

문제 해결의 첫걸음은 원인을 정확히 아는 것입니다. API Gateway와 Lambda 환경에서 multipart/form-data 처리가 어려운 이유는 다음과 같은 몇 가지 구조적 특징 때문입니다.

• API Gateway의 역할 제한: API Gateway는 기본적으로 JSON 페이로드를 처리하는 데 최적화되어 있습니다. 바이너리 데이터가 포함된 복잡한 형식의 요청을 받으면, 이를 그대로 Lambda로 전달하지 않고 중간에서 특별한 처리를 거칩니다. 이 과정에서 데이터가 Base64로 인코딩되는 등 변환이 일어나며, 개발자는 이 변환을 염두에 두고 코드를 작성해야 합니다.
• HTTP 페이로드 파싱의 부재: 전통적인 웹 프레임워크(Express.js, Spring 등)는 multipart/form-data 요청을 받으면 내부적으로 파싱하여 개발자가 쉽게 파일과 텍스트 필드에 접근할 수 있도록 도와주는 미들웨어를 제공합니다. 하지만 순수한 Lambda 함수 환경에서는 이러한 편의 기능이 기본적으로 제공되지 않습니다. 개발자가 직접 요청의 원시(raw) 본문을 파싱해야 하는 책임이 있습니다.
• 상태 비저장(Stateless) 특성: Lambda는 상태를 저장하지 않으므로, 업로드된 파일을 임시 디렉토리에 잠시 저장했다가 처리하는 방식에 제약이 있습니다. 파일을 받으면 메모리상에서 직접 처리하거나, 곧바로 Amazon S3와 같은 영구 스토리지로 전달하는 패턴이 권장됩니다.

이러한 제약사항들을 이해하고 나면, 왜 특정 설정과 라이브러리가 필수적인지 명확하게 파악할 수 있습니다. 이제 본격적으로 아키텍처를 설계하고 단계별로 구축해 보겠습니다.

2. 최종 아키텍처: Client → API Gateway → Lambda → S3

우리가 구축할 파일 업로드 시스템의 전체적인 데이터 흐름은 다음과 같습니다.

1. 클라이언트 (웹 브라우저, 모바일 앱 등): 사용자는 폼(form)을 통해 텍스트 정보(예: 사용자 이름, 게시글 내용)와 함께 이미지 파일을 선택하고 '업로드' 버튼을 클릭합니다. 클라이언트는 이 데이터를 multipart/form-data 형식으로 인코딩하여 우리가 생성할 API Gateway 엔드포인트로 POST 요청을 보냅니다.
2. Amazon API Gateway: 클라이언트의 요청을 가장 먼저 수신하는 관문입니다. 설정된 규칙에 따라 multipart/form-data 요청을 바이너리 데이터로 인지하고, 페이로드를 Base64로 인코딩하여 Lambda 함수를 호출하는 이벤트 객체에 담아 전달합니다.
3. AWS Lambda (Node.js): API Gateway로부터 이벤트 객체를 전달받습니다. 이 함수 안에는 Base64로 인코딩된 multipart/form-data의 원시 본문이 포함되어 있습니다. 우리는 특정 라이브러리를 사용하여 이 본문을 다시 파싱하고, 텍스트 필드와 파일 데이터를 분리해 냅니다.
4. Amazon S3 (Simple Storage Service): Lambda 함수는 파싱된 파일 데이터를 사용하여 S3 버킷에 객체(파일)를 업로드합니다. 텍스트 데이터는 필요에 따라 데이터베이스에 저장하거나 다른 비즈니스 로직을 수행하는 데 사용될 수 있습니다.

이 아키텍처는 서버리스 환경에서 파일 업로드를 처리하는 가장 표준적이고 확장성 있는 모델입니다.

3. Step 1: API Gateway 완벽 설정 가이드 (비-프록시 방식)

가장 많은 실수가 발생하는 구간이 바로 API Gateway 설정입니다. 여기서는 Lambda 비-프록시(non-proxy) 또는 커스텀 통합 방식을 기준으로 설명합니다. 이 방식은 Lambda 프록시 통합보다 설정이 다소 복잡하지만, 요청과 응답을 세밀하게 제어할 수 있다는 장점이 있습니다.

3-1. REST API 및 리소스 생성

1. AWS Management Console에서 API Gateway 서비스로 이동합니다.
2. 'API 생성'을 클릭하고, 'REST API' 섹션에서 '구축'을 선택합니다.
3. '새 API'를 선택하고 API 이름(예: `FileUploadAPI`)을 입력한 후 'API 생성'을 클릭합니다.
4. 생성된 API의 '리소스' 페이지에서 '작업' 드롭다운을 열고 '리소스 생성'을 선택합니다. 리소스 이름(예: `upload`)을 입력하고 '리소스 생성'을 클릭합니다.
5. 새로 생성된 `/upload` 리소스를 선택한 상태에서 '작업' 드롭다운을 열고 '메서드 생성'을 선택합니다. 드롭다운 목록에서 `POST`를 선택하고 체크 표시를 클릭합니다.

3-2. POST 메서드 통합 설정

이제 `POST` 메서드의 설정을 진행합니다. 여기서 Lambda 함수와 연결하게 됩니다.

• 통합 유형: 'Lambda 함수'를 선택합니다.
• Lambda 프록시 통합 사용: **체크를 해제합니다.** 이것이 비-프록시(커스텀) 통합 방식의 핵심입니다.
• Lambda 리전: Lambda 함수를 생성할 리전(예: `ap-northeast-2`)을 선택합니다.
• Lambda 함수: 연결할 Lambda 함수의 이름을 입력합니다. (아직 함수를 만들지 않았더라도 일단 이름을 정해두고 나중에 생성해도 됩니다. 예: `handleFileUpload`)
• '저장'을 클릭합니다. API Gateway가 Lambda 함수를 호출할 권한을 추가할 것인지 묻는 팝업이 나타나면 '확인'을 누릅니다.

3-3. 바이너리 미디어 유형 설정 (가장 중요!)

이 설정이 누락되면 API Gateway는 `multipart/form-data`를 텍스트로 취급하여 Lambda로 전달하기 전에 엉뚱하게 파싱하려고 시도하며, 결국 오류가 발생합니다. 이 설정은 API Gateway에게 특정 Content-Type을 가진 요청은 바이너리 데이터로 간주하고 그대로 통과시키라고 알려주는 역할을 합니다.

1. API Gateway의 왼쪽 메뉴 하단에 있는 '설정'으로 이동합니다.
2. '바이너리 미디어 유형' 섹션에서 '바이너리 미디어 유형 추가'를 클릭합니다.
3. 입력란에 `multipart/form-data`를 정확하게 입력하고 '변경 사항 저장'을 클릭합니다.

주의: 이 설정을 변경한 후에는 반드시 API를 **재배포**해야 변경 사항이 적용됩니다.

3-4. 통합 요청(Integration Request) 매핑 템플릿 설정

비-프록시 방식을 사용했기 때문에, 클라이언트의 요청 본문을 어떤 형태로 Lambda에 전달할지 직접 정의해야 합니다. 우리는 요청 본문 전체를 Base64로 인코딩하여 JSON 객체 안에 담아 전달할 것입니다.

1. 다시 `/upload` 리소스의 `POST` 메서드 설정 화면으로 돌아와 '통합 요청'을 클릭합니다.
2. 페이지 하단의 '매핑 템플릿' 섹션을 확장합니다.
3. '요청 본문 패스스루' 옵션에서 '매핑 템플릿이 정의되지 않은 경우(권장)'를 선택합니다.
4. '매핑 템플릿 추가'를 클릭하고, Content-Type으로 `application/json`을 입력한 후 체크 표시를 클릭합니다. (여기서 `multipart/form-data`를 입력하는 것이 아님에 주의하세요. Lambda는 JSON 이벤트를 받기 때문입니다.)
5. 오른쪽 템플릿 편집기에 아래와 같은 JSON을 입력합니다.

{
  "body": "$util.base64Encode($input.body)",
  "headers": {
    #foreach($header in $input.params().header.keySet())
    "$header": "$util.escapeJavaScript($input.params().header.get($header))"
    #if($foreach.hasNext),#end
    #end
  },
  "isBase64Encoded": true
}

이 템플릿의 의미는 다음과 같습니다.

• `$util.base64Encode($input.body)`: 들어온 요청의 원시(raw) 본문(`$input.body`)을 통째로 Base64 문자열로 인코딩하여 `body`라는 키에 담습니다.
• `headers`: 원본 요청의 헤더 정보들을 `headers` 키에 담습니다. 특히 `Content-Type` 헤더는 `multipart/form-data` 파싱에 필수적인 `boundary` 값을 포함하고 있으므로 반드시 전달해야 합니다.
• `isBase64Encoded`: 이 페이로드가 Base64로 인코딩되었음을 명시적으로 알려주는 플래그입니다.

'저장'을 클릭하여 매핑 템플릿 설정을 완료합니다.

4. Step 2: Lambda 함수 구현 (Node.js) 및 IAM 역할 설정

이제 API Gateway로부터 요청을 받아 처리할 Lambda 함수를 만들 차례입니다. 파일 파싱부터 S3 업로드까지의 전체 과정을 코드로 살펴봅니다.

4-1. IAM 역할 생성

Lambda 함수가 다른 AWS 서비스(CloudWatch Logs, S3)에 접근하려면 적절한 권한이 필요합니다. 먼저 Lambda 함수에 할당할 IAM 역할을 생성합니다.

1. AWS IAM 서비스 콘솔로 이동하여 '역할' -> '역할 만들기'를 클릭합니다.
2. 신뢰할 수 있는 엔터티 유형으로 'AWS 서비스'를 선택하고, 사용 사례로 'Lambda'를 선택한 후 '다음'을 클릭합니다.
3. 권한 정책 추가 단계에서 다음 두 가지 정책을 검색하여 추가합니다.
   • `AWSLambdaBasicExecutionRole`: Lambda 함수가 실행 로그를 Amazon CloudWatch Logs에 기록할 수 있도록 하는 기본 권한입니다.
   • `AmazonS3FullAccess` 또는 직접 생성한 S3 PutObject 권한 정책: 파일을 S3에 업로드해야 하므로 S3 접근 권한이 필요합니다. 개발 단계에서는 `AmazonS3FullAccess`를 사용해도 무방하지만, 실제 운영 환경에서는 보안을 위해 특정 버킷에 대한 `s3:PutObject` 권한만 부여하는 사용자 지정 정책을 만드는 것이 좋습니다.
4. '다음'을 클릭하고 역할 이름(예: `lambda-s3-upload-role`)을 지정한 후 '역할 만들기'를 완료합니다.

4-2. Lambda 함수 생성 및 라이브러리 준비

1. AWS Lambda 서비스 콘솔로 이동하여 '함수 생성'을 클릭합니다.
2. '새로 작성'을 선택하고 함수 이름(API Gateway에서 지정했던 이름, 예: `handleFileUpload`)을 입력합니다.
3. 런타임으로 `Node.js`의 최신 LTS 버전(예: Node.js 18.x)을 선택합니다.
4. 아키텍처는 `x86_64` 또는 `arm64` 중 선호하는 것을 선택합니다.
5. '기본 실행 역할 변경'을 확장하고, '기존 역할 사용'을 선택한 후 방금 생성한 IAM 역할(`lambda-s3-upload-role`)을 선택합니다.
6. '함수 생성'을 클릭합니다.

이제 `multipart/form-data`를 파싱할 라이브러리를 설치해야 합니다. 많은 라이브러리가 있지만, API Gateway와 Lambda 환경의 특성을 잘 고려하여 만들어진 `lambda-multipart-parser`를 사용하는 것이 가장 안정적입니다.

실패 사례: 왜 `parse-multipart` 같은 라이브러리는 문제가 될 수 있는가?

일부 개발자들은 `busboy`나 `parse-multipart`와 같은 일반적인 Node.js용 파서 사용을 시도합니다. 하지만 이런 라이브러리들은 파일 스트림을 기반으로 동작하는 경우가 많아, Base64로 인코딩된 전체 본문을 문자열로 받아 처리하는 Lambda 환경과 맞지 않을 수 있습니다. 특히 텍스트 필드와 파일이 섞여 있을 때 파싱에 실패하는 경우가 빈번합니다. 원문 작성자가 겪었던 문제도 바로 이 지점입니다. `parse-multipart` 패키지가 파일 전용으로 설계되었기 때문에 텍스트 필드가 포함되자 오류가 발생한 것입니다. 따라서 Lambda 이벤트 객체를 직접 다루도록 설계된 전용 파서를 사용하는 것이 중요합니다.

로컬 환경에서 프로젝트를 설정하고 라이브러리를 포함한 배포 패키지를 만들어 보겠습니다.

# 1. 프로젝트 폴더 생성 및 초기화
mkdir lambda-upload-project
cd lambda-upload-project
npm init -y

# 2. 필수 라이브러리 설치
npm install lambda-multipart-parser aws-sdk

# 3. index.js 파일 생성
touch index.js

4-3. 전체 코드 작성 (`index.js`)

이제 `index.js` 파일에 Lambda 함수의 로직을 작성합니다. 이 코드는 API Gateway로부터 받은 이벤트를 파싱하고, 파일을 추출하여 S3에 업로드한 후, 성공 응답을 반환하는 전체 과정을 담고 있습니다.

lambda-multipart-parser를 사용한 Lambda 함수 코드 예시

const parser = require('lambda-multipart-parser');
const AWS = require('aws-sdk');

// S3 클라이언트 초기화
const s3 = new AWS.S3();

exports.handler = async (event) => {
    // S3 버킷 이름. 환경 변수로 설정하는 것을 권장합니다.
    const BUCKET_NAME = process.env.BUCKET_NAME || 'your-s3-bucket-name';

    try {
        console.log('Received event:', JSON.stringify(event, null, 2));

        // API Gateway에서 Base64로 인코딩된 본문을 올바르게 처리하기 위해
        // 이벤트 객체를 그대로 전달합니다.
        const result = await parser.parse(event);
        
        console.log('Parsed result:', result);

        // 'result' 객체에는 'files'와 텍스트 필드들이 포함됩니다.
        // ex) result.files, result.username, result.description 등
        
        // 업로드할 파일이 있는지 확인
        if (!result.files || result.files.length === 0) {
            throw new Error('No files were uploaded.');
        }

        const file = result.files[0];

        // S3에 업로드할 파라미터 준비
        const params = {
            Bucket: BUCKET_NAME,
            Key: `${Date.now()}_${file.filename}`, // 파일 이름 중복을 피하기 위해 타임스탬프 추가
            Body: file.content, // 파서가 반환한 버퍼 형태의 파일 콘텐츠
            ContentType: file.contentType,
        };

        // S3에 파일 업로드
        const uploadResult = await s3.putObject(params).promise();
        console.log('S3 Upload Result:', uploadResult);

        // 텍스트 필드 데이터 활용 예시
        const username = result.username || 'anonymous';
        const description = result.description || 'no description';
        
        console.log(`File uploaded by ${username} with description: ${description}`);

        // 클라이언트에 성공 응답 반환
        return {
            statusCode: 200,
            headers: {
                'Content-Type': 'application/json',
                'Access-Control-Allow-Origin': '*' // CORS 설정
            },
            body: JSON.stringify({
                message: 'File uploaded successfully to S3!',
                s3_key: params.Key,
                bucket: params.Bucket,
                uploader: username
            }),
        };

    } catch (error) {
        console.error('Error occurred:', error);
        
        // 클라이언트에 에러 응답 반환
        return {
            statusCode: 500,
            headers: {
                'Content-Type': 'application/json',
                'Access-Control-Allow-Origin': '*'
            },
            body: JSON.stringify({
                message: 'Failed to upload file.',
                error: error.message,
            }),
        };
    }
};

코드 작성 후, `node_modules` 폴더와 `index.js` 파일을 함께 ZIP 파일로 압축합니다. 그리고 Lambda 콘솔의 '코드 소스' 섹션에서 '업로드' 버튼을 통해 이 ZIP 파일을 업로드합니다.

중요: 코드에서 `BUCKET_NAME`을 하드코딩하는 대신, Lambda 함수의 '구성' -> '환경 변수'에서 설정하는 것이 훨씬 좋은 방법입니다. 이렇게 하면 코드를 변경하지 않고도 다른 버킷을 사용하도록 유연하게 변경할 수 있습니다.

5. Step 3: API 배포 및 Postman으로 테스트하기

모든 설정이 끝났습니다. 이제 API를 배포하고 실제 요청을 보내 테스트해 볼 차례입니다.

1. API Gateway 콘솔의 리소스 페이지에서 '작업' -> 'API 배포'를 선택합니다.
2. 배포 스테이지는 '[새 스테이지]'를 선택하고, 스테이지 이름(예: `dev` 또는 `v1`)을 입력합니다.
3. '배포' 버튼을 클릭합니다.
4. 배포가 완료되면 스테이지 목록에 방금 생성한 스테이지가 나타납니다. 스테이지를 클릭하면 상단에 '호출 URL'이 표시됩니다. 이 URL이 바로 우리가 요청을 보낼 엔드포인트입니다. (예: `https://xxxxxxxxx.execute-api.ap-northeast-2.amazonaws.com/dev/upload`)

Postman 테스트 설정

1. Postman을 열고 새 요청을 생성합니다.
2. 메서드를 `POST`로 설정하고, URL 입력란에 위에서 얻은 '호출 URL'을 붙여넣습니다.
3. 'Body' 탭으로 이동하여 `form-data`를 선택합니다.
4. KEY 열에 파일 필드의 이름(예: `file`)을 입력하고, 오른쪽 값(Value) 열의 드롭다운을 'File'로 변경한 후 'Select Files' 버튼을 눌러 업로드할 파일을 선택합니다. (Lambda 코드에서 `result.files[0]`을 사용했으므로, 어떤 KEY 이름을 쓰든 첫 번째 파일이 처리됩니다.)
5. 다른 KEY 열에 텍스트 필드의 이름(예: `username`, `description`)을 입력하고, 각각의 값을 입력합니다.
6. 'Headers' 탭으로 이동합니다. `Content-Type` 헤더는 Postman이 `form-data`를 사용할 때 자동으로 `multipart/form-data; boundary=...` 형식으로 생성해주므로 **별도로 추가하지 않아도 됩니다.** 만약 이미 있다면 삭제하세요.
7. 'Send' 버튼을 클릭하여 요청을 보냅니다.

요청이 성공하면, Lambda 코드에서 정의한 200 상태 코드와 함께 S3에 저장된 파일의 키 정보가 담긴 JSON 응답을 받게 될 것입니다. AWS S3 콘솔로 이동하여 해당 버킷에 파일이 정상적으로 업로드되었는지 확인해 보세요.

6. 트러블슈팅 및 자주 묻는 질문 (FAQ)

Q: `{"message":"Internal server error"}` 와 함께 502 Bad Gateway 오류가 발생합니다.

A: 이 오류는 주로 Lambda 함수가 API Gateway가 기대하는 형식의 응답을 반환하지 않았을 때 발생합니다. 비-프록시 통합의 경우에도 응답 형식이 중요합니다. 응답 객체가 `statusCode`, `body`, `headers` 등의 키를 포함하는지 확인하세요. 또한, Lambda 함수 실행 로그를 CloudWatch에서 확인하여 실제 함수 내부에서 어떤 에러가 발생했는지 파악하는 것이 가장 중요합니다.

Q: 업로드된 파일이 깨져서 열리지 않습니다.

A: 대부분 Base64 인코딩/디코딩 과정의 문제입니다. 다음 사항을 다시 점검하세요.

• API Gateway 설정의 '바이너리 미디어 유형'에 `multipart/form-data`가 올바르게 추가되었는지 확인하세요.
• 통합 요청 매핑 템플릿에서 `$util.base64Encode($input.body)`를 사용하여 본문을 인코딩하고, `isBase64Encoded: true` 플래그를 이벤트에 포함시켰는지 확인하세요.
• `lambda-multipart-parser`는 `event.isBase64Encoded` 플래그를 자동으로 인지하고 내부적으로 디코딩을 수행합니다. Lambda 함수 코드에서 `event.body`를 직접 디코딩하려는 시도를 하고 있다면 제거해야 합니다.

Q: Lambda 로그에 `AccessDeniedException` 또는 `Access Denied` 오류가 기록됩니다.

A: Lambda 함수에 할당된 IAM 역할에 대상 S3 버킷에 대한 `s3:PutObject` 권한이 없는 경우입니다. IAM 콘솔에서 해당 역할을 찾아 S3 쓰기 권한 정책이 제대로 연결되어 있는지 확인하세요.

Q: Lambda 프록시 통합을 사용하면 안 되나요?

A: 물론 사용 가능합니다. Lambda 프록시 통합은 API Gateway 설정을 훨씬 단순하게 만들어줍니다. 매핑 템플릿을 설정할 필요가 없죠. 하지만 Lambda 함수가 전체 HTTP 요청 객체를 그대로 받게 되므로, 헤더와 본문을 직접 파싱하는 로직이 조금 더 복잡해질 수 있습니다. `lambda-multipart-parser`는 프록시/비-프록시 통합 양쪽을 모두 지원하므로, 어떤 방식을 선택하든 이 라이브러리를 활용할 수 있습니다. 프로젝트의 복잡도와 개발자의 선호도에 따라 선택하면 됩니다.

결론: 안정적인 서버리스 파일 업로드를 향하여

지금까지 AWS API Gateway와 Lambda를 연동하여 텍스트 데이터와 파일을 함께 업로드하고, 최종적으로 S3에 저장하는 전 과정을 상세히 살펴보았습니다. 핵심은 세 가지로 요약할 수 있습니다.

1. 정확한 API Gateway 설정: `바이너리 미디어 유형` 설정은 절대 빠뜨려서는 안 되는 가장 중요한 단계입니다.
2. 적절한 파서 라이브러리 선택: `lambda-multipart-parser`와 같이 Lambda 환경의 특수성(Base64 인코딩 등)을 이해하고 설계된 라이브러리를 사용하는 것이 수많은 시행착오를 줄여줍니다.
3. 단계별 검증: 문제가 발생했을 때, CloudWatch 로그를 통해 Lambda 함수 내부의 오류를 먼저 확인하고, 그 다음 API Gateway 설정, 마지막으로 클라이언트 요청을 순서대로 점검하는 것이 효율적인 디버깅 방법입니다.

이 가이드에서 제시한 아키텍처와 코드는 다양한 서버리스 애플리케이션에서 사용자 프로필 이미지 업로드, 게시판 첨부파일, 데이터 제출 등 파일이 필요한 거의 모든 기능의 기반이 될 수 있습니다. 이제 여러분은 서버리스 환경에서의 파일 업로드라는 높은 장벽을 자신 있게 넘어설 수 있을 것입니다.

Continue Reading →

AWS Lambda와 API Gateway 활용, S3에 Multipart 이미지 업로드 시 파일 깨짐 문제 해결

AWS API Gateway와 Lambda

서비스 개발 중에 클라이언트에서 multipart로 사진을 AWS Lambda로 보내고, Lambda에서 S3로 다시 사진을 업로드하는 작업이 필요했습니다. Flutter를 이용해 서비스를 개발하려 했으나 아직 Flutter용(dart) SDK가 없어서 우리쪽 서버를 거쳐서 보내기로 결정했습니다.

미디어 타입 설정

Lambda 코드 작성 전에 API gateway에서 미디어 타입을 추가해야 합니다.

API Gateway에서 미디어 타입 설정하기

코드 작성 및 팁 공유

인터넷에서 여러 자료를 참고하여 아래와 같은 코드를 작성했습니다. 이 예제는 여러 장의 사진을 받아 1장만 S3로 업로드하는 방법입니다. 한 가지 팁으로는, AWS SDK가 이미 설치되어 있으므로 별도의 설치가 필요하지 않다는 점입니다.

//const AWS = require('aws-sdk');
const multipart = require('parse-multipart');
exports.handler = (event, context, callback) => {
    const s3 = new AWS.S3({
        credentials: {
            accessKeyId: 'your accessKeyId',
            secretAccessKey: 'your secretAccessKey',
        },
        params: { Bucket: 'your Bucket' }
    });

    let bodyBuffer = Buffer.from(event['body-json'], 'base64');
    let boundary = multipart.getBoundary(event.params.header['content-type']);
    let parts = multipart.Parse(bodyBuffer, boundary);
    let data = {
        Key: 'your path',
        Body: parts[0].data,
        ContentEncoding: 'base64',
        ContentType: 'image/jpeg'
    };

    s3.putObject(data, function (err, data) {
      if (err) {
          callback(null, err);
      } else {
          callback(null, data);
      }
   });
};

테스트 및 문제 해결

<html>
<body>
<form action="https://your-url" enctype="multipart/form-data" method="post">
    <input multiple="" name="body-json" type="file" />
    <input type="submit" value="Submit" />
</form>
</body>
</html>

위와 같이 웹페이지를 만들어 테스트를 진행했지만 어떤 때는 동작하고 어떤 때는 동작하지 않는 이상한 상황이 발생했습니다. 원인을 찾기 위해 여러 가지 시도를 해봤지만 결국 문제의 원인은 웹에서 보낼 때 캐릭터셋 지정이 없어서 한글 파일의 경우 파일명이 깨지고 전송 후에 파일 자체가 깨지는 것이었습니다. 이를 해결하기위해 form 태그 안에 accept-charset="UTF-8"속성을 추가하고 다시 테스트해 보니 문제가 해결되었고, S3 업로드도 잘 실행되었습니다.

<html>
<body>
<form action="https://your-url" enctype="multipart/form-data" method="post" accept-charset="UTF-8">
    <input multiple="" name="body-json" type="file" />
    <input type="submit" value="Submit" />
</form>
</body>
</html>

사실상 코드는 큰 문제가 없었는데 캐릭터셋을 생각하지 못하고 코드 문제인 줄 알아서 이것저것 시도하느라 시간을 많이 잡아먹었습니다. 혹시 같은 작업이나 비슷한 문제를 겪는 사람들에게 조금이라도 도움이 되길 바랍니다.

참고 : 여러 형식의 파일 multipart upload 방법(https://blogdeveloperspot.blogspot.com/2019/12/aws-apigateway-lambdanodejs-multipart.html)

Continue Reading →