Skip to content

Storage API

Jump to bottom
JinmuGo edited this page Aug 7, 2026 · 3 revisions

Storage API

OCI Object Storage의 S3 호환 API를 기반으로 파일을 저장합니다. 서버는 직접 파일을 받지 않고, pre-signed URL을 발급하여 클라이언트가 Object Storage와 직접 통신하게 합니다.

아키텍처

┌─────────────┐         upload-url          ┌──────────────┐
│   Client    │ ───────────────────────────> │   Backend    │
│             │ <─────────────────────────── │              │
└─────────────┘         pre-signed URL       └──────────────┘
       │                                              │
       │       PUT file (pre-signed URL)              │
       └──────────────────────────────────────────────>┘
                            │
                            ▼
                    ┌───────────────┐
                    │  OCI Storage  │
                    └───────────────┘

이 방식의 장점:

  • 서버 부하 감소: 대용량 파일이나 트래픽이 백엔드 서버를 거치지 않음
  • 전송 속도 향상: 클라이언트가 Cloud Storage에 직접 업로드/다운로드
  • 보안: pre-signed URL은 만료 시간이 있어 제한된 시간만 사용 가능

API Endpoints

Method Endpoint 설명
POST /storage/upload-url 업로드용 pre-signed PUT URL 발급
POST /storage/download-url 다운로드용 pre-signed GET URL 발급
POST /storage/public-url 공개 객체의 직접 URL 조회
DELETE /storage/objects 객체 삭제 (204 No Content)

업로드 Flow

1. 백엔드에서 upload URL 요청

curl -X POST https://momo.jinmu.me/storage/upload-url \
  -H "Content-Type: application/json" \
  -d '{
    "key": "profiles/123/avatar.png",
    "contentType": "image/png",
    "expiresIn": 300
  }'

2. 응답

{
  "uploadUrl": "https://axttbadsm6ml.compat.objectstorage.ap-hyderabad-1.oraclecloud.com/momo-bucket-dev/profiles/123/avatar.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&...",
  "bucket": "momo-bucket-dev",
  "key": "profiles/123/avatar.png"
}

3. 클라이언트가 직접 업로드

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: image/png" \
  --data-binary @avatar.png

Content-Type은 발급받을 때 지정한 값과 동일해야 합니다.

다운로드 Flow

비공개 파일

curl -X POST https://momo.jinmu.me/storage/download-url \
  -H "Content-Type: application/json" \
  -d '{
    "key": "profiles/123/avatar.png",
    "expiresIn": 3600
  }'
{
  "downloadUrl": "https://axttbadsm6ml.compat.objectstorage.ap-hyderabad-1.oraclecloud.com/momo-bucket-dev/profiles/123/avatar.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&...",
  "bucket": "momo-bucket-dev",
  "key": "profiles/123/avatar.png"
}

공개 파일

버킷이나 객체가 public으로 설정되어 있으면 /storage/public-url로 직접 URL을 조회할 수 있습니다.

curl -X POST https://momo.jinmu.me/storage/public-url \
  -H "Content-Type: application/json" \
  -d '{
    "key": "profiles/123/avatar.png"
  }'
{
  "publicUrl": "https://axttbadsm6ml.compat.objectstorage.ap-hyderabad-1.oraclecloud.com/momo-bucket-dev/profiles/123/avatar.png",
  "bucket": "momo-bucket-dev",
  "key": "profiles/123/avatar.png"
}

삭제 Flow

서버에 설정된 자격 증명으로 객체를 삭제합니다. 성공 시 204 No Content를 반환합니다.

curl -X DELETE https://momo.jinmu.me/storage/objects \
  -H "Content-Type: application/json" \
  -d '{
    "key": "profiles/123/avatar.png"
  }'

URL 만료 시간

목적 기본값 권장
업로드 300초 (5분) 짧게 (5~15분)
다운로드 3600초 (1시간) 상황에 따라 조정

expiresIn은 초 단위입니다. 보안상 업로드 URL은 짧게, 다운로드 URL은 필요한 만큼 설정합니다.

Key 네이밍

  • S3 객체 key는 /를 구분자로 사용합니다.
  • 예시: profiles/{userId}/avatar.png, posts/{postId}/images/1.png
  • 중복을 피하기 위해 UUID나 timestamp를 key에 포함하는 것을 권장합니다.

환경 변수

Storage 동작에 필요한 환경 변수는 Environment Variables를 참조하세요.

Swagger 문서

배포된 앱에서 Swagger UI로 Storage API를 확인할 수 있습니다.

https://momo.jinmu.me/api/docs

로컬 개발 시:

http://localhost:3000/api/docs

Clone this wiki locally