Node.js로 S3 업로드와 Presigned URL 생성

개요

웹 애플리케이션에서 클라이언트가 직접 S3에 파일을 올리도록 구성하면 서버 부하를 줄일 수 있다. 이를 위해 주로 사용하는 방식이 사전 서명 URL(presigned URL)이다. 이 글은 Node.js S3 presigned URL 생성 방법과 AWS S3 업로드 Node 예제, 그리고 S3 멀티파트 업로드 Node 방식까지 다룬다.

사전 서명 URL 개념

사전 서명 URL은 일정 시간 동안 유효한 임시 URL이다. 서버가 AWS 자격증명으로 서명하여 클라이언트에게 전달한다. 클라이언트는 해당 URL로 직접 PUT 또는 POST 요청을 보내 파일을 업로드한다. 서버는 파일 콘텐츠를 직접 처리하지 않아도 된다.

사전 준비

• AWS 계정과 S3 버킷
• IAM 사용자 또는 역할 (권한: s3:PutObject, s3:PutObjectAcl 등)
• Node.js 런타임
• AWS SDK 설치 (v3 권장)

Node.js에서 Presigned URL 생성 (AWS SDK v3)

아래 예제는 AWS SDK for JavaScript v3를 사용한다. v3는 모듈화되어 용량과 성능 측면에서 유리하다.

패키지 설치

npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner

서버 코드 예제

const { S3Client, PutObjectCommand } = require('@aws-sdk/client-s3');
const { getSignedUrl } = require('@aws-sdk/s3-request-presigner');

const s3 = new S3Client({ region: 'ap-northeast-2' });

async function createPresignedUrl(bucketName, key, expiresSeconds = 900) {
  const command = new PutObjectCommand({
    Bucket: bucketName,
    Key: key,
    // 필요한 경우 ContentType 등을 설정
  });
  const url = await getSignedUrl(s3, command, { expiresIn: expiresSeconds });
  return url;
}

// 사용 예시
createPresignedUrl('my-bucket', 'uploads/photo.jpg')
  .then(url => console.log(url))
  .catch(err => console.error(err));

위 코드는 presigned URL을 생성한다. expiresIn 값으로 유효기간을 제어한다. 생성된 URL을 클라이언트에 전달하면 클라이언트가 직접 PUT으로 업로드할 수 있다.

클라이언트 업로드 예시

브라우저에서 fetch를 사용한 업로드 예시이다. 서버가 발급한 URL로 파일을 전송한다.

async function uploadToS3(presignedUrl, file) {
  const res = await fetch(presignedUrl, {
    method: 'PUT',
    headers: {
      'Content-Type': file.type
    },
    body: file
  });
  return res.ok;
}

멀티파트 업로드 필요성

큰 파일 업로드는 네트워크 실패에 취약하다. S3 멀티파트 업로드는 파일을 여러 파트로 나누어 병렬 전송하고, 실패한 파트만 재전송할 수 있어 효율적이다. 대용량 파일 전송 시 S3 멀티파트 업로드 Node 사용을 권장한다.

멀티파트 업로드 흐름

• 서버가 멀티파트 업로드를 시작하고 UploadId를 발급한다.
• 각 파트에 대해 사전 서명 URL을 생성한다.
• 클라이언트가 각 파트를 해당 URL로 업로드한다.
• 모든 파트 업로드 완료 후 서버가 CompleteMultipartUpload 호출로 병합한다.

간단한 멀티파트 예제 (흐름 설명용)

// 1. CreateMultipartUpload -> UploadId 수신
// 2. 각 파트에 대해 Presigned URL 생성 (UploadPartCommand로 서명)
// 3. 클라이언트는 각 URL로 PUT 요청
// 4. 서버는 CompleteMultipartUpload 호출

// 실제 구현은 에러 처리와 파트 검증이 필요

보안과 권한 고려사항

• 발급 권한 최소화: presigned URL을 생성하는 서버만 S3 Put 권한을 가진다.
• 유효기간 짧게 설정: 가능한 짧은 expiresIn 사용.
• 객체 키 규칙: 예측 불가능한 키를 사용해 무단 접근을 방지.
• HTTPS 사용: 전송 보안을 위해 필수.

추가 팁과 주의사항

• Content-Type이나 ACL 설정은 서명 시 일치해야 문제가 생기지 않는다.
• 브라우저에서 큰 파일은 멀티파트를 통해 병렬 업로드 고려.
• 로그와 모니터링으로 업로드 실패 패턴을 파악.

마무리

Node.js S3 presigned URL 방식은 서버 부하를 줄이고 확장성 있는 파일 업로드 구조를 제공한다. AWS S3 업로드 Node 예제와 S3 멀티파트 업로드 Node 방식은 대용량 파일 처리에 유리하다. 구현 시 권한과 만료 시간을 신중히 설계하면 안전하고 효율적인 파일 전송 체계를 만들 수 있다.