seaweedfs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

本技能是一份实用指南，用于基于上游仓库和Wiki部署与运维SeaweedFS。

优先选择多组件部署的生产环境指导，而非

weed mini

快捷方式。

Quick Navigation

快速导航

Situation	Open
Learn the system shape and bootstrap paths	`references/getting-started.md`
Stand up a local all-in-one sandbox	`references/quick-start-mini.md`
Review control-plane, volume, and collection topology	`references/topology-and-setup.md`
Check master, volume, filer, and client API surfaces	`references/api-surfaces.md`
Set replication, TTL, failover masters, and env vars	`references/configuration.md`
Work with performance notes, FAQ topics, and examples	`references/benchmarks-and-use-cases.md`
Work with filer metadata, uploads, JWT, and TUS	`references/filer-core.md`
Choose and scale filer metadata stores	`references/filer-stores.md`
Operate S3 buckets, auth, and IAM/OIDC	`references/s3-gateway.md`
Plan Cloud Drive and remote storage mounts	`references/cloud-drive.md`
Run backups, metrics, repairs, and shell workflows	`references/backup-and-replication.md` , `references/operations.md`
Choose S3 encryption and client tooling	`references/encryption.md` , `references/s3-client-tools.md`
Review transport, JWT, TLS, and exposure controls	`references/security.md`

场景	打开路径
了解系统架构与启动路径	`references/getting-started.md`
搭建本地一体化沙箱环境	`references/quick-start-mini.md`
查看控制平面、卷与集合拓扑结构	`references/topology-and-setup.md`
查看Master、Volume、Filer及客户端API接口	`references/api-surfaces.md`
设置复制策略、TTL、故障转移Master及环境变量	`references/configuration.md`
查看性能说明、常见问题及示例	`references/benchmarks-and-use-cases.md`
处理Filer元数据、上传、JWT及TUS	`references/filer-core.md`
选择并扩展Filer元数据存储	`references/filer-stores.md`
运维S3存储桶、认证及IAM/OIDC	`references/s3-gateway.md`
规划Cloud Drive与远程存储挂载	`references/cloud-drive.md`
执行备份、指标监控、修复及Shell工作流	`references/backup-and-replication.md` , `references/operations.md`
选择S3加密方案与客户端工具	`references/encryption.md` , `references/s3-client-tools.md`
查看传输、JWT、TLS及暴露控制	`references/security.md`

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

规划SeaweedFS部署
在开发或生产环境中运行
```
weed
```
组件
设计Filer、S3或云分层拓扑结构
选择元数据存储与复制模式
为公开或多租户使用加固SeaweedFS
运维备份、指标监控及集群修复工作流

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.

SeaweedFS将卷管理与文件、对象访问路径分离。
Filer层添加了目录、元数据存储及更高层级的协议。
S3、WebDAV、FUSE及其他接口是构建在同一存储服务之上的入口。
生产环境部署应明确记录拓扑结构、凭证、持久化、监控及恢复路径。

Release Highlights (4.40)

版本亮点（4.40）

S3 correctness:
```
CopyObject
```
on a missing source now returns
```
NoSuchKey
```
/
```
NoSuchBucket
```
instead of a misleading error, invalid tagging on
```
CopyObject
```
returns
```
InvalidTag
```
,
```
PutObjectAcl
```
and object-tagging writes for nested keys target the correct object, and raw semicolons in query strings are accepted.
IAM/OIDC hardening: role trust policy is now enforced on direct OIDC bearer-token requests, not only on formal
```
AssumeRoleWithWebIdentity
```
flows.
Filer/TUS security: TUS resumable-upload session authorization is hardened so
```
HEAD
```
/
```
PATCH
```
/
```
DELETE
```
are restricted to the session's own target path, closing a cross-prefix access gap;
```
filer.backup
```
no longer silently loses data on a transient not-found error; log-buffer flushing is optimized with generated vtproto marshalers.
Erasure coding: new
```
ec.check.replication
```
shell command,
```
ec.encode
```
no longer rebalances against a topology snapshot that predates its own new shards, and stale
```
.ecsum
```
checksum sidecars are removed on shard destroy (Go/Rust aligned).
Shell/admin:
```
volume.tier.upload
```
preserves existing replicas,
```
volume.check.disk
```
gains
```
-resurrectMissingNeedles
```
,
```
weed shell
```
shows the current cluster lock holder, and
```
cluster.ps
```
lists S3 servers.
Core: master used-size statistics cover all collections, the Rust volume server verifies
```
.dat
```
integrity against the last indexed needle, and mount surfaces
```
ENOSPC
```
instead of waiting indefinitely.

S3正确性：对不存在的源执行
```
CopyObject
```
时，现在返回
```
NoSuchKey
```
/
```
NoSuchBucket
```
而非误导性错误；
```
CopyObject
```
上的无效标签返回
```
InvalidTag
```
；针对嵌套键的
```
PutObjectAcl
```
和对象标签写入会定位到正确对象；查询字符串中的原始分号已被接受。
IAM/OIDC加固：角色信任策略现在会在直接OIDC承载令牌请求时强制执行，而非仅在正式的
```
AssumeRoleWithWebIdentity
```
流程中。
Filer/TUS安全性：TUS可恢复上传会话授权已加固，
```
HEAD
```
/
```
PATCH
```
/
```
DELETE
```
操作被限制为仅能访问会话自身的目标路径，填补了跨前缀访问漏洞；
```
filer.backup
```
不再在短暂的未找到错误时静默丢失数据；使用生成的vtproto编组器优化了日志缓冲区刷新。
纠删码：新增
```
ec.check.replication
```
Shell命令；
```
ec.encode
```
不再针对早于自身新分片的拓扑快照进行重新平衡；销毁分片时会移除过时的
```
.ecsum
```
校验和副文件（与Go/Rust实现对齐）。
Shell/管理：
```
volume.tier.upload
```
保留现有副本；
```
volume.check.disk
```
新增
```
-resurrectMissingNeedles
```
参数；
```
weed shell
```
显示当前集群锁持有者；
```
cluster.ps
```
列出S3服务器。
核心功能：Master已使用空间统计覆盖所有集合；Rust卷服务器会根据最后索引的Needle验证
```
.dat
```
文件的完整性；挂载时返回
```
ENOSPC
```
而非无限等待。

Release Highlights (4.25)

版本亮点（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.

安全/管理路径：
```
4.24
```
-
```
4.25
```
版本收紧了对破坏性/管理端点的管理员认证，并通过在Filer IAM gRPC调用中附加管理员签名的认证信息，修复了
```
security.toml
```
下的Admin UI行为。
纠删码/多磁盘操作：该版本系列修复了多磁盘及跨服务器布局中的多个EC规划/恢复场景，包括过时分片清理及更安全的源卷删除。
S3/IAM加固：无策略的IAM用户现在会被拒绝而非默认过度授权，同时OIDC/Web身份及审计功能持续完善。

Release Highlights (4.26 -> 4.28)

版本亮点（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.

纠删码/多磁盘操作：EC规划现在能更可靠地在磁盘间分配分片，执行规划中包含
```
disk_id
```
，并且在恢复过程中可从本地分片重建丢失的
```
.ecx
```
/
```
.vif
```
元数据。
完整性检查：清理/fsck流程现在会考虑零大小卷，而非静默跳过，这对稀疏或新建的拓扑结构至关重要。
Filer后端可靠性：Redis3修复了跳表末端的崩溃路径，基于SQL的Filer存储不再强制禁用空闲连接池。
S3审计追踪：GET/HEAD/IAM操作的请求者身份填充更一致，提升了合规性与事件排查效率。
高可用心跳路径：Master现在接受 follower副本上的卷服务器ping目标，提升了多Master部署中的故障转移可见性。

Release Highlights (4.34 -> 4.39)

版本亮点（4.34 -> 4.39）

S3 correctness/compliance: preserved multipart-copy checksums, account-less identities get distinct owners instead of admin, SigV4 query-value sorting, Range-offset validation, tag-value equals-sign preservation, and static config-file hot reload (
```
4.34
```
-
```
4.36
```
).
Iceberg / S3 Tables: namespace property updates, table registration, multi-table transaction commits, view support, table rename, and caller-scoped S3 Tables authorization (
```
4.36
```
).
IAM/STS: AssumeRole authorized by the role trust policy, STS session-policy explicit-deny enforcement, and OIDC groups/roles surfaced for resource-policy ABAC (
```
4.36
```
).
Volume-server crash safety: never delete recoverable EC shards on startup, crash-safe compaction commit with a durable
```
.cpc
```
marker, and phantom-volume detection for deleted-but-open descriptors (
```
4.34
```
-
```
4.35
```
).
Erasure coding correctness (Rust parity): EC scrub improvements, EC storage/read-path fixes, and Rust volume-server scrub parity, plus S3 CRC checksumming support (
```
4.38
```
).
FUSE mounts: write-pattern detection for concurrent writeback tolerance windows and cached supplementary group IDs for faster non-root access (
```
4.35
```
).
Performance/observability: performance CI with profiling and throughput benchmarks, Rust volume-server streaming optimizations, native sparkline trends and per-bucket S3 metrics in the admin dashboard, and large cold
```
GetObject
```
returning
```
503
```
instead of hanging (
```
4.34
```
-
```
4.37
```
).
Ops: async buffered writes in EC-shard copy, volume-tiering and filer-metadata optimizations, S3 quota measurement by logical size, and mount-failover enhancements (
```
4.39
```
).

S3正确性/合规性：保留分段复制校验和；无账户身份获得独立所有者而非管理员；SigV4查询值排序；Range偏移验证；标签值等号保留；静态配置文件热重载（
```
4.34
```
-
```
4.36
```
）。
Iceberg / S3表：命名空间属性更新、表注册、多表事务提交、视图支持、表重命名及调用者范围的S3表授权（
```
4.36
```
）。
IAM/STS：角色信任策略授权AssumeRole；STS会话策略显式拒绝强制执行；OIDC组/角色用于资源策略ABAC（
```
4.36
```
）。
卷服务器崩溃安全性：启动时绝不删除可恢复的EC分片；使用持久化
```
.cpc
```
标记实现崩溃安全的压缩提交；检测已删除但仍打开的描述符对应的幽灵卷（
```
4.34
```
-
```
4.35
```
）。
纠删码正确性（与Rust实现对齐）：EC清理改进、EC存储/读取路径修复、Rust卷服务器清理对齐，以及S3 CRC校验支持（
```
4.38
```
）。
FUSE挂载：写入模式检测以支持并发回写容忍窗口；缓存补充组ID以提升非根用户访问速度（
```
4.35
```
）。
性能/可观测性：带性能分析和吞吐量基准的性能CI；Rust卷服务器流优化；管理仪表板中的原生sparkline趋势及每个存储桶的S3指标；大型冷对象
```
GetObject
```
返回
```
503
```
而非挂起（
```
4.34
```
-
```
4.37
```
）。
运维：EC分片复制中的异步缓冲写入；卷分层及Filer元数据优化；按逻辑大小统计S3配额；挂载故障转移增强（
```
4.39
```
）。

Release Highlights (4.31 -> 4.33)

版本亮点（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
```
).

S3版本控制/IAM：原子化版本化
```
PutObject
```
提交；正确返回
```
NoSuchVersion
```
错误；最新指针修复与恢复；暂停版本化的删除处理；托管IAM策略版本；存储桶只读配额强制执行；
```
4.33
```
版本还修复了HTTP日期条件、校验和 trailer头及空v4签名头名称问题。
纠删码完整性：每个分片的校验和副文件用于位腐检测（
```
4.31
```
）；跨机器均匀分配分片，将共存服务器视为单一故障域，删除前验证分片落地（
```
4.32
```
）；防止不同编码运行的EC分片混合，或重启后遗留幽灵
```
.dat
```
文件（
```
4.33
```
）。
卷服务器：修复自动大小磁盘上的
```
maxVolumeCount
```
死区；删除尾部压缩后保持卷可写；重启时从
```
.vif
```
解析EC数据分片数量（
```
4.31
```
）；新增
```
CheckDisk
```
磁盘健康检测（
```
4.32
```
）。
Filer可扩展性：限制BFS元数据内存及字节字典序S3列表顺序（
```
4.31
```
）；流式元数据订阅日志文件（
```
4.32
```
）；对象大小分布指标、挂载重连OOM修复、按块重放、有限刷新队列及Elasticsearch 8（
```
elastic8
```
）支持（
```
4.33
```
）。
管理/工作流：感知 lanes的调度器修剪；
```
-dataDir
```
默认用于持久化状态及启动时重新加载进行中的任务（
```
4.32
```
）；全集群卷列表JSON导出（
```
4.33
```
）。
Rust卷服务器：限制请求体/存储内容扩展以防止负载下OOM（
```
4.31
```
）；修复重启时EC分片删除遗留的幽灵
```
.dat
```
文件（
```
4.33
```
）。

Release Highlights (4.29 -> 4.30)

版本亮点（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.

S3写入/认证路径：对象写入转向Filer端所有者路由及
```
ObjectTransaction
```
批量处理，减少分布式锁压力；
```
4.30
```
版本还收紧了路径遍历拒绝、所有权控制验证、
```
MetadataDirective=REPLACE
```
及无签名流式上传的JWT处理。
FUSE与Filer协调：POSIX advisory锁现在通过
```
-dlm
```
路由至Filer所有权管理，包含会话租约、保活、环变更冷却及跨挂载写入工作负载的回写缓存崩溃修复。
纠删码与卷修复：EC放置使用共享的
```
ecbalancer.Place
```
路径及放置快照，
```
4.30
```
版本改进了可信副本选择、空存根清理、
```
.vif
```
保留、真空操作后可写卷通知，以及针对只读卷卡住和合并验证的Shell安全性。
运维接口：管理员界面暴露Prometheus指标；S3/IAM/卷/Filer/Master进程添加
```
/healthz
```
和
```
/readyz
```
探针用于编排检查。
Filer、同步及远程接收器：Redis2现在在KV方法中应用
```
keyPrefix
```
；Postgres Filer写入默认使用
```
ON CONFLICT
```
upsert；从发现中移除已下线的Filer；同步/远程存储路径更可靠地保留块大小、清单、偏移量及MIME元数据。

Release Highlights (4.20)

版本亮点（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.

S3/IAM：嵌入式IAM流程新增
```
ListUserPolicies
```
、组内联策略操作、更安全的用户策略往返，以及
```
DeleteBucket
```
时的存储桶范围清理。
挂载/FUSE：
```
weed mount
```
新增
```
-dlm
```
用于跨挂载写入协调，改进了POSIX元数据行为、
```
nlink
```
统计及Filer RPC效率。
Master放置：卷分配更具大小感知性；只读转换先排空待处理大小；修复了可能导致某些DC/机架布局中无限增长的拓扑漏洞。
Filer可靠性：提升了PgBouncer/Postgres兼容性；修复了优雅关闭时的损坏问题；移除了导致内存/CPU回归的冗余Filer磁盘读取。
运维接口：
```
weed shell
```
新增组管理助手；S3用户配置更安全地处理现有用户；Master/Volume现在导出
```
start_time_seconds
```
指标。

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.

不要在生产环境中使用
```
weed mini
```
。
不要将单二进制文件的默认配置视为生产安全配置。
在审查认证、TLS及网络边界之前，不要公开暴露S3或Filer端点。
不要在未验证高可用、扩展及备份特性的情况下选择Filer存储。
不要在未验证恢复能力的情况下设计备份或复制流程。

seaweedfs

Original

Translation

SeaweedFS

SeaweedFS

Quick Navigation

快速导航

When to Use

适用场景

Core Mental Model

核心思维模型

Release Highlights (4.40)

版本亮点（4.40）

Release Highlights (4.25)

版本亮点（4.25）

Release Highlights (4.26 -> 4.28)

版本亮点（4.26 -> 4.28）

Release Highlights (4.34 -> 4.39)

版本亮点（4.34 -> 4.39）

Release Highlights (4.31 -> 4.33)

版本亮点（4.31 -> 4.33）

Release Highlights (4.29 -> 4.30)

版本亮点（4.29 -> 4.30）

Release Highlights (4.20)

版本亮点（4.20）

Prohibitions

禁止事项

Links

相关链接