스토리지

Sonamu는 파일 업로드와 저장을 위한 통합 스토리지 시스템을 제공합니다. 로컬 파일 시스템(fs)과 AWS S3를 지원하며, 환경에 따라 쉽게 전환할 수 있습니다.

기본 구조

import path from "path";
import { defineConfig } from "sonamu";
import { drivers } from "sonamu/storage";

export default defineConfig({
  server: {
    storage: {
      drivers: {
        fs: drivers.fs({
          /* ... */
        }),
        s3: drivers.s3({
          /* ... */
        }),
      },
    },
  },
  // ...
});

drivers

사용할 스토리지 드라이버들을 정의합니다. "fs"(로컬 파일 시스템)와 "s3"(AWS S3) 두 종류를 지원합니다. 타입: Record<DriverKey, () => DriverContract> (DriverKey = "fs" | "s3")

import { drivers } from "sonamu/storage";

export default defineConfig({
  server: {
    storage: {
      drivers: {
        fs: drivers.fs({
          /* ... */
        }), // 로컬 파일 시스템
        s3: drivers.s3({
          /* ... */
        }), // AWS S3
      },
    },
  },
});

파일 저장 시 saveToDisk(diskName, key) 호출에서 사용할 드라이버를 명시적으로 지정합니다. 환경별로 다른 드라이버를 사용하려면 환경 변수를 활용하여 코드 레벨에서 분기할 수 있습니다.

fs 드라이버

로컬 파일 시스템에 파일을 저장합니다. 개발 환경에 적합합니다.

import path from "path";
import { drivers } from "sonamu/storage";

export default defineConfig({
  server: {
    storage: {
      drivers: {
        fs: drivers.fs({
          location: path.join(import.meta.dirname, "/../public/uploaded"),
          visibility: "public",
          urlBuilder: {
            generateURL(key) {
              return `/api/public/uploaded/${key}`;
            },
            generateSignedURL(key) {
              return `/api/public/uploaded/${key}`;
            },
          },
        }),
      },
    },
  },
});

location

파일이 저장될 디렉토리 경로입니다. 타입: string (필수)

drivers.fs({
  location: path.join(import.meta.dirname, "/../public/uploaded"),
  // ...
});

경로 예시:

visibility

파일의 접근 권한을 설정합니다. 타입: "public" | "private"

"public": 누구나 URL로 접근 가능
"private": 인증된 사용자만 접근 가능

drivers.fs({
  location: path.join(import.meta.dirname, "/../public/uploaded"),
  visibility: "public", // 공개 파일
  // ...
});

urlBuilder

파일 URL을 생성하는 함수들을 정의합니다.

drivers.fs({
  // ...
  urlBuilder: {
    // 일반 URL 생성
    generateURL(key) {
      return `/api/public/uploaded/${key}`;
    },

    // 서명된 URL 생성 (임시 접근)
    generateSignedURL(key, expiresIn) {
      // fs에서는 보통 일반 URL과 동일
      return `/api/public/uploaded/${key}`;
    },
  },
});

generateURL: 파일의 공개 URL을 생성합니다.

key: 파일의 고유 키 (예: "profile-images/user-123.jpg")
반환: 접근 가능한 URL

generateSignedURL: 임시로 접근 가능한 서명된 URL을 생성합니다.

key: 파일의 고유 키
expiresIn: 만료 시간 (초, 선택적)
반환: 임시 URL

s3 드라이버

AWS S3에 파일을 저장합니다. 프로덕션 환경에 적합합니다.

import { drivers } from "sonamu/storage";

export default defineConfig({
  server: {
    storage: {
      drivers: {
        s3: drivers.s3({
          credentials: {
            accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? "",
            secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? "",
          },
          region: "ap-northeast-2",
          bucket: "my-app-uploads",
          visibility: "private",
        }),
      },
    },
  },
});

credentials

AWS 인증 정보를 설정합니다. 타입: (필수)

credentials: {
  accessKeyId: string;
  secretAccessKey: string;
}

drivers.s3({
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? "",
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? "",
  },
  // ...
});

AWS 인증 정보는 반드시 환경 변수로 관리하세요. 코드에 직접 작성하지 마세요!

.env:

AWS_ACCESS_KEY_ID=your_access_key_here
AWS_SECRET_ACCESS_KEY=your_secret_key_here

region

S3 버킷이 위치한 AWS 리전입니다. 타입: string (필수)

drivers.s3({
  // ...
  region: "ap-northeast-2", // 서울 리전
});

주요 리전:

ap-northeast-2 - 서울
us-east-1 - 버지니아 북부
us-west-2 - 오레곤
eu-west-1 - 아일랜드
ap-southeast-1 - 싱가포르

bucket

파일을 저장할 S3 버킷 이름입니다. 타입: string (필수)

drivers.s3({
  // ...
  bucket: "my-app-uploads",
});

환경별로 다른 버킷 사용:

drivers.s3({
  // ...
  bucket: process.env.S3_BUCKET ?? "my-app-dev",
});

visibility

S3 객체의 ACL(Access Control List)을 설정합니다. 타입: "public" | "private"

drivers.s3({
  // ...
  visibility: "private", // 인증 필요
});

"public": 퍼블릭 읽기 허용 (public-read ACL)
"private": 프라이빗 (private ACL, 기본값)

실전 예시

개발 환경: fs만 사용

import path from "path";
import { defineConfig } from "sonamu";
import { drivers } from "sonamu/storage";

export default defineConfig({
  server: {
    storage: {
      drivers: {
        fs: drivers.fs({
          location: path.join(import.meta.dirname, "/../public/uploaded"),
          visibility: "public",
          urlBuilder: {
            generateURL(key) {
              return `/api/public/uploaded/${key}`;
            },
            generateSignedURL(key) {
              return `/api/public/uploaded/${key}`;
            },
          },
        }),
      },
    },
  },
  // ...
});

fs + S3 (환경별 전환)

두 드라이버를 모두 등록하고, 코드에서 환경 변수를 기반으로 사용할 드라이버를 선택합니다.

import path from "path";
import { defineConfig } from "sonamu";
import { drivers } from "sonamu/storage";

export default defineConfig({
  server: {
    storage: {
      drivers: {
        // 개발: 로컬 파일 시스템
        fs: drivers.fs({
          location: path.join(import.meta.dirname, "/../public/uploaded"),
          visibility: "public",
          urlBuilder: {
            generateURL(key) {
              return `/api/public/uploaded/${key}`;
            },
            generateSignedURL(key) {
              return `/api/public/uploaded/${key}`;
            },
          },
        }),

        // 프로덕션: AWS S3
        s3: drivers.s3({
          credentials: {
            accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? "",
            secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? "",
          },
          region: process.env.S3_REGION ?? "ap-northeast-2",
          bucket: process.env.S3_BUCKET ?? "my-app-prod",
          visibility: "private",
        }),
      },
    },
  },
  // ...
});

.env.development:

DRIVE_DISK=fs

.env.production:

DRIVE_DISK=s3
S3_REGION=ap-northeast-2
S3_BUCKET=my-app-prod-uploads
AWS_ACCESS_KEY_ID=your_access_key_here
AWS_SECRET_ACCESS_KEY=your_secret_key_here

현재 DriverKey는 "fs"와 "s3" 두 가지만 지원합니다. 공개/비공개 파일을 별도 버킷에 나누어 저장하는 다중 버킷 구성은 현재 지원되지 않습니다.

파일 업로드 사용

스토리지 설정 후 @upload 데코레이터와 BufferedFile.saveToDisk()를 사용하여 파일을 업로드할 수 있습니다.

import { BaseModelClass, Sonamu, upload } from "sonamu";
import { type DriverKey } from "sonamu/storage";

export class FileModel extends BaseModelClass {
  @upload()
  static async upload() {
    const ctx = Sonamu.getContext();
    const file = ctx.bufferedFiles[0];
    if (!file) throw new Error("업로드된 파일이 없습니다.");

    // 환경 변수로 드라이버 선택
    const diskName: DriverKey = process.env.DRIVE_DISK === "s3" ? "s3" : "fs";
    const url = await file.saveToDisk(diskName, `uploads/${Date.now()}-${file.filename}`);

    return { url };
  }
}

→ 파일 업로드 가이드

S3 버킷 설정

S3를 사용하기 전에 AWS 콘솔에서 버킷을 생성하고 설정해야 합니다.

1. 버킷 생성

# AWS CLI로 버킷 생성
aws s3 mb s3://my-app-uploads --region ap-northeast-2

2. CORS 설정

프론트엔드에서 직접 업로드하려면 CORS를 설정합니다. S3 콘솔 → 버킷 → 권한 → CORS 구성:

[
  {
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["GET", "PUT", "POST", "DELETE"],
    "AllowedOrigins": ["https://myapp.com"],
    "ExposeHeaders": ["ETag"]
  }
]

3. IAM 권한

Sonamu가 S3에 접근하려면 적절한 IAM 권한이 필요합니다. 최소 권한 정책:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:PutObject", "s3:GetObject", "s3:DeleteObject", "s3:ListBucket"],
      "Resource": ["arn:aws:s3:::my-app-uploads", "arn:aws:s3:::my-app-uploads/*"]
    }
  ]
}

주의사항

1. 환경 변수 보안

// ❌ 나쁜 예: 코드에 인증 정보 직접 작성
drivers.s3({
  credentials: {
    accessKeyId: "AKIAXXXXXXXXXXXXXXXX",
    secretAccessKey: "wJalrXUtnFEMI/K7MDENG/bPxRfiCY...",
  },
});

// ✅ 좋은 예: 환경 변수 사용
drivers.s3({
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? "",
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? "",
  },
});

2. visibility 선택

// 공개 파일 (프로필 이미지, 상품 이미지 등)
visibility: "public";

// 프라이빗 파일 (개인 문서, 영수증, 계약서 등)
visibility: "private";

3. 파일 경로 설계

// ✅ 좋은 예: 체계적인 경로 구조
const key = `users/${userId}/profile/${Date.now()}.jpg`;
const key = `documents/${year}/${month}/${documentId}.pdf`;

// ❌ 나쁜 예: 평평한 구조
const key = `${Date.now()}.jpg`;

다음 단계

스토리지 설정을 완료했다면:

file-upload - API에서 파일 업로드 구현
cache - 캐시 설정
advanced-features/storage - 고급 스토리지 기능

시작하기

핵심 개념

데이터베이스

API 개발

프론트엔드 통합

테스팅

고급 기능

도구 & CLI

설정

API 레퍼런스

문제 해결

자주 묻는 질문

기본 구조

drivers

fs 드라이버

location

visibility

urlBuilder

s3 드라이버

credentials

region

bucket

visibility

실전 예시

개발 환경: fs만 사용

fs + S3 (환경별 전환)

파일 업로드 사용

S3 버킷 설정

1. 버킷 생성

2. CORS 설정

3. IAM 권한

주의사항

1. 환경 변수 보안

2. visibility 선택

3. 파일 경로 설계

다음 단계

​기본 구조

​drivers

​fs 드라이버

​location

​visibility

​urlBuilder

​s3 드라이버

​credentials

​region

​bucket

​visibility

​실전 예시

​개발 환경: fs만 사용

​fs + S3 (환경별 전환)

​파일 업로드 사용

​S3 버킷 설정

​1. 버킷 생성

​2. CORS 설정

​3. IAM 권한

​주의사항

​1. 환경 변수 보안

​2. visibility 선택

​3. 파일 경로 설계

​다음 단계

기본 구조

drivers

fs 드라이버

location

visibility

urlBuilder

s3 드라이버

credentials

region

bucket

visibility

실전 예시

개발 환경: fs만 사용

fs + S3 (환경별 전환)

파일 업로드 사용

S3 버킷 설정

1. 버킷 생성

2. CORS 설정

3. IAM 권한

주의사항

1. 환경 변수 보안

2. visibility 선택

3. 파일 경로 설계

다음 단계