7화. MinIO — S3 API를 내 방에. 오브젝트 스토리지 입문

앱에서 파일 업로드 기능을 만들 때 AWS S3 SDK를 쓰고 싶은데, 테스트할 S3가 없어서 애매한 적이 있나? 백업 파일을 모아둘 곳이 필요한데 폴더 나누기로는 관리가 안 되나? MinIO는 AWS S3와 API까지 호환되는 오브젝트 스토리지를 도커 한 개로 제공한다. 개발, 백업, 파일 서비스 — "저장"이 필요한 대부분의 자리에 들어맞는 만능 저장소다.

이런 때 유용합니다

• 개발 중인 앱에 파일 업로드 기능이 필요할 때. S3 SDK를 그대로 쓰고, 주소만 내 MinIO로 향하면 된다. 배포할 때 진짜 S3로 갈아타도 코드가 안 바뀐다.
• 사진·문서·백업 파일을 담을 큰 저장소가 필요할 때. 폴더 규칙 대신 버킷과 오브젝트로 체계적으로 관리한다.
• 외부에 파일을 안전하게 건네줘야 할 때. 만료 시간이 있는 서명된 링크(프리사인 URL)로 준다.
• 클라우드 스토리지 전송 요금이 무서울 때. 내 서버 간에는 전송료가 없다.
• 여러 서버가 하나의 파일 저장소를 공유해야 할 때. S3 API라는 공통 언어로 다 붙는다.

필요한 것은 디스크 공간뿐이다. 저장 용량의 한도는 내가 정한다.

MinIO는 어떤 프로그램인가

MinIO는 AWS S3 API와 완전히 호환되는 오픈소스 오브젝트 스토리지다. Go로 작성된 단일 바이너리라 설치가 매우 가볍고, 개인 서버부터 데이터센터 클러스터까지 같은 소프트웨어가 커버한다.

"오브젝트 스토리지"가 낯설다면 이렇게 이해하면 된다. 폴더에 파일을 넣는 방식(파일 시스템) 대신, 버킷에 오브젝트를 넣고 고유 주소로 꺼내는 방식이다. 웹의 파일 서버에는 적합하지 않지만, 백업·이미지·로그·앱 데이터 같은 "쓰고 읽는" 데이터에는 오히려 잘 맞는다.

전체 구성

flowchart LR
    subgraph APP["클라이언트"]
        A["앱·스크립트 - S3 SDK"]
        M["mc CLI - 백업·관리"]
        B["웹 콘솔 - 브라우저"]
    end
    subgraph SRV["Docker 서버"]
        MN["MinIO - S3 API와 콘솔"]
        BK[("data 폴더 - 버킷·오브젝트")]
    end
    A -->|S3 API| MN
    M -->|S3 API| MN
    B --> MN
    MN --> BK

컨테이너는 하나다. S3 API(포트 9000)와 웹 콘솔(포트 9001)이 같은 컨테이너에서 제공된다.

설치 방법

1단계 — 컨테이너

services:
  minio:
    image: minio/minio:latest
    container_name: minio
    command: server /data --console-address ":9001"
    environment:
      MINIO_ROOT_USER: 관리자아이디
      MINIO_ROOT_PASSWORD: 강한비밀번호      # 8자 이상
    volumes:
      - /opt/docker/minio/data:/data
    ports:
      - "9000:9000"   # S3 API
      - "9001:9001"   # 웹 콘솔
    restart: unless-stopped

http://서버IP:9001로 콘솔에 접속해 관리자 계정으로 로그인하면 준비 끝이다. 콘솔에서 버킷 생성·업로드·정책 설정이 전부 가능하니, 처음엔 명령어 없이 콘솔만으로도 충분히 쓸 수 있다.

2단계 — 버킷과 접근 계정

버킷은 S3의 최상위 저장 단위다. 콘솔에서 만들어도 되고, 공식 CLI(mc)로 만들어도 된다.

mc alias set local http://서버IP:9000 관리자아이디 비밀번호
mc mb local/photos        # photos 버킷 생성

앱이 접근할 때는 루트 계정 대신 전용 계정(Access Key)을 만들어 권한을 최소한으로 제한하는 습관이 중요하다. 콘솔의 Identity 메뉴에서 버킷별 권한을 가진 키를 발급할 수 있다.

3단계 — 프리사인 URL

이 MinIO의 킬러 기능이다. 업로드·다운로드 권한을 일정 시간만 유효한 URL로 빌려주는 방식으로, 파일이 내 앱 서버를 경유하지 않고 클라이언트와 MinIO가 직접 통신하게 된다.

mc share download --expire 24h local/photos/report.pdf

클라우드 스토리지 서비스들이 "서명된 URL"로 제공하는 바로 그 기능이다.

4단계 — 백업과 버전 관리

• 버전 관리를 켜두면 실수로 덮어쓴 파일도 이전 버전이 남는다. 콘솔의 버킷 설정에서 한 번 클릭.
• 백업은 mc mirror 또는 rclone으로 다른 저장소(NAS 등)에 미러링하면 된다. cron 한 줄.
• 수명 주기 규칙으로 "90일 지난 백업 버전 자동 삭제" 같은 정책도 가능하다.

운영하며 쌓은 것들

루트 계정과 앱 계정을 분리한다. 루트 계정(MINIO_ROOT_USER)은 관리 전용으로 쓰지 않고, 앱·스크립트마다 별도 Access Key를 발급해 권한을 버킷 단위로 제한한다. 키 하나가 새어도 피해 범위가 해당 버킷으로 한정된다.

콘솔은 외부에 노출하지 않는다. 9001 웹 콘솔은 사설망에서만 접근 가능하게 두고, S3 API(9000)만 필요한 경우에 도메인을 붙인다. 도메인을 붙일 때도 HTTPS를 거쳐야 프리사인 URL이 정상 동작한다.

버전 관리는 백업용 버킷에 기본으로 켠다. "어제 백업했는데 오늘 덮어썼다"는 오브젝트 스토리지의 고전적 사고다. 버전 관리가 켜져 있으면 덮어쓰기가 아니라 새 버전이 된다.

트러블슈팅 정리

자주 묻는 질문

AWS S3와 호환이 정확히 무엇을 말하는 건가?

S3의 API 명령(버킷 생성, 오브젝트 업로드/다운로드, 프리사인 URL 등)을 같은 형식으로 이해한다는 뜻이다. AWS SDK로 MinIO를 바로 쓸 수 있고, rclone 같은 S3 호환 도구도 설정의 주소만 바꾸면 된다.

용도를 하나만 고르라면 뭘 추천하나?

개인 서버 기준으로는 백업 저장소가 가장 좋다. 버전 관리·수명 주기·S3 호환 도구 생태계 덕분에 백업 체계를 깔끔하게 만들 수 있다. 앱 개발용 테스트 S3로도 훌륭하다.

사진 서버(Immich) 대신 써도 되나?

목적이 다르다. Immich는 사진 열람·분류 경험을 제공하고, MinIO는 저장 인프라다. 오히려 조합이 가능한 영역이라, 필요하면 백업 단계에서 함께 쓸 수 있다.

서버 한 대로 충분하다 연재 목차 — 시리즈 소개 · 1화. Home Assistant · 2화. Frigate + go2rtc · 3화. Seafile 13 · 4화. Immich · 5화. Vaultwarden · 6화. Mailcow

버킷 운영과 프리사인 URL 기반 파일 서비스 경험을 바탕으로 작성했습니다.