Working With Buckets and Objects Using mc

한국어 원문으로 표시합니다.

목표

S3 호환 스토리지의 기본 조작 — 별칭, 버킷, 객체 업로드, 접두어, 목록, ETag, 복사, 메타데이터 — 를 손으로 익히고 오브젝트 스토리지에 디렉터리가 없다는 사실을 체감한다.

왜 중요한가

S3 API 를 이해하는 것은 특정 벤더를 배우는 일이 아닙니다. AWS S3, MinIO, SeaweedFS, Garage, Ceph RGW 가 전부 같은 API 를 말하기 때문에, 이 API 는 사실상의 이식성 계층입니다. 실제로 2025~2026년 MinIO 커뮤니티 에디션이 배포를 중단했을 때 애플리케이션 쪽 이주 비용이 크지 않았던 이유가 이것입니다 — 엔드포인트와 자격 증명만 바꾸면 코드는 대체로 그대로였습니다. 이 실습에서 특히 기억할 것은 6번 스텝의 ETag 입니다. 단일 파트 업로드에서 ETag 는 내용의 md5 이고, 그래서 업로드가 온전했는지 클라이언트가 스스로 검증할 수 있습니다. 다음 실습에서 멀티파트 업로드의 ETag 가 이것과 어떻게 달라지는지를 다룰 때, 여기서 본 규칙이 출발점이 됩니다.

단계

mc alias set local http://127.0.0.1:9000 <액세스키> <시크릿키> 로 별칭을 만든다. 자격 증명은 /opt/fixtures/s3/creds.env 에 있다. mc ls local 이 오류 없이 끝나야 한다.
버킷 lab-media 를 만든다. mc ls local 목록에 나타나야 한다.
/opt/fixtures/s3/logo.png 를 local/lab-media/img/logo.png 로 올린다.
/opt/fixtures/s3/ 의 banner.png 를 img/banner.png 로, readme.txt 를 doc/readme.txt 로, sales.csv 를 doc/sales.csv 로 올린다.
mc ls --recursive local/lab-media 결과를 /root/s3/list.txt 에 저장한다. 정확히 4줄이어야 한다.
/root/s3/etag.txt 에 etag=<값> 과 md5=<값> 두 줄을 적는다. logo.png 의 ETag(따옴표 제거)와 로컬 파일 md5 가 같아야 한다.
doc/readme.txt 를 doc/README.txt 로 서버 사이드 복사한 뒤 원본을 지운다. mc ls local/lab-media/doc/ 에 README.txt 만 있고 readme.txt 는 없어야 한다.
sales.csv 를 text/csv Content-Type 으로 다시 올린다. mc stat local/lab-media/doc/sales.csv 출력에 text/csv 가 보여야 한다.

참고

별칭 확인: mc alias list
재귀 목록: mc ls --recursive local/lab-media
Content-Type 지정: mc cp --attr "Content-Type=text/csv" 파일 local/버킷/키
흔한 실수 1: 버킷 이름에 대문자나 밑줄을 쓰는 것 — DNS 규칙을 따릅니다.
흔한 실수 2: img/ 를 폴더로 착각해 따로 만들려는 것 — 키 이름의 일부일 뿐입니다.

S3 별칭 설정하기

mc alias set local http://127.0.0.1:9000 <액세스키> <시크릿키> 로 별칭을 만든다. 자격 증명은 /opt/fixtures/s3/creds.env 에 있다. mc ls local 이 오류 없이 끝나야 한다.

엔드포인트와 자격 증명을 별칭 하나로 묶습니다. 자격 증명은 /opt/fixtures/s3/creds.env 에 있습니다.

버킷 만들기

버킷 lab-media 를 만든다. mc ls local 목록에 나타나야 한다.

버킷 이름은 DNS 규칙을 따릅니다 — 소문자, 숫자, 하이픈만 쓸 수 있습니다.

객체 하나 올리기

/opt/fixtures/s3/logo.png 를 local/lab-media/img/logo.png 로 올린다.

로컬 경로와 대상 키를 함께 지정합니다. 대상 키의 슬래시는 폴더가 아니라 이름의 일부입니다.

접두어로 정리하기

/opt/fixtures/s3/ 의 banner.png 를 img/banner.png 로, readme.txt 를 doc/readme.txt 로, sales.csv 를 doc/sales.csv 로 올린다.

img/ 와 doc/ 아래에 나눠 올립니다. 실제로는 폴더가 만들어지는 게 아니라 키 이름이 그렇게 되는 것입니다.

재귀 목록 뽑기

mc ls --recursive local/lab-media 결과를 /root/s3/list.txt 에 저장한다. 정확히 4줄이어야 한다.

기본 목록은 접두어 단위로 접혀 보입니다. 전부 펼치는 옵션이 있습니다.

ETag 와 로컬 해시 비교하기

/root/s3/etag.txt 에 etag=<값> 과 md5=<값> 두 줄을 적는다. logo.png 의 ETag(따옴표 제거)와 로컬 파일 md5 가 같아야 한다.

단일 파트 업로드의 ETag 는 내용의 md5 입니다. 두 값을 나란히 적어 비교하세요.

서버 사이드 복사 후 원본 지우기

doc/readme.txt 를 doc/README.txt 로 서버 사이드 복사한 뒤 원본을 지운다. mc ls local/lab-media/doc/ 에 README.txt 만 있고 readme.txt 는 없어야 한다.

이름 변경은 없습니다. 복사하고 지우는 것이 이름 변경입니다. 다운로드 없이 서버에서 처리되게 하세요.

Content-Type 지정해 올리고 확인하기

sales.csv 를 text/csv Content-Type 으로 다시 올린다. mc stat local/lab-media/doc/sales.csv 출력에 text/csv 가 보여야 한다.

확장자로 추측되기도 하지만 명시하는 편이 안전합니다. 객체 메타데이터를 조회해 확인하세요.