오늘날의 모바일 애플리케이션은 단순히 정보를 소비하는 창구를 넘어 사용자가 적극적으로 콘텐츠를 생산하고 공유하는 플랫폼으로 진화했습니다. 인스타그램의 사진과 릴스, 유튜브의 동영상, 중고 거래 앱의 상품 이미지, 클라우드 드라이브의 문서 파일까지, 성공적인 서비스의 이면에는 사용자가 생성한 수많은 파일을 안정적으로 처리하는 기술이 자리 잡고 있습니다. 하지만 늘어나는 사용자만큼, 혹은 그 이상으로 빠르게 증가하는 파일 데이터는 개발자와 인프라 담당자에게 커다란 숙제를 안겨줍니다. 바로 '서버 부하'와 '비용' 문제입니다.
만약 여러분의 Flutter 앱이 사용자가 업로드하는 파일을 애플리케이션 서버를 통해 S3와 같은 스토리지로 전달하는 전통적인 방식을 사용하고 있다면, 서비스가 성장할수록 서버는 점점 더 느려지고 네트워크 비용은 눈덩이처럼 불어나는 '비용 폭탄'을 맞이할 위험이 큽니다. 사용자는 느린 업로드 속도에 불만을 느끼고, 회사는 불필요한 인프라 비용으로 골머리를 앓게 됩니다.
이 글에서는 이러한 문제를 근본적으로 해결하고, 여러분의 Flutter 앱을 한 단계 더 높은 수준의 아키텍처로 끌어올릴 수 있는 'AWS S3로 직접 파일 업로드' 방식을 심도 있게 다룹니다. 특히, 서버리스의 꽃이라 불리는 API Gateway와 Lambda를 활용하여 보안과 효율성을 모두 잡는 Pre-signed URL(미리 서명된 URL) 생성부터, 많은 개발자들이 함정에 빠지는 IAM 권한 문제와 CORS 설정까지, 실전에서 마주할 수 있는 모든 과정을 총정리하여 상세히 안내합니다. 이 가이드를 끝까지 따라오시면, 서버 부하와 비용 걱정 없이 확장 가능한 파일 업로드 시스템을 구축할 수 있는 튼튼한 기반을 다지게 될 것입니다.
왜 파일 업로드는 서버를 우회해야 하는가? (전통 방식의 치명적 단점)
현대적인 접근법을 이해하기 전에, 왜 기존 방식이 더 이상 유효하지 않은지 명확히 짚고 넘어갈 필요가 있습니다. 전통적인 파일 업로드 아키텍처는 다음과 같은 흐름을 가집니다.
[전통 방식] Flutter App → Application Server (e.g., EC2) → AWS S3
- 데이터 수신: Flutter 클라이언트가 이미지나 동영상 파일을 HTTP 요청의 Body에 담아 우리가 운영하는 애플리케이션 서버(예: AWS EC2, Spring Boot, NestJS 서버 등)로 전송합니다.
- 서버 처리: 서버는 이 거대한 파일 데이터를 네트워크 소켓으로부터 모두 읽어들여 메모리나 임시 디스크 공간에 저장합니다.
- 데이터 재전송: 서버는 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단계: 허가 요청] Flutter 앱이 파일 업로드를 시작하기 전에, 우리 서버(API)에 "
profile-images/user-123.jpg 라는 이름으로 파일을 올리고 싶으니, 임시 업로드 허가증을 발급해주세요." 라고 요청합니다.
- [2단계: 검증 및 생성] 서버는 이 요청을 보낸 사용자가 로그인된 정식 사용자인지, 프로필 이미지를 업로드할 권한이 있는지 등을 먼저 확인합니다. 모든 검증을 통과하면, 서버만이 안전하게 보관하고 있는 AWS 자격 증명을 사용하여 아주 제한적인 권한을 가진 특별한 URL을 생성합니다. 이 URL에는 다음과 같은 정보가 암호화된 서명과 함께 포함됩니다.
- 누가(Who): 이 URL을 생성한 주체(서버의 AWS 자격 증명)
- 무엇을(What):
profile-images/user-123.jpg 라는 특정 객체(파일)
- 어떤 작업을(Action): 객체를 생성하는 작업(
PUT 요청)
- 언제까지(When): 앞으로 5분(300초) 동안만 유효함
- [3단계: 허가증 반환] 서버는 이렇게 생성된, 유효 시간이 짧고 특정 작업만 허용하는 Pre-signed URL을 Flutter 앱에게 응답으로 전달합니다.
- [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를 구성해야 합니다. 많은 개발자들이 이 단계를 놓쳐 원인 모를 오류에 시달리곤 합니다.
- AWS Management Console에 로그인하여 S3 서비스로 이동합니다.
- '버킷 만들기'를 클릭하고, 전역적으로 고유한 버킷 이름을 입력합니다 (예:
my-flutter-uploads-2023). 리전은 사용자와 가까운 곳(예: ap-northeast-2, 서울)을 선택합니다.
- '모든 퍼블릭 액세스 차단' 설정을 그대로 유지합니다. Pre-signed URL을 사용할 것이므로 버킷 자체를 공개할 필요가 전혀 없습니다. 이것이 보안의 기본입니다.
- 버킷 생성을 완료한 후, 생성된 버킷의 '권한' 탭으로 이동합니다.
- 아래로 스크롤하여 '교차 출처 리소스 공유(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 엔드포인트를 만들 차례입니다.
- AWS Console에서 API Gateway 서비스로 이동합니다.
- 다양한 API 타입 중 'HTTP API'의 '구축'을 선택합니다. HTTP API는 REST API보다 더 간단하고 저렴하여 이런 용도에 적합합니다.
- '통합' 단계에서 '통합 추가'를 클릭합니다.
- 통합 대상: Lambda
- Lambda 함수: 위에서 생성한 Lambda 함수 (예:
presigned-url-generator-nodejs)를 선택합니다.
- API 이름을 지정하고(예:
FileUploadAPI) 다음으로 넘어갑니다.
- '경로 구성' 단계에서 '경로 만들기'를 클릭합니다.
- 메서드: GET
- 경로:
/presigned-url (또는 원하는 경로)
- 통합 대상: 방금 생성한 Lambda 통합을 선택합니다.
- 나머지 설정은 기본값으로 두고 API를 생성합니다.
- 생성이 완료되면 대시보드에서 '호출 URL'을 확인할 수 있습니다. 이 URL이 바로 Flutter 앱에서 API를 호출할 때 사용할 엔드포인트입니다. (예:
https://abcdef123.execute-api.ap-northeast-2.amazonaws.com/presigned-url)
- 마지막으로, 왼쪽 메뉴에서 '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 정책 설정하기
- AWS Console에서 IAM 서비스로 이동합니다.
- 왼쪽 메뉴에서 '역할'을 선택하고, API Gateway와 연동된 Lambda 함수가 사용하는 역할을 찾습니다. (보통
함수이름-role-xxxxxx 와 같은 이름입니다.)
- 해당 역할을 클릭하고 '권한' 탭에서 '권한 추가' > '인라인 정책 생성'을 선택합니다.
- 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 애플리케이션을 만들 수 있을 것입니다. 이는 단순한 기능 구현을 넘어, 비즈니스의 성장에 따라 유연하게 대처할 수 있는 강력한 기술적 자산을 확보하는 길입니다.
