Aptos Indexer GRPC 全节点数据流架构、配置与端到端本地调试指南【免费下载链接】aptos-coreAptos is a layer 1 blockchain built to support the widespread use of blockchain through better technology and user experience.项目地址: https://gitcode.com/GitHub_Trending/ap/aptos-core导读本文围绕 Aptos 仓库中 indexer-grpc-fullnode/README.md 展开深入讲解在 Aptos 全节点Fullnode内直接开启 gRPC 事务流服务的机制它如何把链上交易以流式、分批的方式推送给索引器工作进程如何通过fullnode.yaml中的indexer_grpc配置块控制吞吐以及如何用grpcurl在本地完成从启动节点到拉取交易流的全流程验证。读完本文你将掌握在既有网络上搭建索引器全节点的完整步骤、每个配置参数的含义与默认值以及底层流协调器Stream Coordinator的分批并行处理原理。一、Indexer GRPC Fullnode 是什么Indexer GRPC 是 Aptos 生态中面向低延迟链上数据索引的基础设施见 Indexer GRPC 总览。而indexer-grpc-fullnode是其中运行在全节点进程内部的一个模块它在本机打开一个 gRPC 端点客户端例如后续的 cache-worker 等下游工作进程连接该端点发起请求后gRPC 端点会维护一条流并以**批次batch**为单位把交易推送给客户端。该模块的定位可以从源码结构确认目录 ecosystem/indexer-grpc/indexer-grpc-fullnode/src 下包含runtime.rs服务启动引导、fullnode_data_service.rs标准接口实现、localnet_data_service.rs数据服务接口实现、stream_coordinator.rs流协调与分批处理核心、convert.rsAptos 交易对象到 protobuf 对象的转换等文件。值得注意的两个关键特性流式分批客户端建立一条长连接流服务端持续推送TransactionsFromNodeResponse而不是一次性的请求-响应。批次内无序README 明确说明transactions within a batch may be out of order同一批次内的交易可能乱序。因此客户端不能假定批次内部有序而必须依赖批次携带的版本范围start/end version做去重与补齐。二、核心配置indexer_grpc 配置块2.1 README 给出的最小配置在对接既有网络时只需在fullnode.yaml中加入以下配置块即可开启 Indexer GRPCindexer_grpc: enabled: true address: 0.0.0.0:50051 processor_task_count: 10 processor_batch_size: 100 output_batch_size: 100各字段含义如下结合 config/src/config/indexer_grpc_config.rs 的IndexerGrpcConfig定义配置项README 示例源码默认值含义enabledtruefalse是否开启 Indexer GRPC 服务默认关闭address0.0.0.0:500510.0.0.0:50051gRPC 服务监听地址默认端口常量DEFAULT_GRPC_STREAM_PORT 50051processor_task_count10None运行时按接口类型取默认数据服务接口为 1否则为 20并行抓取/处理事务的处理器任务数fan out 的线程数processor_batch_size1001000DEFAULT_PROCESSOR_BATCH_SIZE每个处理器任务单次从存储抓取的交易数量output_batch_size100100DEFAULT_OUTPUT_BATCH_SIZE单条流响应TransactionsOutput中返回的交易条数transaction_channel_size未配置35DEFAULT_TRANSACTION_CHANNEL_SIZE流传输通道的缓冲区容量mpsc channel 大小max_transaction_filter_size_bytes未配置10000DEFAULT_MAX_TRANSACTION_FILTER_SIZE_BYTES事务过滤器transaction filter的最大字节数限制use_data_service_interface未配置false若为true节点将暴露与生产数据服务Transaction Stream Service API一致的接口可把索引器全节点当作 data service 实例使用2.2 配置校验规则必须同时开启 Table Info 服务从源码看IndexerGrpcConfig实现了ConfigSanitizer其中有一条硬性校验indexer_grpc_config.rs#L106-L130当indexer_grpc.enabled true时若indexer_table_info.table_info_service_mode未启用配置校验会直接报错indexer_table_info.table_info_service_mode must be enabled if indexer_grpc.enabled is true因此实际部署时fullnode.yaml中还需要配套开启 table info 服务例如indexer_table_info.table_info_service_mode: IndexingOnly。这一点在 README 中未显式说明但源码中的 sanitizer 测试test_sanitize_table_info_serviceindexer_grpc_config.rs#L154-L184明确验证了开启 grpc 但关闭 table info 会失败这一行为。2.3 配置生效路径runtime 引导bootstrap函数runtime.rs#L36-L135是服务的启动入口其关键逻辑若config.indexer_grpc.enabled为false直接返回None不启动任何服务从NodeConfig中读取address、processor_task_count未配置时用get_default_processor_task_count按接口类型取默认、processor_batch_size、output_batch_size、transaction_channel_size、max_transaction_filter_size_bytes组装成ServiceContext创建 tokio 运行时并启动 gRPC server绑定配置的地址注册了 gRPC reflection 服务注册了 indexer v1、transaction v1、util timestamp 三份 file descriptor set并配置了 HTTP/2 keepalive间隔 60s、超时 5s根据use_data_service_interface选择暴露FullnodeDataServer标准全节点接口还是RawDataServer数据服务兼容接口两者都启用了 zstd 发送压缩并接受 zstd/gzip 压缩。三、底层原理流如何产生与推送3.1 协议定义流式接口的协议定义在 protos/proto/aptos/internal/fullnode/v1/fullnode_data.proto核心为FullnodeData服务service FullnodeData { rpc Ping(PingFullnodeRequest) returns (PingFullnodeResponse); rpc GetTransactionsFromNode(GetTransactionsFromNodeRequest) returns (stream TransactionsFromNodeResponse); }一次完整流的结构在 proto 注释中有明确约定StreamStatus: INIT with version x loop k: TransactionOutput data(size n) StreamStatus: BATCH_END with version x (k 1) * n - 1即先发送INIT状态携带起始版本作为握手随后循环推送一批交易数据 一个BATCH_END状态。BATCH_END携带该批次的起止版本客户端据此校验是否存在缺口gap。请求方可通过starting_version指定起始版本、通过transactions_count限定返回条数不设置则无限流式推送。3.2 FullnodeDataService 的实现fullnode_data_service.rs 实现了上述 RPCget_transactions_from_node校验starting_version必须设置源码注释说明Live mode unavailable for FullnodeDataService若需实时模式请开启use_data_service_interface随后创建mpsc通道spawn 一个异步任务驱动IndexerStreamCoordinator循环处理批次把TransactionsFromNodeResponse推入流最后以ReceiverStream包装通道返回给 tonic 框架。响应有两种类型Status向客户端发送INIT/BATCH_END事件与Data轻量包装后的编码交易。每批处理结束后发送BATCH_END客户端可用 start/end version 做连续性校验若BATCH_END发送失败则终止循环此时客户端无法可靠校验缺口。ping返回FullnodeInfochain_id、当前时间戳、known_latest_version并统计端到端延迟指标。3.3 Stream Coordinator 的四阶段流水线stream_coordinator.rs 是整个流服务的核心引擎process_next_batch以四阶段流水线处理每一批源码注释 1~4 阶段从存储抓取fetch_transactions_from_storage根据processor_task_count与processor_batch_size拆分成多个TransactionBatchInfo并行tokio::spawn抓取结果按版本排序后汇总带重试逻辑fetch_raw_txns_with_retries默认 3 次重试重试间隔 300ms若遇到版本已被修剪pruned错误则直接返回out_of_range而不重试。转换为 Rust 对象convert_to_api_txns把链上交易转为 REST API 层交易对象补充 block height、epoch、时间戳等块元数据按约 100KB 的MINIMUM_TASK_LOAD_SIZE_IN_BYTES再切分子任务用spawn_blocking并行执行。转换为 protobuf 对象convert_to_pb_txns核心实现在 convert.rs约 1169 行覆盖 Move 结构、签名、事件、JWK 等各类交易的序列化。编码并发送按output_batch_size切块、再按消息大小上限MESSAGE_SIZE_LIMIT二次切块chunk_transactions包装为TransactionsOutput推入流通道。get_batches中有一个关键细节end_version min(self.end_version, self.highest_known_version 1)且ensure_highest_known_version会循环查询最新账本状态并 sleep 等待新交易——这正是实时跟随链头的实现机制。四、本地调试全流程4.1 方案一对接既有网络README 原始流程按官方指引获取genesis、waypoint和fullnode.yaml在fullnode.yaml中加入上文indexer_grpc配置块并记得同时配置indexer_table_info.table_info_service_mode见 2.2 节启动全节点cargo run -p aptos-node --release -- -f ./fullnode.yaml另开终端安装grpcurl后从仓库根目录发起流式请求grpcurl -max-msg-sz 10000000 -d { starting_version: 0 } \ -import-path crates/aptos-protos/proto \ -proto aptos/internal/fullnode/v1/fullnode_data.proto \ -plaintext 127.0.0.1:50051 \ aptos.internal.fullnode.v1.FullnodeData/GetTransactionsFromNode注意README 中的-import-path crates/aptos-protos/proto指向旧路径。在当前仓库中 proto 文件位于 protos/proto/aptos/internal/fullnode/v1/fullnode_data.proto因此实际执行时-import-path应改为protos/proto。-max-msg-sz 10000000将单条消息上限放大到约 10MB避免因批次较大导致读取失败。4.2 方案二本地测试模式indexer-grpc 总览 README 的补充流程ecosystem/indexer-grpc/README.md 提供了不依赖既有网络的本地试验方式创建测试数据目录并启动测试模式全节点mkdir test_indexer_grpc cargo run -p aptos-node -- --test --test-dir test_indexer_grpc用Ctrl-C暂停节点在自动生成的test_indexer_grpc/0/node.yaml中加入上文indexer_grpc配置块再次启动cargo run -p aptos-node -- --test --test-dir test_indexer_grpc用与 4.1 相同的grpcurl命令验证端点。4.3 常见问题排查流无输出确认starting_version对应的数据未被修剪。源码中若请求版本已被修剪服务端会返回out_of_range错误信息提示If this node uses fast sync, older transactions are not available——使用 fast sync 的全节点不保留历史交易。配置校验失败检查是否开启了indexer_table_info.table_info_service_mode见 2.2。端口冲突本地同时运行多个服务时每个服务的health_check_port必须不同见总览 README 的说明。五、与完整 Indexer GRPC 链路的关系indexer-grpc-fullnode只是整个 Indexer GRPC 链路的第一个环节。生产环境Cloud Setup中完整的服务拓扑为见 ecosystem/indexer-grpc/README.mdIndexer fullnode本文主体在节点内暴露 gRPC 事务流cache-workerindexer-grpc-cache-worker/README.md从全节点 gRPC 拉取数据并写入 Redis 缓存file-storeindexer-grpc-file-store/README.md从缓存读取数据并归档到对象存储GCS 或本地目录元数据由metadata.jsonchain_id / blob_size / version驱动data-serviceindexer-grpc-data-service/README.md面向外部索引器的统一查询入口同时从缓存与文件存储取数支持 TLS/非 TLS 双端点与whitelisted_auth_tokens鉴权。本地联调时同样按此顺序启动先跑 redisredis-server建本地文件存储目录mkdir test_indexer_grpc_filestore配置中file_store_type: LocalFileStore再依次启动 cache-worker → file-store → contenteditable="false">【免费下载链接】aptos-coreAptos is a layer 1 blockchain built to support the widespread use of blockchain through better technology and user experience.项目地址: https://gitcode.com/GitHub_Trending/ap/aptos-core创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Aptos Indexer GRPC 全节点数据流：架构、配置与端到端本地调试指南
Aptos Indexer GRPC 全节点数据流架构、配置与端到端本地调试指南【免费下载链接】aptos-coreAptos is a layer 1 blockchain built to support the widespread use of blockchain through better technology and user experience.项目地址: https://gitcode.com/GitHub_Trending/ap/aptos-core导读本文围绕 Aptos 仓库中 indexer-grpc-fullnode/README.md 展开深入讲解在 Aptos 全节点Fullnode内直接开启 gRPC 事务流服务的机制它如何把链上交易以流式、分批的方式推送给索引器工作进程如何通过fullnode.yaml中的indexer_grpc配置块控制吞吐以及如何用grpcurl在本地完成从启动节点到拉取交易流的全流程验证。读完本文你将掌握在既有网络上搭建索引器全节点的完整步骤、每个配置参数的含义与默认值以及底层流协调器Stream Coordinator的分批并行处理原理。一、Indexer GRPC Fullnode 是什么Indexer GRPC 是 Aptos 生态中面向低延迟链上数据索引的基础设施见 Indexer GRPC 总览。而indexer-grpc-fullnode是其中运行在全节点进程内部的一个模块它在本机打开一个 gRPC 端点客户端例如后续的 cache-worker 等下游工作进程连接该端点发起请求后gRPC 端点会维护一条流并以**批次batch**为单位把交易推送给客户端。该模块的定位可以从源码结构确认目录 ecosystem/indexer-grpc/indexer-grpc-fullnode/src 下包含runtime.rs服务启动引导、fullnode_data_service.rs标准接口实现、localnet_data_service.rs数据服务接口实现、stream_coordinator.rs流协调与分批处理核心、convert.rsAptos 交易对象到 protobuf 对象的转换等文件。值得注意的两个关键特性流式分批客户端建立一条长连接流服务端持续推送TransactionsFromNodeResponse而不是一次性的请求-响应。批次内无序README 明确说明transactions within a batch may be out of order同一批次内的交易可能乱序。因此客户端不能假定批次内部有序而必须依赖批次携带的版本范围start/end version做去重与补齐。二、核心配置indexer_grpc 配置块2.1 README 给出的最小配置在对接既有网络时只需在fullnode.yaml中加入以下配置块即可开启 Indexer GRPCindexer_grpc: enabled: true address: 0.0.0.0:50051 processor_task_count: 10 processor_batch_size: 100 output_batch_size: 100各字段含义如下结合 config/src/config/indexer_grpc_config.rs 的IndexerGrpcConfig定义配置项README 示例源码默认值含义enabledtruefalse是否开启 Indexer GRPC 服务默认关闭address0.0.0.0:500510.0.0.0:50051gRPC 服务监听地址默认端口常量DEFAULT_GRPC_STREAM_PORT 50051processor_task_count10None运行时按接口类型取默认数据服务接口为 1否则为 20并行抓取/处理事务的处理器任务数fan out 的线程数processor_batch_size1001000DEFAULT_PROCESSOR_BATCH_SIZE每个处理器任务单次从存储抓取的交易数量output_batch_size100100DEFAULT_OUTPUT_BATCH_SIZE单条流响应TransactionsOutput中返回的交易条数transaction_channel_size未配置35DEFAULT_TRANSACTION_CHANNEL_SIZE流传输通道的缓冲区容量mpsc channel 大小max_transaction_filter_size_bytes未配置10000DEFAULT_MAX_TRANSACTION_FILTER_SIZE_BYTES事务过滤器transaction filter的最大字节数限制use_data_service_interface未配置false若为true节点将暴露与生产数据服务Transaction Stream Service API一致的接口可把索引器全节点当作 data service 实例使用2.2 配置校验规则必须同时开启 Table Info 服务从源码看IndexerGrpcConfig实现了ConfigSanitizer其中有一条硬性校验indexer_grpc_config.rs#L106-L130当indexer_grpc.enabled true时若indexer_table_info.table_info_service_mode未启用配置校验会直接报错indexer_table_info.table_info_service_mode must be enabled if indexer_grpc.enabled is true因此实际部署时fullnode.yaml中还需要配套开启 table info 服务例如indexer_table_info.table_info_service_mode: IndexingOnly。这一点在 README 中未显式说明但源码中的 sanitizer 测试test_sanitize_table_info_serviceindexer_grpc_config.rs#L154-L184明确验证了开启 grpc 但关闭 table info 会失败这一行为。2.3 配置生效路径runtime 引导bootstrap函数runtime.rs#L36-L135是服务的启动入口其关键逻辑若config.indexer_grpc.enabled为false直接返回None不启动任何服务从NodeConfig中读取address、processor_task_count未配置时用get_default_processor_task_count按接口类型取默认、processor_batch_size、output_batch_size、transaction_channel_size、max_transaction_filter_size_bytes组装成ServiceContext创建 tokio 运行时并启动 gRPC server绑定配置的地址注册了 gRPC reflection 服务注册了 indexer v1、transaction v1、util timestamp 三份 file descriptor set并配置了 HTTP/2 keepalive间隔 60s、超时 5s根据use_data_service_interface选择暴露FullnodeDataServer标准全节点接口还是RawDataServer数据服务兼容接口两者都启用了 zstd 发送压缩并接受 zstd/gzip 压缩。三、底层原理流如何产生与推送3.1 协议定义流式接口的协议定义在 protos/proto/aptos/internal/fullnode/v1/fullnode_data.proto核心为FullnodeData服务service FullnodeData { rpc Ping(PingFullnodeRequest) returns (PingFullnodeResponse); rpc GetTransactionsFromNode(GetTransactionsFromNodeRequest) returns (stream TransactionsFromNodeResponse); }一次完整流的结构在 proto 注释中有明确约定StreamStatus: INIT with version x loop k: TransactionOutput data(size n) StreamStatus: BATCH_END with version x (k 1) * n - 1即先发送INIT状态携带起始版本作为握手随后循环推送一批交易数据 一个BATCH_END状态。BATCH_END携带该批次的起止版本客户端据此校验是否存在缺口gap。请求方可通过starting_version指定起始版本、通过transactions_count限定返回条数不设置则无限流式推送。3.2 FullnodeDataService 的实现fullnode_data_service.rs 实现了上述 RPCget_transactions_from_node校验starting_version必须设置源码注释说明Live mode unavailable for FullnodeDataService若需实时模式请开启use_data_service_interface随后创建mpsc通道spawn 一个异步任务驱动IndexerStreamCoordinator循环处理批次把TransactionsFromNodeResponse推入流最后以ReceiverStream包装通道返回给 tonic 框架。响应有两种类型Status向客户端发送INIT/BATCH_END事件与Data轻量包装后的编码交易。每批处理结束后发送BATCH_END客户端可用 start/end version 做连续性校验若BATCH_END发送失败则终止循环此时客户端无法可靠校验缺口。ping返回FullnodeInfochain_id、当前时间戳、known_latest_version并统计端到端延迟指标。3.3 Stream Coordinator 的四阶段流水线stream_coordinator.rs 是整个流服务的核心引擎process_next_batch以四阶段流水线处理每一批源码注释 1~4 阶段从存储抓取fetch_transactions_from_storage根据processor_task_count与processor_batch_size拆分成多个TransactionBatchInfo并行tokio::spawn抓取结果按版本排序后汇总带重试逻辑fetch_raw_txns_with_retries默认 3 次重试重试间隔 300ms若遇到版本已被修剪pruned错误则直接返回out_of_range而不重试。转换为 Rust 对象convert_to_api_txns把链上交易转为 REST API 层交易对象补充 block height、epoch、时间戳等块元数据按约 100KB 的MINIMUM_TASK_LOAD_SIZE_IN_BYTES再切分子任务用spawn_blocking并行执行。转换为 protobuf 对象convert_to_pb_txns核心实现在 convert.rs约 1169 行覆盖 Move 结构、签名、事件、JWK 等各类交易的序列化。编码并发送按output_batch_size切块、再按消息大小上限MESSAGE_SIZE_LIMIT二次切块chunk_transactions包装为TransactionsOutput推入流通道。get_batches中有一个关键细节end_version min(self.end_version, self.highest_known_version 1)且ensure_highest_known_version会循环查询最新账本状态并 sleep 等待新交易——这正是实时跟随链头的实现机制。四、本地调试全流程4.1 方案一对接既有网络README 原始流程按官方指引获取genesis、waypoint和fullnode.yaml在fullnode.yaml中加入上文indexer_grpc配置块并记得同时配置indexer_table_info.table_info_service_mode见 2.2 节启动全节点cargo run -p aptos-node --release -- -f ./fullnode.yaml另开终端安装grpcurl后从仓库根目录发起流式请求grpcurl -max-msg-sz 10000000 -d { starting_version: 0 } \ -import-path crates/aptos-protos/proto \ -proto aptos/internal/fullnode/v1/fullnode_data.proto \ -plaintext 127.0.0.1:50051 \ aptos.internal.fullnode.v1.FullnodeData/GetTransactionsFromNode注意README 中的-import-path crates/aptos-protos/proto指向旧路径。在当前仓库中 proto 文件位于 protos/proto/aptos/internal/fullnode/v1/fullnode_data.proto因此实际执行时-import-path应改为protos/proto。-max-msg-sz 10000000将单条消息上限放大到约 10MB避免因批次较大导致读取失败。4.2 方案二本地测试模式indexer-grpc 总览 README 的补充流程ecosystem/indexer-grpc/README.md 提供了不依赖既有网络的本地试验方式创建测试数据目录并启动测试模式全节点mkdir test_indexer_grpc cargo run -p aptos-node -- --test --test-dir test_indexer_grpc用Ctrl-C暂停节点在自动生成的test_indexer_grpc/0/node.yaml中加入上文indexer_grpc配置块再次启动cargo run -p aptos-node -- --test --test-dir test_indexer_grpc用与 4.1 相同的grpcurl命令验证端点。4.3 常见问题排查流无输出确认starting_version对应的数据未被修剪。源码中若请求版本已被修剪服务端会返回out_of_range错误信息提示If this node uses fast sync, older transactions are not available——使用 fast sync 的全节点不保留历史交易。配置校验失败检查是否开启了indexer_table_info.table_info_service_mode见 2.2。端口冲突本地同时运行多个服务时每个服务的health_check_port必须不同见总览 README 的说明。五、与完整 Indexer GRPC 链路的关系indexer-grpc-fullnode只是整个 Indexer GRPC 链路的第一个环节。生产环境Cloud Setup中完整的服务拓扑为见 ecosystem/indexer-grpc/README.mdIndexer fullnode本文主体在节点内暴露 gRPC 事务流cache-workerindexer-grpc-cache-worker/README.md从全节点 gRPC 拉取数据并写入 Redis 缓存file-storeindexer-grpc-file-store/README.md从缓存读取数据并归档到对象存储GCS 或本地目录元数据由metadata.jsonchain_id / blob_size / version驱动data-serviceindexer-grpc-data-service/README.md面向外部索引器的统一查询入口同时从缓存与文件存储取数支持 TLS/非 TLS 双端点与whitelisted_auth_tokens鉴权。本地联调时同样按此顺序启动先跑 redisredis-server建本地文件存储目录mkdir test_indexer_grpc_filestore配置中file_store_type: LocalFileStore再依次启动 cache-worker → file-store → contenteditable="false">【免费下载链接】aptos-coreAptos is a layer 1 blockchain built to support the widespread use of blockchain through better technology and user experience.项目地址: https://gitcode.com/GitHub_Trending/ap/aptos-core创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考