서버리스 아키텍처, 특히 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
우리가 구축할 파일 업로드 시스템의 전체적인 데이터 흐름은 다음과 같습니다.
- 클라이언트 (웹 브라우저, 모바일 앱 등): 사용자는 폼(form)을 통해 텍스트 정보(예: 사용자 이름, 게시글 내용)와 함께 이미지 파일을 선택하고 '업로드' 버튼을 클릭합니다. 클라이언트는 이 데이터를
multipart/form-data형식으로 인코딩하여 우리가 생성할 API Gateway 엔드포인트로 POST 요청을 보냅니다. - Amazon API Gateway: 클라이언트의 요청을 가장 먼저 수신하는 관문입니다. 설정된 규칙에 따라
multipart/form-data요청을 바이너리 데이터로 인지하고, 페이로드를 Base64로 인코딩하여 Lambda 함수를 호출하는 이벤트 객체에 담아 전달합니다. - AWS Lambda (Node.js): API Gateway로부터 이벤트 객체를 전달받습니다. 이 함수 안에는 Base64로 인코딩된
multipart/form-data의 원시 본문이 포함되어 있습니다. 우리는 특정 라이브러리를 사용하여 이 본문을 다시 파싱하고, 텍스트 필드와 파일 데이터를 분리해 냅니다. - Amazon S3 (Simple Storage Service): Lambda 함수는 파싱된 파일 데이터를 사용하여 S3 버킷에 객체(파일)를 업로드합니다. 텍스트 데이터는 필요에 따라 데이터베이스에 저장하거나 다른 비즈니스 로직을 수행하는 데 사용될 수 있습니다.
이 아키텍처는 서버리스 환경에서 파일 업로드를 처리하는 가장 표준적이고 확장성 있는 모델입니다.
3. Step 1: API Gateway 완벽 설정 가이드 (비-프록시 방식)
가장 많은 실수가 발생하는 구간이 바로 API Gateway 설정입니다. 여기서는 Lambda 비-프록시(non-proxy) 또는 커스텀 통합 방식을 기준으로 설명합니다. 이 방식은 Lambda 프록시 통합보다 설정이 다소 복잡하지만, 요청과 응답을 세밀하게 제어할 수 있다는 장점이 있습니다.
3-1. REST API 및 리소스 생성
- AWS Management Console에서 API Gateway 서비스로 이동합니다.
- 'API 생성'을 클릭하고, 'REST API' 섹션에서 '구축'을 선택합니다.
- '새 API'를 선택하고 API 이름(예: `FileUploadAPI`)을 입력한 후 'API 생성'을 클릭합니다.
- 생성된 API의 '리소스' 페이지에서 '작업' 드롭다운을 열고 '리소스 생성'을 선택합니다. 리소스 이름(예: `upload`)을 입력하고 '리소스 생성'을 클릭합니다.
- 새로 생성된 `/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을 가진 요청은 바이너리 데이터로 간주하고 그대로 통과시키라고 알려주는 역할을 합니다.
- API Gateway의 왼쪽 메뉴 하단에 있는 '설정'으로 이동합니다.
- '바이너리 미디어 유형' 섹션에서 '바이너리 미디어 유형 추가'를 클릭합니다.
- 입력란에 `multipart/form-data`를 정확하게 입력하고 '변경 사항 저장'을 클릭합니다.
주의: 이 설정을 변경한 후에는 반드시 API를 **재배포**해야 변경 사항이 적용됩니다.
3-4. 통합 요청(Integration Request) 매핑 템플릿 설정
비-프록시 방식을 사용했기 때문에, 클라이언트의 요청 본문을 어떤 형태로 Lambda에 전달할지 직접 정의해야 합니다. 우리는 요청 본문 전체를 Base64로 인코딩하여 JSON 객체 안에 담아 전달할 것입니다.
- 다시 `/upload` 리소스의 `POST` 메서드 설정 화면으로 돌아와 '통합 요청'을 클릭합니다.
- 페이지 하단의 '매핑 템플릿' 섹션을 확장합니다.
- '요청 본문 패스스루' 옵션에서 '매핑 템플릿이 정의되지 않은 경우(권장)'를 선택합니다.
- '매핑 템플릿 추가'를 클릭하고, Content-Type으로 `application/json`을 입력한 후 체크 표시를 클릭합니다. (여기서 `multipart/form-data`를 입력하는 것이 아님에 주의하세요. Lambda는 JSON 이벤트를 받기 때문입니다.)
- 오른쪽 템플릿 편집기에 아래와 같은 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 역할을 생성합니다.
- AWS IAM 서비스 콘솔로 이동하여 '역할' -> '역할 만들기'를 클릭합니다.
- 신뢰할 수 있는 엔터티 유형으로 'AWS 서비스'를 선택하고, 사용 사례로 'Lambda'를 선택한 후 '다음'을 클릭합니다.
- 권한 정책 추가 단계에서 다음 두 가지 정책을 검색하여 추가합니다.
- `AWSLambdaBasicExecutionRole`: Lambda 함수가 실행 로그를 Amazon CloudWatch Logs에 기록할 수 있도록 하는 기본 권한입니다.
- `AmazonS3FullAccess` 또는 직접 생성한 S3 PutObject 권한 정책: 파일을 S3에 업로드해야 하므로 S3 접근 권한이 필요합니다. 개발 단계에서는 `AmazonS3FullAccess`를 사용해도 무방하지만, 실제 운영 환경에서는 보안을 위해 특정 버킷에 대한 `s3:PutObject` 권한만 부여하는 사용자 지정 정책을 만드는 것이 좋습니다.
- '다음'을 클릭하고 역할 이름(예: `lambda-s3-upload-role`)을 지정한 후 '역할 만들기'를 완료합니다.
4-2. Lambda 함수 생성 및 라이브러리 준비
- AWS Lambda 서비스 콘솔로 이동하여 '함수 생성'을 클릭합니다.
- '새로 작성'을 선택하고 함수 이름(API Gateway에서 지정했던 이름, 예: `handleFileUpload`)을 입력합니다.
- 런타임으로 `Node.js`의 최신 LTS 버전(예: Node.js 18.x)을 선택합니다.
- 아키텍처는 `x86_64` 또는 `arm64` 중 선호하는 것을 선택합니다.
- '기본 실행 역할 변경'을 확장하고, '기존 역할 사용'을 선택한 후 방금 생성한 IAM 역할(`lambda-s3-upload-role`)을 선택합니다.
- '함수 생성'을 클릭합니다.
이제 `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에 업로드한 후, 성공 응답을 반환하는 전체 과정을 담고 있습니다.
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를 배포하고 실제 요청을 보내 테스트해 볼 차례입니다.
- API Gateway 콘솔의 리소스 페이지에서 '작업' -> 'API 배포'를 선택합니다.
- 배포 스테이지는 '[새 스테이지]'를 선택하고, 스테이지 이름(예: `dev` 또는 `v1`)을 입력합니다.
- '배포' 버튼을 클릭합니다.
- 배포가 완료되면 스테이지 목록에 방금 생성한 스테이지가 나타납니다. 스테이지를 클릭하면 상단에 '호출 URL'이 표시됩니다. 이 URL이 바로 우리가 요청을 보낼 엔드포인트입니다. (예: `https://xxxxxxxxx.execute-api.ap-northeast-2.amazonaws.com/dev/upload`)
Postman 테스트 설정
- Postman을 열고 새 요청을 생성합니다.
- 메서드를 `POST`로 설정하고, URL 입력란에 위에서 얻은 '호출 URL'을 붙여넣습니다.
- 'Body' 탭으로 이동하여 `form-data`를 선택합니다.
- KEY 열에 파일 필드의 이름(예: `file`)을 입력하고, 오른쪽 값(Value) 열의 드롭다운을 'File'로 변경한 후 'Select Files' 버튼을 눌러 업로드할 파일을 선택합니다. (Lambda 코드에서 `result.files[0]`을 사용했으므로, 어떤 KEY 이름을 쓰든 첫 번째 파일이 처리됩니다.)
- 다른 KEY 열에 텍스트 필드의 이름(예: `username`, `description`)을 입력하고, 각각의 값을 입력합니다.
- 'Headers' 탭으로 이동합니다. `Content-Type` 헤더는 Postman이 `form-data`를 사용할 때 자동으로 `multipart/form-data; boundary=...` 형식으로 생성해주므로 **별도로 추가하지 않아도 됩니다.** 만약 이미 있다면 삭제하세요.
- '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에 저장하는 전 과정을 상세히 살펴보았습니다. 핵심은 세 가지로 요약할 수 있습니다.
- 정확한 API Gateway 설정: `바이너리 미디어 유형` 설정은 절대 빠뜨려서는 안 되는 가장 중요한 단계입니다.
- 적절한 파서 라이브러리 선택: `lambda-multipart-parser`와 같이 Lambda 환경의 특수성(Base64 인코딩 등)을 이해하고 설계된 라이브러리를 사용하는 것이 수많은 시행착오를 줄여줍니다.
- 단계별 검증: 문제가 발생했을 때, CloudWatch 로그를 통해 Lambda 함수 내부의 오류를 먼저 확인하고, 그 다음 API Gateway 설정, 마지막으로 클라이언트 요청을 순서대로 점검하는 것이 효율적인 디버깅 방법입니다.
이 가이드에서 제시한 아키텍처와 코드는 다양한 서버리스 애플리케이션에서 사용자 프로필 이미지 업로드, 게시판 첨부파일, 데이터 제출 등 파일이 필요한 거의 모든 기능의 기반이 될 수 있습니다. 이제 여러분은 서버리스 환경에서의 파일 업로드라는 높은 장벽을 자신 있게 넘어설 수 있을 것입니다.
