SeaweedFS 配置参数详解
全面详解 SeaweedFS v4.48 三大组件（master、volume、filer/S3）的启动参数与 master.toml、filer.toml 配置模板，覆盖 Raft 选主、复制策略、卷增长、元数据后端、分层存储、维护脚本等核心配置项
SeaweedFSSeaweedFS文件存储S3 兼容配置详解命令行2026/10/06
SeaweedFS 配置参数详解
目标：详解 SeaweedFS v4.48 三个核心组件（master、volume server、filer/S3 网关）的全部关键启动参数，以及通过
weed scaffold生成的master.toml与filer.toml配置文件模板，帮助读者按生产需求完成精细调优。
一、配置文件体系
SeaweedFS 使用 命令行参数为主、TOML 配置文件为辅 的配置体系：
- 命令行参数：每个子命令（
weed master/weed volume/weed filer）均支持-flag形式； - TOML 配置：
master.toml（master 专属）与filer.toml（filer 专属），用于高级配置； - 配置文件查找顺序（优先级从高到低）：
./master.toml
$HOME/.seaweedfs/master.toml
/usr/local/etc/seaweedfs/master.toml
/etc/seaweedfs/master.toml
filer 同理（filer.toml）。
生成配置模板：
weed scaffold -config=master > /etc/seaweedfs/master.toml
weed scaffold -config=filer > /etc/seaweedfs/filer.toml
weed scaffold -config=security > /etc/seaweedfs/security.toml
weed scaffold -config=shell > /etc/seaweedfs/shell.toml
二、master 参数详解
2.1 核心参数
| 参数 | 默认值 | 说明 |
|---|---|---|
-port | 9333 | master HTTP 监听端口 |
-port.grpc | 19333 | master gRPC/Raft 监听端口 |
-ip | 本机 IP | 对外通告的 IP 或主机名，集群场景必须显式指定 |
-ip.bind | 同 -ip | 实际绑定的 IP 地址 |
-mdir | /tmp | master 数据目录（Raft 状态、卷索引） |
-peers | 空 | 组成 Raft 集群的 master 列表，ip:port,ip:port,... |
-defaultReplication | 000 | 默认复制策略（见 2.2） |
-volumeSizeLimitMB | 30720（30GB） | 单卷最大容量 |
-fileSizeLimitMB | 1024 | 单文件最大可拆块上传大小 |
-garbageThreshold | 0.3 | 卷内垃圾数据占比超过该值可触发 vacuum |
-electionTimeout | 500ms | Raft 选举超时 |
-heartbeatInterval | 300ms | master 与 volume 心跳间隔 |
-raftHashicorp | false | 使用 Hashicorp Raft 实现（默认内置 Raft） |
-resumeState | false | 崩溃后恢复 Raft 状态再启动 |
2.2 复制策略 -defaultReplication
3 位数字 xyz：
| 策略 | 含义 | 副本数 |
|---|---|---|
000 | 单副本 | 1 |
001 | 2 副本，不同机架 | 2 |
010 | 2 副本，同一机架 | 2 |
100 | 2 副本，不同数据中心 | 2 |
110 | 3 副本，跨数据中心 | 3 |
200 | 3 副本，2 个数据中心 | 3 |
2.3 master.toml 配置模板
生成后关键节（实测 weed scaffold -config=master）：
# /etc/seaweedfs/master.toml
# master 周期性自动维护脚本（等价于在 weed shell 中依次执行）
[master.maintenance]
scripts = """
lock
ec.encode -fullPercent=95 -quietFor=1h
ec.rebuild -apply
ec.balance -apply
fs.log.purge -daysAgo=7
volume.deleteEmpty -quietFor=24h -apply
volume.balance -apply
volume.fix.replication -apply
s3.clean.uploads -timeAgo=24h
unlock
"""
sleep_minutes = 17 # 每轮维护脚本间隔
# 文件 ID 序号生成方式
[master.sequencer]
type = "raft" # raft（默认）或 snowflake
sequencer_snowflake_id = 0 # snowflake 模式时每 master 需唯一（1~1023）
# 分层存储：旧卷自动迁移到 S3 云存储
[storage.backend]
[storage.backend.s3.default]
enabled = false
aws_access_key_id = ""
aws_secret_access_key = ""
region = "us-east-2"
bucket = "your_bucket_name" # 需预先创建
endpoint = ""
storage_class = "STANDARD_IA"
# 卷增长策略：每种复制策略对应的预创建卷数
[master.volume_growth]
copy_1 = 7 # 单副本：1 x 7 = 7 个卷
# copy_2 = 3 # 双副本：1 x 3 = 3 个卷
要点：
[master.maintenance]：master 内置定时维护，无需外部 crontab；[master.sequencer]：raft模式下主 master 统一分配文件 ID；多主场景可换snowflake避免单点；[storage.backend.s3]：开启后 volume 写满会自动把旧卷迁移到 AWS S3/MinIO 等对象存储，本地只留热数据；[master.volume_growth]：决定写满后一次性创建多少个新卷。
三、volume 参数详解
| 参数 | 默认值 | 说明 |
|---|---|---|
-port | 8080 | volume HTTP 端口 |
-port.grpc | 18080 | volume gRPC 端口 |
-ip | 本机 IP | 对外通告地址 |
-dir | /tmp | 数据卷目录，可 dir1,dir2 指定多个（分摊不同磁盘） |
-max | 8 | 每个数据目录最多预创建的逻辑卷数（volumeId 从 0 到 max-1） |
-mserver | localhost:9333 | master 地址列表，ip:port,ip:port 逗号分隔 |
-dataCenter | 空 | 所属数据中心名（配合 100/110/200 复制策略） |
-rack | 空 | 所属机架名（配合 001/010/110 复制策略） |
-disk | hdd | 磁盘类型标签：hdd / ssd / 自定义 tag |
-minFreeSpacePercent | 10 | 磁盘剩余空间低于该比例则不再分配卷 |
-maxCpuPercent | 80 | CPU 使用上限 |
-compactionMBps | 50 | 卷压缩（vacuum）限速 |
-concurrentDownloadLimitMB | 128 | 并发下载带宽上限 |
-concurrentUploadLimitMB | 256 | 并发上传带宽上限 |
-publicUrl | 空 | 对外暴露的公网地址（如 http://cdn.example.com:8080） |
数据目录与卷结构
ls /data/seaweed/vol/
# 1.dat 1.idx 2.dat 2.idx ... 16.dat 16.idx
.dat：数据卷文件，内部按 block 追加写；.idx：卷内文件 ID → 偏移索引。
四、filer 参数详解
4.1 核心参数
| 参数 | 默认值 | 说明 |
|---|---|---|
-port | 8888 | filer HTTP 端口 |
-port.grpc | 18888 | filer gRPC 端口 |
-master | localhost:9333 | master 地址列表（failover） |
-defaultStoreDir | 空 | filer 元数据默认存储目录 |
-maxMB | 4 | 大于该值的文件自动拆分到多个 chunk |
-collection | 空 | 所有文件写入指定 collection |
-filerGroup | 空 | 多个 filer 组成同一 filer 组共享元数据 |
-encryptVolumeData | false | 数据卷加密 |
-dirListLimit | 1000 | 单目录列表条目上限 |
-downloadMaxMBps | 0(不限) | 单次下载限速 |
-disableDirListing | false | 关闭目录列举 |
4.2 S3 网关参数（-s3 开启）
| 参数 | 默认值 | 说明 |
|---|---|---|
-s3.port | 8333 | S3 API 端口 |
-s3.domainName | 空 | 桶的虚拟主机风格域名（如 s3.example.com） |
-s3.autoCreateBucket | false | 写入不存在的桶时自动创建 |
-s3.allowEmptyFolder | true | 允许空目录（S3 无目录概念） |
-s3.allowDeleteBucketNotEmpty | false | 允许删除非空桶 |
-s3.auditLogConfig | 空 | 审计日志配置路径 |
-s3.cacheCapacityMB | 0 | S3 网关本地缓存容量 |
-iam.config | 空 | 高级 IAM 配置（S3 用户/策略） |
4.3 filer.toml 配置模板
生成后关键节（实测 weed scaffold -config=filer）：
# /etc/seaweedfs/filer.toml
[filer.options]
# HTTP DELETE 目录时递归删除所有子目录与文件
recursive_delete = false
# S3 删除空目录的延迟
# s3.empty_folder_cleanup_delay = "2m"
# ---------- 元数据后端：默认 LevelDB2 ----------
[leveldb2]
enabled = true
dir = "./filerldb2" # 单机本地存储，推荐
[leveldb3]
enabled = false
dir = "./filerldb3" # 每 bucket 独立 meta store
[rocksdb]
enabled = false
dir = "./filerrdb" # 需自编译 rocksdb 支持
[sqlite]
enabled = false
dbFile = "./filer.db"
# ---------- 关系型数据库后端 ----------
[mysql] # 或 memsql / tidb
enabled = false
dsn = "root@tcp(localhost:3306)/seaweedfs?collation=utf8mb4_bin"
# 表结构（自动创建）：
# CREATE TABLE IF NOT EXISTS `filemeta` (
# `dirhash` BIGINT NOT NULL,
# `name` VARCHAR(766) NOT NULL,
# `directory` TEXT NOT NULL,
# `meta` LONGBLOB,
# PRIMARY KEY (`dirhash`, `name`)
# ) DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin;
[postgres] # 或 cockroachdb / yugabytedb
enabled = false
hostname = "localhost"
port = 5432
username = "postgres"
password = ""
database = "postgres"
schema = ""
sslmode = "disable"
要点：
- 元数据后端默认
leveldb2，单机无需任何数据库即可运行； - 需要跨机房 filer 组共享元数据时，建议切换
postgres/mysql后端并配合-filerGroup； - 切换后端后重启 filer 即生效，无需迁移原目录数据（如从 leveldb2 切到 sqlite）。
五、security.toml（安全配置）
weed scaffold -config=security > /etc/seaweedfs/security.toml
核心配置：
# 各组件管理员密钥（JWT 签名）
[master]
signing_key = "" # 生成：openssl rand -base64 32
[volume]
signing_key = ""
[filer]
signing_key = ""
jwt.filer_signing_key = ""
[s3]
# S3 SSE-S3 加密密钥
sse.key = ""
sse.kek = ""
未配置签名密钥时，任何客户端均可访问 S3（实测日志提示：
Registered IAM gRPC service on filer (unauthenticated; set jwt.filer.signing.key in security.toml to require admin Bearer token)）。生产环境务必配置。
六、shell.toml（运维终端配置）
weed scaffold -config=shell > /etc/seaweedfs/shell.toml
# 定义多个集群快捷方式
[cluster.clu]
master = "seaweed-node1:9333,seaweed-node2:9333,seaweed-node3:9333"
# 定义命令别名
[command.alias]
"ls" = "fs.ls"
"df" = "fs.du -s"
使用：
weed shell -cluster=clu
七、常见调优组合
7.1 单机高吞吐（hdd 大磁盘）
weed master -port=9333 -mdir=/data/master
weed volume -dir=/data/v1,/data/v2,/data/v3 -max=32 -disk=hdd \
-mserver=127.0.0.1:9333 -compactionMBps=200 -concurrentUploadLimitMB=512
weed filer -master=127.0.0.1:9333 -s3 -s3.port=8333
7.2 双数据中心三副本
# 数据中心 A（2 副本 + 1 远程）
weed master -peers=... -defaultReplication=110
weed volume -dataCenter=dc-a -rack=r1 -dir=/data/vol -max=16 -mserver=...
# 数据中心 B
weed volume -dataCenter=dc-b -rack=r1 -dir=/data/vol -max=16 -mserver=...
7.3 元数据入 MySQL/PostgreSQL 的多 filer 组
# filer.toml 启用 [postgres] 并配置 dsn
# 每台 filer 加 -filerGroup=prod 参数
weed filer -master=... -filerGroup=prod -s3 -s3.port=8333
八、参数查询速查
weed master -h # 全部 master 参数
weed volume -h # 全部 volume 参数
weed filer -h # 全部 filer 参数
weed server -h # 一键全栈参数（含各组件前缀，如 -master.xxx / -volume.xxx / -filer.xxx）
weed shell -h # 运维终端用法
章节目录