SeaweedFS 使用 YDB 作为 Filer 元数据存储:配置、认证与底层原理全解
SeaweedFS 使用 YDB 作为 Filer 元数据存储:配置、认证与底层原理全解
SeaweedFS 的 Filer 组件负责维护文件系统与 S3 对象的元数据,并支持多种后端存储。本指南围绕仓库 weed/filer/ydb/readme.md 展开,讲解如何将 SeaweedFS Filer 接入 YDB(Yandex 开源的分布式数据库,官方仓库为 ydb-platform/ydb),覆盖编译要求、配置文件参数、认证方式、本地测试环境搭建,并结合 ydb_store.go 等源码剖析表结构、分区策略、SQL 执行与事务实现的底层原理。读完本文,你将能独立完成 SeaweedFS + YDB 的元数据存储部署与问题排查。
一、YDB 作为 Filer 后端:适用场景概述
YDB 是一款支持强一致性、水平扩展的分布式 SQL 数据库,其 Go 驱动为 github.com/ydb-platform/ydb-go-sdk(官方 ydb-go-sdk)。SeaweedFS 在 weed/filer/ydb 目录下实现了 YdbStore,把它注册为 filer 的候选存储之一(见 ydb_store.go 的 init() 函数,通过 filer.Stores = append(...) 完成注册)。
选择 YDB 的典型动机包括:使用 Yandex Cloud 托管 YDB 服务、已有 YDB 基础设施、或需要比单机嵌入式数据库更强的分布式元数据能力。值得注意的是,由于 ydb-go-sdk 编译产物较大,YDB 存储默认不会打进二进制,需要在构建时显式启用 ydb build tag(详见下文"编译要求")。
二、编译要求:必须启用 ydb build tag
doc.go 明确写道:引用的 github.com/ydb-platform/ydb-go-sdk/v3 库太大,因此该包只在 make full_install 时编译。也就是说,仓库内所有 ydb_*.go 文件都带有 //go:build ydb 构建约束(ydb_store.go、ydb_queries.go、ydb_types.go、ydb_store_kv.go)。
根目录 Makefile 的 full_install 目标已包含 ydb tag:
full_install: admin-generate
cd weed; go install -tags "elastic gocdk sqlite ydb tarantool tikv rclone"
而 docker/Makefile 也支持通过 make go_build tags=ydb 构建包含 YDB 的 Docker 镜像。集成入口在 filer_server.go:_ "github.com/seaweedfs/seaweedfs/weed/filer/ydb" 的匿名导入负责在启动时加载该 store 实现。
三、配置文件:完整的 [ydb] 配置段
readme.md 给出的配置段如下,这是启用 YDB 存储的最小完整配置:
[ydb]
enabled=true
dsn=grpcs://ydb-ru.yandex.net:2135/?database=/ru/home/username/db
prefix="seaweedfs"
useBucketPrefix=true
poolSizeLimit=50
dialTimeOut = 10
在仓库中,scaffold/filer.toml 提供了由 weed scaffold 生成的官方配置模板,字段与 readme 保持一致,并标注了 useBucketPrefix = true # Fast Bucket Deletion 的用途说明。
各参数含义如下:
| 参数 | 示例值 | 作用 |
|---|---|---|
enabled |
true |
是否启用 YDB 存储,置 false 时 filer 不会选择该后端 |
dsn |
grpcs://ydb-ru.yandex.net:2135/?database=/ru/home/username/db |
YDB 连接串,grpcs:// 为 TLS 加密端口(2135),本地测试常用 grpc:// 明文端口(2136) |
prefix |
"seaweedfs" |
表路径前缀,最终表路径为 prefix + "/filemeta",多环境共用同一数据库时可隔离命名空间 |
useBucketPrefix |
true |
是否启用桶级独立表(支持整桶快速删除,见"桶级表"章节) |
poolSizeLimit |
50 |
YDB Session 池大小上限,<= 0 时不强制限制 |
dialTimeOut |
10 |
连接超时(秒),0 时使用默认值 10 |
3.1 参数解析与隐藏默认值
在 ydb_store.go 的 Initialize 中,配置键 prefix 即 <a href="https://link.gitcode.com/i/40419fa0381285b01c64d827fec69128" target="_blank">ydb] 段前缀,除了上述字段,还读取了 readme 未列出的分区与分页参数,并设置默认值([ydb_store.go):
| 参数 | 默认值 | 含义 |
|---|---|---|
partitionBySizeEnabled |
true |
是否按数据量自动分区 |
partitionSizeMb |
200 |
分区大小阈值(MB),超过则自动分裂 |
partitionByLoadEnabled |
true |
是否按负载自动分区 |
minPartitionsCount |
5 |
最少分区数 |
maxPartitionsCount |
1000 |
最大分区数 |
maxListChunk |
2000 |
单次目录列表查询的最大返回条数(分页分块上限) |
prefix |
"seaweedfs" |
表路径前缀 |
dialTimeOut |
10 |
连接超时(秒) |
连接阶段(ydb_store.go)会依次应用:ydb.WithDialTimeout(...) 设置拨号超时、environ.WithEnvironCredentials() 从环境变量读取认证凭据、ydb.WithSessionPoolSizeLimit(poolSizeLimit) 限制连接池;若 dsn 为空,则回退读取环境变量 YDB_CONNECTION_STRING(这一点与下文认证方式中的第 5 个环境变量对应)。
四、认证方式:五种环境变量
readme.md 明确指出,认证凭据由下列环境变量之一提供,源码层面由 environ.WithEnvironCredentials()(ydb_store.go)统一解析:
YDB_SERVICE_ACCOUNT_KEY_FILE_CREDENTIALS=<path/to/sa_key_file>—— 使用指定路径的服务账号密钥文件认证(适用于 Yandex Cloud 服务账号)。YDB_ANONYMOUS_CREDENTIALS="1"—— 匿名访问认证,用于连接测试性质的 YDB 安装(本地 Docker 测试环境即采用此方式)。YDB_METADATA_CREDENTIALS="1"—— 使用元数据服务认证,适用于 Yandex Cloud 虚拟机或云函数内部。YDB_ACCESS_TOKEN_CREDENTIALS=<access_token>—— 使用短期访问令牌认证,例如 IAM Token。YDB_CONNECTION_STRING="grpcs://endpoint/?database=database"—— 提供完整连接串(当配置中dsn为空时,同样通过该环境变量获取连接目标)。
在 scaffold/filer.toml 中也以注释形式保留了前四种变量的说明,便于生成配置后直接查阅。实际部署时按目标环境选用其中一种即可,无需在 toml 中暴露任何密钥明文。
五、底层原理:表结构与分区策略
YDB 存储的核心是一张名为 filemeta 的表(常量 DEFAULT_TABLE = "filemeta",定义于 abstract_sql_store.go),建表逻辑集中在 ydb_types.go 的 createTableOptions():
- 列定义:
dir_hash(int64,目录路径哈希)、directory(Utf8,目录路径)、name(Utf8,文件名)、meta(String,序列化的文件元数据与 chunk 列表)、expire_at(Optional,TTL 过期时间)。 - 主键:
(dir_hash, directory, name)复合主键,其中dir_hash由util.HashStringToLong对目录字符串取哈希得到,用于平衡分区分布。 - TTL 支持:
expire_at列启用 YDB 行级 TTL(TimeToLiveModeValueSinceUnixEpoch,单位为秒),这正是 SeaweedFS 文件 TTL(entry.TtlSec)能下沉到数据库层的实现基础——写入时若TtlSec > 0则写入过期时间戳,否则写入Null(见 ydb_types.go)。 - 自动分区:按
(dir_hash, name)分区键,同时开启按大小(默认 200MB)与按负载两种自动分区策略,分区数约束在 5~1000 之间。这是 YDB 横向扩展与 SeaweedFS 海量小文件元数据需求匹配的关键设计。
写入时若某个 entry 的 chunk 数量超过阈值,meta 字段还会经 util.MaybeGzipData 做条件 gzip 压缩以降低存储开销(ydb_store.go),读取时对称地 MaybeDecompressData 解压。
六、核心读写路径:SQL 与事务实现
所有 YQL 语句集中在 ydb_queries.go,每一条都通过 PRAGMA TablePathPrefix("%v") 动态注入表路径前缀,再对 filemeta 执行:
- upsert(写入/更新):
UPSERT INTO filemeta (dir_hash, name, directory, meta, expire_at) VALUES (...),同时服务InsertEntry与UpdateEntry。 - find(读取):按
dir_hash + directory + name精确查询meta列,再反序列化为filer.Entry。 - delete(删除):按主键三列
DELETE。 - deleteFolderChildren(整目录删除):按
dir_hash + directory批量删除。 - list(目录列举):
WHERE name > $start_name AND name LIKE $prefix ORDER BY name ASC LIMIT $limit,支持游标分页与前缀过滤(对应ListDirectoryPrefixedEntries,用于 S3 前缀列目录);includeStartFile场景改用name >= $start_name的含起点版本。
在 ydb_store.go 的 doTxOrDB 中实现了统一执行器:若上下文携带 tx(来自 BeginTransaction),则在已开启的 YDB 事务内执行;否则直接在 query.Session 上执行,并使用 query.WithIdempotent() 保证幂等重试。ListDirectoryEntries 采用 maxListChunk(默认 2000)分块拉取、逐块推进游标的循环(ydb_store.go),避免单次查询过大。
事务支持方面,ydb_store.go 通过 CreateSession + BeginTransaction(WithSerializableReadWrite()) 开启可串行化读写事务,并将事务对象注入 context,配合 CommitTransaction / RollbackTransaction 完成提交回滚。
此外,YDB 后端还实现了 KV 接口(ydb_store_kv.go):KvPut/KvGet/KvDelete 通过 abstract_sql.GenDirAndName(key) 把二进制 KV key 映射为 (dir, name) 元组后复用同一张 filemeta 表存储,为 SeaweedFS 分布式锁等 KV 依赖提供支持。
七、桶级表:useBucketPrefix 的行为
当 useBucketPrefix=true 时,YdbStore 实现 filer.BucketAware 接口(ydb_store.go),使每个 S3 bucket 拥有独立的表:
- 桶创建回调
OnBucketCreation会按seaweedfs/<bucket>/filemeta路径建表(ydb_store.go); - 桶删除回调
OnBucketDeletion会先DropTable再移除 Scheme 目录,实现整桶快速删除(ydb_store.go); - 路径分派逻辑
getPrefix(ydb_store.go)会解析filer.options.buckets_folder(默认/buckets,见 filer_server.go)下的路径,识别桶名后切换到对应前缀;命中.开头的内部目录(如.system)则保持默认前缀不动。
该模式下读写某个 bucket 时只命中该桶的小表,减小了热点冲突;关闭 useBucketPrefix 则所有数据汇聚到单一 filemeta 表。
八、本地测试与开发环境
readme 作者自述使用 make dev_ydb 启动开发数据库进行测试。仓库内对应的自动化测试目标在 docker/Makefile:
test_ydb: tags = ydb
test_ydb: build
docker compose -f compose/test-ydb-filer.yml -p seaweedfs up
其编排文件 compose/test-ydb-filer.yml 提供了开箱即用的本地环境,核心要点:
- 使用
cr.yandex/yc/yandex-docker-local-ydb本地镜像,暴露 2135(TLS gRPC)、2136(明文 gRPC)、8765(监控端口)三个端口; - SeaweedFS 容器通过环境变量注入 YDB 配置(无需改 toml):
WEED_YDB_ENABLED: "true"、WEED_YDB_DSN: "grpc://ydb:2136/?database=local"、WEED_YDB_PREFIX: "seaweedfs",并以YDB_ANONYMOUS_CREDENTIALS: 1使用匿名认证; - 同时启动内置 S3 网关(
-s3.port=8000),并显式关闭 leveldb2(WEED_LEVELDB2_ENABLED: "false")以保证 filer 使用 YDB 后端。
单元测试方面,ydb_store_test.go 展示了直连本地 YDB(grpc://localhost:2136/?database=local)并运行 store_test.TestFilerStore 全量 CRUD 用例的写法,其注释提示需先在 docker 目录下执行 make test_ydb 准备环境。
九、部署建议与注意事项
- DSN 协议选择:生产环境使用
grpcs://(TLS,默认端口 2135);本地 Docker 测试使用grpc://(明文,端口 2136)。 - 认证方式与密钥安全:优先使用服务账号密钥文件或元数据服务(Yandex Cloud 场景),匿名认证仅限测试安装;密钥通过环境变量注入,切勿写入配置文件。
- 多环境隔离:同一 YDB 数据库内可通过不同
prefix隔离多套 SeaweedFS 环境,避免建表冲突。 - 桶前缀取舍:S3 桶较多且需要快速删除整桶时开启
useBucketPrefix;需要极简运维、单表管理时可关闭。 - 分区参数:默认按大小(200MB)与负载自动分区足以覆盖大多数场景,仅在数据特征极端时可调
partitionSizeMb与分区数上下限。 - 构建约束:必须使用
make full_install或显式带-tags ydb编译(如make go_build tags=ydb),否则运行时会提示找不到 YDB 存储。
十、总结
SeaweedFS 对 YDB 的支持,本质上是把 Filer 的元数据模型映射到一张复合主键的 YDB 表,借助 YDB 的自动分区、行级 TTL 与可串行化事务,获得分布式、可水平扩展的元数据存储能力。通过 [ydb] 配置段 + 五种认证环境变量即可完成接入,配合 docker/Makefile 的 test_ydb 目标可在数分钟内拉起本地验证环境。本文涉及的源码均可在此仓库中直接查阅:ydb_store.go、ydb_types.go、ydb_queries.go、ydb_store_kv.go 与编排示例 test-ydb-filer.yml。