SeaweedFS : stockage distribué haute performance pour objets et fichiers

SeaweedFS est un système de stockage distribué rapide capable de servir des milliards de fichiers avec un accès disque en O(1). Écrit en Go et distribué sous licence Apache 2.0, il fournit un stockage objet (API S3), un système de fichiers distribué (Filer) et un montage FUSE, le tout via un unique binaire weed. Ce guide vous accompagne dans le déploiement d’un cluster 3 nœuds avec master HA (Raft), volume servers, filer et S3 gateway — chaque commande a été testée sur un lab KVM réel.

Ce que vous allez apprendre

Architecture : comprendre les rôles master, volume server, filer et S3 gateway
Déploiement : installer un cluster 3 nœuds avec haute disponibilité (Raft)
API S3 : créer des buckets, uploader et télécharger des fichiers
Filer : utiliser l’interface fichiers HTTP avec hiérarchie de répertoires
Réplication : configurer la réplication inter-rack avec le modèle XYZ

Qu’est-ce que SeaweedFS ?

SeaweedFS est un système de stockage distribué inspiré du papier Haystack de Facebook. Son objectif principal : stocker et servir des milliards de petits fichiers (images, documents, logs) avec un accès disque en O(1) — une seule lecture disque par fichier, sans couche de métadonnées intermédiaire.

Analogie : si un système de fichiers classique est une bibliothèque où le bibliothécaire consulte un index puis cherche le livre, SeaweedFS est un entrepôt avec des numéros d’étagère : donnez le numéro, le fichier est récupéré directement sans recherche.

Ce qui distingue SeaweedFS

Caractéristique	Détail
Accès O(1)	Seulement 16 octets de métadonnées par blob, une seule lecture disque
Binaire unique	Un seul exécutable `weed` pour tous les composants
Multi-interface	API S3, Filer HTTP/gRPC, FUSE, WebDAV
Réplication flexible	Modèle XYZ (datacenter/rack/même rack)
Erasure Coding	Réduction d’espace pour données froides (10+4 par défaut)
Cloud tiering	Migration transparente vers S3/GCS/Azure pour données tièdes
Kubernetes	Driver CSI officiel pour stockage persistant

SeaweedFS vs alternatives

Critère	SeaweedFS	MinIO	Garage	Ceph
Cas d’usage principal	Blobs + fichiers	Stockage objet S3	S3 léger, géo-distribué	Stockage unifié
Langage	Go	Go	Rust	C++
Licence	Apache 2.0	AGPLv3	AGPLv3	LGPL
Interface fichiers	Filer + FUSE	Non	Non	CephFS
API S3	Oui (gateway)	Natif	Oui	Oui (RGW)
Complexité	Moyenne	Simple	Simple	Élevée
RAM minimum	~128 Mo/composant	~512 Mo	~256 Mo	~4 Go/OSD

Architecture et concepts clés

SeaweedFS repose sur 4 composants qui peuvent tourner ensemble (mode all-in-one) ou séparément (production).

Architecture SeaweedFS : master cluster Raft, volume servers, filer et S3 gateway

Master Server (port 9333)

Le master gère la topologie du cluster : il sait quels volume servers sont disponibles, dans quels datacenters et racks. En cluster de 3, les masters utilisent le protocole Raft pour élire un leader et assurer la haute disponibilité.

Rôles du master :

Assigner des identifiants de fichiers (file ID) via /dir/assign
Localiser les volumes via les lookups
Gérer la réplication et l’équilibrage des volumes
Port gRPC : 19333 (port HTTP + 10000)

Volume Server (port 8080)

Le volume server stocke les données réelles. Chaque volume server gère plusieurs volumes (fichiers .dat de 30 Go par défaut). Les blobs sont écrits séquentiellement dans ces volumes, ce qui garantit l’accès O(1).

Caractéristiques :

16 octets de métadonnées par fichier (cookie, needle ID, taille)
Pas d’index en mémoire pour les lookups — accès direct via offset
Compaction automatique pour récupérer l’espace des fichiers supprimés

Filer (port 8888)

Le filer ajoute une couche système de fichiers au-dessus des volume servers. Il transforme les file IDs en chemins lisibles (/documents/rapport.pdf). Les métadonnées du filer sont stockées dans un backend configurable : LevelDB (défaut), MySQL, PostgreSQL, Redis, etcd, etc.

Fonctionnalités :

API HTTP : upload, download, listing de répertoires
FUSE : montage comme un système de fichiers local
WebDAV : accès depuis n’importe quel client WebDAV
Notifications : événements en temps réel (création, modification, suppression)

S3 Gateway (port 8333)

Le S3 gateway expose une API compatible AWS S3 au-dessus du filer. Les buckets S3 correspondent à des répertoires dans le filer (/buckets/nom-du-bucket/).

Modèle de réplication XYZ

SeaweedFS utilise un format à 3 chiffres XYZ pour définir la réplication :

Chiffre	Signification	Portée
X	Copies sur d’autres datacenters	Inter-DC
Y	Copies sur d’autres racks (même DC)	Inter-rack
Z	Copies sur le même rack	Intra-rack

Exemples concrets :

Valeur	Copies totales	Description
`000`	1	Pas de réplication (développement)
`001`	2	1 copie sur le même rack
`010`	2	1 copie sur un rack différent du même DC
`100`	2	1 copie sur un datacenter différent
`200`	3	2 copies sur 2 datacenters différents

Ports réseau

Service	Port HTTP	Port gRPC	Usage
Master	9333	19333	Topologie, assignation
Volume	8080	18080	Stockage données
Filer	8888	18888	Système de fichiers
S3 Gateway	8333	18333	API S3 compatible

Lab : déployer un cluster SeaweedFS 3 nœuds

Prérequis

3 machines (physiques ou virtuelles) sous Ubuntu 24.04 avec 2 Go de RAM minimum
Accès SSH entre les nœuds
AWS CLI v2 installé sur votre poste pour tester l’API S3

Créer les VMs avec KVM

Créez un fichier cloud-init.yaml pour provisionner les 3 VMs :

#cloud-config
hostname: seaweedfs-node
users:
  - name: bob
    groups: sudo
    shell: /bin/bash
    sudo: ALL=(ALL) NOPASSWD:ALL
    ssh_authorized_keys:
      - ssh-ed25519 VOTRE_CLE_PUBLIQUE
packages:
  - chrony
  - wget
runcmd:
  - cd /tmp && wget -q https://github.com/seaweedfs/seaweedfs/releases/latest/download/linux_amd64.tar.gz && tar -xzf linux_amd64.tar.gz && mv weed /usr/local/bin/weed && chmod +x /usr/local/bin/weed
  - mkdir -p /var/lib/seaweedfs/master /var/lib/seaweedfs/volume /var/lib/seaweedfs/filer

Créez les 3 VMs :

for i in 1 2 3; do
  sudo virt-install \
    --name seaweed${i} \
    --ram 2048 --vcpus 1 \
    --disk path=/var/lib/libvirt/images/seaweed${i}.qcow2,size=15,backing_store=/var/lib/libvirt/images/ubuntu-24.04-cloud.img,format=qcow2 \
    --os-variant ubuntu24.04 \
    --cloud-init user-data=cloud-init.yaml \
    --network bridge=virbr0 \
    --graphics none --noautoconsole --import
done

Vérification : attendez 2 minutes puis récupérez les IP :

sudo virsh net-dhcp-leases default

Dans notre lab, les IP sont :

Nœud	IP	Rôle
seaweed1	192.168.122.187	Master + Volume + Filer + S3
seaweed2	192.168.122.159	Master + Volume
seaweed3	192.168.122.144	Master + Volume

Configurez les hostnames et /etc/hosts sur chaque nœud :

# Sur chaque nœud, ajouter les entrées
sudo tee -a /etc/hosts << EOF
192.168.122.187 seaweed1
192.168.122.159 seaweed2
192.168.122.144 seaweed3
EOF

Vérification : confirmez l’installation du binaire sur chaque nœud :

ssh bob@192.168.122.187 "weed version"
# version 30GB 4.13 linux amd64

Mode all-in-one (développement)

Pour tester rapidement, SeaweedFS peut démarrer tous les composants avec une seule commande :

weed server \
  -dir=/var/lib/seaweedfs/volume \
  -master.port=9333 \
  -volume.port=8080 \
  -ip=192.168.122.187 \
  -filer \
  -s3

Cette commande lance simultanément le master (9333), le volume server (8080), le filer (8888) et le S3 gateway (8333).

Vérification :

curl -s http://192.168.122.187:9333/cluster/status
# {"IsLeader":true,"Leader":"192.168.122.187:9333.19333"}

Déploiement multi-nœuds (production)

Démarrer les 3 masters (cluster Raft)

Lancez un master sur chaque nœud avec la liste des pairs :

# Sur seaweed1
weed master \
  -mdir=/var/lib/seaweedfs/master \
  -ip=192.168.122.187 \
  -port=9333 \
  -defaultReplication=001 \
  -peers=192.168.122.187:9333,192.168.122.159:9333,192.168.122.144:9333

# Sur seaweed2
weed master \
  -mdir=/var/lib/seaweedfs/master \
  -ip=192.168.122.159 \
  -port=9333 \
  -defaultReplication=001 \
  -peers=192.168.122.187:9333,192.168.122.159:9333,192.168.122.144:9333

# Sur seaweed3
weed master \
  -mdir=/var/lib/seaweedfs/master \
  -ip=192.168.122.144 \
  -port=9333 \
  -defaultReplication=001 \
  -peers=192.168.122.187:9333,192.168.122.159:9333,192.168.122.144:9333

Vérification : après ~10 secondes, un leader est élu via Raft :

curl -s http://192.168.122.144:9333/cluster/status
# {
#   "IsLeader": true,
#   "Leader": "192.168.122.144:9333.19333",
#   "Peers": [
#     "192.168.122.159:9333.19333",
#     "192.168.122.187:9333.19333"
#   ]
# }

Démarrer les volume servers

Lancez un volume server sur chaque nœud, dans des racks différents pour la réplication :

# Sur seaweed1
weed volume \
  -dir=/var/lib/seaweedfs/volume \
  -ip=192.168.122.187 -port=8080 \
  -mserver=192.168.122.187:9333,192.168.122.159:9333,192.168.122.144:9333 \
  -max=10 -dataCenter=dc1 -rack=rack1

# Sur seaweed2
weed volume \
  -dir=/var/lib/seaweedfs/volume \
  -ip=192.168.122.159 -port=8080 \
  -mserver=192.168.122.187:9333,192.168.122.159:9333,192.168.122.144:9333 \
  -max=10 -dataCenter=dc1 -rack=rack2

# Sur seaweed3
weed volume \
  -dir=/var/lib/seaweedfs/volume \
  -ip=192.168.122.144 -port=8080 \
  -mserver=192.168.122.187:9333,192.168.122.159:9333,192.168.122.144:9333 \
  -max=10 -dataCenter=dc1 -rack=rack3

Vérification : la topologie montre les 3 volume servers :

curl -s http://192.168.122.144:9333/vol/status | python3 -m json.tool
# "DataCenters": {
#   "dc1": {
#     "rack1": { "192.168.122.187:8080": [...] },
#     "rack2": { "192.168.122.159:8080": [...] },
#     "rack3": { "192.168.122.144:8080": [...] }
#   }
# }

Démarrer le filer

Le filer s’installe sur un ou plusieurs nœuds (ici seaweed1) :

# Sur seaweed1
weed filer \
  -ip=192.168.122.187 \
  -port=8888 \
  -master=192.168.122.187:9333,192.168.122.159:9333,192.168.122.144:9333

Vérification :

curl -s -H "Accept: application/json" http://192.168.122.187:8888/ | python3 -m json.tool
# {"Path":"/","Entries":[...],"EmptyFolder":false}

Démarrer le S3 gateway

Créez d’abord le fichier de credentials S3 :

{
  "identities": [
    {
      "name": "admin",
      "credentials": [
        {
          "accessKey": "seaweedadmin",
          "secretKey": "seaweedadmin123"
        }
      ],
      "actions": ["Admin", "Read", "Write", "List", "Tagging", "Lock"]
    },
    {
      "name": "readonly",
      "credentials": [
        {
          "accessKey": "seaweedread",
          "secretKey": "seaweedread123"
        }
      ],
      "actions": ["Read", "List"]
    }
  ]
}

Enregistrez-le dans /etc/seaweedfs-s3.json, puis lancez le S3 gateway :

weed s3 \
  -port=8333 \
  -filer=192.168.122.187:8888 \
  -config=/etc/seaweedfs-s3.json

Vérification :

curl -s http://192.168.122.187:8333/ | head -5
# <?xml version="1.0" encoding="UTF-8"?>

Services systemd (production)

Pour un déploiement persistant, créez des fichiers de service systemd.

[Unit]
Description=SeaweedFS Master
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=root
ExecStart=/usr/local/bin/weed master \
  -mdir=/var/lib/seaweedfs/master \
  -ip=ADRESSE_IP_DU_NOEUD \
  -port=9333 \
  -defaultReplication=001 \
  -peers=IP1:9333,IP2:9333,IP3:9333
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

[Unit]
Description=SeaweedFS Volume Server
After=seaweedfs-master.service
Wants=seaweedfs-master.service

[Service]
Type=simple
User=root
ExecStart=/usr/local/bin/weed volume \
  -dir=/var/lib/seaweedfs/volume \
  -ip=ADRESSE_IP_DU_NOEUD \
  -port=8080 \
  -mserver=IP1:9333,IP2:9333,IP3:9333 \
  -max=10 \
  -dataCenter=dc1 \
  -rack=rackN
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

[Unit]
Description=SeaweedFS Filer
After=seaweedfs-master.service
Wants=seaweedfs-master.service

[Service]
Type=simple
User=root
ExecStart=/usr/local/bin/weed filer \
  -ip=ADRESSE_IP_DU_NOEUD \
  -port=8888 \
  -master=IP1:9333,IP2:9333,IP3:9333
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

[Unit]
Description=SeaweedFS S3 Gateway
After=seaweedfs-filer.service
Wants=seaweedfs-filer.service

[Service]
Type=simple
User=root
ExecStart=/usr/local/bin/weed s3 \
  -port=8333 \
  -filer=ADRESSE_IP_DU_NOEUD:8888 \
  -config=/etc/seaweedfs-s3.json
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Utiliser l’API native (blob store)

L’API native de SeaweedFS fonctionne en 2 étapes : assigner un identifiant, puis uploader vers le volume server.

Assigner et uploader

# Étape 1 : demander un file ID au master
curl -s http://192.168.122.144:9333/dir/assign
# {"fid":"4,031c0dfc08","url":"192.168.122.187:8080","publicUrl":"192.168.122.187:8080","count":1}

# Étape 2 : uploader le fichier sur le volume server
echo "Hello SeaweedFS!" > /tmp/test.txt
curl -F file=@/tmp/test.txt http://192.168.122.187:8080/4,031c0dfc08
# {"name":"test.txt","size":17,"eTag":"c76e4f38","mime":"text/plain"}

Télécharger et supprimer

# Télécharger via le volume server
curl http://192.168.122.187:8080/4,031c0dfc08
# Hello SeaweedFS!

# Supprimer
curl -X DELETE http://192.168.122.187:8080/4,031c0dfc08
# {"size":51}

Assigner avec réplication

# Réplication inter-rack (010)
curl -s "http://192.168.122.144:9333/dir/assign?replication=010"
# Le master choisit un volume répliqué sur un rack différent

Utiliser le Filer

Le filer expose une interface fichiers avec chemins hiérarchiques via HTTP.

Upload et listing

# Uploader un fichier dans /documents/
curl -F file=@/tmp/rapport.txt http://192.168.122.187:8888/documents/
# {"name":"rapport.txt","size":18}

# Lister le contenu (HTML par défaut)
curl http://192.168.122.187:8888/documents/

# Lister en JSON
curl -H "Accept: application/json" http://192.168.122.187:8888/documents/
# {"Path":"/documents","Entries":[{"FullPath":"/documents/rapport.txt",...}]}

Télécharger un fichier

curl http://192.168.122.187:8888/documents/rapport.txt
# (contenu du fichier)

Utiliser l’API S3

Configurer AWS CLI

export AWS_ACCESS_KEY_ID=seaweedadmin
export AWS_SECRET_ACCESS_KEY=seaweedadmin123
export AWS_DEFAULT_REGION=us-east-1

Opérations S3

# Créer un bucket
aws --endpoint-url http://192.168.122.187:8333 s3 mb s3://mon-bucket
# make_bucket: mon-bucket

# Lister les buckets
aws --endpoint-url http://192.168.122.187:8333 s3 ls
# 2026-03-01 10:57:44 mon-bucket

# Uploader un fichier
echo "Fichier via S3" > /tmp/s3-test.txt
aws --endpoint-url http://192.168.122.187:8333 s3 cp /tmp/s3-test.txt s3://mon-bucket/documents/
# upload: ./s3-test.txt to s3://mon-bucket/documents/s3-test.txt

# Uploader un gros fichier (multipart automatique)
dd if=/dev/urandom of=/tmp/bigfile.bin bs=1M count=10 2>/dev/null
aws --endpoint-url http://192.168.122.187:8333 s3 cp /tmp/bigfile.bin s3://mon-bucket/data/
# upload: ./bigfile.bin to s3://mon-bucket/data/bigfile.bin

# Lister le contenu récursivement
aws --endpoint-url http://192.168.122.187:8333 s3 ls s3://mon-bucket --recursive
# 2026-03-01 10:58:00   10485760 data/bigfile.bin
# 2026-03-01 10:57:59         15 documents/s3-test.txt

# Télécharger
aws --endpoint-url http://192.168.122.187:8333 s3 cp s3://mon-bucket/documents/s3-test.txt /tmp/download.txt
cat /tmp/download.txt
# Fichier via S3

# Générer une URL présignée (valide 1 heure)
aws --endpoint-url http://192.168.122.187:8333 s3 presign s3://mon-bucket/documents/s3-test.txt --expires-in 3600

Supprimer des objets et buckets

# Supprimer un objet
aws --endpoint-url http://192.168.122.187:8333 s3 rm s3://mon-bucket/data/bigfile.bin

# Supprimer un bucket (doit être vide)
aws --endpoint-url http://192.168.122.187:8333 s3 rb s3://mon-bucket

# Forcer la suppression (bucket + contenu)
aws --endpoint-url http://192.168.122.187:8333 s3 rb s3://mon-bucket --force

Commandes essentielles

Cluster et topologie

# Statut du cluster (identifier le leader)
curl -s http://IP_MASTER:9333/cluster/status

# Statut des volumes
curl -s http://IP_MASTER:9333/vol/status

# Version
weed version

Administration avec weed shell

SeaweedFS fournit un shell interactif pour l’administration :

weed shell -master=192.168.122.144:9333

Commandes utiles dans le shell :

# Lister les volumes
volume.list

# Vérifier la santé du cluster
cluster.check

# Équilibrer les volumes
volume.balance

# Compacter un volume (récupérer l'espace)
volume.vacuum

# Forcer la réplication d'un volume
volume.fix.replication

Erasure Coding

Pour les données froides, l’Erasure Coding (EC) remplace la réplication par un codage 10+4, réduisant l’espace de 300 % (réplication 3x) à 140 % :

# Dans weed shell
ec.encode -collection=archive -fullPercent=95
ec.rebuild -force

Dépannage

Problèmes courants et solutions

Symptôme	Cause probable	Solution
`no leader` lors du démarrage	Raft n’a pas convergé	Vérifier que les 3 masters sont démarrés et joignables (port 9333 et 19333)
`no writable volumes`	Volumes non assignés ou max atteint	Augmenter `-max` sur les volume servers ou compacter avec `volume.vacuum`
`connection refused` sur 8888	Filer non démarré	Lancer `weed filer` avec les bons `-master`
Upload S3 échoue avec `InvalidAccessKeyId`	Credentials S3 non configurés	Vérifier `-config=/etc/seaweedfs-s3.json` ou utiliser les flags env `AWS_ACCESS_KEY_ID`
Bucket “already exists”	Répertoire préexistant dans le filer	Les buckets S3 correspondent à `/buckets/nom/` dans le filer
`-ip` invalide pour `weed s3`	Le flag correct est `-ip.bind`	Utiliser `weed s3 -ip.bind=IP` au lieu de `-ip=IP`

Commandes de diagnostic

# Vérifier les processus
ps aux | grep weed

# Vérifier les ports ouverts
ss -tlnp | grep -E '9333|8080|8888|8333'

# Consulter les logs master
journalctl -u seaweedfs-master -f

# Topologie complète avec volumes
curl -s http://IP_MASTER:9333/vol/status | python3 -m json.tool

# Vérifier le leader Raft
for ip in IP1 IP2 IP3; do
  echo -n "$ip: "
  curl -s http://${ip}:9333/cluster/status
  echo ""
done

Sécurité

Credentials S3

Créez des identités avec le minimum de droits nécessaires :

{
  "identities": [
    {
      "name": "app-backend",
      "credentials": [
        {
          "accessKey": "app-key-xxxxx",
          "secretKey": "secret-xxxxx"
        }
      ],
      "actions": ["Read:mon-bucket", "Write:mon-bucket", "List:mon-bucket"]
    }
  ]
}

Les actions peuvent être restreintes à un bucket spécifique avec la syntaxe Action:bucket.

Réseau

Isolez le réseau interne : les ports 9333 et 8080 ne doivent pas être exposés sur Internet
Exposez uniquement le S3 gateway (8333) derrière un reverse proxy avec TLS
TLS natif : SeaweedFS supporte les certificats via -cert.file et -key.file

Chiffrement

# Volume server avec chiffrement au repos
weed volume -dir=/var/lib/seaweedfs/volume -encryptVolumeData

Bonnes pratiques

Dimensionnement

Masters : 3 instances minimum pour le quorum Raft (nombre impair)
Volume servers : au moins autant que le facteur de réplication
Filer : 1 ou 2 instances (avec un backend de métadonnées externe pour la HA)
RAM : 128 Mo par composant minimum, 512 Mo recommandé

Organisation

Un rack par nœud physique : pour que la réplication 010 protège contre la perte d’un serveur
Datacenters : utilisez -dataCenter pour identifier les sites géographiques
Collections : groupez les données par type (-collection=images, -collection=logs) pour faciliter la maintenance

Performance

SSD pour les masters : les écritures Raft bénéficient de la faible latence
HDD pour les volume servers : l’accès séquentiel exploite bien les disques mécaniques
-max : définissez le nombre maximum de volumes par serveur selon l’espace disque disponible (1 volume = 30 Go par défaut)
Compaction : exécutez volume.vacuum régulièrement pour récupérer l’espace des fichiers supprimés

À retenir

SeaweedFS est un stockage distribué haute performance avec accès O(1) par fichier, idéal pour les blobs et petits fichiers
Le binaire unique weed exécute tous les composants : master, volume, filer, S3
Les masters Raft (3 minimum) assurent la haute disponibilité ; les volume servers stockent les données réelles
Le filer ajoute une couche système de fichiers avec hiérarchie, FUSE et WebDAV
La réplication XYZ (000, 001, 010, 100, 200) contrôle finement la distribution des copies
L’API S3 compatible AWS permet d’utiliser aws s3, s3cmd et tout SDK S3 existant
Pour la production : déployez chaque composant séparément, utilisez -dataCenter et -rack, et configurez des services systemd
L’Erasure Coding (10+4) réduit considérablement l’espace pour les données froides par rapport à la réplication 3x

Prochaines étapes

Garage : stockage S3 léger Alternative Rust légère pour le stockage objet géo-distribué

Ceph : stockage unifié Stockage distribué block, objet et fichiers avec CRUSH

GlusterFS : système de fichiers distribué Agrégation de stockage en réseau avec réplication et dispersion

MinIO : stockage objet S3 Serveur S3 haute performance pour les architectures cloud-native

Ressources

Site officiel : github.com/seaweedfs/seaweedfs
Documentation : github.com/seaweedfs/seaweedfs/wiki
API S3 compatibility : github.com/seaweedfs/seaweedfs/wiki/Amazon-S3-API
Haystack Paper (Facebook) : usenix.org/legacy/event/osdi10/tech/full_papers/Beaver.pdf