SeaweedFS 는 Apache 라이선스를 따르는 독립적인 오픈 소스 프로젝트이며, 지속적인 개발은 이러한 멋진 후원자들의 지원 덕분에 가능합니다. SeaweedFS 를 더욱 강력하게 성장시키기를 원하신다면 Patreon 의 스폰서로 참여해 주시기를 부탁드립니다.

저와 다른 후원자들에게 여러분의 지원이 정말로 감사하겠습니다!

• 플랫폼별 바이너리 다운로드

• Slack 에서의 SeaweedFS

• Twitter 에서의 SeaweedFS

• Telegram 에서의 SeaweedFS

• Reddit 에서의 SeaweedFS

• SeaweedFS 메일링 리스트

• Wiki 문서

• SeaweedFS 화이트페이퍼

• SeaweedFS 소개 슬라이드 2025.5

• SeaweedFS 소개 슬라이드 2021.5

• SeaweedFS 소개 슬라이드 2019.3

• 빠른 시작

• 소개

• 기능

• 예제: Seaweed Object Store 사용

• 아키텍처

• 다른 파일 시스템과 비교

• 개발 계획

• 설치 가이드

• 디스크 관련 주제

• 벤치마크

• 기업용

• 라이선스

최신 바이너리를 https://github.com/seaweedfs/seaweedfs/releases 에서 다운로드하고 단일 weed (또는 weed.exe) 파일을 압축 해제하거나, go install github.com/seaweedfs/seaweedfs/weed@latest 를 실행합니다. 그런 다음 하나의 명령어로 자격증명과 미리 생성된 버킷을 갖춘 사용 가능한 S3 Object Store 를 시작합니다:

AWS_ACCESS_KEY_ID=admin \
AWS_SECRET_ACCESS_KEY=secret \
S3_BUCKET=my-bucket \
...

그만 — S3 엔드포인트는 http://localhost:8333 에 있으며, my-bucket 이 이미 존재하고 admin / secret 은 유효한 자격증명입니다. S3_BUCKET 은 쉼표로 구분된 목록을 받습니다 (예: raw,processed); S3 Tables (Iceberg) 버킷을 위해 S3_TABLE_BUCKET 을 사용하세요. 환경 변수를 모두 제거하면 해당 부분을 건너뜁니다 (AWS 키 없음 → 개발용 "모든 권한 허용" 모드로 S3 실행).

동일한 명령어로 모든 다른 기능도 시작됩니다:

S3 엔드포인트: http://localhost:8333
Master UI: http://localhost:9333
Volume Server: http://localhost:9340
Filer UI: http://localhost:8888
WebDAV: http://localhost:7333
Admin UI: http://localhost:23646

macOS: 바이너리가 격리되어 있다면 먼저 xattr -d com.apple.quarantine ./weed 를 실행하세요.

개발, 테스트, SeaweedFS 학습 및 단일 노드 배포에 완벽합니다. 확장하려면 더 많은 Volume Server 를 추가하여 weed volume -dir="/some/data/dir2" -master="<master_host>:9333" -port=8081 로 실행하세요.

docker run -p 8333:8333 \
-e AWS_ACCESS_KEY_ID=admin \
-e AWS_SECRET_ACCESS_KEY=secret \
...

위 weed mini 명령어와 동일한 동작 — S3 엔드포인트는 http://localhost:8333 에 있으며 my-bucket 이 미리 생성됩니다. 환경 변수를 제거하면 개발용 익명 실행을 수행합니다.

SeaweedFS 는 단순하고 확장성이 뛰어난 분산 파일 시스템입니다. 두 가지 목표가 있습니다:

• 수십억 개의 파일을 저장하세요!
• 파일을 빠르게 제공하세요!

SeaweedFS 는 소규모 파일을 효율적으로 처리하기 위해 Blob Store 로 시작되었습니다. 모든 파일 메타데이터를 중앙 마스터에서 관리하는 대신, 중앙 마스터는 Volume Server 의 볼륨을 관리하고, 이 Volume Server 는 파일과 그 메타데이터를 관리합니다. 이는 중앙 마스터의 병행 압력을 완화하고 파일 메타데이터를 Volume Server 에 분산시켜 더 빠른 파일 액세스 (O(1), 일반적으로 하나의 디스크 읽기 작업) 를 가능하게 합니다.

각 파일의 메타데이터는 40 바이트의 디스크 저장 오버헤드만 있습니다. O(1) 디스크 읽기가 너무 단순하므로 실제 사용 사례로 성능을 도전해 주셔도 좋습니다.

SeaweedFS 는 Facebook 의 Haystack 설계 논문 (paper) 을 구현하여 시작되었습니다. 또한 SeaweedFS 는 f4: Facebook 의 Warm BLOB Storage System 에서의 아이디어를 바탕으로 에러스 코딩 (erasure coding) 을 구현했으며, Facebook 의 Tectonic Filesystem 과 Google 의 Colossus File System 과 많은 유사점을 가집니다.

blob store 위에 optional Filer 를 통해 디렉터리와 POSIX 속성을 지원할 수 있습니다. Filer 는 커스터마이징 가능한 메타데이터 스토어 (예: MySql, Postgres, Redis, Cassandra, HBase, Mongodb, Elastic Search, LevelDB, RocksDB, Sqlite, MemSql, TiDB, Etcd, CockroachDB, YDB 등) 를 가진 별도의 선형 확장 가능한 stateless 서버입니다.

SeaweedFS 는 클라우드와 투명적으로 통합할 수 있습니다. 로컬 클러스터에 핫 데이터 (hot data), 클라우드에 워밍 데이터 (warm data) 를 배치하여 O(1) 액세스 시간을 가지며, SeaweedFS 는 빠른 로컬 액세스 시간과 탄력적인 클라우드 스토리지 용량을 동시에 달성할 수 있습니다. 또한, 클라우드 스토리지 액세스 API 비용은 최소화됩니다. 직접적인 클라우드 스토리지보다 빠르고 저렴합니다!

SeaweedFS 는 자체적인 Iceberg REST Catalog를 제공하여 동일한 클러스터를 자체적인 lakehouse 으로 변환시킵니다.
Spark, Trino, Dremio, DuckDB, RisingWave 는 Iceberg 테이블을 직접 쿼리할 수 있습니다 — Hive Metastore, Glue 또는 외부 카탈로그 서비스는 필요 없습니다. 스토리지 및 테이블 메타데이터는 하나의 시스템에 존재하여 온프레미스 및 소규모 팀 분석 스택을 단순화합니다.

• 랭 (rack) 과 데이터 센터를 인식하는 다른 복제 수준을 지원합니다.

• 자동 마스터 서버 페이오버 — 단일 장애점 (SPOF) 없음.

• 파일 MIME 타입에 따라 자동 압축.

• 삭제 또는 업데이트 후 디스크 공간을 회수하기 위한 자동 컴팩션.

• 자동 엔트리 TTL 만료.

• 유연한 용량 확장: 일부 디스크 공간이 있는 서버를 총 스토리지 공간에 추가할 수 있습니다.

• 서버 추가/제거는 관리 명령어에 의해 트리거되지 않는 한 데이터 리밸런싱을 유발하지 않습니다.

• 선택적 이미지 크기 조정.

• ETag, Accept-Range, Last-Modified 등을 지원합니다.

• 메모리/레벨 DB/읽기 전용 모드 튜닝을 지원하여 메모리/성능 균형을 제공합니다.

• 쓰기 가능 및 읽기 전용 볼륨의 리밸런싱을 지원합니다.

• 커스터마이징 가능한 다중 스토리지 티어: 성능과 비용을 균형있게 맞추기 위한 커스터마이징 스토리지 디스크 타입.

• 투명한 클라우드 통합: 워밍 데이터를 위한 계층형 클라우드 스토리지를 통한 무한 용량.

• 에러스 코딩을 통한 워밍 스토리지 랭 인식 10.4 에러스 코딩은 저장 비용을 줄이고 가용성을 높입니다. 기업 버전은 EC 비율을 커스터마이징할 수 있습니다.

• Filer 서버는 HTTP 를 통해 "일반적인" 디렉터리와 파일을 제공합니다.

• 파일 TTL 은 자동으로 파일 메타데이터 및 실제 파일 데이터를 만료시킵니다.

• Mount filer 는 FUSE 를 통해 로컬 디렉터리로 직접 파일을 읽기/쓰기를 수행합니다.

• Filer Store Replication 은 filer 메타데이터 스토어에 대한 HA 를 가능하게 합니다.

• Active-Active 복제는 비동기적 일방향 또는 양방향 클러스터 간 연속 복제를 가능하게 합니다.

• Amazon S3 호환 API 는 S3 툴링으로 파일을 액세스합니다.

• Hadoop 호환 파일 시스템은 Hadoop/Spark/Flink 등에서 파일을 액세스하거나 HBase 를 실행합니다.

• 비동기 클라우드 복제는 로컬 액세스가 매우 빠르고 Amazon S3, Google Cloud Storage, Azure, BackBlaze 로 백업됩니다.

• WebDAV 는 Mac 및 Windows 에서 매핑된 드라이브로 또는 모바일 장치에서 액세스합니다.

• AES256-GCM 암호화 스토리지는 암호화된 데이터를 안전하게 저장합니다.

• Super Large Files 는 수십 TB 의 대형 또는 초대형 파일을 저장합니다.

• Cloud Drive 는 클라우드 스토리지를 로컬 클러스터에 마운트하여 비동기 쓰기 백으로 빠른 읽기/쓰기를 위해 캐시합니다.

• Gateway to Remote Object Store 는 Cloud Drive 를 넘어 원격 객체 스토리지의 버킷 작업을 거울링합니다.

• S3 Table Buckets 는 Iceberg 테이블을 위한 전용 네임스페이스를 엄격한 레이아웃 유효성 검사로 노출합니다.

• 내장된 Iceberg REST Catalog 는 S3 엔드포인트와 함께 실행되며 외부 메타스토어는 필요 없습니다.

• Apache Spark, Trino, Dremio, DuckDB, RisingWave 와의 네이티브 통합 기능 제공.

• 자동화된 테이블 유지 관리: 컴팩션, 스냅샷 만료, 유실 파일 제거, 매니페스트 재작성.

• 표준 S3 버킷 정책 을 통해 버킷, 네임스페이스, 테이블 수준의 세밀한 IAM 권한 부여.

• Kubernetes CSI Driver 는 Container Storage Interface (CSI) 드라이버입니다.

• SeaweedFS Operator

기본적으로 마스터 노드는 9333 포트에서 실행되며, 볼륨 노드는 8080 포트에서 실행됩니다. 하나의 마스터 노드와 8080, 8081 포트에서 두 개의 볼륨 노드를 시작합니다. 이상적으로는 서로 다른 기계에서 시작해야 합니다. localhost 를 예제로 사용합니다.

SeaweedFS 는 HTTP REST 연산을 사용하여 읽기, 쓰기, 삭제합니다. 응답은 JSON 또는 JSONP 형식입니다.

> ./weed master

> weed volume -dir="/tmp/data1" -max=5 -master="localhost:9333" -port=8080 &
> weed volume -dir="/tmp/data2" -max=10 -master="localhost:9333" -port=8081 &

블로브 (blob), 또한 니들 (needle), 쉐이크 (chunk) 또는 잘못 이해된 파일로 불리기도 하지만, 사실은 바이트 배열입니다. 이름, MIME 타입, 생성 또는 업데이트 시간 등의 속성을 가질 수 있습니다. 기본적으로는 2 MB ~ 64 MB 정도의 상대적으로 작은 크기의 바이트 배열입니다. 크기는 고정되지 않습니다.

블로브를 업로드하려면 먼저 /dir/assign 에 HTTP POST, PUT, 또는 GET 요청을 보내 fid 와 볼륨 서버 URL 을 받습니다:

> curl http://localhost:9333/dir/assign
{"count":1,"fid":"3,01637037d6","url":"127.0.0.1:8080","publicUrl":"localhost:8080"}

두 번째로, 블로브 콘텐츠를 저장하려면 응답에서 url + '/' + fid 에 HTTP 멀티파트 POST 요청을 보냅니다:

> curl -F file=@/home/chris/myphoto.jpg http://127.0.0.1:8080/3,01637037d6
{"name":"myphoto.jpg","size":43234,"eTag":"1cc0118e"}

업데이트하려면 업데이트된 블로브 콘텐츠를 포함한 다른 POST 요청을 보냅니다.

삭제하려면 동일한 url + '/' + fid URL 에 HTTP DELETE 요청을 보냅니다:

> curl -X DELETE http://127.0.0.1:8080/3,01637037d6

이제 fid, 이 경우 3,01637037d6 를 데이터베이스 필드에 저장할 수 있습니다.

번호 3 은 볼륨 ID 를 나타냅니다. 쉼표 후에는 파일 키 (file key) 01 와 파일 쿠키 (file cookie) 637037d6 입니다.

볼륨 ID 는 부호 없는 32 비트 정수입니다. 파일 키는 부호 없는 64 비트 정수입니다. 파일 쿠키는 URL 추측을 방지하기 위한 부호 없는 32 비트 정수입니다.

파일 키와 파일 쿠키 모두 hex 로 코딩됩니다. <볼륨 ID, 파일 키, 파일 쿠키> 튜플을 자체 형식으로 저장하거나 단순히 fid 를 문자열로 저장할 수 있습니다.

문자열로 저장된 경우, 이론적으로는 8+1+16+8=33 바이트가 필요합니다. char(33) 이 충분하며, 실제로는 더 이상 필요하지 않습니다. 대부분의 사용자는 2^32 볼륨을 필요로 하지 않기 때문입니다.

공간이 정말 중요한 경우, 파일 ID 를 바이너리 형식으로 저장할 수 있습니다. 볼륨 ID 는 4 바이트 정수, 파일 키는 8 바이트 long 숫자, 파일 쿠키는 4 바이트 정수가 필요합니다. 따라서 16 바이트가 더 이상 충분합니다.

URL 을 렌더링하는 방법의 예입니다.
먼저 파일의 볼륨 ID 로 볼륨 서버의 URL 을 조회합니다:

> curl http://localhost:9333/dir/lookup?volumeId=3
{"volumeId":"3","locations":[{"publicUrl":"localhost:8080","url":"localhost:8080"}]}

대개 볼륨 서버가 많지 않고 볼륨이 자주 움직이지 않으므로, 대부분의 경우 결과를 캐시할 수 있습니다. 복제 유형에 따라 하나의 볼륨은 여러 복제 위치를 가질 수 있습니다. 읽기 위해 무작위로 하나를 선택하세요.

이제 공개 URL 을 가져와서 URL 을 렌더링하거나 URL 을 통해 직접 볼륨 서버에서 읽을 수 있습니다:

http://localhost:8080/3,01637037d6.jpg

여기서 파일 확장자 ".jpg" 를 추가합니다. 이는 선택 사항이며 클라이언트가 파일 콘텐츠 타입을 지정하는 방법 중 하나입니다.

더 나은 URL 을 원한다면 다음 대안 URL 형식을 사용할 수 있습니다:

http://localhost:8080/3/01637037d6/my_preferred_name.jpg
http://localhost:8080/3/01637037d6.jpg
http://localhost:8080/3,01637037d6.jpg
...

이미지의 축소 버전을 원한다면 일부 파라미터를 추가할 수 있습니다:

http://localhost:8080/3/01637037d6.jpg?height=200&width=200
http://localhost:8080/3/01637037d6.jpg?height=200&width=200&mode=fit
http://localhost:8080/3/01637037d6.jpg?height=200&width=200&mode=fill

SeaweedFS 는 볼륨 수준에서 복제 전략을 적용합니다. 따라서 blob id 를 가져올 때 복제 전략을 지정할 수 있습니다. 예를 들어:

curl http://localhost:9333/dir/assign?replication=001

복제 파라미터 옵션은 다음과 같습니다:

000: 복제 없음
001: 같은 랭크에서 한 번 복제
010: 다른 랭크에서 한 번 복제, 그러나 동일한 데이터 센터
...

더 많은 복제 세부 사항은 wiki 에서 찾을 수 있습니다.

마스터 서버를 시작할 때 기본 복제 전략을 설정할 수도 있습니다.

볼륨 서버는 특정 데이터 센터 이름으로 시작할 수 있습니다:

weed volume -dir=/tmp/1 -port=8080 -dataCenter=dc1
weed volume -dir=/tmp/2 -port=8081 -dataCenter=dc2

blob 키를 요청할 때, 선택적 "dataCenter" 파라미터는 할당된 볼륨을 특정 데이터 센터로 제한할 수 있습니다. 예를 들어, 이는 할당된 볼륨이 'dc1'으로 제한되어야 함을 지정합니다:

http://localhost:9333/dir/assign?dataCenter=dc1

• 단일 장애점 없음
• 자체 키로 삽입
• 큰 파일 분할
• 단순 이름 공간으로 컬렉션

일반적으로 분산 파일 시스템은 각 파일을 쉐이크로 나눕니다. 중앙 서버는 파일명 및 쉐이크의 매핑을 유지하며, 또한 각 쉐이크 서버가 가진 쉐이크를 유지합니다.

주요 단점은 중앙 서버가 많은 작은 파일을 효율적으로 처리할 수 없다는 점이며, 모든 읽기 요청이 중앙 마스터를 거쳐야 하므로 많은 동시 사용자에 대한 확장성이 잘 되지 않을 수 있습니다.

쉘웨어 FS 는 쉐이크를 관리하는 대신 마스터 서버에서 데이터 볼륨을 관리합니다. 각 데이터 볼륨의 크기는 32GB이며, 많은 blob 를 보유할 수 있습니다. 그리고 각 저장 노드는 많은 데이터 볼륨을 가질 수 있습니다. 따라서 마스터 노드는 볼륨에 대한 메타데이터만 저장해야 하며, 이는 상당히 작은 양의 데이터이며 일반적으로 안정적입니다.

실제 blob 메타데이터는 blob 볼륨, 오프셋 및 크기가 있으며, 각 볼륨 서버에서 각 볼륨에 저장됩니다. 각 볼륨 서버는 자신의 디스크에서 자체 blob 의 메타데이터만 관리하며, 각 blob 에 16 바이트만 있으면 모든 액세스는 메모리에서 메타데이터를 읽을 수 있으며 실제 파일 데이터를 읽기 위해 하나의 디스크 작업만 필요합니다.

비교를 위해, Linux 의 xfs 인덱스 구조체는 536 바이트입니다.

구조는 상당히 단순합니다. 실제 데이터는 저장 노드의 볼륨에 저장됩니다. 하나의 볼륨 서버는 여러 볼륨을 가질 수 있으며, 기본 인증으로 읽기 및 쓰기 액세스를 모두 지원할 수 있습니다.