Blockscout 部署 — 设计

日期: 2026-03-03 目标: 用 Blockscout 替换当前 matter-labs/block-explorer，连接本地 BabyDriver era-core 节点 决策: 方案 A — 全栈官方 Docker，zkSync 原生支持

---

背景

当前 block-explorer（matter-labs/block-explorer fork）已连接本地 era-core 节点（Task 1-5 完成）， 但功能有限（无合约验证、无统计图表、无函数签名解析）。 Blockscout 是功能最完整的开源区块浏览器，原生支持 zkSync (CHAIN_TYPE=zksync)。

许可证: Blockscout 后端 GPL-3.0，前端 Apache 2.0 — 已确认可接受。

---

架构

服务拓扑

Host Machine
├── era-core (L2 RPC)        :3050
├── reth (L1 RPC)            :8545
└── Docker Compose (Blockscout)
    ├── db (PostgreSQL 17)    :7432 → 5434 (host)
    ├── stats-db (PG 17)     :7433 (internal only)
    ├── redis                 :6379 (internal only)
    ├── backend (Elixir)      :4000 (internal)
    ├── nft-media-handler     (internal, same image as backend)
    ├── frontend (Next.js)    :3000 (internal)
    ├── stats                 :8050 (internal)
    ├── visualizer            :8050 (internal)
    ├── sig-provider          :8050 (internal)
    ├── smart-contract-verifier :8050 (internal)
    ├── user-ops-indexer      :8050 (internal)
    └── proxy (nginx)         :3010 (host) → routes to backend/frontend
                              :8080 (host) → stats
                              :8081 (host) → visualizer

端口规划

服务	Host 端口	说明
era-core RPC	3050	已占用，不变
era-core PG	5432	已占用，不变
reth L1	8545	已占用，不变
Blockscout 主入口	3010	nginx proxy → 前端+API
Blockscout Stats	8080	stats API
Blockscout Visualizer	8081	合约可视化
Blockscout DB	5434	PostgreSQL 映射

注意: nginx proxy 默认端口 80 改为 3010，避免系统端口冲突。

---

Docker 镜像

全部使用官方预编译镜像，无需本地构建：

服务	镜像
backend	ghcr.io/blockscout/blockscout:latest
frontend	ghcr.io/blockscout/frontend:latest
stats	ghcr.io/blockscout/stats:latest
visualizer	ghcr.io/blockscout/visualizer:latest
sig-provider	ghcr.io/blockscout/sig-provider:latest
smart-contract-verifier	ghcr.io/blockscout/smart-contract-verifier:latest
user-ops-indexer	ghcr.io/blockscout/user-ops-indexer:latest
db / stats-db	postgres:17
redis	redis:alpine
proxy	nginx

---

zkSync 配置

Blockscout 内建 zkSync 支持，通过环境变量启用：

# Backend
CHAIN_TYPE=zksync
CHAIN_ID=271

# L2 RPC (era-core)
ETHEREUM_JSONRPC_HTTP_URL=http://host.docker.internal:3050/
ETHEREUM_JSONRPC_TRACE_URL=http://host.docker.internal:3050/
ETHEREUM_JSONRPC_WS_URL=ws://host.docker.internal:3050/
ETHEREUM_JSONRPC_VARIANT=geth

# zkSync Batch 索引
INDEXER_ZKSYNC_BATCHES_ENABLED=true
INDEXER_ZKSYNC_BATCHES_CHUNK_SIZE=50

注意: ETHEREUM_JSONRPC_VARIANT=geth 即可，Blockscout 会根据 CHAIN_TYPE=zksync 自动使用 zkSync 特有的 RPC 方法。

---

品牌定制

通过前端环境变量，无需改代码：

NEXT_PUBLIC_NETWORK_NAME=BabyDriver
NEXT_PUBLIC_NETWORK_SHORT_NAME=BABY
NEXT_PUBLIC_NETWORK_ID=271
NEXT_PUBLIC_NETWORK_CURRENCY_NAME=Ether
NEXT_PUBLIC_NETWORK_CURRENCY_SYMBOL=ETH
NEXT_PUBLIC_NETWORK_CURRENCY_DECIMALS=18
NEXT_PUBLIC_IS_TESTNET=true
NEXT_PUBLIC_HOMEPAGE_CHARTS=['daily_txs']

Logo 通过 NEXT_PUBLIC_NETWORK_LOGO 和 NEXT_PUBLIC_NETWORK_LOGO_DARK 环境变量指定， 或通过 volume 挂载到前端容器的静态资源目录。

---

迁移策略

1. 停掉旧 matter-labs explorer: cd refs/block-explorer && docker compose -f docker-compose-baby.yaml down

2. 创建 Blockscout BabyDriver 配置文件（compose + env files）

3. 拉取镜像 + 启动: docker compose -f docker-compose-baby.yaml up -d

4. Blockscout 自动从 block 0 开始索引（无需数据迁移）

5. 访问 http://localhost:3010 验证

旧 explorer 保留不删除，其 Docker images 和 compose 文件留存以备回退。

---

数据持久化

volumes:
  blockscout-db-data:      # 主数据库
  blockscout-stats-db-data: # 统计数据库
  blockscout-redis-data:    # Redis 缓存
  blockscout-logs:          # 后端日志

---

文件结构

refs/blockscout/docker-compose/
├── docker-compose-baby.yaml     # BabyDriver 专用（新建，单文件）
├── envs/
│   ├── baby-blockscout.env      # 后端环境变量（新建）
│   ├── baby-frontend.env        # 前端环境变量（新建）
│   ├── baby-stats.env           # Stats 环境变量（新建）
│   └── baby-smart-contract-verifier.env  # 合约验证器（新建）
└── proxy/
    └── default.conf.template    # nginx 配置（修改端口）

---

验证标准

1. docker compose -f docker-compose-baby.yaml up -d 所有容器 healthy

2. http://localhost:3010 显示 BabyDriver 品牌

3. 区块自动索引，显示 block 0-N

4. 交易详情页可查看

5. API http://localhost:3010/api/v2/blocks 返回数据