用 Docker Compose 搭建 Linera Indexer 与 Block Exporter 全链路测试环境-港品优选

用 Docker Compose 搭建 Linera Indexer 与 Block Exporter 全链路测试环境

【免费下载链接】linera-protocolMain repository for the Linera protocol项目地址: https://gitcode.com/GitHub_Trending/li/linera-protocol

本篇指南基于 Linera 协议仓库 docker/README.indexer-test.md 展开，介绍如何在容器化环境中一键搭建用于测试Linera Indexer（索引器）与Block Exporter（区块导出器）的完整测试栈：从存储服务、单验证者网络（含 faucet 水龙头链）、gRPC 索引器，到区块导出器及其数据落盘目标一应俱全。读完本文，你将掌握该测试环境的启动/验证/停止流程、全部可配置环境变量与依赖顺序，并能结合仓库中的 Compose 编排与源码理解每条配置背后的实现细节，直接复用于本地开发与 CI 验证。

为什么需要一套"容器化测试栈"

Linera 是一个面向多链（microchain）架构的协议，验证者、索引器、区块导出器、水龙头等服务需要协同运行才能形成一条可观测、可消费的数据链路。单独手工启动这些组件非常繁琐，而且难以保证依赖顺序与状态一致性。

仓库中的 docker/docker-compose.indexer-test.yml 就是为了解决这个问题而设计的：它用单个 Compose 文件编排起所有测试组件，让开发者一条命令启动、一条命令清理，可以反复验证索引器与区块导出器在真实网络上的行为。当前所有组件被打包进同一个名为linera-all-test的 Docker 镜像，方便统一构建与分发。

组件一览与启动顺序

这套测试栈共包含以下组件，按启动顺序排列：

顺序	服务	角色
1	Linera Storage Service / 数据库	验证者与导出器的存储后端（ScyllaDB + PostgreSQL）
2	Linera Indexer	基于 gRPC 的索引器服务，消费区块并将数据写入 PostgreSQL
3	Linera Block Exporter	导出区块与 blob，同时暴露 Prometheus 指标
4	Linera Network	单验证者网络，含 faucet 水龙头链

需要注意，Compose 文件中还包含linera-explorer（前端 3001 / API 3002）与storage-init（等待 Scylla 命名空间初始化）两个辅助服务，用于可视化和保证导出器启动时机正确。

快速开始

1. 构建 Docker 镜像

cd docker ./make-all-build.sh

2. 启动全部服务

# 在 /docker 目录下 ./make-all-up.sh

这里有必要看一下脚本实际做了什么。docker/make-all-up.sh 会先清理上一次运行遗留的数据（删除./exporter-data/、./indexer-data/、./scylla-data/目录），随后执行docker system prune -f与docker volume prune -f清理孤儿容器与悬空卷，最后以强制重建方式拉起服务：

docker-compose -f ./docker-compose.indexer-test.yml up --force-recreate --remove-orphans

--force-recreate确保每个容器都用最新镜像重建，--remove-orphans移除不再被 Compose 文件引用的旧容器。正因如此，每次make-all-up.sh都是一次"干净状态"的启动。

3. 验证服务是否就绪

服务启动后可分别探测以下端口：

服务	探测命令	说明
Storage Service	`curl http://localhost:1235`	存储服务
Indexer	`curl http://localhost:8081`	索引器 gRPC 端口
Block Exporter	`curl http://localhost:8882`	导出器服务端口
Metrics	`curl http://localhost:9091/metrics`	Prometheus 指标端点
Faucet	`curl http://localhost:8080`	水龙头服务

这些端口全部来自 docker/docker-compose.indexer-test.yml 中的端口映射，可通过环境变量覆盖（见下文）。

4. 停止服务

# 在 /docker 目录下 ./make-all-down.sh

docker/make-all-down.sh 执行docker-compose down --volumes --remove-orphans，随后同样清理数据目录与悬空资源，保证下次启动从全新状态开始。

配置详解：环境变量

所有端口与路径均可通过.env.indexer-test环境变量配置：

变量	默认值	用途
`LINERA_STORAGE_SERVICE_PORT`	`1235`	存储服务端口
`INDEXER_PORT`	`8081`	索引器 gRPC 端口
`INDEXER_DATABASE_PATH`	`/data/indexer.db`	索引器数据库路径（SQLite）
`BLOCK_EXPORTER_PORT`	`8882`	区块导出器端口
`METRICS_PORT`	`9091`	指标端点端口
`FAUCET_PORT`	`8080`	水龙头服务端口
`LINERA_INDEXER_IMAGE`	`linera-all-test`	Docker 镜像名

仓库中的 docker/.env.indexer-test 是实际生效的默认文件，内容比 README 列出的变量更完整，还包含：

# PostgreSQL Database configuration POSTGRES_USER=postgres POSTGRES_PASSWORD=postgres POSTGRES_DB=linera_indexer POSTGRES_PORT=5432 # Explorer configuration EXPLORER_FRONTEND_PORT=3001 EXPLORER_API_PORT=3002 # Docker images LINERA_EXPLORER_IMAGE=linera-explorer-new

Compose 文件中的每个值都带有${VAR:-default}回退语法，例如"${INDEXER_PORT:-8081}:${INDEXER_PORT:-8081}"，意味着即使不设置任何环境变量，服务也能用默认端口启动。

自定义配置

如需覆盖默认设置：

复制.env.indexer-test为.env.local
修改.env.local中的值
用显式指定环境文件的方式启动：

docker-compose -f docker-compose.indexer-test.yml --env-file .env.local up

服务依赖与健康检查

Compose 文件为每个服务都定义了healthcheck与depends_on，形成一条严格的启动链：

Storage Service 最先启动：postgres用pg_isready探测，scylla用cqlsh -e 'SELECT now() FROM system.local'探测，两者就绪后索引器才能启动；
Indexer 等待 Storage 健康：linera-indexer通过nc -z localhost 8081探测自身端口，depends_on要求 scylla 与 postgres 均为service_healthy；
Block Exporter 等待 Indexer 健康：linera-block-exporter通过nc -z localhost 8882探测，且依赖storage-init完成（service_completed_successfully）；
Network 等待 Block Exporter 健康：linera-network通过nc -z localhost 8080探测 faucet 端口，depends_on要求linera-indexer健康。

其中storage-init是一个"等待器"容器，循环执行：

./linera storage check-existence --storage scylladb:tcp:scylla:9042:table_default_server_0_db

直到 Scylla 中的存储命名空间被网络初始化成功才退出，确保区块导出器连接的是已就绪的存储。这种多层健康检查 + 显式依赖的设计，避免了"导出器先于存储就绪导致连接失败"的经典时序问题。

ScyllaDB 的主机调优

值得注意的一点是，scylla-setup是一个以privileged: true运行的特权容器，挂载宿主机的/proc、/sys与/etc/sysctl.d，执行 docker/compose-scylla-setup.sh。该脚本按照 ScyllaDB 官方建议，根据宿主机 CPU 核数与内存动态计算并设置内核参数，包括：

fs.aio-max-nr：异步 I/O 上限（65536 × shard 数 × 1.5，最低 1048576）；
net.core.somaxconn/net.ipv4.tcp_max_syn_backlog：套接字与 SYN 队列；
vm.max_map_count、vm.swappiness、vm.dirty_ratio等内存参数；
fs.file-max/fs.nr_open文件描述符上限；
关闭 Transparent Huge Pages（THP）与 NUMA balancing。

脚本支持--persist模式，将计算出的参数写入/etc/sysctl.d/99-scylladb.conf以便重启后依然生效。容器内 Scylla 以--developer-mode 1 --overprovisioned 1启动，适合在开发/测试机而非生产硬件上运行。

区块导出器：从 Compose 到源码

linera-block-exporter的启动命令为：

./linera-exporter run \ --storage scylladb:tcp:scylla:9042:table_default_server_0_db \ --config-path /exporter-config.toml \ --metrics-port ${METRICS_PORT:-9091}

其配置文件挂载自 docker/exporter-config.toml，对应源码中的BlockExporterConfig（见 linera-exporter/src/config.rs）。该结构体包含：

id：导出器状态标识；
service_config：服务监听地址与端口（0.0.0.0:8882）；
destination_config：导出目标列表，committee_destination = true表示同时向当前委员会导出；
limits：资源限制；
metrics_port：/metrics端点的监听端口。

示例配置定义了两个导出目标：一个是Logging类型，把区块与 blob 记录追加到/data/linera-exporter.log；另一个是Indexer类型，通过明文 gRPC（tls = "ClearText"）将数据推送到linera-indexer:8081。limits小节给出了缓存与队列的推荐值：persistence_period_ms = 10_000、work_queue_size = 256、各缓存容量 1024 MB / 8192 条。这些配置项与 README 中"exporter-data下的linera-exporter.log记录了它处理过的所有区块与 blob"的描述一一对应。

索引器：gRPC 服务与存储

linera-indexer的启动命令为：

./linera-indexer-grpc \ --port ${INDEXER_PORT:-8081} \ --postgres postgresql://postgres:postgres@postgres:5432/linera_indexer

即索引器通过 gRPC 对外提供数据查询，把区块数据持久化到 PostgreSQL。镜像构建方式见 docker/Dockerfile.indexer：它从仓库根目录构建linera-indexer-examplecrate 的linera-indexer-grpc二进制（cargo build -p linera-indexer-example --bin linera-indexer-grpc），运行镜像基于debian:bookworm-slim，并安装netcat-openbsd（供健康检查使用）与sqlite3等工具。Dockerfile 的构建参数（target、build_flag、build_folder、build_features、binaries）允许跨架构构建或直接注入预编译二进制以加速迭代。

数据持久化

Compose 文件定义了几个命名卷与绑定挂载目录：

postgres-data：PostgreSQL 数据（命名卷postgres-data）；
scylla-data：ScyllaDB 数据（命名卷scylla-data）；
exporter-data：区块导出器日志与数据，绑定挂载./exporter-data，其中的linera-exporter.log是"日志导出器"目的地的落盘文件，记录了它处理过的全部区块与 blob，可直接查看当前导出进度；
network-data：网络配置与状态，挂载到容器的/data。

README 中提到的indexer-data卷（内含indexer.dbSQLite 文件）用于查看索引器数据库的当前状态。需要说明的是，当前 Compose 编排以 PostgreSQL 作为索引器的持久化后端，SQLite 路径描述的是旧版/本地运行形态下索引器数据库的观察方式；无论哪种形态，"数据落到宿主机可访问目录"的设计意图是一致的。

故障排查

查看日志

# 全部服务 docker-compose -f docker-compose.indexer-test.yml logs # 指定服务 docker-compose -f docker-compose.indexer-test.yml logs linera-indexer

检查服务健康状态

docker-compose -f docker-compose.indexer-test.yml ps

重置数据

docker-compose -f docker-compose.indexer-test.yml down -v

-v会一并删除命名卷中的数据，配合make-all-down.sh的目录清理，可彻底回到初始状态。

开发与调试

代码变更后重建

docker build -f Dockerfile.indexer-test -t linera-all-test .. docker-compose -f docker-compose.indexer-test.yml up --force-recreate

进入容器调试

docker-compose -f docker-compose.indexer-test.yml exec linera-indexer bash

从"跑起来"到"理解数据流"

最后梳理一下整条链路的数据流，帮助你把 Compose 中的每个服务串起来：

linera-network启动单验证者网络与 faucet 链，--with-block-exporter参数让网络连接导出器；
linera-block-exporter从 Scylla 存储中读取区块与 blob，按exporter-config.toml的destination_config同时写入日志文件与推送 gRPC 索引器；
linera-indexer接收 gRPC 数据并写入 PostgreSQL，对外提供索引查询能力；
linera-explorer连接 PostgreSQL，把链上数据以 Web 界面呈现（前端 3001、API 3002）。

这套测试栈既适合在本地快速验证索引器/导出器的行为，也适合作为 CI 中的集成测试基座。结合 docker/ci-compose.sh 可以看到类似的编排思路被用于生成测试配置并拉起整套服务。相关的索引器代码位于 linera-indexer（gRPC 服务与插件）与 linera-exporter（导出器实现），需要深入研究某一层时可以直接从这两个 crate 入手。

【免费下载链接】linera-protocolMain repository for the Linera protocol项目地址: https://gitcode.com/GitHub_Trending/li/linera-protocol

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析