AWS S3 완벽 활용 가이드

AWS S3의 고급 기능과 최적화 전략을 다룹니다. 멀티파트 업로드, 프리사인드 URL, 버킷 정책, 라이프사이클 관리 등 실무에서 필요한 핵심 기능들을 학습합니다.

---

---

들어가며

이 글에서는 AWS S3 완벽 활용 가이드에 대해 상세히 알아보겠습니다. 총 12가지 주요 개념을 다루며, 각각의 개념에 대한 설명과 실제 코드 예제를 함께 제공합니다.

목차

1. S3_클라이언트_초기화
2. 기본_파일_업로드
3. 프리사인드_URL_생성
4. 멀티파트_업로드_시작
5. 파트_업로드_및_완료
6. 파일_다운로드_스트림
7. 버킷_정책_설정
8. 라이프사이클_규칙_설정
9. 객체_복사_및_이동
10. 버전_관리_활성화
11. 배치_삭제_작업
12. 서버측_암호화_설정

---

1. S3 클라이언트 초기화

개요

AWS SDK v3를 사용하여 S3 클라이언트를 초기화합니다. 최신 모듈형 아키텍처로 필요한 명령만 임포트하여 번들 크기를 최적화합니다.

코드 예제

import { S3Client } from "@aws-sdk/client-s3";

const s3Client = new S3Client({
  region: "ap-northeast-2",
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!
  }
});

설명

리전과 자격 증명을 설정하여 S3 클라이언트를 생성합니다. 환경 변수를 사용하여 보안을 강화합니다.

---

2. 기본 파일 업로드

개요

PutObjectCommand를 사용하여 파일을 S3 버킷에 업로드합니다. 메타데이터와 콘텐츠 타입을 함께 설정할 수 있습니다.

코드 예제

import { PutObjectCommand } from "@aws-sdk/client-s3";

async function uploadFile(key: string, body: Buffer) {
  const command = new PutObjectCommand({
    Bucket: "my-bucket",
    Key: key,
    Body: body,
    ContentType: "image/jpeg",
    Metadata: { uploadedBy: "admin" }
  });
  return await s3Client.send(command);
}

설명

버킷 이름, 키, 파일 데이터를 지정하여 업로드합니다. 메타데이터로 추가 정보를 저장할 수 있습니다.

---

3. 프리사인드 URL 생성

개요

일시적으로 파일에 접근할 수 있는 서명된 URL을 생성합니다. 보안이 필요한 파일 다운로드나 업로드에 활용됩니다.

코드 예제

import { GetObjectCommand } from "@aws-sdk/client-s3";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";

async function generatePresignedUrl(key: string) {
  const command = new GetObjectCommand({
    Bucket: "my-bucket",
    Key: key
  });
  return await getSignedUrl(s3Client, command, {
    expiresIn: 3600
  });
}

설명

1시간 동안 유효한 서명된 URL을 생성합니다. 클라이언트가 직접 S3에 접근할 수 있어 서버 부하를 줄입니다.

---

4. 멀티파트 업로드 시작

개요

대용량 파일을 여러 조각으로 나누어 업로드합니다. 네트워크 장애 시 재시도가 가능하고 병렬 처리로 속도를 향상시킵니다.

코드 예제

import { CreateMultipartUploadCommand } from "@aws-sdk/client-s3";

async function startMultipartUpload(key: string) {
  const command = new CreateMultipartUploadCommand({
    Bucket: "my-bucket",
    Key: key,
    ContentType: "video/mp4"
  });
  const response = await s3Client.send(command);
  return response.UploadId;
}

설명

멀티파트 업로드를 시작하고 UploadId를 받습니다. 이후 각 파트를 업로드할 때 이 ID를 사용합니다.

---

5. 파트 업로드 및 완료

개요

각 파트를 업로드하고 모든 파트가 완료되면 하나의 객체로 병합합니다. ETag를 수집하여 최종 완료 요청에 사용합니다.

코드 예제

import { UploadPartCommand, CompleteMultipartUploadCommand } from "@aws-sdk/client-s3";

async function uploadPart(uploadId: string, partNumber: number, body: Buffer) {
  const command = new UploadPartCommand({
    Bucket: "my-bucket", Key: "video.mp4",
    UploadId: uploadId, PartNumber: partNumber, Body: body
  });
  const { ETag } = await s3Client.send(command);
  return { PartNumber: partNumber, ETag };
}

설명

각 파트를 순차적으로 업로드하고 ETag를 수집합니다. 모든 파트 완료 후 CompleteMultipartUpload로 병합합니다.

---

6. 파일 다운로드 스트림

개요

GetObjectCommand로 파일을 스트림 방식으로 다운로드합니다. 메모리 효율적으로 대용량 파일을 처리할 수 있습니다.

코드 예제

import { GetObjectCommand } from "@aws-sdk/client-s3";
import { Readable } from "stream";

async function downloadFile(key: string) {
  const command = new GetObjectCommand({
    Bucket: "my-bucket", Key: key
  });
  const response = await s3Client.send(command);
  return response.Body as Readable;
}

설명

Body를 Readable 스트림으로 받아 파일 시스템에 저장하거나 클라이언트로 전송할 수 있습니다.

---

7. 버킷 정책 설정

개요

버킷 레벨에서 접근 권한을 제어하는 정책을 설정합니다. 특정 IP나 사용자에 대한 접근을 허용 또는 거부할 수 있습니다.

코드 예제

import { PutBucketPolicyCommand } from "@aws-sdk/client-s3";

const policy = {
  Version: "2012-10-17",
  Statement: [{
    Effect: "Allow", Principal: "*",
    Action: "s3:GetObject",
    Resource: "arn:aws:s3:::my-bucket/public/*"
  }]
};
await s3Client.send(new PutBucketPolicyCommand({
  Bucket: "my-bucket", Policy: JSON.stringify(policy)
}));

설명

public 폴더의 모든 객체를 공개 읽기 가능하도록 설정합니다. JSON 정책으로 세밀한 권한 제어가 가능합니다.

---

8. 라이프사이클 규칙 설정

개요

객체의 수명 주기를 자동으로 관리합니다. 일정 기간 후 자동으로 저렴한 스토리지 클래스로 이동하거나 삭제합니다.

코드 예제

import { PutBucketLifecycleConfigurationCommand } from "@aws-sdk/client-s3";

await s3Client.send(new PutBucketLifecycleConfigurationCommand({
  Bucket: "my-bucket",
  LifecycleConfiguration: { Rules: [{
    Id: "archive-old-files", Status: "Enabled",
    Transitions: [{ Days: 30, StorageClass: "GLACIER" }],
    Expiration: { Days: 365 }
  }]}
}));

설명

30일 후 Glacier로 이동하고 365일 후 삭제합니다. 스토리지 비용을 최적화할 수 있습니다.

---

9. 객체 복사 및 이동

개요

S3 내에서 객체를 복사하거나 이동합니다. 서버로 다운로드/업로드 없이 S3 내부에서 처리되어 빠르고 비용 효율적입니다.

코드 예제

import { CopyObjectCommand, DeleteObjectCommand } from "@aws-sdk/client-s3";

async function moveObject(sourceKey: string, destKey: string) {
  await s3Client.send(new CopyObjectCommand({
    Bucket: "my-bucket", CopySource: `/my-bucket/${sourceKey}`,
    Key: destKey
  }));
  await s3Client.send(new DeleteObjectCommand({
    Bucket: "my-bucket", Key: sourceKey
  }));
}

설명

먼저 대상 위치로 복사한 후 원본을 삭제하여 이동 효과를 구현합니다. 네트워크 전송이 없어 빠릅니다.

---

10. 버전 관리 활성화

개요

객체의 모든 버전을 보관하여 실수로 삭제하거나 덮어쓴 파일을 복구할 수 있습니다. 규정 준수에도 유용합니다.

코드 예제

import { PutBucketVersioningCommand } from "@aws-sdk/client-s3";

async function enableVersioning() {
  await s3Client.send(new PutBucketVersioningCommand({
    Bucket: "my-bucket",
    VersioningConfiguration: {
      Status: "Enabled"
    }
  }));
}

설명

버전 관리를 활성화하면 모든 PUT, DELETE 작업이 새 버전을 생성합니다. 이전 버전 복구가 가능합니다.

---

11. 배치 삭제 작업

개요

여러 객체를 한 번에 삭제합니다. 개별 삭제보다 효율적이며 최대 1000개까지 한 번에 처리할 수 있습니다.

코드 예제

import { DeleteObjectsCommand } from "@aws-sdk/client-s3";

async function deleteMultiple(keys: string[]) {
  await s3Client.send(new DeleteObjectsCommand({
    Bucket: "my-bucket",
    Delete: {
      Objects: keys.map(Key => ({ Key }))
    }
  }));
}

설명

키 배열을 받아 한 번의 API 호출로 여러 객체를 삭제합니다. API 호출 비용과 시간을 절약할 수 있습니다.

---

12. 서버측 암호화 설정

개요

S3에 저장되는 데이터를 자동으로 암호화합니다. AES-256 또는 KMS 키를 사용하여 보안을 강화합니다.

코드 예제

import { PutObjectCommand } from "@aws-sdk/client-s3";

async function uploadEncrypted(key: string, body: Buffer) {
  await s3Client.send(new PutObjectCommand({
    Bucket: "my-bucket", Key: key, Body: body,
    ServerSideEncryption: "AES256",
    // 또는 KMS 사용: ServerSideEncryption: "aws:kms"
  }));
}

설명

업로드 시 서버 측 암호화를 지정하여 저장 데이터를 보호합니다. KMS를 사용하면 키 관리가 더욱 세밀해집니다.

---

마치며

이번 글에서는 AWS S3 완벽 활용 가이드에 대해 알아보았습니다. 총 12가지 개념을 다루었으며, 각각의 사용법과 예제를 살펴보았습니다.

관련 태그

#AWS #S3 #CloudStorage #FileUpload #ServerlessArchitecture