SeaweedFS 使用 YDB 作为 Filer 元数据存储:配置、认证与底层原理全解

原创2026-09-30 17:14:411,928 阅读
文章标签:分布式文件系统对象存储后端

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)统一解析:

  1. YDB_SERVICE_ACCOUNT_KEY_FILE_CREDENTIALS=<path/to/sa_key_file> —— 使用指定路径的服务账号密钥文件认证(适用于 Yandex Cloud 服务账号)。
  2. YDB_ANONYMOUS_CREDENTIALS="1" —— 匿名访问认证,用于连接测试性质的 YDB 安装(本地 Docker 测试环境即采用此方式)。
  3. YDB_METADATA_CREDENTIALS="1" —— 使用元数据服务认证,适用于 Yandex Cloud 虚拟机或云函数内部。
  4. YDB_ACCESS_TOKEN_CREDENTIALS=<access_token> —— 使用短期访问令牌认证,例如 IAM Token。
  5. 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 准备环境。

九、部署建议与注意事项

  1. DSN 协议选择:生产环境使用 grpcs://(TLS,默认端口 2135);本地 Docker 测试使用 grpc://(明文,端口 2136)。
  2. 认证方式与密钥安全:优先使用服务账号密钥文件或元数据服务(Yandex Cloud 场景),匿名认证仅限测试安装;密钥通过环境变量注入,切勿写入配置文件。
  3. 多环境隔离:同一 YDB 数据库内可通过不同 prefix 隔离多套 SeaweedFS 环境,避免建表冲突。
  4. 桶前缀取舍:S3 桶较多且需要快速删除整桶时开启 useBucketPrefix;需要极简运维、单表管理时可关闭。
  5. 分区参数:默认按大小(200MB)与负载自动分区足以覆盖大多数场景,仅在数据特征极端时可调 partitionSizeMb 与分区数上下限。
  6. 构建约束:必须使用 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。

登录后查看全文
seaweedfs