> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockdb.chaintable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 服务与组件

> BlockDB 各 gRPC 服务、后台服务及核心组件的职责与定位。

# 服务与组件

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

## meta-service

`meta-service` 是独立的元数据管理进程，负责逻辑表的生命周期与 schema 定义：

| 子服务 | 职责 |
| - | - |
| `TableMetaService` | 普通表的创建、保存、删除与列表 |
| `BlockMetaService` | Block State / Event 表的创建、保存、配置更新、删除与列表 |
| `TimeMetaService` | Time 表的创建、保存、删除与列表 |

核心读写服务通过 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`）入队，由多线程异步落库，保证近实时的写响应，同时受控于队列容量避免数据库过载。

详见[写入架构](/zh/architecture/batch-write)。

## batch-write

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

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

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

详见[写入架构](/zh/architecture/batch-write)。

## batch-worker

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

* 消费 S3 中已提交的任务文件。
* 执行排序、去重、批量落库（详见[写入架构](/zh/architecture/batch-write)）。

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

## subscribe

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

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

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

## state-compactor

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

## 核心代码包

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

| 包 | 职责 |
| - | - |
| `service` | read / block-read / scan 等服务实现 |
| `blockwrite` | write 服务中的区块写入逻辑、事务与并发控制 |
| `blocksubscribe` | subscribe 服务（Kafka 事件源、流式订阅） |
| `batchwrite` | batch-write 与 batch-worker（任务生命周期、worker 调度） |
| `meta` | Meta 客户端（缓存、GRPC 调用） |
| `store` | 底层 SQL 构造器，统一封装数据访问 |
| `cache` / `mq` / `eventbus` | Redis 缓存 / Kafka 生产者 / 事件总线 |
| `asyncqueue` | 实时写的内存异步队列 |
| `physicalschema` | 逻辑元数据到物理表结构的解析 |
| `config` / `runtime` / `metrics` | 配置、运行时依赖注入、指标采集 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.