Seaweedfs

SeaweedFS

This skill is a practical router for deploying and operating SeaweedFS from the upstream repository and wiki.

Prefer production guidance from multi-component setups over weed mini shortcuts.

Quick Navigation

When to Use

• Planning a SeaweedFS deployment
• Running weed components in development or production
• Designing filer, S3, or cloud-tier topologies
• Choosing metadata stores and replication patterns
• Hardening SeaweedFS for public or multi-tenant use
• Operating backups, metrics, and cluster repair workflows

Core Mental Model

• SeaweedFS separates volume management from file and object access paths.
• The filer layer adds directories, metadata stores, and higher-level protocols.
• S3, WebDAV, FUSE, and other interfaces are front doors on top of the same storage services.
• Production deployments should document topology, credentials, persistence, monitoring, and recovery paths explicitly.

Release Highlights (4.25)

• Security/admin path: 4.24-4.25 tightens admin auth on destructive/admin endpoints and fixes Admin UI behavior under security.toml by attaching admin-signed auth on filer IAM gRPC calls.
• Erasure coding / multi-disk ops: the release line fixes several EC planner/recovery cases across multi-disk and cross-server layouts, including stale-shard cleanup and safer source-volume deletion.
• S3/IAM hardening: IAM users without policies are now denied instead of implicitly over-permitted, while OIDC/web-identity and audit surfaces continue to mature.

Release Highlights (4.26 -> 4.28)

• Erasure coding / multi-disk ops: EC planning now packs shards across disks more reliably, includes disk_id in execution planning, and can rebuild lost .ecx / .vif metadata from local shards during recovery.
• Integrity checks: scrubbing/fsck paths now account for zero-sized volumes instead of silently skipping them, which matters for sparse or recently created topologies.
• Filer backend reliability: Redis3 avoids a skiplist-end panic path, and SQL-based filer stores no longer force-disable idle connection pooling.
• S3 audit trail: requester identity is populated more consistently for GET/HEAD/IAM operations, improving compliance and incident triage.
• HA heartbeat path: masters now accept volume-server ping targets on follower replicas, which improves failover visibility in multi-master deployments.

Release Highlights (4.31 -> 4.33)

• S3 versioning/IAM: atomic versioned PutObject commits, proper NoSuchVersion errors, latest-pointer repair and recovery, suspended-versioning delete handling, managed IAM policy versions, and bucket read-only quota enforcement; 4.33 also fixes HTTP-date conditionals, checksum trailer headers, and empty v4 signed header names.
• Erasure coding integrity: per-shard checksum sidecars for bitrot detection (4.31), even shard spreading across machines with co-located servers treated as a single fault domain and pre-deletion shard-landing verification (4.32), and guards preventing EC shards from different encode runs mixing or leaving phantom .dat on restart (4.33).
• Volume server: fixes maxVolumeCount dead zone on auto-sized disks, keeps volumes writable after deletion-tail compaction, resolves EC data-shard count from .vif on reboot (4.31), and adds CheckDisk disk-health detection (4.32).
• Filer scalability: bounded BFS-metadata memory and byte-lexicographic S3 list order (4.31), streamed metadata-subscription log files (4.32), and object-size distribution metrics, mount-reconnect OOM fixes, per-chunk replay, a bounded flush queue, and Elasticsearch 8 (elastic8) support (4.33).
• Admin/worker: lane-aware scheduler pruning, -dataDir defaulting for persisted state and in-flight task reload on startup (4.32), plus full cluster volume list JSON export (4.33).
• Rust volume server: bounded request body / stored-content expansion to prevent OOM under load (4.31); stops EC-shard-deletion phantom .dat on restart (4.33).

Release Highlights (4.29 -> 4.30)

• S3 write/auth path: object writes move toward filer-side owner routing and ObjectTransaction batches, reducing distributed-lock pressure; 4.30 also tightens path traversal rejection, ownership-control validation, MetadataDirective=REPLACE, and JWT handling for unsigned-streaming uploads.
• FUSE and filer coordination: POSIX advisory locks are now routed through filer ownership under -dlm, with session leases, keepalive, ring-change cooling, and writeback-cache crash fixes for cross-mount write workloads.
• Erasure coding and volume repair: EC placement uses the shared ecbalancer.Place path and placement snapshots, while 4.30 improves credible-replica selection, empty-stub cleanup, .vif preservation, writable-volume notification after vacuum, and shell safety around stuck read-only volumes and merge verification.
• Operations surfaces: admin exposes Prometheus metrics, and S3/IAM/volume/filer/master processes add /healthz and /readyz probes for orchestration checks.
• Filer, sync, and remote sinks: Redis2 now applies keyPrefix in KV methods, Postgres filer writes default to ON CONFLICT upsert, dropped filers are pruned from discovery, and sync/remote-storage paths preserve chunk size, manifest, offset, and MIME metadata more reliably.

Release Highlights (4.20)

• S3/IAM: embedded IAM flows gained ListUserPolicies, group inline policy actions, safer user-policy round trips, and bucket-scoped cleanup on DeleteBucket.
• Mount/FUSE: weed mount adds -dlm for cross-mount write coordination and improves POSIX metadata behavior, nlink accounting, and filer RPC efficiency.
• Master placement: volume assignment is more size-aware, readonly transitions drain pending size first, and a topology bug that could cause endless growth in some DC/rack layouts was fixed.
• Filer reliability: PgBouncer/Postgres compatibility improved, graceful shutdown corruption was fixed, and redundant filer disk reads that caused memory/CPU regressions were removed.
• Ops surfaces: weed shell gained group-management helpers, S3 user provisioning handles existing users more safely, and master/volume now export start_time_seconds metrics.

Prohibitions

• Do not use weed mini for production.
• Do not treat single-binary defaults as production-safe configuration.
• Do not expose S3 or filer endpoints publicly before reviewing auth, TLS, and network boundaries.
• Do not choose a filer store without validating HA, scaling, and backup properties.
• Do not design backup or replication flows without restore validation.

Links

• Documentation
• Releases
• GitHub
• Docker Hub

SeaweedFS Plan

Progress tracking for documentation ingestion.

Base Information

• Skill name: seaweedfs
• Upstream repository: https://github.com/seaweedfs/seaweedfs
• Primary documentation entry: https://github.com/seaweedfs/seaweedfs/wiki/Getting-Started
• Upstream release tracked for frontmatter: 4.17 (2026-03-11)
• Goal: produce an operator-focused SeaweedFS skill with concise references and a short router SKILL.md
• Source constraints: use upstream repository and wiki only; skip low-value policy/legal pages
• Exclusions from queue: deprecated replication pages, changelog/policy/compliance pages that do not improve operator guidance

Initialization

• [x] Visit the upstream repository root
• [x] Visit the Getting Started wiki page
• [x] Create plan.md
• [x] Create base SKILL.md
• [x] Create references/

Queue

Introduction

• [x] Getting Started
• [x] Quick Start with weed mini
• [x] Components
• [x] Production Setup
• [x] Benchmarks
• [x] FAQ
• [x] Applications

API

• [x] Master Server API
• [x] Volume Server API
• [x] Filer Server API
• [x] Client Libraries
• [x] SeaweedFS Java Client

Configuration

• [x] Replication
• [x] Store file with a Time To Live
• [x] Failover Master Server
• [x] Erasure Coding for warm storage
• [x] Server Startup via Systemd
• [x] Environment Variables

Filer

• [x] Filer Setup
• [x] Directories and Files
• [x] File Operations Quick Reference
• [x] Data Structure for Large Files
• [x] Filer Data Encryption
• [x] Filer Commands and Operations
• [x] Filer JWT Use
• [x] TUS Resumable Uploads

Filer Stores

• [x] Filer Stores
• [x] Filer Cassandra Setup
• [x] Filer Redis Setup
• [x] Super Large Directories
• [x] Path-Specific Filer Store
• [x] Choosing a Filer Store
• [x] Customize Filer Store

Management

• [ ] Admin UI
• [ ] Worker
• [ ] Plugin Worker Scheduling

Cloud Drive

• [x] Cloud Drive Benefits
• [ ] Cloud Drive Architecture
• [x] Configure Remote Storage
• [x] Mount Remote Storage
• [x] Cache Remote Storage
• [ ] Cloud Drive Quick Setup
• [ ] Gateway to Remote Object Storage

AWS S3 API

• [x] Amazon S3 API
• [ ] Supported APIs vs Minio
• [ ] S3 Conditional Operations
• [ ] S3 CORS
• [ ] S3 Object Lock and Retention
• [ ] S3 Object Versioning
• [ ] S3 API Benchmark
• [ ] S3 API FAQ
• [ ] S3 Bucket Quota
• [ ] S3 Rate Limiting
• [ ] S3 API Audit log
• [ ] S3 Nginx Proxy
• [ ] Docker Compose for S3

Advanced Filer Configurations

• [ ] Migrate to Filer Store
• [ ] Add New Filer Store
• [ ] Filer Store Replication
• [ ] Filer Active Active cross cluster continuous synchronization
• [ ] Filer as a Key-Large-Value Store
• [ ] Path Specific Configuration
• [ ] Filer Change Data Capture

S3 Table Bucket

• [ ] S3 Table Bucket
• [ ] SeaweedFS Iceberg Catalog
• [ ] Iceberg Table Maintenance
• [ ] S3 Tables Security

S3 Authentication & IAM

• [x] S3 Configuration
• [x] S3 Credentials
• [x] OIDC Integration
• [ ] S3 Policy Variables
• [ ] S3 Bucket Policies
• [ ] Amazon IAM API
• [ ] AWS IAM CLI

Server-Side Encryption

• [x] Server-Side Encryption
• [x] Server-Side Encryption SSE-KMS
• [x] Server-Side Encryption SSE-C

S3 Client Tools

• [x] AWS CLI with SeaweedFS
• [ ] s3cmd with SeaweedFS
• [x] rclone with SeaweedFS
• [x] restic with SeaweedFS
• [ ] nodejs with Seaweed S3

Replication and Backup

• [x] Async Backup
• [x] Async Filer Metadata Backup
• [ ] Kubernetes Backups and Recovery with K8up

Metadata Change Events

• [ ] Filer Metadata Events
• [ ] Filer Notification Webhook

Messaging

• [ ] Structured Data Lake with SMQ and SQL
• [ ] Seaweed Message Queue
• [ ] SQL Queries on Message Queue
• [ ] SQL Quick Reference
• [ ] PostgreSQL-compatible Server weed db
• [ ] Pub-Sub to SMQ to SQL
• [ ] Kafka to Kafka Gateway to SMQ to SQL

Use Cases

• [ ] Use Cases
• [ ] Actual Users

Operations

• [x] System Metrics
• [x] weed shell
• [ ] Data Backup
• [ ] Deployment to Kubernetes and Minikube

Advanced

• [ ] Large File Handling
• [ ] Optimization
• [ ] Optimization for Many Small Buckets
• [ ] Volume Management
• [ ] Tiered Storage
• [ ] Cloud Tier
• [ ] Cloud Monitoring
• [ ] Load Command Line Options from a file
• [ ] SRV Service Discovery
• [ ] Volume Files Structure

Security

• [x] Security Overview
• [x] Security Configuration
• [ ] Cryptography and FIPS Compliance
• [ ] Run Blob Storage on Public Internet

Misc Use Case Examples

• [ ] UrBackup with SeaweedFS
• [ ] Docker Image Registry with SeaweedFS
• [ ] SeaweedFS in Docker Swarm
• [ ] Words from SeaweedFS Users
• [ ] Independent Benchmarks
• [ ] Hardware

Notes

• Deprecated pages intentionally skipped: Async Replication to another Filer, Async Replication to Cloud.
• Process rule: ingest exactly one queue page, update references immediately, mark it complete, then move on.

API Surfaces

Sources:

• https://github.com/seaweedfs/seaweedfs/wiki/Master-Server-API
• https://github.com/seaweedfs/seaweedfs/wiki/Volume-Server-API
• https://github.com/seaweedfs/seaweedfs/wiki/Filer-Server-API
• https://github.com/seaweedfs/seaweedfs/wiki/Client-Libraries
• https://github.com/seaweedfs/seaweedfs/wiki/SeaweedFS-Java-Client

Master Server API

What this page is about

• It documents the master HTTP endpoints for id assignment, lookup, volume growth, collection deletion, health, and topology status.
• It explains how write placement, vacuum triggering, and writable-volume inventory are exposed operationally.
• It shows that the master API is the control-plane surface for capacity and placement decisions.

Actionable takeaways

• Use dir/assign when clients or higher-level services need file ids with explicit placement constraints such as replication, collection, rack, TTL, or disk label.
• Reserve batches of file ids with count only when the client understands the suffix format (_1, _2, etc.) and can consume them safely.
• Use dir/lookup for current volume locations and for JWT-bearing file-specific lookups when update/delete authorization flows need them.
• Inspect dir/status and vol/status to confirm writable capacity, topology spread, disk tags, and actual volume state before changing placement policy.
• Pre-grow writable capacity with vol/grow ahead of bucket launches, TTL changes, or new replication classes so writes do not stall on empty pools.
• Trigger vol/vacuum manually only when you understand the compaction cost; it rewrites live data and swaps volume files rather than reclaiming space instantly.
• Use cluster/status and cluster/healthz for control-plane checks in load balancers, orchestrators, and readiness probes.
• Delete a collection with col/delete only when the lifecycle really intends to remove all corresponding volumes.
• Prefer pretty=y only for human inspection; keep machine integrations tolerant of compact JSON.

Gotchas / prohibitions

• Do not treat master APIs as free of side effects; vol/grow, vol/vacuum, and col/delete materially change cluster state.
• Do not trigger vacuum aggressively on busy clusters without understanding IO impact and readonly transitions during compaction.
• Do not assume write placement will work unless matching writable volumes exist for the exact <collection, replication, ttl, disk> combination.
• Do not forget that disk labels and topology selectors narrow the eligible placement pool.

How to apply in a real repo

• Separate read-only inspection endpoints from mutating admin endpoints in automation.
• Put dir/status, vol/status, cluster/status, and cluster/healthz into diagnostics and health dashboards.
• Add guarded runbooks for vol/grow, vol/vacuum, and col/delete with approval steps and expected blast radius.

Volume Server API

What this page is about

• It documents the data-plane HTTP interface for reading, writing, deleting, and inspecting file ids on volume servers.
• It includes practical request headers for authorization, conditional reads, gzip, ranges, and metadata.
• It exposes health and status endpoints suitable for orchestration and diagnostics.

Actionable takeaways

• Treat direct volume URLs as the low-level object path for GET, HEAD, PUT/POST, and DELETE by file id.
• Require JWT authorization on direct read or write flows when security is enabled; the page documents bearer tokens issued by master.
• Use HTTP range requests and conditional headers (If-Modified-Since, If-None-Match) for efficient client downloads and cache validation.
• Use image resize/crop query parameters only when that server-side transformation behavior is intentionally part of the application contract.
• Send Content-MD5 for integrity-sensitive uploads and Seaweed-* headers only for small, deliberate custom metadata.
• Use the direct master /submit convenience upload only for simple workflows; it trades placement control for convenience.
• Inspect /status for per-volume file counts, delete counts, and readonly state when debugging compaction, garbage, or capacity anomalies.
• Use /healthz for liveness and readiness probes because it reflects the local node's own health and master connectivity.

Gotchas / prohibitions

• Do not use the master /submit shortcut for workflows that need explicit replication, TTL, collection, or disk placement choices.
• Do not rely on readDeleted=true after restarts or compaction; the page explicitly limits it.
• Do not attach unbounded custom metadata; the Seaweed-* payload is stored as JSON and intended to stay below 64KB.
• Do not expose direct volume endpoints broadly if your security model expects clients to go through filer or S3 instead.

How to apply in a real repo

• Decide explicitly which clients may talk to volume servers directly and which must use filer or S3 gateways.
• Put /healthz and /status into volume-server operational checks.
• Document upload integrity expectations, supported metadata headers, and any sanctioned image transformation behavior.

Filer Server API

What this page is about

• It documents the path-based HTTP interface for file and directory reads, writes, appends, metadata, moves, copies, listing, tagging, and deletion.
• It clarifies how filer parameters map to placement, chunking, TTL, and metadata behavior.
• It captures several important operational caveats around retries, append chunk growth, and recursive deletion.

Actionable takeaways

• Use filer APIs when applications want path semantics, automatic directory creation, or protocol-friendly file operations instead of raw volume ids.
• Set placement fields (collection, replication, dataCenter, rack, dataNode) on writes only when the workload truly needs them; otherwise keep routing simple.
• Enable write retries at the client layer because the page explicitly recommends them for filer writes.
• Keep append sizes reasonably large, because every append creates another chunk reference in metadata.
• Use metadata=true for inspection tooling and JSON directory listing with pagination (lastFileName, limit) for scalable browsing.
• Prefer file tagging through Seaweed-* headers when you need lightweight custom attributes stored with filer metadata.
• Use mv.from for metadata-only renames and relocations; use cp.from when you need an independent copy and accept size-dependent cost for chunked files.
• Treat empty-folder creation as an explicit POST only when the workload needs directory placeholders.
• Use skipChunkDeletion=true only for expert workflows that intentionally leave chunks behind, such as special migration or metadata repair scenarios.

Gotchas / prohibitions

• Do not build a small-append-heavy workload without chunk-growth controls; metadata can fragment badly.
• Do not assume cp.from is metadata-only for large files; chunked copies duplicate data.
• Do not use recursive delete or skipChunkDeletion casually, because they can create large blast radius or orphaned data.
• Do not skip parent directory checks blindly for latency gains unless the calling workflow guarantees directory correctness.

How to apply in a real repo

• Offer filer as the default integration surface for file-oriented applications and document when S3 is a better fit.
• Standardize write retry policy, append sizing, tagging conventions, and recursive delete safeguards.
• Expose directory listing pagination and metadata-read patterns in application integration notes.

Client Libraries

What this page is about

• It lists community client libraries across multiple languages.
• It also points to the upstream gRPC proto files and the Java gRPC client maintained in the SeaweedFS repository.
• It signals that SeaweedFS does not enforce one canonical application SDK for every language.

Actionable takeaways

• Treat most language libraries on the page as ecosystem integrations rather than guaranteed first-party SDKs.
• Prefer protocol-level choices first: filer HTTP, S3 API, or internal gRPC, then pick the client library that matches that surface.
• Review the upstream proto definitions in weed/pb when you need strongly typed internal integrations or custom code generation.
• Use the repository-hosted Java gRPC client as the closest thing to an upstream-maintained client reference.

Gotchas / prohibitions

• Do not assume every listed library is current, equally maintained, or feature-complete.
• Do not choose a library purely by language fit without checking whether it targets filer HTTP, raw volume access, S3, or gRPC.

How to apply in a real repo

• Document approved client paths per language and protocol instead of presenting the entire ecosystem list to operators.
• For critical integrations, prefer direct protocol testing against SeaweedFS endpoints even when a wrapper library is used.

SeaweedFS Java Client

What this page is about

• It describes the upstream Java gRPC client extracted from SeaweedFS's Hadoop-compatible file system work.
• It covers build coordinates, direct read/write behavior, replication control, metadata event watching, and basic filesystem operations.
• It positions the Java client as a filer-centric gRPC integration rather than a blob/S3 client.

Actionable takeaways

• Use the Java client when a JVM application needs efficient filer-backed filesystem semantics rather than S3 compatibility.
• Connect to the filer's gRPC port (18888 by default when filer HTTP runs on 8888) instead of the HTTP port.
• Expect data reads and writes to go directly to volume servers while filer handles metadata, which reduces the data-path overhead compared with plain filer HTTP.
• Use the client when recursive metadata event watching is valuable; the page highlights it as stronger than single-directory local file-watch semantics.
• Set replication explicitly on writes when the application, not only the filer default, owns durability decisions.
• Use the standard stream abstractions and filesystem helpers for JVM code that wants normal InputStream/OutputStream style access.

Gotchas / prohibitions

• Do not assume this Java client covers blob-storage or S3 APIs; the page says blob storage APIs are not included.
• Do not point the client at the filer HTTP port by mistake; the examples use gRPC.
• Do not rely on example dependency versions blindly; align them with the tracked SeaweedFS release and artifact availability in Maven Central.

How to apply in a real repo

• Document filer gRPC endpoints separately from HTTP endpoints for JVM teams.
• Reserve the Java client for workloads that benefit from direct volume reads/writes, recursive metadata subscriptions, or stream-like filesystem access.
• Keep S3 integrations and filer gRPC integrations as separate guidance paths so application teams do not mix the abstractions.

Backup and Replication

Sources:

• https://github.com/seaweedfs/seaweedfs/wiki/Async-Backup
• https://github.com/seaweedfs/seaweedfs/wiki/Async-Filer-Metadata-Backup

Async Backup

What this page is about

• It explains continuous filer-driven backup to cloud or local sinks using change events.
• It documents weed filer.backup, sink configuration, and mirrored versus incremental strategies.

Actionable takeaways

• Use weed filer.backup for near-real-time backup driven by filer metadata change logs.
• Generate replication.toml with weed scaffold -config=replication and keep only the sink sections you actually use.
• Expect backup state to resume across restarts because SeaweedFS stores progress offsets in filer metadata.
• Choose mirrored mode when deletes should propagate and path structure should stay the same.
• Choose incremental mode when point-in-time style daily snapshots are more valuable than delete mirroring.
• Consider cloud object storage as a practical backup sink because the page highlights low-ingest-cost economics.
• For EC-heavy clusters, treat the 4.24-4.25 line as replication-safety work too: shard planning/recovery is safer, stale partial shards are pruned more carefully, and source-volume deletion is gated on verifying a healthy shard set.
• For the 4.26-4.28 line, include EC metadata recovery in DR drills: SeaweedFS can now rebuild lost .ecx / .vif metadata from local shards, but you should still validate the recovery path before counting it as a full substitute for backups.
• For the 4.29-4.30 line, include filer-sync and remote-sink metadata correctness in DR checks: chunk-size validation prevents zero-byte propagation, manifest chunks resolve against the source filer, filtered-event markers keep sync_offset fresh, and S3/GCS remote sinks forward MIME type as ContentType.

Gotchas / prohibitions

• Do not treat backup as restore-ready without separately validating recovery.
• Do not choose incremental mode if you expect deletions to be reflected in the backup.
• Do not run backup without a stable replication.toml shared across failover backup workers.
• Do not assume volume balancing should move remote-tiered volumes; the 4.24 line explicitly fixes that behavior.
• Do not accept a green sync process as proof of a good restore; verify object content type, manifest expansion, and zero-byte edge cases after upgrading through 4.30.

How to apply in a real repo

• Define one backup strategy per dataset: mirrored DR copy or date-partitioned incremental retention.
• Keep backup process supervision and restart behavior under the same operational ownership as filer.

Async Filer Metadata Backup

What this page is about

• It describes continuous backup of filer metadata alone into a separate backup store.
• It is designed for cases where the primary filer store cannot be easily replicated or is embedded.

Actionable takeaways

• Use weed filer.meta.backup when the metadata plane needs a separate protection strategy from content backup.
• Configure the backup store with the same store-style configuration concepts as filer.toml, but do not assume it must be the same backend type as the source.
• Expect metadata-backup progress to be resumable because the offset is tracked in the backup store itself.
• Consider cheap local or streamed secondary stores for metadata protection when the primary store is expensive or operationally awkward to replicate.

Gotchas / prohibitions

• Do not confuse metadata backup with full content backup; this protects namespace and metadata state, not volume data by itself.
• Do not assume source and backup store must be identical; the page explicitly allows heterogenous pairs.

How to apply in a real repo

• Keep metadata backup as a separate control in the recovery plan, especially when using embedded or hard-to-replicate filer stores.
• Validate restore paths from the backup store before trusting it as the only metadata fallback.

Benchmarks and Use Cases

Sources:

• https://github.com/seaweedfs/seaweedfs/wiki/Benchmarks
• https://github.com/seaweedfs/seaweedfs/wiki/FAQ
• https://github.com/seaweedfs/seaweedfs/wiki/Applications

Benchmarks

What this page is about

• It explains what the built-in weed benchmark command measures and why benchmark numbers are highly dependent on topology and hardware.
• It provides a simple single-machine setup and describes the default benchmark workload.
• It frames benchmark output as a workload-specific data point rather than an absolute product claim.

Actionable takeaways

• Use weed benchmark mainly as a repeatable comparative test for your own environment, not as proof of universal performance.
• Prefer multi-machine tests when evaluating a distributed deployment, because single-host benchmarks hide network and placement costs.
• Understand the default workload before reading the numbers: the built-in benchmark writes and then randomly reads roughly one million 1KB files.
• Treat the default benchmark as a small-object, operations-per-second stress test because each file involves id assignment plus upload and later random read lookup.
• Change benchmark parameters when you need throughput-oriented validation for larger objects instead of tiny-file request rates.
• Inspect weed benchmark -h and record the exact flags used so benchmark runs are reproducible across hardware changes and release upgrades.

Gotchas / prohibitions

• Do not quote the wiki's sample numbers as generally applicable production capacity.
• Do not benchmark a multi-node design on one machine and assume the result predicts cluster behavior.
• Do not compare results across environments unless file size, concurrency, hardware, and deployment topology are all documented.

How to apply in a real repo

• Add a benchmark protocol that records topology, disk class, CPU, network shape, SeaweedFS version, and benchmark flags.
• Run at least two benchmark profiles: small-object IOPS and larger-object throughput.
• Keep benchmark output next to ops notes so performance claims stay tied to the tested environment.

FAQ

What this page is about

• It answers recurring operator questions around volume sizing, disk types, preallocation, data safety, large-file behavior, memory usage, and gRPC addressing.
• It clarifies the difference between SeaweedFS volumes and physical disks.
• It captures several practical failure patterns that commonly show up during early production adoption.

Actionable takeaways

• Plan for many SeaweedFS volumes; replication, TTL, collection, disk type, and S3 bucket isolation all consume distinct volume pools.
• If you hit no free volumes left, first revisit -volumeSizeLimitMB on master and -max on volume servers rather than treating it as a generic capacity bug.
• Leave disk type empty on homogeneous all-SSD clusters unless you have a specific path-based policy reason to tag disks differently.
• Pre-create extra writable volumes with the master vol/grow endpoint when new collections, buckets, or replica classes are about to come online.
• Treat the master and volume web UIs as quick health surfaces, but not as substitutes for explicit monitoring and runbooks.
• Use filer-based HTTP access, gRPC APIs, or generated bindings according to the interface your application actually needs; the FAQ does not push one client language ecosystem.
• Count safety features in layers: CRC/Etag validation, replication or erasure coding, optional filer encryption, TLS, JWT, and S3 access control.
• Size chunking for large files deliberately because metadata growth is linear with chunk count; larger chunks reduce metadata pressure.
• Keep extra free disk space for compaction, especially when configuring many volumes on a server.
• Reduce memory pressure on older small-file-heavy volumes by moving suitable cold data into erasure-coded read-only form.
• Use _large_disk builds only when you need volumes above 30GB, and treat them as a cluster-wide compatibility boundary.
• Expect deleted space to remain allocated until vacuum runs; schedule weed shell maintenance instead of assuming immediate reclaim.
• When overriding gRPC ports, propagate the <host>:<httpPort>.<grpcPort> form consistently to all dependent commands.
• For IPv6, set -ip.bind with the interface scope when using link-local addresses.

Gotchas / prohibitions

• Do not equate a SeaweedFS volume with a physical disk; the system expects many volumes per environment.
• Do not mix standard and _large_disk binaries inside one cluster.
• Do not over-provision total volume capacity beyond real disk headroom, or compaction and growth will fail at the worst time.
• Do not expect deletions to free disk immediately without vacuum.
• Do not override gRPC ports on one component and forget to update all the clients that reference it.

How to apply in a real repo

• Put volume-capacity math, vol/grow procedures, vacuum policy, and _large_disk compatibility rules into the operator guide.
• Treat disk-type naming and path-specific filer config as reviewed configuration, especially on SSD-only clusters.
• Capture large-file chunk sizing and memory tradeoffs in workload-specific architecture notes.
• Add a troubleshooting section for custom gRPC ports, IPv6 scope syntax, and mount cleanup after unclean restarts.

Applications

What this page is about

• It lists example applications and integrations that already use SeaweedFS.
• It is not a technical integration guide; it mainly shows which access patterns appear in real projects.
• The examples point to filer-backed sync tools, media storage, attachment storage, and Nginx-based processing flows.

Actionable takeaways

• Expect SeaweedFS to appear behind several application styles: GUI file explorers and sync tools, media ingestion systems, attachment stores, and HTTP backends.
• Treat the filer interface as a common integration surface when applications need filesystem-like semantics rather than raw volume ids.
• Consider SeaweedFS a backend building block rather than a finished end-user product; most examples wrap it in application-specific logic or UI.
• Use this page as evidence that operator documentation should cover both direct application access and reverse-proxy-mediated access paths.

Gotchas / prohibitions

• Do not treat this page as a compatibility matrix or support policy.
• Do not infer production architecture requirements from the examples alone; they are ecosystem signals, not reference designs.

How to apply in a real repo

• Include a short "integration surfaces" section that maps application needs to filer HTTP, S3, WebDAV, FUSE, or custom gateways.
• Keep reverse-proxy, media-processing, and sync-client considerations visible in deployment reviews if the workload resembles the listed examples.

Cloud Drive and Remote Storage

Sources:

• https://github.com/seaweedfs/seaweedfs/wiki/Cloud-Drive-Benefits
• https://github.com/seaweedfs/seaweedfs/wiki/Configure-Remote-Storage
• https://github.com/seaweedfs/seaweedfs/wiki/Mount-Remote-Storage
• https://github.com/seaweedfs/seaweedfs/wiki/Cache-Remote-Storage

Cloud Drive Benefits

What this page is about

• It distinguishes SeaweedFS Cloud Drive from Cloud Tier and explains why operators use Cloud Drive.
• It frames Cloud Drive as a mounted remote-object namespace with local caching and optional write-back.

Actionable takeaways

• Use Cloud Drive when you need the cloud provider's object layout to remain directly usable outside SeaweedFS.
• Use Cloud Tier instead when you want SeaweedFS-native volume movement and transparent filer data encryption.
• Expect Cloud Drive to cache remote content locally with effectively unbounded capacity design rather than classic eviction-first proxy caching.
• Use Cloud Drive when workloads need local-latency reads, explicit cache warming/uncaching, and the ability to detach from the cloud later.
• Remember that Cloud Drive can serve multiple access methods on top of remote data once mounted into SeaweedFS.

Gotchas / prohibitions

• Do not assume Cloud Drive encrypts provider-visible files the way Cloud Tier plus filer encryption can.
• Do not confuse Cloud Drive with a simple proxy; the docs explicitly describe different caching and write-back behavior.

How to apply in a real repo

• Decide early whether a dataset needs provider-native readability (Cloud Drive) or SeaweedFS-native cold-volume movement (Cloud Tier).
• Document cache warmup, uncache, and write-back policy for each mounted remote dataset.

Configure Remote Storage

What this page is about

• It documents how remote cloud backends are registered for Cloud Drive and related remote-storage features.
• It lists supported provider types and the remote.configure workflow.

Actionable takeaways

• Register remote backends first with remote.configure before mounting or using them elsewhere in SeaweedFS.
• Use the logical remote name as the stable reference and rotate credentials behind it as needed.
• For S3-compatible providers beyond AWS, be ready to tune endpoint, path-style, and signature-version flags.
• Treat provider-specific auth sources, such as GCS service-account JSON versus ADC, as part of the environment design.
• Use the shell command to inspect current remote configs, update them, or delete stale entries.

Gotchas / prohibitions

• Do not assume every S3-compatible vendor works with AWS defaults only.
• Do not hardcode credentials into many places when a named remote configuration can centralize them.

How to apply in a real repo

• Keep one inventory of remote names, provider types, and endpoint quirks.
• Validate provider-specific signature and path-style behavior before production cutover.

Mount Remote Storage

What this page is about

• It documents how a configured remote backend is mounted into filer paths and how metadata pull strategies work.
• It covers eager versus lazy metadata loading, listing cache TTL, metadata refresh, and write-back choices.

Actionable takeaways

• Mount remotes with remote.mount after remote configuration is in place, targeting either a whole bucket or a remote subdirectory.
• Choose eager metadata pull for small or medium buckets that need instant local listing after mount.
• Choose lazy metadata strategy for very large buckets when you want fast mount time and on-demand metadata fetch.
• Use listingCacheTTL when you need automatic remote listing refresh without remounting.
• Use remote.meta.sync on eager mounts without TTL when remote-side changes must be refreshed locally.
• Use weed filer.remote.sync for continuous write-back of local changes to the mounted remote.
• Use remote.copy.local for batch or recovery-style synchronization of local-only files.
• Expect remote.unmount to drop local metadata and cached file content.

Gotchas / prohibitions

• Do not choose lazy mode if empty directory listings would confuse users or applications that expect ls to work immediately.
• Do not rely on eager metadata forever without refresh if the remote source changes externally.
• Do not assume write-back happens automatically unless filer.remote.sync or a batch copy path is actually running.

How to apply in a real repo

• Define one of four standard mount profiles: eager, eager+TTL, lazy, or lazy+TTL.
• Pair writable mounts with an explicit sync strategy and monitoring for sync lag or failures.

Cache Remote Storage

What this page is about

• It documents explicit cache warming and cache eviction for mounted remote paths.
• It focuses on the remote.cache and remote.uncache shell commands.

Actionable takeaways

• Use remote.cache for proactive warmup instead of waiting for lazy reads.
• Filter caching by directory, name pattern, size, or age so local storage is spent on the files that matter.
• Use remote.uncache to reclaim local capacity while keeping metadata and remote source-of-truth intact.
• Schedule both commands regularly when workloads need predictable local residency rules.
• Expect SeaweedFS to skip already synchronized or unsafe-to-uncache files to avoid unnecessary copying or data loss.

Gotchas / prohibitions

• Do not uncache files that are not yet synchronized to remote.
• Do not assume Cloud Drive caching policy is automatic enough for all workloads; explicit warmup/uncache jobs may still be necessary.

How to apply in a real repo

• Define cache/uncache cron policies by directory, age, and size class.
• Monitor local-capacity consumption and sync health alongside Cloud Drive usage.

Configuration

Sources:

• https://github.com/seaweedfs/seaweedfs/wiki/Replication
• https://github.com/seaweedfs/seaweedfs/wiki/Store-file-with-a-Time-To-Live
• https://github.com/seaweedfs/seaweedfs/wiki/Failover-Master-Server
• https://github.com/seaweedfs/seaweedfs/wiki/Erasure-Coding-for-warm-storage
• https://github.com/seaweedfs/seaweedfs/wiki/Server-Startup-via-Systemd
• https://github.com/seaweedfs/seaweedfs/wiki/Environment-Variables

Replication

What this page is about

• It explains SeaweedFS replication as a volume-level placement policy defined by a three-digit string for cross-datacenter, cross-rack, and same-rack copies.
• It clarifies the write-consistency model and the fact that replication repair is manual rather than immediate.
• It adds practical guidance for changing replication and operating through disk failures or topology shifts.

Actionable takeaways

• Treat replication as a property of volumes and write placement, not of individual file objects in isolation.
• Understand the three digits as additional copies across data center, rack, and server scopes; total copies are 1 + sum(digits).
• Use -defaultReplication on master or filer to set a sane default and override only when a workload truly needs different durability.
• Size topology labels (dataCenter, rack) correctly before relying on placement strings, because replication meaning depends on those labels being real.
• Expect SeaweedFS writes to require success on all intended replicas; failed replica creation fails the write.
• Use volume.fix.replication from weed shell as the explicit repair path for under-replicated readonly volumes.
• Use volume.fix.replication -doDelete=false during topology changes when you want to heal missing copies without deleting surplus ones mid-migration.
• After changing a volume's replication with volume.configure.replication, expect it to become readonly until repair is completed.
• Pair high replication factors with serious capacity planning; they multiply storage needs quickly.
• Consider erasure coding for warmer data when full replication would be too space-expensive.

Gotchas / prohibitions

• Do not assume SeaweedFS automatically restores missing replicas during transient failures; the page explicitly says repair is manual.
• Do not configure replication strings that your real topology cannot satisfy.
• Do not change replication policies without a follow-up repair plan and capacity check.
• Do not confuse multiple volume processes on one host with true host-level fault isolation.

How to apply in a real repo

• Record supported replication strings, the topology they require, and the business reason for each class.
• Make volume.fix.replication part of scheduled operations and failure-recovery procedures.
• Review rack and datacenter labels as part of every deployment change, because bad labels silently undermine durability assumptions.

Store File with a Time To Live

What this page is about

• It explains SeaweedFS TTL semantics for expiring files and the volume-level design used to reclaim space efficiently.
• It shows how TTL participates both in file-id assignment and in the actual upload.
• It adds deployment guidance for sizing TTL volumes and keeping them operationally separate.

Actionable takeaways

• Treat TTL as both a placement concern and a file metadata concern: the assign step selects a matching TTL volume and the write step stores the file's own expiry.
• Keep the volume TTL equal to or longer than the per-file TTL when mixing values for operational simplification.
• Expect files to return 404 after expiry even before the underlying expired volume is physically deleted.
• Understand that SeaweedFS reclaims TTL space efficiently by grouping files into TTL-specific volumes and deleting the whole expired volume after it ages out.
• Reduce volume size limits for TTL-heavy workloads when disk space is tight, because active TTL volumes can still grow toward the normal maximum size.
• Use a small set of TTL classes instead of many unique TTL variations to avoid exploding the number of specialized volume pools.
• Consider using S3 lifecycle configuration when TTL behavior is needed through the S3 surface.

Gotchas / prohibitions

• Do not forget to pass TTL during both id assignment and upload if you want deterministic placement and file expiry behavior.
• Do not mix many TTL variations casually; each distinct TTL creates its own operational pool.
• Do not mix TTL and non-TTL workloads in the same cluster without reviewing shared volume-size constraints.

How to apply in a real repo

• Define an allowed TTL catalog and map application retention classes to it.
• Treat TTL clusters or pools as separate capacity domains when retention-heavy workloads differ from normal object storage.
• Document the lag between logical expiry and physical volume deletion so support teams understand disk-usage timing.

Failover Master Server

What this page is about

• It explains how SeaweedFS master HA works through a Raft-elected leader and follower forwarding.
• It shows bootstrap patterns for running multiple masters together with volume servers.
• It also clarifies the operational limitation around changing the master set later.

Actionable takeaways

• Use an odd-sized master set such as 3 or 5 when you need control-plane failover.
• Keep the peer list identical across all masters and ensure the -ip value matches the hostname/IP used in -peers.
• Configure volume servers with as many master endpoints as possible so they can reconnect to another master after leader loss.
• Expect temporary write unavailability for some volumes during leader transition until all volume heartbeats reach the new leader.
• Treat the master set as relatively static infrastructure, similar to a consensus cluster, not something to scale up and down casually.

Gotchas / prohibitions

• Do not assume master membership can be changed live; the page says adding a new master requires stopping the existing master set and restarting with the new list.
• Do not use inconsistent hostnames or IPs between -ip and -peers, or the cluster identity will break.
• Do not configure only one master endpoint on volume servers if failover is a requirement.

How to apply in a real repo

• Treat the master peer list as immutable cluster metadata managed through infrastructure code.
• Add a brief operator note that leader failover can temporarily reduce writable capacity until fresh heartbeats arrive.
• Include master peer-list validation in deployment reviews and cluster bootstrap scripts.

Erasure Coding for Warm Storage

What this page is about

• It explains SeaweedFS's RS(10,4) erasure coding model for warm or cold data.
• It positions EC as a space-saving alternative to high replica counts while keeping recovery at the whole-volume level.
• It describes the admin/worker plugin flow, detection thresholds, shard balancing, and read-path tradeoffs.

Actionable takeaways

• Use EC for data that is no longer hot enough to justify in-memory indexes and full-replica overhead.
• Expect the open-source default to be 10+4, which tolerates up to four lost shards with roughly 1.4x storage overhead.
• Start the admin service and worker so the erasure_coding plugin can detect eligible volumes and perform encoding.
• Tune encoding thresholds deliberately: fullness ratio, quiet period, minimum size, and optional collection filter.
• Keep collections capable of holding both normal writable volumes and erasure-coded warm volumes; new writes still land on normal volumes.
• Run EC balancing so shards spread across disks, servers, and racks instead of accumulating risky concentration.
• Expect an extra network hop for normal EC reads and slower recovery reads when shards are missing.
• Use EC repair when losing shards, but plan for whole-volume data transfer during reconstruction.

Gotchas / prohibitions

• Do not use EC for workloads that still need frequent updates; the page says deletion is supported but update is not.
• Do not forget that compaction requires converting EC volumes back to normal volumes first.
• Do not enable EC and ignore shard-balancing hygiene; uneven placement can make recovery impossible after a host failure.
• Do not present EC as a write-path optimization; it is a warm-storage cost and memory optimization with read tradeoffs.

How to apply in a real repo

• Define a warm-data policy that says when volumes transition from replicated writable state into EC-managed storage.
• Pair EC enablement with admin/worker deployment, threshold tuning, and balancing procedures.
• Document the operational difference between normal-volume repair and EC shard repair so recovery expectations stay realistic.

Server Startup via Systemd

What this page is about

• It provides sample systemd unit files for master, volume, and filer services.
• It highlights mount ordering and startup delays for data directories that depend on separate filesystems.
• It shows a simple pattern rather than a hardened production unit template.

Actionable takeaways

• Create separate unit files for master, volume, and filer when you want OS-native service management outside containers or Kubernetes.
• Add mount dependencies in After= when the SeaweedFS data directory lives on a filesystem that is mounted later in boot.
• Use ExecStartPre=/bin/sleep ... only as a simple guard when mount timing is unreliable; prefer explicit mount dependencies where possible.
• Set WorkingDirectory intentionally when filer config files such as filer.toml are resolved relative to that directory.
• Enable services explicitly so nodes recover after reboots.

Gotchas / prohibitions

• Do not copy the sample units verbatim into production without replacing IPs, directories, user/group, and service flags.
• Do not rely on arbitrary sleep alone if proper systemd dependencies can model the required storage ordering.
• Do not run everything as root unless the environment truly requires it.

How to apply in a real repo

• Provide hardened systemd units with explicit users, restart policy, mount ordering, and absolute config paths.
• Keep bootstrap templates separate for master, volume, filer, and optional S3/admin/worker processes.
• Document which directories must exist and which config files are expected in the working directory.

Environment Variables

What this page is about

• It explains how SeaweedFS command flags and configuration-file keys map to environment variables.
• It covers WEED_ prefix rules, security-related variables, Docker usage, and filer store configuration through env vars.
• It also highlights store-selection constraints and migration caveats.

Actionable takeaways

• Use plain uppercase flag names for many command options and WEED_-prefixed variables for global logging/config flags and config-file settings.
• Translate dotted config keys to WEED_ environment variables by replacing dots with underscores.
• Prefer environment variables for secrets such as JWT keys, TLS material, and filer-store credentials when config files live in version control.
• For S3 credentials, follow the dedicated precedence rules and keep environment variables as one supported source rather than the only one.
• Disable WEED_LEVELDB2_ENABLED when switching filer metadata to an external store; only one filer store should be enabled.
• Use comma-separated values for array-like settings such as cluster addresses.
• Run weed scaffold -config=filer to discover the current set of store configuration keys instead of guessing them.
• Treat environment-based store changes as configuration for new deployments or planned migrations, not in-place metadata migration.

Gotchas / prohibitions

• Do not enable multiple filer stores at once.
• Do not assume changing environment variables migrates existing filer metadata.
• Do not hardcode secrets in committed filer.toml or security.toml when env vars can externalize them cleanly.

How to apply in a real repo

• Publish one env-var naming guide for flags, WEED_ config keys, and secret injection.
• Keep container examples explicit about disabling leveldb2 when an external metadata store is chosen.
• Separate immutable non-secret config from secret-bearing env vars in deployment manifests.

Encryption

Sources:

• https://github.com/seaweedfs/seaweedfs/wiki/Server-Side-Encryption
• https://github.com/seaweedfs/seaweedfs/wiki/Server-Side-Encryption-SSE-KMS
• https://github.com/seaweedfs/seaweedfs/wiki/Server-Side-Encryption-SSE-C

Server-Side Encryption

What this page is about

• It introduces SeaweedFS S3-side encryption choices and positions SSE-S3 as the SeaweedFS-managed default-style option.

Actionable takeaways

• Use SSE-S3 when you want SeaweedFS-managed encryption with low operational overhead.
• Expect SSE-S3 to work with explicit AES256 upload headers and bucket default encryption behavior.

SSE-KMS

What this page is about

• It explains how SeaweedFS integrates with external key-management systems for S3 encryption.
• It covers AWS KMS, Google Cloud KMS, OpenBao/Vault, and experimental Azure Key Vault support.

Actionable takeaways

• Use SSE-KMS when key ownership must stay in an external KMS rather than inside SeaweedFS.
• Put KMS provider configuration inside the S3 config JSON and choose a sensible default provider.
• Use bucket-to-provider mapping when different data classes need different KMS backends.
• Enable cache settings thoughtfully for Vault/OpenBao-style providers to balance latency and key-freshness needs.
• Keep KMS permissions minimal and document key rotation ownership.

Gotchas / prohibitions

• Do not treat experimental Azure Key Vault support as equivalent to the fully supported providers.
• Do not mix KMS rollout with unclear IAM ownership; encryption and access control both live in the same S3 config surface.

SSE-C

What this page is about

• It explains customer-provided-key encryption where clients supply the AES-256 key on each request and SeaweedFS never stores it.

Actionable takeaways

• Use SSE-C when clients must retain exclusive control of encryption keys while still using server-side encryption semantics.
• Expect clients to send the algorithm, base64 key, and key MD5 on upload and every subsequent encrypted-object read or copy.
• Test copy and re-encryption flows explicitly because source and destination keys may differ.
• Keep operational guidance clear that losing the client-side key means losing access to the object.

Gotchas / prohibitions

• Do not expect SeaweedFS to recover or store SSE-C keys for you.
• Do not omit SSE-C headers when reading or copying an encrypted object.

How to apply in a real repo

• Define approved encryption modes per workload: simple SSE-S3, externally governed SSE-KMS, or customer-controlled SSE-C.
• Keep KMS configuration, IAM policy, and bucket default encryption decisions in one operator-owned design document.
• Add encryption-mode interoperability tests for upload, download, copy, multipart, and range-request flows.

Filer Core

Sources:

• https://github.com/seaweedfs/seaweedfs/wiki/Filer-Setup
• https://github.com/seaweedfs/seaweedfs/wiki/Directories-and-Files
• https://github.com/seaweedfs/seaweedfs/wiki/File-Operations-Quick-Reference
• https://github.com/seaweedfs/seaweedfs/wiki/Data-Structure-for-Large-Files
• https://github.com/seaweedfs/seaweedfs/wiki/Filer-Data-Encryption
• https://github.com/seaweedfs/seaweedfs/wiki/Filer-Commands-and-Operations
• https://github.com/seaweedfs/seaweedfs/wiki/Filer-JWT-Use
• https://github.com/seaweedfs/seaweedfs/wiki/TUS-Resumable-Uploads

Filer Setup

What this page is about

• It shows where filer.toml can live and how to scaffold it.
• It is a minimal entry point rather than a full deployment guide.

Actionable takeaways

• Keep filer.toml in the working directory, $HOME/.seaweedfs/, or /etc/seaweedfs/ so filer starts with an explicit metadata-store configuration.
• Generate the current sample config with weed scaffold -config=filer -output=. instead of inventing filer store keys by hand.
• Use the scaffold output as the authoritative starting point before selecting or disabling stores.

Gotchas / prohibitions

• Do not launch filer in production without reviewing the generated default store choice.
• Do not maintain hand-written stale config examples when weed scaffold can emit the current schema.

How to apply in a real repo

• Keep a generated filer config template under configuration management and annotate only the settings that differ from defaults.
• Treat filer config generation as part of bootstrap docs and CI smoke tests.

Directories and Files

What this page is about

• It explains the filer path model, read/write flow, metadata-store complexity, and scaling behavior.
• It shows how filer combines path-oriented operations with chunk storage on volume servers.
• It clarifies the difference between filer-heavy HTTP/S3 workloads and mount-based workloads.

Actionable takeaways

• Use filer when applications need directories, path listing, rename semantics, or filesystem-compatible access.
• Expect filer reads to resolve metadata first and then fetch content from volume servers.
• Expect filer writes to stream through filer, chunk large files, and then persist chunk metadata to the filer store.
• Choose the filer metadata store based on lookup/listing scale requirements; the page explicitly frames filer scalability around the backing store.
• Remember that file rename is metadata-only, while directory rename is proportional to the number of nested entries.
• Scale out multiple filer instances when HTTP or S3 traffic makes filer part of the content data path.
• Expect lower filer load when using weed mount, because content IO goes directly between mount clients and volume servers.

Gotchas / prohibitions

• Do not assume directory rename is cheap on very large trees.
• Do not evaluate filer scalability without considering the behavior and limits of the selected metadata store.
• Do not size filer instances the same way for mount-only and HTTP/S3-heavy workloads; the traffic profile is different.

How to apply in a real repo

• Map workload types to filer scaling plans: metadata-only mount traffic versus full content proxy traffic.
• Document rename cost expectations for large directory trees.
• Keep example flows for HTTP upload/download and paginated listing in operator references and integration tests.

Mount/FUSE reliability notes (4.20)

• weed mount -dlm adds distributed lock coordination for cross-mount write paths; use it when several mounts can modify the same tree concurrently.
• Recent fixes tighten POSIX-facing behavior for directory nlink, parent mtime/ctime, hard-link metadata, and nanosecond timestamp precision.
• Mount mutation paths now avoid some redundant filer RPCs, and writeback cache mode pre-allocates file IDs to reduce write amplification under sustained change.
• If you saw metadata flush problems for files unlinked while still open, re-test before keeping downstream workarounds.

Mount/FUSE reliability notes (4.29)

• 4.29 adds filer-managed POSIX advisory lock primitives behind weed mount -dlm, including owner routing, session leases, keepalive reassertion, ring-change cooling, and fail-closed warm-up behavior. Use this release line when multiple FUSE mounts coordinate writes to the same namespace.
• Writeback-cache users should retest concurrent append and attribute paths; the release fixes a SetAttr / GetAttr crash around concurrent chunk append.
• Treat lock behavior as an integration surface: test cross-mount locks, filer owner restarts, and ring changes before relying on the new DLM path for application correctness.

Filer reliability notes (4.20)

• Graceful shutdown no longer risks the same corruption path as earlier 4.17-era builds, so shutdown/restart drills are worth revalidating after upgrade.
• Filer no longer aborts entry deletion just because hard-link cleanup failed, and redundant disk reads that caused memory/CPU regressions were removed.

Filer reliability notes (4.29 -> 4.30)

• 4.29 serializes same-path mutations with a per-path lock and adds filer-side object transactions for atomic multi-entry object writes. Prefer this upstream write path over custom app-side locking when coordinating S3-style mutations.
• 4.30 prunes filers dropped from master discovery, adds jitter to retry backoff in wdclient / daily tasks, and returns immediately on the first distributed-operation error. Update runbooks that assumed stale filer endpoints would linger until process restart.
• Redis2 filer stores now apply keyPrefix in KV methods, and Postgres filer writes default to ON CONFLICT upsert so a conflict does not abort the whole transaction. Re-test migrations or custom SQL assumptions after upgrade.

File Operations Quick Reference

What this page is about

• It condenses common filer HTTP operations for upload, download, delete, move, copy, listing, and metadata.
• It serves as a quick operator and integration cheat sheet rather than a deeper protocol explanation.

Actionable takeaways

• Use PUT for simple direct uploads and POST multipart uploads when the client or tooling already supports that form.
• Use recursive DELETE carefully for directory cleanup workflows.
• Treat mv.from as the fast path for rename/relocation and cp.from as the safe path for duplication or backup-before-change workflows.
• Use JSON directory listing with pagination for automation instead of scraping the HTML directory view.
• Use custom Seaweed-* headers and TTL query parameters only when the application contract actually needs them.

Gotchas / prohibitions

• Do not mistake the quick-reference TTL example for the broader TTL volume-planning guidance; retention still affects storage pools and capacity.
• Do not reorganize large trees heavily without remembering directory moves are not the same cost profile as file moves.

How to apply in a real repo

• Keep these operations in smoke tests and runbooks so operators can validate filer behavior quickly.
• Document when teams should prefer copy over move, especially for rollback-sensitive workflows.

Data Structure for Large Files

What this page is about

• It explains how SeaweedFS chunks large files and when manifest chunks are introduced to cap metadata growth.
• It distinguishes small files, medium files, and super-large files by metadata behavior rather than by a single hard size limit.

Actionable takeaways

• Treat chunk size as a tuning parameter that affects both metadata volume and IO behavior.
• Expect medium-size large files to store chunk references directly in filer metadata along with per-chunk details such as offset, size, compression, and encryption markers.
• Expect very large files to switch to manifest chunks so the filer store does not need to hold an ever-growing flat list of chunk descriptors.
• Use larger chunk sizes when metadata scale becomes a concern for huge-file workloads, while balancing read/write behavior.
• Keep in mind that the practical size ceiling is driven by metadata design and access predictability, not only raw storage space.

Gotchas / prohibitions

• Do not design huge-file workloads as if filer metadata cost were constant regardless of chunk count.
• Do not assume recursive manifest indirection exists by default for arbitrarily deep large-file trees.

How to apply in a real repo

• Document chosen chunk-size defaults for each workload class.
• Include manifest-chunk behavior in large-file architecture reviews so metadata-store sizing stays realistic.

Filer Data Encryption

What this page is about

• It explains file-content encryption for data written through filer while metadata remains in the filer store.
• It positions encryption as protection for data stored on volume servers and potentially in cloud tiers.

Actionable takeaways

• Use weed filer -encryptVolumeData when the threat model includes compromised volume servers or remote storage tiers.
• Expect SeaweedFS to generate a random AES256-GCM key per file chunk during writes.
• Protect the filer store aggressively because it holds the metadata needed to recover per-chunk encryption keys.
• Treat encrypted chunk storage as a useful control for cloud-tier or untrusted-storage placements.
• Remember that deleting the relevant metadata effectively renders encrypted chunk data unreadable, which can help with data-forgetting workflows.

Gotchas / prohibitions

• Do not enable filer data encryption and then treat the filer store as low-sensitivity infrastructure.
• Do not assume volume servers themselves manage or understand plaintext encryption context; the protection boundary is above them.

How to apply in a real repo

• Pair -encryptVolumeData with strict filer-store access control and backup policy.
• Document clearly which paths write through filer and therefore benefit from this encryption model.

Filer Commands and Operations

What this page is about

• It documents CLI and API-side copy workflows around filer.
• It distinguishes local-to-filer bulk copy from filer-internal file duplication.

Actionable takeaways

• Use weed filer.copy for efficient local filesystem to filer ingestion because data goes straight to volume servers and filer only registers metadata.
• Use filer HTTP cp.from for server-side copies within the filer namespace when you want to avoid download/re-upload cycles.
• Use gRPC CreateEntry()-style registration patterns only when building custom ingestion or integration tooling that needs direct filer metadata registration.
• Prefer weed filer.copy when directory trees from local disk need to be preserved into filer paths automatically.

Gotchas / prohibitions

• Do not assume filer-internal copy shares chunks; the docs describe independent chunk copies.
• Do not funnel large local imports through naive client-side GET+POST workflows when weed filer.copy exists.

How to apply in a real repo

• Document separate ingestion paths for local bulk import and in-cluster duplication.
• Keep weed filer.copy in operational migration and bootstrap playbooks.

Filer JWT Use

What this page is about

• It explains how filer accepts JWTs and where token generation must happen.
• It is a narrow usage note that complements the broader security documentation.

Actionable takeaways

• Generate filer JWTs in an external trusted service using the same signing key and timeout settings configured in security.toml.
• Send filer JWTs through one of three supported channels: Authorization: Bearer, jwt= query parameter, or the HTTP-only AT cookie.
• Keep token issuance and expiry aligned with filer-side configuration so apparently valid tokens do not fail due to mismatched TTL assumptions.

Gotchas / prohibitions

• Do not expect filer itself to mint JWTs for clients.
• Do not leave token transport ambiguous; standardize one delivery mode per application surface where possible.

How to apply in a real repo

• Put filer JWT issuance behind the same identity boundary that already manages application auth.
• Prefer header or cookie transport for browser and API clients unless query-string usage is unavoidable.

TUS Resumable Uploads

What this page is about

• It documents SeaweedFS support for the TUS resumable-upload protocol on filer.
• It covers endpoint layout, enable/disable flags, supported protocol extensions, and example client flows.

Actionable takeaways

• Use the default /.tus endpoint when applications need resumable uploads over unstable networks.
• Customize or disable the endpoint with -tusBasePath on weed filer or -filer.tusBasePath on weed server.
• Expect support for creation, creation-with-upload, and termination, but not concatenation.
• Standardize clients on TUS 1.0.0 headers and offset-based resume flows.
• Validate upload-size and session-expiration limits against application expectations; the page lists a 5GB default max size and temporary session retention.

Gotchas / prohibitions

• Do not expose TUS paths without the same auth and path-governance review applied to normal filer uploads.
• Do not assume multi-file concatenation support exists.
• Do not forget to test resume behavior through proxies and load balancers if uploads span long durations.

How to apply in a real repo

• Offer TUS as the preferred upload path for browser and mobile workloads that need resumability.
• Keep direct TUS capability checks, resume tests, and cancellation tests in integration coverage.

Filer Stores

Sources:

• https://github.com/seaweedfs/seaweedfs/wiki/Filer-Stores
• https://github.com/seaweedfs/seaweedfs/wiki/Filer-Cassandra-Setup
• https://github.com/seaweedfs/seaweedfs/wiki/Filer-Redis-Setup
• https://github.com/seaweedfs/seaweedfs/wiki/Super-Large-Directories
• https://github.com/seaweedfs/seaweedfs/wiki/Path-Specific-Filer-Store
• https://github.com/seaweedfs/seaweedfs/wiki/Choosing-a-Filer-Store
• https://github.com/seaweedfs/seaweedfs/wiki/Customize-Filer-Store

Filer Stores

What this page is about

• It compares available filer metadata backends by lookup behavior, directory scaling, rename characteristics, TTL support, and operational notes.
• It also describes the save/load path for migrating metadata between stores.

Actionable takeaways

• Treat filer store choice as an architecture decision that defines metadata HA, scaling, rename behavior, TTL support, and operational tooling.
• Start with the comparison table to narrow stores by required properties such as distributed HA, atomic renames, fast bucket deletion, or bucket-per-store isolation.
• Use fs.meta.save and fs.meta.load from weed shell when migrating filer metadata between stores.
• Stop writes or otherwise freeze metadata changes during save/load migrations so exported metadata stays consistent.
• Be conservative with concurrent metadata loads because the page warns that some stores, such as Redis, may not tolerate that path well.
• Treat memory as testing only and local embedded stores as operationally different from distributed stores even if performance looks attractive.

Gotchas / prohibitions

• Do not switch stores in place without an explicit metadata export/import plan.
• Do not choose a store only by raw lookup speed; directory scale, rename semantics, HA, and deletion behavior matter too.
• Do not enable concurrent metadata loads blindly across all backends.

How to apply in a real repo

• Record approved filer stores with the reasons they fit each deployment class.
• Add a migration runbook for fs.meta.save/fs.meta.load, including write freeze and validation steps.

Postgres / PgBouncer note (4.20)

• Postgres-backed filer deployments using PgBouncer should revalidate simple-protocol compatibility after upgrading to 4.20, because the upstream fix moved to the pgx v5 API path for that mode.

Patch notes (4.28)

• SQL-backed filer stores in the 4.28 line no longer force-disable idle connection pooling; re-check pool sizing and connection-lifetime assumptions if you previously worked around excessive reconnect churn.
• Redis3-backed deployments also gain a crash fix for inconsistent skiplist ends, so clusters using redis3 for very large directories should prefer 4.28+ before treating unexplained filer panics as environmental only.

Filer Cassandra Setup

What this page is about

• It shows the Cassandra schema and minimal filer configuration for a Cassandra-backed metadata store.
• It positions Cassandra as one example of using an existing distributed datastore for filer metadata.

Actionable takeaways

• Create the keyspace and filemeta table before starting filer against Cassandra.
• Increase Cassandra replication appropriately for production instead of keeping the one-node example.
• Use the cassandra2 section in filer.toml with explicit hosts and keyspace settings.
• Keep filer startup simple once the schema and config are in place; the complexity is mostly in datastore provisioning.

Gotchas / prohibitions

• Do not use the sample replication_factor=1 outside single-node testing.
• Do not start filer against Cassandra before the keyspace and table exist.

How to apply in a real repo

• Ship Cassandra schema creation as part of infrastructure provisioning, not as a manual post-step.
• Keep the chosen keyspace and host list under configuration management.

Filer Redis Setup

What this page is about

• It compares the redis2 and redis3 metadata-store implementations.
• It focuses on how Redis stores directory listings and why very large directories need a different structure.

Actionable takeaways

• Use redis2 when Redis speed is attractive and most directories stay within roughly hundreds of thousands to low millions of entries.
• Understand that redis2 stores a directory's child names in one sorted set, which is simple and fast for many common cases.
• Use redis3 when directories can grow into tens of millions or billions of entries, because it spreads names across skip-list-indexed sorted sets.
• Expect redis3 writes and updates to cost extra Redis operations compared with redis2.
• Remember that simple file reads remain efficient because they do not need to scan sibling names.

Gotchas / prohibitions

• Do not choose redis2 blindly for extreme single-directory fanout.
• Do not assume Redis directory-list design is free; very large directory support trades some write/update simplicity for scale.

How to apply in a real repo

• Match redis2 versus redis3 to directory cardinality, not only to latency preference.
• Document the loss or cost of directory-list behavior clearly if super-large directories are part of the workload design.

Super Large Directories

What this page is about

• It explains how SeaweedFS keeps metadata scalable for directories with enormous direct-child counts.
• It covers the Cassandra and Redis strategies and the operational sacrifices required.

Actionable takeaways

• Use superLargeDirectories only when direct-child counts are so high that the normal partitioning or directory-list structure becomes a bottleneck.
• Expect SeaweedFS to sacrifice direct listing of that configured directory in exchange for better distribution of metadata load.
• In Cassandra, large directories switch to a full_path-based partitioning strategy to spread entries across nodes.
• In Redis, SeaweedFS simply stops maintaining the full child-name list for the configured directory.
• Remember that deeper subdirectories under the large root can still be listed normally even if the top-level super-large directory itself cannot.
• Configure super-large directories before data lands there, while the target folder is still empty.

Gotchas / prohibitions

• Do not enable superLargeDirectories if directory listing for that exact folder is still a hard requirement.
• Do not expect metadata import/export to work for the configured large root directory.
• Do not change or remove configured superLargeDirectories entries casually; the page warns this can lead to data loss.

How to apply in a real repo

• Reserve this feature for identity-style namespaces such as users, UUIDs, IPs, or URL-based buckets where direct listing is already unnecessary.
• Document the irreversible nature and listing loss in architecture decisions before enabling it.

Path-Specific Filer Store

What this page is about

• It explains how different filer stores can be assigned to different path prefixes.
• It positions path-specific routing as a scaling and isolation mechanism for metadata workloads.

Actionable takeaways

• Use path-specific stores when one metadata backend cannot serve all paths equally well because of consistency, tombstone, scale, or noisy-neighbor concerns.
• Configure path-specific stores by adding a named store section, setting location, and enabling it.
• Expect SeaweedFS to match incoming paths efficiently against configured locations and route metadata operations to the matched store.
• Understand that stored paths are trimmed relative to the configured location prefix, which makes the metadata portable across future mount points or filer instances.
• Use this feature for new directories or new updates only.

Gotchas / prohibitions

• Do not apply a path-specific store to existing directories and expect old metadata to remain visible automatically; the page warns old data becomes effectively lost or invisible.
• Do not reuse identical config blocks carelessly when several path-specific stores use the same backend type.

How to apply in a real repo

• Use path-specific routing to isolate hot prefixes, tenant-specific metadata, or special-consistency domains.
• Document which prefixes are backed by which stores and why, including migration constraints for existing data.

Choosing a Filer Store

What this page is about

• It adds workload-based guidance for choosing between Cassandra/Scylla-style stores and alternatives such as Redis.
• The concrete example focuses on update-heavy directories and tombstone buildup.

Actionable takeaways

• Be wary of LSM-tree tombstone buildup in directories with very high churn.
• Consider Redis plus path-specific routing for hot staging folders or other prefixes that receive constant updates and deletions.
• Keep Cassandra or ScyllaDB attractive for distributed scale and native TTL, but not as a universal answer for every metadata hotspot.

Gotchas / prohibitions

• Do not choose a filer store once and assume every path in the namespace has the same workload profile.
• Do not ignore high-churn directory tombstones when diagnosing slower metadata reads.

How to apply in a real repo

• Profile metadata hot spots by path and switch only the problematic prefixes to a better-fitting store when needed.
• Treat store selection as workload-specific, not purely vendor- or feature-driven.

Customize Filer Store

What this page is about

• It documents the extension points required to add a new filer metadata backend to SeaweedFS itself.
• It highlights the FilerStore interface, registration, and server import wiring.

Actionable takeaways

• Implement the full FilerStore interface if you need a custom metadata backend integrated directly into SeaweedFS.
• Include transactional methods and key-value helpers, not only basic entry CRUD, because the interface covers more than simple path lookups.
• Register the store in the supported-store list and ensure the filer server imports it so the backend becomes loadable.
• Treat a custom store as product-level integration work, not just external configuration.

Gotchas / prohibitions

• Do not implement a partial backend that omits transaction, directory-listing, or KV methods expected by the filer.
• Do not forget the registration/import steps or the store will compile but never activate.

How to apply in a real repo

• Prefer existing built-in stores unless a genuine missing backend or compliance requirement justifies code-level extension.
• If a custom store is necessary, keep the implementation and validation in the SeaweedFS fork or contribution workflow, not only in deployment docs.

Getting Started

Source: https://github.com/seaweedfs/seaweedfs/wiki/Getting-Started

What this page is about

• It contrasts the beginner-friendly weed mini path with the multi-component production path.
• It shows the minimal commands for master, volume, and combined single-host setups.
• It includes Docker-based bootstrap examples and persistence notes.

Actionable takeaways

• Use weed mini -dir=/data only for learning, demos, local validation, and quick S3 experiments.
• Treat weed server and explicit weed master plus weed volume commands as the baseline for production-oriented reasoning.
• Put the weed binary on every relevant host and inspect subcommand flags with ./weed -h, ./weed master -h, and ./weed volume -h before composing services.
• When starting a master, set -ip to a reachable address instead of relying on localhost if other nodes must join.
• When starting a volume server, define the master address, storage directory, and capacity limit deliberately instead of relying on defaults.
• If the master uses a non-default gRPC port, pass the master address as <host>:<port>.<grpcPort> to dependent services.
• For a simple one-master, one-volume topology, weed server is the shortest path for a combined process layout on one host.
• Validate installation by uploading a directory with weed upload and comparing logical file size to actual disk usage; text-heavy workloads may compress significantly.
• In containers, persist /data with Docker volumes or host mounts; the page explicitly points to volumes as the preferred persistence mechanism.
• Expose the standard service ports intentionally and document which interfaces are meant for admin, filer, S3, or volume access.
• Set -publicIp correctly in containerized or NATed deployments so clients and peers resolve the node address properly.

Gotchas / prohibitions

• Do not use weed mini for production; the page states it may change without backward compatibility guarantees.
• Do not assume localhost values work once nodes are distributed across machines or containers.
• Do not skip persistent storage planning for Docker deployments.
• Do not forget the gRPC port behavior when overriding master ports.

How to apply in a real repo

• Document two bootstrap modes separately: local learning (weed mini) and production (weed master plus weed volume or weed server).
• Keep example commands parameterized with explicit IPs, ports, and storage paths so operators do not cargo-cult local defaults.
• Add a smoke-test checklist around weed upload, cluster status, UI availability, and disk consumption after initial deploy.
• Make persistence and advertised address settings part of every Docker or Kubernetes deployment review.

Operations

Sources:

• https://github.com/seaweedfs/seaweedfs/wiki/System-Metrics
• https://github.com/seaweedfs/seaweedfs/wiki/weed-shell

System Metrics

What this page is about

• It explains SeaweedFS metrics export for Prometheus/Grafana in both push and pull modes.
• It shows how masters distribute push-gateway config to other components.

Actionable takeaways

• Choose push mode when a Prometheus Pushgateway fits the environment and pull mode when Prometheus can scrape each service directly.
• Set the metrics address on all masters when using push mode so volume servers and filers can inherit the target.
• Restart filers and volume servers after changing master metrics settings because they need to re-read the configuration.
• Use dedicated metrics ports per process when exposing scrape endpoints directly.
• Reuse the upstream Grafana dashboard as a starting point instead of building panels from scratch.
• Master and volume processes now export start_time_seconds, which is useful for restart detection and rollout dashboards.
• 4.29 exposes Admin Server Prometheus metrics; scrape it separately from master/volume/filer metrics when the admin worker participates in EC placement or vacuum workflows.
• 4.30 adds /healthz and /readyz probes across S3, IAM, volume, filer, and master services. Prefer readiness probes for traffic admission and health probes for restart decisions in orchestrated deployments.

Gotchas / prohibitions

• Do not change master metrics configuration and assume other services pick it up live.
• Do not reuse the same pull metrics port across several services on one host.

How to apply in a real repo

• Standardize one monitoring mode per environment to avoid half-configured push and pull setups.
• Keep metric-port and Pushgateway settings in the same deployment templates as service endpoints.

weed shell

What this page is about

• It presents weed shell as the main interactive maintenance surface for cluster, filer, volume, EC, S3, and remote-storage operations.
• It also shows the lock/unlock pattern for safe volume maintenance.

Actionable takeaways

• Treat weed shell as the operator console for controlled maintenance and recovery rather than ad-hoc HTTP calls alone.
• Use lock and unlock around volume-changing operations so concurrent cluster activity does not interfere with repairs.
• Rely on volume.fix.replication, volume.vacuum, volume.balance, ec.*, fs.meta.*, remote.*, and s3.* commands as the canonical operational toolkit.
• Use dry-run or preview-style flags such as -n before performing replication repair when possible.
• Use volume.check.disk, volume.fsck, fs.meta.cat, and fs.verify when diagnosing missing chunks or filer-to-volume inconsistencies.
• Recent shell updates add group-management commands and make s3.user.provision idempotent for existing users by attaching policy instead of failing the whole flow.
• When scripting weed shell, prompt suppression on piped input reduces brittle non-interactive automation.
• The 4.24-4.25 line is operationally important for erasure coding on multi-disk servers: the planner now treats (server, disk_id) distinctly, stale shards are pruned more safely, and same-server multi-disk EC reads/recovery are fixed.
• The 4.26-4.28 line extends that EC story: execution plans now keep explicit disk_id attribution, lost .ecx / .vif metadata can be reconstructed from local shards, and zero-sized volumes are no longer skipped by scrub/fsck workflows.
• The 4.29-4.30 line moves EC encode/repair to shared ecbalancer.Place placement and snapshots placement once per detection cycle, which matters for large topologies that previously timed out. It also improves credible-replica metrics, removes empty stub replicas before distributing EC shards, preserves .vif metadata when a coexisting regular volume is deleted, and re-notifies writable volumes after worker vacuum.
• volume.fsck no longer halts purge on a stuck read-only volume, and volume.merge verifies output before overwriting replicas. Keep those checks in repair runbooks instead of bypassing shell safety.
• Revalidate admin scripts after 4.24: several volume/admin RPCs and destructive operations now require admin auth.

Gotchas / prohibitions

• Do not run invasive volume operations without a lock.
• Do not skip the diagnostic commands when chunk loss symptoms appear; the shell gives the actual repair workflow.
• Do not treat 4.23 as a safe stop on multi-disk EC deployments; upstream explicitly calls out the 4.24 / 4.25 line as the safe upgrade path there.

How to apply in a real repo

• Build runbooks around weed shell commands instead of bespoke one-off admin scripts where practical.
• Keep copy-pastable repair sequences for under-replication, missing chunks, and remote-storage sync tasks.

Quick Start with weed mini

Source: https://github.com/seaweedfs/seaweedfs/wiki/Quick-Start-with-weed-mini

What this page is about

• It documents the all-in-one weed mini command for learning, prototyping, and small deployments.
• It explains which services start automatically, how S3 credentials work, and which web interfaces become available.
• It adds practical flags for ports, directories, reverse proxies, and IAM configuration.

Actionable takeaways

• Use weed mini -dir=/data when you need a single-process SeaweedFS sandbox with master, volume, filer, S3, WebDAV, Admin UI, and maintenance worker enabled together.
• Expect these default endpoints during local work: master :9333, filer :8888, S3 :8333, WebDAV :7333, Admin UI :23646, and volume :9340.
• Change data paths with -dir, and override ports explicitly with flags such as -master.port and -s3.port instead of relying on hard-coded defaults in scripts.
• If SeaweedFS sits behind Nginx, Cloudflare Tunnel, or another reverse proxy, set -s3.externalUrl so S3 request signing uses the externally visible URL.
• The page states that embedded IAM is available in mini, so it is viable for local S3 auth experiments without a separate IAM service.
• If no S3 credentials are configured, the S3 gateway starts in "Allow All" mode; this is convenient for development but unsafe for shared environments.
• Authentication turns on automatically as soon as any credentials are configured, whether through environment variables, -s3.config, Admin UI, or weed shell.
• For local credential bootstrap, set AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and S3_ENDPOINT before starting weed mini.
• The Admin UI can be used after startup to create or rotate identities dynamically.
• AWS CLI access patterns differ based on auth mode: use --no-sign-request only when the endpoint is intentionally unauthenticated.
• Keep -s3.iam.config or -s3.config under explicit configuration management when you need reproducible local or demo environments.
• Treat the performance section as a boundary marker: separate components, tune volume sizes, configure replication, and add monitoring before promoting a workload beyond mini.

Gotchas / prohibitions

• Do not promote weed mini to production; the page repeats that it is for learning, development, and testing.
• Do not expose the default unauthenticated S3 mode outside a trusted environment.
• Do not put SeaweedFS behind a reverse proxy without setting -s3.externalUrl if clients use signed S3 requests.
• Do not assume adding credentials is a no-op; it changes the gateway from open access to authenticated mode.

How to apply in a real repo

• Offer weed mini only as a developer bootstrap or CI smoke-test profile, never as the main production recipe.
• Write local runbooks that call out endpoint URLs, auth mode, and where credentials are sourced from.
• Include a reverse-proxy checklist for s3.externalUrl, TLS termination, and endpoint testing with signed requests.
• Make the transition path from mini to multi-component deployment explicit in the skill and any operator notes.

S3 API

This topic is consolidated into references/s3-gateway.md.

Open that file for the maintained guidance on the S3 gateway, auth, and IAM.

S3 Auth and IAM

This topic is consolidated into references/s3-gateway.md.

Open that file for the maintained guidance on S3 auth, IAM, static credentials, and OIDC integration.

S3 Client Tools

Sources:

• https://github.com/seaweedfs/seaweedfs/wiki/AWS-CLI-with-SeaweedFS
• https://github.com/seaweedfs/seaweedfs/wiki/rclone-with-SeaweedFS
• https://github.com/seaweedfs/seaweedfs/wiki/restic-with-SeaweedFS

AWS CLI with SeaweedFS

What this page is about

• It documents how to use AWS CLI against the SeaweedFS S3 endpoint.
• It covers endpoint config, signature version, reverse-proxy caveats, presigned URLs, and encryption examples.

Actionable takeaways

• Point AWS CLI at SeaweedFS with --endpoint-url and keep signature version on s3v4.
• Set a region and credentials even for local or test use, because the client expects them for request signing.
• Use presigned URLs when authenticated objects need temporary shareable access without exposing static credentials.
• Validate reverse-proxy subpath behavior carefully; the docs call it undefined relative to normal S3 domain conventions and require X-Forwarded-Prefix handling.
• Test SSE-S3, SSE-KMS, and SSE-C flows from the same CLI clients teams already use for AWS.

Gotchas / prohibitions

• Do not rely on subpath-hosted S3 endpoints unless you have explicitly validated forwarded-prefix handling.
• Do not forget to force SigV4 when using AWS CLI with SeaweedFS.

How to apply in a real repo

• Publish one standard AWS CLI profile or wrapper example for SeaweedFS endpoints.
• Include presign and encryption smoke tests in S3 compatibility validation.

rclone with SeaweedFS

What this page is about

• It shows rclone configuration against the SeaweedFS S3 endpoint, including path-style access and multipart tuning.
• It also includes an example of client-side encryption through an external KMS shim.

Actionable takeaways

• Configure rclone as provider = Other with force_path_style = true against the SeaweedFS endpoint.
• Tune multipart thresholds such as upload_cutoff and chunk_size intentionally for your object sizes and network path.
• Use rclone for efficient bulk copy workflows where checksums and fast-listing behavior matter.
• Treat client-side encryption as separate from SeaweedFS SSE modes; the example uses an external KMS helper.

Gotchas / prohibitions

• Do not assume reverse-proxy subpaths are standard S3 behavior; validate forwarded-prefix handling if you must use them.

restic with SeaweedFS

What this page is about

• It explains how to use SeaweedFS as an S3-compatible restic backend.
• It emphasizes that credentials are required even when the values are effectively arbitrary in a local setup.

Actionable takeaways

• Provide AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY in both SeaweedFS and restic environments, because restic expects non-anonymous S3 auth.
• Pre-create and authorize the target bucket before initializing a restic repository on SeaweedFS.
• Use SeaweedFS as a practical local or self-hosted S3 backend for restic repository storage.

Gotchas / prohibitions

• Do not expect restic to work reliably against anonymous S3 access.
• Do not skip bucket creation and basic S3 auth setup before running restic init.

How to apply in a real repo

• Publish tested rclone and restic examples alongside AWS CLI instructions so operators can use the tool that matches their backup workflow.
• Validate backup/restore or copy/list flows with real endpoint URLs, auth, and proxy layout.

S3 Gateway

Sources:

• https://github.com/seaweedfs/seaweedfs/wiki/Amazon-S3-API
• https://github.com/seaweedfs/seaweedfs/wiki/S3-Configuration
• https://github.com/seaweedfs/seaweedfs/wiki/S3-Credentials
• https://github.com/seaweedfs/seaweedfs/wiki/OIDC-Integration

Amazon S3 API

What this page is about

• It explains how weed s3 exposes an S3-compatible gateway backed by filer.
• It covers bucket-to-collection mapping, multi-node deployment, reverse-proxy behavior, and authentication modes.

Actionable takeaways

• Treat the S3 gateway as a stateless protocol layer over filer, not as an independent storage plane.
• Remember that each bucket maps to /buckets/<bucket_name> and its own collection, which makes bucket deletion efficient but amplifies volume planning needs.
• Lower -volumeSizeLimitMB and configure /buckets/ path behavior when the environment will host many buckets.
• Run multiple S3 nodes against one or more filers when horizontal scaling is needed; colocating filer and S3 is the simplest multi-node pattern.
• Plan reverse-proxy deployments around forwarded-host, forwarded-port, and forwarded-prefix handling so SigV4 validation remains correct.
• Understand the auth mode switch: no credentials means Allow All, any configured identity means authenticated mode.
• Use static config, dynamic s3.configure, Admin UI, or OIDC/IAM config according to the deployment's identity lifecycle.
• Scope actions per bucket whenever possible instead of handing out broad global permissions.

Gotchas / prohibitions

• Do not expose the default unauthenticated S3 mode outside trusted environments.
• Do not ignore bucket-per-collection volume growth when sizing multi-tenant S3 clusters.
• Do not put S3 behind a reverse proxy without testing forwarded-header and signature behavior.

S3 Configuration

What this page is about

• It separates SeaweedFS S3 auth into two systems: basic credentials and advanced IAM/STS.
• It explains zero-config behavior, config precedence, reverse-proxy handling, and key fallback rules for IAM mode.

Actionable takeaways

• Choose -s3.config for static access-key style users and -s3.iam.config for OIDC, STS, roles, and policy documents.
• Treat zero-config mode as convenience, not security: it enables open access unless policies explicitly default to deny.
• Remember that in-memory policy storage is ephemeral unless IAM config uses persistent filer-backed storage.
• Use -s3.externalUrl or correct forwarded headers when the S3 gateway sits behind proxies and SigV4 validation depends on public URL shape.
• Keep basic identities out of -s3.iam.config; that file is for IAM/STS structures, not identities.
• Use both config systems together when static access-key users and OIDC/STS users must coexist.
• Understand STS signing-key fallback order so cluster key management stays predictable.

Gotchas / prohibitions

• Do not mistake zero configuration for secure-by-default behavior.
• Do not put identities into IAM config and expect them to load.
• Do not rely on default in-memory policies if persistence across restarts matters.

S3 Credentials

What this page is about

• It details the basic access-key credential system used by -s3.config.
• It covers config precedence, Admin UI integration, environment-variable fallback, and bucket-scoped permissions.

Actionable takeaways

• Prefer a dedicated config file for production-grade static credentials.
• Use filer-backed credential storage or Admin UI when you need live updates without restarting S3 nodes.
• Treat environment variables as fallback convenience, not the main production control plane.
• Leverage bucket-scoped actions or wildcard bucket patterns to keep user permissions narrow.
• Remember that higher-priority config sources override lower-priority ones completely; SeaweedFS does not merge them.
• Use multiple credentials per identity when key rotation or multiple clients must map to the same logical user.

Gotchas / prohibitions

• Do not expect config file, filer config, and env vars to merge.
• Do not grant global Admin when a bucket-scoped permission set is enough.
• Do not rely on fallback env vars if an older filer-backed config may still override them.

OIDC Integration

What this page is about

• It explains advanced IAM mode for OIDC, STS, role mapping, and IAM-style policies.
• It documents provider configuration, trust policies, and group/claim-to-role mapping.

Actionable takeaways

• Use -s3.iam.config when identity comes from OIDC providers such as Keycloak, Okta, Auth0, Azure AD, Google, or Cognito.
• Model the configuration around four pieces: sts, providers, policies, and roles.
• Use role-mapping rules on claims such as groups to map IdP identities onto SeaweedFS IAM roles.
• Keep TLS validation explicit with CA certificates and avoid tlsInsecureSkipVerify outside testing.
• Define trust policies tightly so only the intended issuer and web-identity flow can assume a role.
• Keep a default role only when the security model truly wants an implicit fallback.

Gotchas / prohibitions

• Do not mix static access-key identities into IAM config.
• Do not disable TLS verification for a real IdP deployment.
• Do not use overly broad trust policies if the IdP serves multiple applications or realms.

How to apply in a real repo

• Publish one auth decision tree: open test mode, static credentials, or full IAM/STS/OIDC.
• Keep proxy-aware S3 endpoint configuration in the same place as TLS and public URL settings.
• Standardize one production credential-management path: file-based or filer/Admin-UI-backed.
• Use bucket-scoped permissions by default for tenant isolation.
• Align IdP claim design, SeaweedFS role names, and IAM policy scope before rollout.
• Validate the full login-to-role-assumption path in staging, including JWKS refresh and token expiry behavior.

Patch-level IAM notes (4.20)

• Embedded IAM now supports ListUserPolicies and group inline policy actions, which reduces the need for external policy bookkeeping when operating many S3 identities.
• User-policy round trips preserve the exact policy document more reliably, and GetUserPolicy fallback no longer drops actions/resources.
• DeleteBucket now prunes bucket-scoped IAM actions tied to that bucket, so cleanup is safer after tenant teardown.
• In S3 failover flows, ErrNotFound is no longer treated as filer health failure by itself; treat missing objects differently from actual filer unavailability.

Patch-level audit note (4.28)

• 4.28 populates requester identity more consistently for GET/HEAD and IAM-related S3 operations. If you depend on SeaweedFS audit logs for investigations or compliance, refresh dashboards/parsers after upgrade so they ingest the richer requester field instead of assuming only write-path attribution.

Patch-level S3 notes (4.29 -> 4.30)

• 4.29 routes more S3 object mutations to the owning filer through filer-side ObjectTransaction and ObjectTransactionBatch flows, including versioned puts, copy/delete-marker handling, multipart completion, object-lock writes, and metadata-only self-copy. Expect less pressure on distributed locks, but retest multi-filer object-write concurrency before removing downstream serialization.
• Bucket configuration writes now use field-level filer patches, and object-lock paths gained extended-attribute guard clauses. Revalidate bucket/object-lock automation that previously rewrote whole config documents.
• IAM/OIDC trust-policy examples now use the oidc: condition prefix. Keep local examples aligned so web-identity role assumption tests match upstream semantics.
• 4.30 rejects .. in S3/Iceberg URL path variables, validates ownership-control rules, honors MetadataDirective=REPLACE for system metadata on CopyObject, and authenticates JWT unsigned-streaming uploads. Treat this as both a compatibility and security regression-test target.
• Anonymous unsigned-streaming PutObject is allowed only through the intended unauthenticated path; do not confuse that with a recommendation to expose unsigned uploads on production gateways.

Security

Sources:

• https://github.com/seaweedfs/seaweedfs/wiki/Security-Overview
• https://github.com/seaweedfs/seaweedfs/wiki/Security-Configuration

Security Overview

What this page is about

• It separates SeaweedFS security into control-plane gRPC mTLS and data-plane HTTP/HTTPS plus JWT controls.
• It explains how masters, filers, volumes, and S3 interact under that security model.

Actionable takeaways

• Secure gRPC and HTTP independently; they are different communication planes with different configuration blocks.
• Use mutual TLS for gRPC between masters, volumes, filers, S3, and other clients when cluster trust boundaries matter.
• Use JWT on volume writes and optionally reads when direct volume access must be controlled.
• Use filer JWT keys when filer HTTP must be protected and S3 still needs to proxy through it.
• Keep short JWT lifetimes in mind; volume-file tokens are intentionally brief and file-id-scoped.
• Disable unnecessary HTTP surfaces or directory metadata exposure if public access is not intended.
• Recent 4.24-4.25 releases tightened admin auth on destructive/admin endpoints and filer IAM gRPC calls; treat older unauthenticated admin automation as suspect until revalidated.
• If security.toml is enabled, explicitly test Admin UI and filer IAM paths together, because the 4.25 line fixed an auth propagation issue there.

Gotchas / prohibitions

• Do not enable HTTPS on filer or volume without also enabling the matching client-side HTTPS config.
• Do not expose filer UI or directory metadata casually on public endpoints.
• Do not assume unknown file ids alone are an adequate security boundary once services are internet-facing.

Security Configuration

What this page is about

• It documents security.toml, JWT keys, TLS settings, and environment-variable overrides.
• It serves as the concrete configuration map for the security model above.

Actionable takeaways

• Generate security.toml with weed scaffold -config=security and version-control only the non-secret parts.
• Prefer environment variables for JWT keys and TLS secret paths when deployment config is stored in Git or templates.
• Keep the same relevant JWT config synchronized across all services that must mint or validate those tokens.
• Use the guard whitelist and CORS settings deliberately; they are not substitutes for real auth, but they narrow exposure.
• Treat the filer signing key as security-sensitive beyond filer auth because it also participates in STS fallback behavior.
• Recent IAM/S3 updates also harden the default posture: users with no policies are denied, OIDC/web-identity support is broader, and auditability/revocation options increased. Reflect that in runbooks instead of assuming older permissive behavior.

Gotchas / prohibitions

• Do not leave JWT keys empty when you intend the associated protections to be active.
• Do not forget to distribute the same security config to all participating services that validate a given token type.
• Do not store plaintext secrets in committed config when env var overrides are available.
• Do not assume old admin endpoints remain callable without admin auth; 4.24 tightened several destructive and diagnostic paths.

How to apply in a real repo

• Publish one security baseline covering mTLS, JWT write/read controls, HTTPS, UI exposure, and secret injection.
• Keep separate environment templates for local, internal production, and internet-facing deployments.
• Test every enabled security layer end-to-end, including S3-to-filer HTTPS/JWT flows.

Topology and Setup

Sources:

• https://github.com/seaweedfs/seaweedfs/wiki/Components
• https://github.com/seaweedfs/seaweedfs/wiki/Production-Setup

Components

What this page is about

• It defines the core SeaweedFS services and how they combine into object, file, and S3 access paths.
• It explains the master quorum model, volume responsibilities, and the role of the optional filer and S3 layers.
• It introduces volume and collection concepts that directly affect sizing and bucket design.

Actionable takeaways

• Treat SeaweedFS as two layers: the core object store (master plus volume) and the higher-level access layer (filer, s3, WebDAV, FUSE, and related front doors).
• Run an odd number of master servers so Raft can form a majority; 1 or 3 stable masters are the practical defaults the page emphasizes.
• Keep the master set small and reliable instead of scaling the quorum broadly; more unstable masters weaken the control plane rather than improving it.
• Expect the elected leader to assign file ids, place writes onto volumes, and maintain the authoritative cluster view.
• Plan volume servers around capacity and redundancy at the volume level rather than at the individual object level.
• Use filer when applications need path semantics, directories, or filesystem-like access patterns instead of only object ids.
• Use the S3 service as an optional access layer on top of filer semantics when AWS-compatible buckets are required.
• Model storage growth around volumes, not individual files: a volume is a large container file that packs many smaller objects together.
• Revisit the default volume sizing (30GB) and auto-created volume count (8) before deploying small-disk or bucket-heavy environments.
• Use collections to separate datasets, lifecycle requirements, or S3 buckets; bucket deletion is fast because it maps to removing the collection's volumes.
• Lower the volume size limit if many collections or buckets would otherwise reserve too much disk headroom.

Gotchas / prohibitions

• Do not deploy an even number of masters; quorum behavior depends on an odd-sized set.
• Do not assume more masters automatically improve reliability; the page recommends a small stable quorum.
• Do not size capacity per file or per bucket alone; replication and TTL apply per volume.
• Do not forget that each S3 bucket gets its own collection, which can amplify disk planning mistakes when default volume sizes stay large.

How to apply in a real repo

• Document the topology explicitly: control plane masters, data plane volume servers, metadata plane filer store, and any protocol gateways.
• Include a bucket and collection sizing rule in runbooks so operators evaluate volume size limits before creating many tenants.
• Separate application-facing endpoints by protocol and note which ones depend on filer being present.
• Treat master quorum count, volume size limit, and collection strategy as first-class architecture decisions rather than bootstrap defaults.

Production Setup

What this page is about

• It assembles the production deployment from the bottom up: masters, volume servers, filer store, filer, then optional S3 or FUSE access.
• It adds practical port, IP, and multi-disk guidance for single-node and distributed clusters.
• It explains how SeaweedFS expects operators to handle balancing and maintenance in real environments.

Actionable takeaways

• Build production incrementally: stabilize object storage first, then add filer-backed file services, then add S3, FUSE, metrics, and security.
• Open and document the default service ports explicitly: master 9333/19333, volume 8080/18080, filer 8888/18888, and S3 8333.
• Set -ip carefully on multi-homed hosts so inter-node communication uses the intended network path.
• If a service should listen on one address but advertise another, combine -ip and -ip.bind intentionally instead of relying on interface defaults.
• For single-node setups that still need filer and S3, weed server -filer -s3 is the compact starting point, but volume sizing still needs manual review.
• Reduce -master.volumeSizeLimitMB on smaller hosts so one server can keep several writable volumes instead of exhausting space on a few oversized defaults.
• When running multiple masters, define the full -peers list consistently on every node and keep the master data directory persistent.
• Add -metrics.address in production if Prometheus scraping or push-based metrics collection is part of the environment.
• On volume servers, use -dataCenter and -rack deliberately because replication placement depends on this topology metadata.
• If one host has several physical disks, either provide a comma-separated -dir list with matching -max values or run multiple volume servers on different ports.
• Use -index=leveldb on very large volume servers to reduce memory pressure from index handling.
• Throttle maintenance impact on hot nodes with -compactionMBps rather than letting compaction consume unbounded disk bandwidth.
• Expect new capacity to receive new writes but not automatic rebalance of existing data; manual weed shell commands are the explicit maintenance path.
• Recent master updates make volume assignment more size-aware and drain pending size before marking a volume readonly, which improves placement predictability during high-ingest periods.
• If a topology has more racks than the requested replica count, upgrade before diagnosing endless new-volume growth as a capacity problem; 4.20 fixes one such placement bug.
• Generate filer.toml with weed scaffold -config=filer and choose the filer store according to HA and scale needs instead of accepting leveldb2 blindly.
• Treat a shared filer store plus multiple peer filer processes as the recommended production model because it makes filers stateless.
• Start S3 alongside filer when possible so the S3 endpoint follows the same filer-backed metadata view and multi-filer setup stays simpler.
• Use weed mount -volumeServerAccess=filerProxy when clients sit outside the internal cluster and only filer should be exposed publicly.
• Prefer scheduled balancing and replication repair during off-hours instead of continuous aggressive rebalancing.

Gotchas / prohibitions

• Do not build a two-master cluster; the page explicitly says two nodes cannot reach consensus safely.
• Do not use multiple -dir values on the same physical disk, because the automatic volume accounting will overestimate usable capacity.
• Do not assume replication placement across multiple volume processes on one host equals physical host redundancy.
• Do not rely on the default local filer store when you need multiple filers or shared metadata.
• Do not expect new volume servers to backfill old data automatically; rebalance is manual by design.

How to apply in a real repo

• Separate deployment recipes into layers: masters, volumes, filer store, filer, S3/FUSE, and maintenance jobs.
• Make network advertisement, rack/datacenter labels, and volume sizing mandatory config inputs in templates.
• Treat filer store selection and shared metadata design as an architecture review item, not a post-deploy tweak.
• Put manual balancing and replication repair into scheduled ops procedures rather than assuming background self-healing.