> ## 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 作为逻辑层数据库的整体多服务设计、部署方式与底层依赖。

# 架构总览

BlockDB 是一层**逻辑数据库**。它由一组相互独立的 gRPC 服务组成，这些服务既可以组装进**同一个无状态的 blockdb 进程**一起运行，也可以**拆分为独立服务**按需部署与扩展。

## 多服务设计

BlockDB 把对外能力拆分为若干服务，每个服务可以独立启停。核心进程 `cmd/blockdb` 通过 `-services` 标志选择要启动的服务集合：

| 服务 | 对外 API | 分类 |
| - | - | - |
| `read` | `GetRow` / `BatchGetRows` / `FilterRows`（普通表读） | 读 |
| `block-read` | `GetEvent` / `GetState` / `GetConsensusHeight` / `GetBlockRows`（区块与状态读） | 读 |
| `scan` | `Scan`（全表流式扫描） | 读 |
| `write` | `UpsertRows` / `DeleteRows` / `UpsertBlock` / `UpsertTimeRows`（各类写） | 写 |
| `batch-write` | `InitWriteJob` / `CommitWriteJob` / `CancelWriteJob`（大批量写任务提交） | 写 |
| `batch-worker` | 后台批量写入 worker（执行 S3 中已提交的任务） | 写（后台） |
| `subscribe` | `Subscribe`（区块事件流式订阅） | 订阅 |
| `state-compactor` | 后台定时通过 `_archive` 表重算 state `latest` 表（必须单实例） | 后台 |

## 元数据服务

`cmd/meta-service` 是独立的元数据进程，负责逻辑表的生命周期与定义管理，包含三个子服务：`TableMetaService`（普通表）、`BlockMetaService`（Block 表）、`TimeMetaService`（Time 表）。核心服务通过 Meta 客户端读取表元数据，自身不持有物理表结构信息。

## 可集成或独立部署

同一套逻辑数据库，可以根据场景自由组合：

* **进程内集成**：把多个服务放进同一个 blockdb 进程，本地共享依赖，便于开发和中小规模部署。
* **独立部署**：按读写等资源特征把服务拆成独立进程，各自水平扩展、独立运维。

进程内的服务组合与拆分不改变对外 API，只影响运行形态。

## 推荐部署拓扑

目前实际部署推荐按读 / 写 / 后台的边界分组：

```text theme={null}
                  ┌──────────────┐
                  │ meta-service │  表元数据管理（独立）
                  └──────────────┘

  读服务（一个 binary）         写服务（一个 binary）
  ┌──────────────┐            ┌──────────────┐
  │ read         │            │ write        │
  │ block-read   │            │              │
  └──────────────┘            └──────────────┘

  独立部署                         独立部署
  ┌──────────────┐  ┌───────────┐ ┌──────────────┐
  │ scan         │  │ subscribe │ │ batch-worker │
  └──────────────┘  └───────────┘ └──────────────┘
```

* **所有读 API（scan 除外）集成在同一个 binary**：`read` + `block-read`。
* **所有写 API 集成在同一个服务**：`write`。
* **`scan` 与 `subscribe` 各自独立部署**：避免大扫描拖累读服务、长连接订阅影响其它服务。
* **批量写入 worker 独立部署**：`batch-worker` 独立扩缩容，与实时读写隔离。

## 底层依赖

BlockDB 作为逻辑层，自身不直接管理数据文件，底层依赖以下设施：

* **物理数据库**：遵循 MySQL 协议的物理在线数据库，BlockDB 通过标准 SQL 完成实际读写。
* **Redis**：作为缓存使用（如区块读取缓存）。
* **Kafka**：作为事件总线，分发区块写入事件并支撑订阅。
* **对象存储**：用于大批量写入的数据中转，以及区块 bundle 等文件的存取。

## 设计要点

* **无状态**：核心服务进程不持有本地状态，可自由组合、水平扩展。
* **元数据与计算分离**：meta-service 管理表元数据，核心读写服务保持无状态。
* **按资源特征拆分**：读 / 写 / 扫描 / 订阅按资源消耗与并发模型拆分为不同服务，便于独立调优与扩缩容。

各模块目录与职责参见[组件介绍](/zh/architecture/components)；大批量写入的具体流程见[大批量写](/zh/architecture/batch-write)。


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