seaweedfs

SeaweedFS

此技能是一个实用路由指南，可根据上游代码仓库和 Wiki 部署与运维 SeaweedFS。

生产环境建议优先参考多组件部署指南，而不是 weed mini 之类的快捷方案。

快速导航

场景	打开
了解系统架构和引导方式	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

适用场景

• 规划 SeaweedFS 部署
• 在开发或生产环境中运行 weed 组件
• 设计 filer、S3 或云分层拓扑
• 选择元数据存储和复制模式
• 加强 SeaweedFS 的安全性，以用于公开场景或多租户场景
• 运维备份、指标和集群修复工作流

核心概念

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

4.48 版本亮点

• S3 可信代理（aws:SourceIp）：在 security.toml 中配置允许列表，可在不重新引入地址伪造漏洞的情况下恢复对转发标头的支持。直接 TCP 对端位于允许列表中时，会从右向左遍历 X-Forwarded-For（然后检查 X-Real-Ip）以确定 aws:SourceIp；否则使用直接对端地址。此设置适用于存储桶策略引擎、IAM 附加策略引擎，以及 IAM 角色/会话策略中间件。请参阅 references/s3-gateway.md 和 references/security.md。
• 管理端绑定默认值：配置 -adminPassword 或 [https.admin] mTLS 时，-ip 默认值会自动升级为 0.0.0.0；未配置身份验证的部署仍默认绑定回环地址，显式指定的 -ip 始终优先。管理端 worker/plugin gRPC 控制平面现在也会遵循 -ip，而不再绑定所有接口。
• 远程存储和分层存储的分片并发：可针对每个远程存储（remote.configure -upload_concurrency / -download_concurrency）以及 master.toml 中的每个 S3 后端配置 upload_concurrency / download_concurrency；volume.tier.upload|download|move|evict 支持 -concurrent 标志。未设置或设为 0 时沿用之前的默认值（S3 上传 1 个分片，下载 5 个分片）。请参阅 references/cloud-drive.md。
• S3 正确性：ListMultipartUploads 现在会返回 Initiated 时间戳（重复列出时保留原始时间）；POST 策略上传会保留对象版本；删除版本时会遵循对象锁保留期限；对象锁配置与对象锁操作会分别进行授权；排序在前缀之前的列表标记不会排除任何内容；错误响应前会排空请求正文；分片上传完成会原子地提交上传并移除 .uploads。
• Helm：为生成的只读 S3 身份授予 List 权限；主节点配置变更时会滚动重启主节点 Pod；admin.allowInsecureBind 可通过管理端身份验证渲染检查。
• Filer：已接受的元数据日志记录在关闭后仍会保留；关闭路径会在元数据存储关闭前完成汇合；Filer 新增了自己的 disableHttp 标志；并清理了清单解析错误的传播逻辑。
• Shell：fs.verify -pruneEntries 会删除针叶丢失的条目；fs.mergeVolumes 在源卷仅包含孤立针叶时会发出警告。
• Rust 卷：升级至 tonic/prost 0.14；尾部扫描现在会流式读取并释放存储锁；将含 8–15 个参数的函数改为使用参数结构体；修复了 Windows 构建问题。
• Enterprise：新增 KVCache 子系统——面向 LMCache 的 KV 缓存服务，用于大模型推理 KV 缓存分层；支持按集合配置写入并发，并限制清理过程的内存占用。

发布亮点（4.41 → 4.45）

• S3 写入路径：在直接写入路径上，大块列表会折叠为清单块；单对象上传和分段上传完成时，按 filer 的 maxMB 分块；存储类别随缓存的列表元数据一起传递；写入存储桶策略现在需要存储桶策略操作。新增 RenameObject，可禁用上传时自动创建存储桶，并加强了对版本控制暂停状态和空删除标记的处理。
• IAM/STS 成熟度：从高级 IAM 配置加载文档式策略；已附加的策略可以列出其授予访问权限的存储桶；管理员的角色会话仍限定在其角色范围内；IAM 管理操作会按 IAM 操作授权；管理界面新增可视化 IAM 策略编辑器和存储桶策略管理功能。
• 主节点/拓扑心跳摘要：卷心跳携带摘要，仅发送发生变化的卷，并在拓扑变动期间保持主节点信息最新；移除热路径中的分配和复制操作，减少内存抖动；卷列表改为流式传输。
• 纠删码清理：编码、解码和分片迁移在中断后会回滚或恢复到一致状态；ec.balance 新增 -volumeIds 筛选项；新增用于测试 EC 生命周期的混沌测试工具。
• Filer：支持带分块集写入条件的条件式 UpdateEntry；新增 filer.meta.scan，用于审计目录的变更历史；TUS 新增可配置的最大大小和会话过期时间，以及串联扩展；以非递归方式删除的文件夹不再清理其子项。
• 管理功能/工作进程：新增 Lance 目录和用于维护该目录的 Rust 插件工作进程；seaweed-worker 提供健康、就绪和指标接口；管理界面显示各层级的容量，并可编辑存储桶生命周期规则。
• 核心：为副本迁移、EC 分片迁移和工作进程迁移设置吞吐量限制；Range 请求仅在没有任何范围重叠时返回 416，并会拒绝起始偏移量等于文件大小的请求；FUSE 挂载新增 Windows（WinFsp）支持。

发布亮点（4.40）

• 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 服务。
• 核心：主节点的已用空间统计覆盖所有集合；Rust 卷服务端会根据最后一个已索引 needle 校验 .dat 的完整性；挂载现在会返回 ENOSPC，而非无限期等待。

发布亮点（4.25）

• 安全/管理路径：4.24-4.25 加强了破坏性操作和管理端点的管理认证，并通过在 filer IAM gRPC 调用中附加管理员签名认证，修复了 security.toml 下的管理 UI 行为。
• 纠删码/多磁盘运维：此版本系列修复了多磁盘和跨服务器布局中的多种 EC 规划与恢复问题，包括清理过期分片，以及更安全地删除源卷。
• S3/IAM 加固：没有策略的 IAM 用户现在会被拒绝访问，而不再默认获得过多权限；同时，OIDC/网络身份和审计能力也在持续完善。

发布亮点（4.26 -> 4.28）

• 纠删码/多磁盘运维：EC 规划现在能更可靠地将分片分布到各个磁盘，在执行规划中加入了 disk_id，并能在恢复期间根据本地分片重建丢失的 .ecx / .vif 元数据。
• 完整性检查：scrub/fsck 路径现在会将零大小卷纳入检查，而不是悄然跳过；这对于稀疏或近期创建的拓扑至关重要。
• Filer 后端可靠性：Redis3 不再触发 skiplist 尾部的 panic 路径，基于 SQL 的 filer 存储也不再强制禁用空闲连接池。
• S3 审计跟踪：GET/HEAD/IAM 操作的请求者身份填充得更加一致，有助于合规和事件排查。
• 高可用心跳路径：现在主节点会在从节点副本上接受卷服务器 ping 目标，从而提高多主节点部署中的故障转移可见性。

发布亮点（4.34 -> 4.39）

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

发布亮点（4.31 -> 4.33）

• S3 版本控制/IAM：原子化提交带版本控制的 PutObject、正确返回 NoSuchVersion 错误、修复并恢复最新版本指针、处理暂停版本控制时的删除操作、托管 IAM 策略版本，以及强制执行存储桶只读配额；4.33 还修复了 HTTP 日期条件请求、校验和尾部标头，以及空的 v4 签名标头名称。
• 纠删码完整性：通过分片校验和旁文件检测位腐；4.31 实现此功能，4.32 将分片均匀分布到各机器（将共置的服务视为单个故障域），并在删除前验证分片落盘情况；4.33 增加防护，避免不同编码批次的 EC 分片混杂，或重启时留下虚假的 .dat 文件。
• 卷服务：修复自动调整大小的磁盘上 maxVolumeCount 的失效区间；删除尾部压缩后仍保持卷可写；重启时从 .vif 解析 EC 数据分片数量（4.31）；并新增磁盘健康检测 CheckDisk（4.32）。
• Filer 可扩展性：限制 BFS 元数据内存占用，并按字节字典序排列 S3 列表（4.31）；流式处理元数据订阅日志文件（4.32）；新增对象大小分布指标、修复挂载重连导致的 OOM、按块重放、限制刷新队列长度，并支持 Elasticsearch 8（elastic8）（4.33）。
• 管理端/工作进程：按通道修剪调度器、为持久化状态设置 -dataDir 默认值，并在启动时重新加载正在执行的任务（4.32）；另新增完整的集群卷列表 JSON 导出（4.33）。
• Rust 卷服务：限制请求正文和已存储内容的扩展，防止负载下发生 OOM（4.31）；修复 EC 分片删除后重启时留下虚假 .dat 文件的问题（4.33）。

发布亮点（4.29 -> 4.30）

• S3 写入/认证路径：对象写入逐步转向由 Filer 负责所有者路由和 ObjectTransaction 批处理，以减轻分布式锁压力；4.30 还加强了路径遍历拒绝、所有权控制验证、MetadataDirective=REPLACE，以及对无签名流式上传的 JWT 处理。
• FUSE 与 Filer 协调：在 -dlm 模式下，POSIX 建议锁现在通过 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 元数据。

发布亮点（4.20）

• S3/IAM：嵌入式 IAM 流程新增 ListUserPolicies、用户组内联策略操作、更安全的用户策略往返处理，以及在 DeleteBucket 时按存储桶范围清理。
• 挂载/FUSE：weed mount 新增 -dlm，用于协调跨挂载写入，并改进 POSIX 元数据行为、nlink 计数和 Filer RPC 效率。
• Master 放置：卷分配更注重大小；只读状态转换会先清空待处理大小；并修复了在某些数据中心/机架布局中可能导致无限增长的拓扑错误。
• Filer 可靠性：改进 PgBouncer/Postgres 兼容性，修复优雅关闭时的数据损坏，并移除了导致内存/CPU 性能退化的冗余 Filer 磁盘读取。
• 运维界面：weed shell 新增用户组管理助手；S3 用户配置更安全地处理已有用户；Master/卷现在会导出 start_time_seconds 指标。

禁止事项

• 请勿在生产环境中使用 weed mini。
• 请勿将单二进制默认配置视为适用于生产环境的配置。
• 在检查身份验证、TLS 和网络边界之前，请勿公开 S3 或 filer 端点。
• 在验证高可用、扩展和备份特性之前，请勿选择 filer 存储。
• 未经恢复验证，请勿设计备份或复制流程。

链接

• 文档
• 发行版
• GitHub
• Docker Hub