​

服务与组件

BlockDB 的能力由一组 gRPC 服务与后台服务组成，所有服务均可通过 cmd/blockdb 的 -services 标志灵活组装。

​

meta-service

meta-service 是独立的元数据管理进程，负责逻辑表的生命周期与 schema 定义： 核心读写服务通过 Meta 客户端（pkg/blockdb/meta）向 meta-service 获取表元数据，自身不持有物理表结构信息。

​

read

提供普通表的行级读取能力，实现 TableReadService：

• GetRow：按业务主键读取单行。
• BatchGetRows：按多个主键批量读取，单次 RPC。
• FilterRows：按条件筛选行，支持排序、分页。

定位为普通表语义的读取入口。

​

block-read

提供 Block 表的区块维度读取能力，实现 BlockReadService 与 L2BlockReadService：

• GetEvent：按区块时刻读取事件。
• GetState：按区块时刻读取状态快照，自动注入 height ≤ 目标高度。
• GetConsensusHeight：获取表的当前共识高度。
• GetBlockRows：获取某区块高度的全部数据行。

定位为区块语义的读取入口，支持历史高度回溯。

​

scan

提供全表流式扫描能力，实现 TableScanService：

• Scan：接收 SQL 查询，以流式方式（stream）返回结果行，避免内存撑爆。

用于大批量离线读取场景，因资源占用较大，推荐独立部署避免影响在线读写。

​

write

所有逻辑表的实时写入入口，在一个服务内聚合了 TableWriteService、BlockWriteService 和 TimeWriteService：

• 普通表：UpsertRows / DeleteRows。
• Block 表：UpsertBlock。
• Time 表：UpsertTimeRows。

写入请求通过内存异步队列（asyncqueue）入队，由多线程异步落库，保证近实时的写响应，同时受控于队列容量避免数据库过载。 详见写入架构。

​

batch-write

提供海量数据的异步批量写入任务管理，实现 BatchWriteService：

• InitWriteJob：初始化写入任务，返回 S3 presigned 上传 URL 与任务 ID。
• CommitWriteJob：提交任务，触发后台 worker 处理。
• CancelWriteJob：取消任务。

用户通过 S3 中转百万行级别的数据，提交吞吐无上限，写入吞吐可达数十万~百万行/s。 详见写入架构。

​

batch-worker

后台执行批量写入任务的 worker，与 batch-write 配合使用：

• 消费 S3 中已提交的任务文件。
• 执行排序、去重、批量落库（详见写入架构）。

推荐独立部署，与实时写入隔离，以便独立扩缩容。

​

subscribe

提供区块事件流式订阅能力，实现 BlockSubscribeService：

• Subscribe：订阅一张或多张 Block 表的区块写入事件。

其事件源来自 write 服务通过 Kafka（eventbus）发布的 BlockSubscribeEvent。订阅方以 gRPC 流式接收事件，驱动下游增量消费。因需要维持长连接，推荐独立部署。

​

state-compactor

后台定时任务，通过扫描 _archive 表全量重算 state latest 表，确保最新状态表与归档数据一致。必须单实例运行，避免并发写冲突。

​

核心代码包

以下是与各服务对应的核心代码包（位于 pkg/blockdb/）：