
Aptos Indexer GRPC Data Service 部署与配置指南从 YAML 配置、TLS/非 TLS 双端点到 HTTP2 保活与 gRPC Web UI 调试【免费下载链接】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-coreIndexer GRPC data service 是 Aptos Indexer GRPC 体系中面向下游索引器indexer提供链上交易流数据的 gRPC 服务它同时从内存缓存Redis/InMemory Cache与冷存储文件库GCS file store读取数据以流式方式持续推送交易。本文基于 ecosystem/indexer-grpc/indexer-grpc-data-service/README.md 及其源码完整讲解该服务的 YAML 配置逐项语义、GCS 服务账号与启动方式、TLS 与非 TLS 双端点设计、HTTP2 ping 长连接保活机制以及如何使用 grpcui 在浏览器中调试流式接口并辅以源码级原理剖析帮助你快速上手部署与排查。服务定位连接缓存 文件库的数据出口在整个 Indexer GRPC 生产链路中data service 处于对外提供数据的出口位置。上游由 cache worker 负责将 fullnode 产生的交易写入 Redis 热缓存file store worker 负责将数据落盘到 GCS 冷存储data service 则以只读姿态同时消费这两层存储为下游索引器提供统一的GetTransactions流式 gRPC 接口。这一点在服务自身描述中写得很明确Indexer GRPC data service fetches data from both cache and file store见 indexer-grpc-data-service/Cargo.toml。在生产环境中整个 Indexer GRPC 的启动顺序为fullnode → cache worker → file store worker → data service参考 ecosystem/indexer-grpc/README.md 的 General Startup 一节data service 需要依赖前序组件把数据准备好尤其是 GCS 冷存储中必须有 file store 元数据chain_id 等服务才会真正开始对外提供服务。前置条件与启动方式服务账号与 bucket 权限data service 需要读取 GCS bucket 中的归档交易因此必须准备一个对${file_store_bucket_name}具有read权限的服务账号 JSON 文件例如xxx.json通过环境变量SERVICE_ACCOUNT指定该服务账号 JSON 文件的路径。从 GCS file store 实现 可以看到服务在初始化时会用该服务账号访问 bucket上游 Indexer GRPC 总览文档也强调若使用 GCS 文件操作器服务账号应被授予Object Owner读写每个文件与Bucket Owner校验 bucket 是否存在两类角色。data service 本身只做读取因此服务账号具备read权限即可满足其自身职责。启动命令服务通过统一的 server framework 启动入口在 main.rs解析命令行参数后调用ServerArgs::run::IndexerGrpcDataServiceConfig()启动命令为cargo run --release -- -c config.yaml其中-c指定 YAML 配置文件路径。main.rs在 Unix 平台下还会启用 jemalloc 作为全局内存分配器适合长时间运行的高吞吐服务。YAML 配置详解README 给出了一份可运行的 YAML 示例逐字段说明如下health_check_port: 8083 server_config: whitelisted_auth_tokens: - token1 - token2 file_store_config: file_store_type: GcsFileStore gcs_file_store_bucket_name: indexer-grpc-file-store-bucketname data_service_grpc_tls_config: data_service_grpc_listen_address: 0.0.0.0:50052 cert_path: /path/to/cert.cert key_path: /path/to/key.pem data_service_grpc_non_tls_config: data_service_grpc_listen_address: 0.0.0.0:50051 redis_read_replica_address: 127.0.0.1:6379各配置项在 config.rs 中有严格定义#[serde(deny_unknown_fields)]意味着未知字段会导致启动报错配置必须精确配置项类型必填说明health_check_portu16是健康检查端口由 server framework 统一读取见 server-framework/src/lib.rs供负载均衡探活使用多服务同机部署时各配置必须不同server_config.whitelisted_auth_tokensVecString否允许消费端点的 token 列表。从源码注释看该字段已标记为Deprecated废弃默认空列表server_config.disable_auth_checkbool否废弃字段若设置则跳过鉴权检查默认falseserver_config.file_store_config枚举是交易归档的冷存储配置file_store_type支持GcsFileStore与LocalFileStore两种server_config.data_service_grpc_tls_config对象二者至少其一TLS 端点https配置含监听地址、证书与私钥路径server_config.data_service_grpc_non_tls_config对象二者至少其一非 TLS 端点http配置仅含监听地址server_config.redis_read_replica_addressRedisUrl是Redis 只读副本地址data service 从该 Redis 读取热缓存server_config.data_service_response_channel_sizeusize否响应 channel 缓冲大小默认3见DEFAULT_MAX_RESPONSE_CHANNEL_SIZEserver_config.enable_cache_compressionbool否是否读取压缩缓存数据默认false对应Base64UncompressedProto格式server_config.in_memory_cache_config对象否内存缓存配置默认空配置server_config.txns_to_strip_filter过滤表达式否命中过滤条件的交易会被剥离清除 payload、签名、事件与 writeset 后仍下发给客户端默认空 OR 过滤不剥离任何交易仅用于紧急情况其中 TLS 与非 TLS 配置在validate()中有一个强制约束二者至少配置其一否则直接报错拒绝启动if self.data_service_grpc_non_tls_config.is_none() self.data_service_grpc_tls_config.is_none() { bail!(At least one of data_service_grpc_non_tls_config and data_service_grpc_tls_config must be set); }file_store_config 的两种形态file_store_type通过 serde tag 方式区分见 indexer-grpc-utils/src/config.rsGcsFileStore生产推荐file_store_config: file_store_type: GcsFileStore gcs_file_store_bucket_name: indexer-grpc-file-store-bucketname # 可选gcs_file_store_bucket_sub_dir: 子目录 # 可选enable_compression: falseGCS 冷存储适合生产环境长期归档README 的总览文档指出生产环境当前依赖 GCS bucket 做冷存储因此最宜在 GCP 上运行。LocalFileStore本地调试file_store_config: file_store_type: LocalFileStore local_file_store_path: test_indexer_grpc_filestore本地目录即冷存储适合单机联调不需要云 bucket 与服务账号。TLS 与非 TLS 双端点设计README 专门解释了两个端点的关系data_service_grpc_tls_configTLS 加密的 gRPC 端点https可以只暴露 TLS 端点data_service_grpc_non_tls_config无加密的 gRPC 端点http也可以只暴露非 TLS 端点。两者采用非互斥non mutual-exclusive方式引入是为了避免客户端兼容性问题——在迁移/混合部署阶段允许服务同时监听两个端口让不同能力是否支持 TLS的客户端各自选择接入。从源码看两个端点由两个独立 tokio 任务分别拉起TLS 端会从cert_path/key_path读取 PEM 证书并构造tonic::Identity两个端点都会注册 gRPC reflection 服务与相同的RawDataServer实现见 config.rs。HTTP2-ping 长连接保活机制长时间运行的流式连接容易遭遇网络静默中断README 为此引入HTTP2 ping 主动探测来检测连接是否断开HTTP2_PING_INTERVAL_DURATIONHTTP2 ping 发送间隔常量默认 60sHTTP2_PING_TIMEOUT_DURATIONHTTP2 ping 超时常量默认 10s。两个常量在 config.rs 中硬编码并在启动 gRPC server 时通过tonic的 builder 生效Server::builder() .http2_keepalive_interval(Some(HTTP2_PING_INTERVAL_DURATION)) .http2_keepalive_timeout(Some(HTTP2_PING_TIMEOUT_DURATION)) .add_service(svc_clone) .add_service(reflection_service_clone) .serve(listen_address)这套机制可以帮助服务端主动垃圾回收死连接garbage collect dead connections从而及时释放资源。重要限制HTTP2 ping 需要链路各层代理都支持 HTTP2 ping 帧。README 明确指出AWS/ALB 等代理可能不支持该特性因为 ping 帧经过 ALB 时无法透传导致保活失效因此在 ALB 之后的部署中需要自行评估健康检查与连接保活方案。用 grpcui Web UI 调试服务对于流式接口的日常调试README 推荐使用grpcui图形化工具。安装以 Mac 为例brew install grpcui启动服务cargo run --release -- -c config.yaml打开 Web UIgrpcui -plaintext 127.0.0.1:50052注意这里使用的端口必须与配置文件中data_service_grpc_listen_address的端口保持一致-plaintext表示以非 TLS 方式连接因此该地址应对应data_service_grpc_non_tls_config.data_service_grpc_listen_address示例中为0.0.0.0:50051。若该配置被省略、只启用了 TLS 端点则需要改用 TLS 连接参数并指向 TLS 端口由于服务注册了 gRPC reflectiongrpcui 可以自动发现aptos.indexer.v1.RawData/GetTransactions等接口并进行流式调用无需手动指定 proto 文件。数据读取路径与流式服务原理结合源码可以更深入地理解 data service 的内部工作方式核心逻辑位于 service.rs双路数据读取缓存优先、冷存储兜底get_transactions是流式server-streaminggRPC 接口每个请求都会 spawn 一个data_fetcher_task异步任务按以下顺序取数InMemoryCache 优先先用内存缓存直接命中一段交易in_memory_cache.get_transactions(start_version)命中即返回Redis 热缓存内存未命中则通过CacheOperator批量读取 Redis 中编码的 proto 数据命中后经spawn_blocking解码Base64UncompressedProto或Lz4CompressedProto由enable_cache_compression决定后返回File store 冷存储兜底若 Redis 中的该段数据已被驱逐CacheEvicted则回源到 GCS/Local file store 读取最多重试NUM_DATA_FETCH_RETRIES 5次。关键健壮性设计数据未就绪AheadOfCache当请求的版本超出缓存当前头部时任务休眠AHEAD_OF_CACHE_RETRY_SLEEP_DURATION_MS 50ms后重试等待数据追平瞬时错误重试缓存/file store 读取出错时休眠TRANSIENT_DATA_ERROR_RETRY_SLEEP_DURATION_MS 1000ms后重试多任务并行取数数据被驱逐出缓存时按每 1000 笔交易一个存储块切分最多MAX_FETCH_TASKS_PER_REQUEST 5个任务并行回源顺序与去重ensure_sequential_transactions会按版本排序多个批次合并重叠区间、对完全包含的批次去重并在发现版本间隙时直接panic保证下游拿到的数据严格连续对应的单元测试test_ensure_sequential_transactions_merges_and_sorts覆盖了无重叠、完全重叠与部分重叠三种场景见 service.rs慢客户端保护响应 channel 发送超时为RESPONSE_CHANNEL_SEND_TIMEOUT 120s防止慢消费者长期占住服务端任务连接时长不足 10s 会被计入短连接指标chain_id 校验启动取数任务时会同时读取 file store 元数据与 Redis 中的 chain_id 并比对不一致时直接返回Chain ID mismatch错误交易剥离stripping命中txns_to_strip_filter的交易会被清空 payload、签名、events 与 writeset保留交易骨架与版本号后再下发用于应对特定模块交易过大导致的紧急场景service.rs 中以 sender 地址、module 地址、module 名、函数名为条件的剥离测试均验证了该行为。可观测性服务内置 Prometheus 指标见 metrics.rs 与 service.rs 中的埋点包括但不限于CONNECTION_COUNT接入的连接数SHORT_CONNECTION_COUNT短连接10s计数ERROR_COUNT按data_fetch_failed/redis_connection_failed/redis_get_chain_id_failed等标签区分的错误计数LATEST_PROCESSED_VERSION_PER_PROCESSOR/PROCESSED_VERSIONS_COUNT_PER_PROCESSOR/PROCESSED_LATENCY_IN_SECS_PER_PROCESSOR按处理器维度统计的已处理版本水位、数量与数据延迟BYTES_READY_TO_TRANSFER_FROM_SERVER/BYTES_READY_TO_TRANSFER_FROM_SERVER_AFTER_STRIPPING剥离前后的待传输字节量NUM_TRANSACTIONS_STRIPPED被剥离交易数。这些指标配合health_check_port的探活端点可用于监控大盘与告警配置仓库的 dashboards 目录中也包含 Indexer GRPC 相关面板定义。小结Indexer GRPC data service 是 Aptos 链上数据低延迟索引出口的关键一环它通过内存缓存 → Redis 热缓存 → GCS/本地冷存储三级读取路径以流式 gRPC 持续向索引器输送严格有序的交易数据通过 TLS/非 TLS 双端点设计兼顾安全与兼容通过 HTTP2 ping 保活主动清理死连接并通过多级重试、慢客户端保护与交易剥离机制保障生产可用性。部署时只需按本文的 YAML 结构准备好服务账号、bucket、Redis 与配置文件执行cargo run --release -- -c config.yaml即可启动调试时借助 grpcui 与内置 reflection 即可快速验证流式接口的行为。【免费下载链接】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),仅供参考