Storage Manager

Sonamu는 Flydrive 기반의 통합 파일 스토리지 시스템을 제공합니다. 로컬 파일 시스템(fs)과 AWS S3를 동일한 인터페이스로 사용할 수 있으며, 필요에 따라 여러 디스크를 관리할 수 있습니다.

왜 Storage Manager가 필요한가?

문제 상황

// ❌ 각 드라이버마다 다른 API
if (env === 'local') {
  fs.writeFileSync('uploads/avatar.png', buffer);
  url = '/uploads/avatar.png';
} else {
  await s3.putObject({
    Bucket: 'my-bucket',
    Key: 'uploads/avatar.png',
    Body: buffer
  });
  url = 'https://s3.amazonaws.com/my-bucket/uploads/avatar.png';
}

문제점:

환경마다 다른 코드 작성
드라이버 변경 시 코드 수정 필요
URL 생성 로직이 분산됨

Storage Manager 사용

// ✅ 통합된 인터페이스
await Sonamu.storage.use().put('uploads/avatar.png', buffer);
const url = await Sonamu.storage.use().getUrl('uploads/avatar.png');

장점:

드라이버 독립적인 코드
설정만 변경하면 드라이버 교체 가능
일관된 URL 생성

기본 개념

여러 **디스크(Disk)**를 관리하는 매니저입니다.

Disk

디스크는 파일을 저장하는 하나의 드라이버 인스턴스입니다.

// 기본 디스크 사용
const disk = Sonamu.storage.use();

// 특정 디스크 사용
const s3Disk = Sonamu.storage.use('s3');
const fsDisk = Sonamu.storage.use('fs');

기본 설정

sonamu.config.ts

import { drivers, type SonamuConfig } from "sonamu";

export const config: SonamuConfig = {
  server: {
    storage: {
      default: 'fs',  // 기본 디스크
      drivers: {
        fs: drivers.fs({
          location: './uploads',  // 저장 위치
          urlBuilder: {
            generateURL: (key) => `/uploads/${key}`,
          }
        }),
      }
    }
  }
};

설정 요소:

default: 기본으로 사용할 디스크 이름
drivers: 디스크 이름별 드라이버 팩토리

디스크 사용

기본 디스크

// 기본 디스크 사용 (config.default)
const disk = Sonamu.storage.use();

// 파일 저장
await disk.put('avatar.png', buffer);

// URL 가져오기
const url = await disk.getUrl('avatar.png');
// => '/uploads/avatar.png' (fs)
// => 'https://bucket.s3.amazonaws.com/avatar.png' (s3)

특정 디스크

// fs 디스크
const fsDisk = Sonamu.storage.use('fs');
await fsDisk.put('temp/file.txt', 'content');

// s3 디스크
const s3Disk = Sonamu.storage.use('s3');
await s3Disk.put('backup/file.txt', 'content');

여러 디스크 관리

다중 디스크 설정

export const config: SonamuConfig = {
  server: {
    storage: {
      default: process.env.STORAGE_DISK || 'fs',
      drivers: {
        // 로컬 개발용
        fs: drivers.fs({
          location: './uploads',
          urlBuilder: {
            generateURL: (key) => `/uploads/${key}`,
          }
        }),
        
        // 프로덕션용 (S3)
        s3: drivers.s3({
          credentials: {
            accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
            secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
          },
          region: process.env.AWS_REGION!,
          bucket: process.env.AWS_BUCKET!,
          urlBuilder: {
            generateURL: (key) => 
              `https://${process.env.AWS_BUCKET}.s3.amazonaws.com/${key}`,
          }
        }),
        
        // 공개 파일용
        public: drivers.s3({
          credentials: {
            accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
            secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
          },
          region: process.env.AWS_REGION!,
          bucket: process.env.AWS_PUBLIC_BUCKET!,
          urlBuilder: {
            generateURL: (key) => 
              `https://${process.env.AWS_PUBLIC_BUCKET}.s3.amazonaws.com/${key}`,
          }
        }),
      }
    }
  }
};

용도별 디스크 사용

class UserModelClass extends BaseModel {
  // 프로필 사진 → 공개 디스크
  async uploadAvatar(ctx: Context) {
    const { files } = Sonamu.getContext();
    const file = files?.[0]; // 첫 번째 파일 사용
    const url = await file.saveToDisk(
      `avatars/${ctx.user.id}.png`,
      'public'  // 공개 디스크
    );
    return url;
  }
  
  // 개인 문서 → 기본 디스크 (private)
  async uploadDocument(ctx: Context) {
    const { files } = Sonamu.getContext();
    const file = files?.[0]; // 첫 번째 파일 사용
    const url = await file.saveToDisk(
      `documents/${ctx.user.id}/${file.filename}`
      // 기본 디스크 사용
    );
    return url;
  }
  
  // 백업 → 별도 디스크
  async backupData(data: any) {
    const json = JSON.stringify(data);
    await Sonamu.storage
      .use('backup')
      .put(`backups/${Date.now()}.json`, json);
  }
}

환경별 전략

개발/프로덕션 분리

개발 환경
프로덕션 환경

로컬 파일 시스템 사용

// .env.development
STORAGE_DISK=fs

// sonamu.config.ts
storage: {
  default: process.env.STORAGE_DISK || 'fs',
  drivers: {
    fs: drivers.fs({
      location: './uploads',
      urlBuilder: {
        generateURL: (key) => `/uploads/${key}`,
      }
    }),
  }
}

장점:

AWS 계정 불필요
빠른 개발
비용 없음

S3 사용

// .env.production
STORAGE_DISK=s3
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...
AWS_REGION=ap-northeast-2
AWS_BUCKET=my-app-uploads

// sonamu.config.ts
storage: {
  default: process.env.STORAGE_DISK || 's3',
  drivers: {
    s3: drivers.s3({
      credentials: {
        accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
      },
      region: process.env.AWS_REGION!,
      bucket: process.env.AWS_BUCKET!,
    }),
  }
}

장점:

무제한 용량
CDN 연동 가능
안정적인 서비스

하이브리드 전략

export const config: SonamuConfig = {
  server: {
    storage: {
      default: 's3',
      drivers: {
        // 메인 저장소: S3
        s3: drivers.s3({ /* ... */ }),
        
        // 임시 파일: 로컬
        fs: drivers.fs({
          location: './temp',
          urlBuilder: {
            generateURL: (key) => `/temp/${key}`,
          }
        }),
      }
    }
  }
};

// 사용
class FileModelClass extends BaseModel {
  // 영구 저장 → S3
  async upload(ctx: Context) {
    const { files } = Sonamu.getContext();
    const file = files?.[0]; // 첫 번째 파일 사용
    return file.saveToDisk('uploads/file.pdf');  // S3
  }

  // 임시 처리 → 로컬
  async processTempFile(ctx: Context) {
    const { files } = Sonamu.getContext();
    const file = files?.[0]; // 첫 번째 파일 사용
    const tempPath = `temp/${Date.now()}.tmp`;
    await file.saveToDisk(tempPath, 'fs');  // 로컬
    
    // 처리 후 삭제
    await Sonamu.storage.use('fs').delete(tempPath);
  }
}

실전 예제

1. 프로필 사진 업로드

class UserModelClass extends BaseModel {
  @upload()
  async uploadAvatar(ctx: Context) {
    const { files } = Sonamu.getContext();
    const file = files?.[0]; // 첫 번째 파일 사용

    if (!file) {
      throw new Error('파일이 없습니다');
    }

    // 파일명: user-{id}-{timestamp}.{ext}
    const filename = `user-${ctx.user.id}-${Date.now()}.${file.extname}`;
    const key = `avatars/${filename}`;

    // 기본 디스크에 저장
    const url = await file.saveToDisk(key);

    // DB 업데이트
    await this.updateOne(['id', ctx.user.id], { avatar_url: url });

    return { url };
  }
}

2. 다중 파일 업로드

class PostModelClass extends BaseModel {
  @upload()
  async uploadImages(postId: number) {
    const { files } = Sonamu.getContext();

    const urls = await Promise.all(
      files.map(async (file, index) => {
        const key = `posts/${postId}/image-${index}.${file.extname}`;
        return await file.saveToDisk(key);
      })
    );
    
    return { urls };
  }
}

3. 디스크별 분리

class FileModelClass extends BaseModel {
  @upload()
  async upload(type: 'public' | 'private') {
    const { files } = Sonamu.getContext();
    const file = files?.[0]; // 첫 번째 파일 사용

    if (!file) {
      throw new Error('파일이 없습니다');
    }
    
    // 타입에 따라 다른 디스크 사용
    const disk = type === 'public' ? 'public' : undefined;
    const key = `${type}/${Date.now()}-${file.filename}`;
    
    const url = await file.saveToDisk(key, disk);
    
    return { url, type };
  }
}

Storage Manager API

use(diskName?)

디스크 인스턴스를 반환합니다.

// 기본 디스크
const disk = Sonamu.storage.use();

// 특정 디스크
const s3 = Sonamu.storage.use('s3');
const fs = Sonamu.storage.use('fs');

반환값: Disk 인스턴스 (Flydrive)

defaultDisk

기본 디스크 이름을 반환합니다.

const defaultName = Sonamu.storage.defaultDisk;
// => 'fs' 또는 's3' 등

Disk API (Flydrive)

Storage Manager가 반환하는 Disk는 Flydrive의 Disk 인스턴스입니다.

주요 메서드

const disk = Sonamu.storage.use();

// 파일 저장
await disk.put('path/to/file.txt', 'content');
await disk.put('path/to/file.txt', buffer);

// 파일 읽기
const content = await disk.get('path/to/file.txt');

// 파일 존재 확인
const exists = await disk.exists('path/to/file.txt');

// 파일 삭제
await disk.delete('path/to/file.txt');

// URL 가져오기
const url = await disk.getUrl('path/to/file.txt');

// Signed URL 가져오기 (S3)
const signedUrl = await disk.getSignedUrl('path/to/file.txt', {
  expiresIn: '1h'
});

주의사항

Storage Manager 사용 시 주의사항:

환경변수 필수: S3 사용 시 AWS 자격증명 필요

// ❌ 하드코딩 금지
credentials: {
  accessKeyId: 'AKIA...',
  secretAccessKey: '...',
}

// ✅ 환경변수 사용
credentials: {
  accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
}

디스크 이름 오타: 존재하지 않는 디스크 사용 시 에러

// ❌ 오타
Sonamu.storage.use('S3')  // 에러!

// ✅ 정확한 이름
Sonamu.storage.use('s3')

경로 구분자: 플랫폼 독립적으로 / 사용

// ✅ 항상 슬래시
await disk.put('uploads/avatar.png', buffer);

// ❌ 백슬래시 사용 금지
await disk.put('uploads\\avatar.png', buffer);

URL 빌더 필수: fs 드라이버는 urlBuilder 설정 필요

// ❌ urlBuilder 없음
fs: drivers.fs({
  location: './uploads',
})

// ✅ urlBuilder 설정
fs: drivers.fs({
  location: './uploads',
  urlBuilder: {
    generateURL: (key) => `/uploads/${key}`,
  }
})

Lazy Initialization: 디스크는 첫 사용 시 초기화됨

// 설정 오류는 use() 호출 시 발견됨
try {
  const disk = Sonamu.storage.use('s3');
} catch (error) {
  // 잘못된 S3 설정 등
}

다음 단계

스토리지 드라이버

fs, S3 드라이버 상세 설정

파일 저장 및 조회

파일 업로드 및 다운로드

URL 빌더

파일 URL 생성하기

시작하기

핵심 개념

데이터베이스

API 개발

프론트엔드 통합

테스팅

고급 기능

도구 & CLI

설정

API 레퍼런스

문제 해결

자주 묻는 질문

​왜 Storage Manager가 필요한가?

​문제 상황

​Storage Manager 사용

​기본 개념

​Storage Manager

​Disk

​기본 설정

​sonamu.config.ts

​디스크 사용

​기본 디스크

​특정 디스크

​여러 디스크 관리

​다중 디스크 설정

​용도별 디스크 사용

​환경별 전략

​개발/프로덕션 분리

​하이브리드 전략

​실전 예제

​1. 프로필 사진 업로드

​2. 다중 파일 업로드

​3. 디스크별 분리

​Storage Manager API

​use(diskName?)

​defaultDisk

​Disk API (Flydrive)

​주요 메서드

​주의사항

​다음 단계