Blockscout 部署 — 实现

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: 用 Blockscout 全栈 Docker 替换 matter-labs/block-explorer，连接本地 BabyDriver era-core 节点，zkSync 原生支持 + 品牌定制。

Architecture: Blockscout 官方 Docker 镜像 + 自定义 docker-compose-baby.yaml（单文件自包含）。所有服务通过 nginx 代理对外暴露，backend 通过 host.docker.internal:3050 连接 era-core。使用官方 env 文件作为基础，通过 compose environment 覆盖 BabyDriver 特有配置。

Tech Stack: Blockscout 9.x (Elixir), Next.js frontend, PostgreSQL 17, Redis, nginx, Docker Compose

Design Doc: docs/plans/2026-03-03-blockscout-replacement-design.md

---

Task 1: 停止旧 matter-labs block explorer

Context: 当前 refs/block-explorer 有 5 个 Docker 容器在运行（app:3010, worker:3001, data-fetcher:3040, api:3020, postgres:5433）。需要先停掉，释放端口 3010。

Files:

• Read: refs/block-explorer/docker-compose-baby.yaml

Step 1: 停止旧容器

Run:

cd /Users/judybaby/CodeBase/github/Layer2/refs/block-explorer
docker compose -f docker-compose-baby.yaml down

Expected: 所有 5 个容器停止。

Step 2: 确认端口已释放

Run:

lsof -i :3010 -i :3020 -i :5433

Expected: 无输出（端口已释放）。注意 :3050 和 :5432 仍被 era-core 使用，不应影响。

Step 3: 确认 era-core 仍在运行

Run:

curl -s -X POST http://localhost:3050 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

Expected: 返回 {"jsonrpc":"2.0","result":"0x...","id":1}（era-core 正常）。

---

Task 2: 创建 BabyDriver logo 目录 + nginx 配置

Context: Blockscout 前端通过 env var 指定 logo URL，同时 nginx proxy 需要自定义端口（3010 代替默认 80）。

Files:

• Create: refs/blockscout/docker-compose/baby-assets/babydriver-logo.svg

• Create: refs/blockscout/docker-compose/baby-assets/babydriver-logo-dark.svg

• Create: refs/blockscout/docker-compose/baby-proxy/default.conf.template

Step 1: 创建 logo 资源目录

Run:

mkdir -p /Users/judybaby/CodeBase/github/Layer2/refs/blockscout/docker-compose/baby-assets

Step 2: 复制 logo 文件

复制已有的 BabyDriver logo SVG 文件：

cp /Users/judybaby/CodeBase/github/Layer2/refs/block-explorer/packages/app/public/images/babydriver-logo.svg \
   /Users/judybaby/CodeBase/github/Layer2/refs/blockscout/docker-compose/baby-assets/babydriver-logo.svg

cp /Users/judybaby/CodeBase/github/Layer2/refs/block-explorer/packages/app/public/images/babydriver-logo-dark.svg \
   /Users/judybaby/CodeBase/github/Layer2/refs/blockscout/docker-compose/baby-assets/babydriver-logo-dark.svg

Step 3: 创建自定义 nginx 配置

Create refs/blockscout/docker-compose/baby-proxy/default.conf.template:

map $http_upgrade $connection_upgrade {
  default upgrade;
  ''      close;
}

# Main server — port 3010 (not 80, to avoid system port conflicts)
server {
    listen       3010;
    server_name  localhost;
    proxy_http_version 1.1;

    # Serve logo assets
    location /baby-assets/ {
        alias /baby-assets/;
    }

    location ~ ^/(api(?!-docs$)|socket|sitemap.xml|auth/auth0|auth/auth0/callback|auth/logout) {
        proxy_pass            ${BACK_PROXY_PASS};
        proxy_http_version    1.1;
        proxy_set_header      Host "$host";
        proxy_set_header      X-Real-IP "$remote_addr";
        proxy_set_header      X-Forwarded-For "$proxy_add_x_forwarded_for";
        proxy_set_header      X-Forwarded-Proto "$scheme";
        proxy_set_header      Upgrade "$http_upgrade";
        proxy_set_header      Connection $connection_upgrade;
        proxy_cache_bypass    $http_upgrade;
    }
    location / {
        proxy_pass            ${FRONT_PROXY_PASS};
        proxy_http_version    1.1;
        proxy_set_header      Host "$host";
        proxy_set_header      X-Real-IP "$remote_addr";
        proxy_set_header      X-Forwarded-For "$proxy_add_x_forwarded_for";
        proxy_set_header      X-Forwarded-Proto "$scheme";
        proxy_set_header      Upgrade "$http_upgrade";
        proxy_set_header      Connection $connection_upgrade;
        proxy_cache_bypass    $http_upgrade;
    }
}

# Stats API — port 8080
server {
    listen       8080;
    server_name  localhost;
    proxy_http_version 1.1;
    proxy_hide_header Access-Control-Allow-Origin;
    proxy_hide_header Access-Control-Allow-Methods;
    add_header 'Access-Control-Allow-Origin' 'http://localhost:3010' always;
    add_header 'Access-Control-Allow-Credentials' 'true' always;
    add_header 'Access-Control-Allow-Methods' 'PUT, GET, POST, OPTIONS, DELETE, PATCH' always;

    location / {
        proxy_pass            http://stats:8050/;
        proxy_http_version    1.1;
        proxy_set_header      Host "$host";
        proxy_set_header      X-Real-IP "$remote_addr";
        proxy_set_header      X-Forwarded-For "$proxy_add_x_forwarded_for";
        proxy_set_header      X-Forwarded-Proto "$scheme";
        proxy_set_header      Upgrade "$http_upgrade";
        proxy_set_header      Connection $connection_upgrade;
        proxy_cache_bypass    $http_upgrade;
    }
}

# Visualizer API — port 8081
server {
    listen       8081;
    server_name  localhost;
    proxy_http_version 1.1;
    proxy_hide_header Access-Control-Allow-Origin;
    proxy_hide_header Access-Control-Allow-Methods;
    add_header 'Access-Control-Allow-Origin' 'http://localhost:3010' always;
    add_header 'Access-Control-Allow-Credentials' 'true' always;
    add_header 'Access-Control-Allow-Methods' 'PUT, GET, POST, OPTIONS, DELETE, PATCH' always;
    add_header 'Access-Control-Allow-Headers' 'DNT,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization,x-csrf-token' always;

    location / {
        proxy_pass            http://visualizer:8050/;
        proxy_http_version    1.1;
        proxy_buffering       off;
        proxy_set_header      Host "$host";
        proxy_set_header      X-Real-IP "$remote_addr";
        proxy_connect_timeout 30m;
        proxy_read_timeout    30m;
        proxy_send_timeout    30m;
        proxy_set_header      X-Forwarded-For "$proxy_add_x_forwarded_for";
        proxy_set_header      X-Forwarded-Proto "$scheme";
        proxy_set_header      Upgrade "$http_upgrade";
        proxy_set_header      Connection $connection_upgrade;
        proxy_cache_bypass    $http_upgrade;
        if ($request_method = 'OPTIONS') {
            add_header 'Access-Control-Allow-Origin' 'http://localhost:3010' always;
            add_header 'Access-Control-Allow-Credentials' 'true' always;
            add_header 'Access-Control-Allow-Methods' 'PUT, GET, POST, OPTIONS, DELETE, PATCH' always;
            add_header 'Access-Control-Allow-Headers' 'DNT,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization,x-csrf-token' always;
            add_header 'Access-Control-Max-Age' 1728000;
            add_header 'Content-Type' 'text/plain charset=UTF-8';
            add_header 'Content-Length' 0;
            return 204;
        }
    }
}

Step 4: 验证文件结构

Run:

ls -la /Users/judybaby/CodeBase/github/Layer2/refs/blockscout/docker-compose/baby-assets/
ls -la /Users/judybaby/CodeBase/github/Layer2/refs/blockscout/docker-compose/baby-proxy/

Expected: 2 个 SVG 文件 + 1 个 nginx 配置文件。

---

Task 3: 创建 docker-compose-baby.yaml

Context: 单文件自包含的 Docker Compose，不使用 extends。引用官方 env 文件作为基础，通过 environment 覆盖 BabyDriver 专有值。

重要: 跳过 nft_media_handler（需 AWS 配置）和 user-ops-indexer（无 ERC-4337 合约），开发环境不需要。

Files:

• Create: refs/blockscout/docker-compose/docker-compose-baby.yaml

Step 1: 创建 docker-compose-baby.yaml

Create file at refs/blockscout/docker-compose/docker-compose-baby.yaml:

# BabyDriver Blockscout — 全栈区块浏览器
# 前置条件：era-core 节点运行在 host:3050, reth L1 运行在 host:8545
#
# 启动: docker compose -f docker-compose-baby.yaml up -d
# 停止: docker compose -f docker-compose-baby.yaml down
# 查看日志: docker compose -f docker-compose-baby.yaml logs -f backend
#
# 端口:
#   3010 — 主入口 (nginx → frontend + API)
#   8080 — Stats API
#   8081 — Visualizer API
#   5434 — PostgreSQL (避免和 era-core 5432 冲突)

services:
  # ──────────────────────────────────────────
  # 基础设施
  # ──────────────────────────────────────────
  redis-db:
    image: redis:alpine
    container_name: baby-redis
    restart: always
    command: redis-server
    volumes:
      - redis-data:/data

  db-init:
    image: postgres:17
    container_name: baby-db-init
    volumes:
      - blockscout-db-data:/var/lib/postgresql/data
    entrypoint:
      - sh
      - -c
      - |
        chown -R 2000:2000 /var/lib/postgresql/data

  db:
    image: postgres:17
    container_name: baby-db
    user: 2000:2000
    shm_size: 256m
    restart: always
    depends_on:
      db-init:
        condition: service_completed_successfully
    command: postgres -c 'max_connections=200' -c 'client_connection_check_interval=60000'
    environment:
      POSTGRES_DB: blockscout
      POSTGRES_USER: blockscout
      POSTGRES_PASSWORD: ceWb1MeLBEeOIfk65gU8EjF8
    ports:
      - "5434:5432"
    volumes:
      - blockscout-db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U blockscout -d blockscout"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 10s

  stats-db-init:
    image: postgres:17
    container_name: baby-stats-db-init
    volumes:
      - stats-db-data:/var/lib/postgresql/data
    entrypoint:
      - sh
      - -c
      - |
        chown -R 2000:2000 /var/lib/postgresql/data

  stats-db:
    image: postgres:17
    container_name: baby-stats-db
    user: 2000:2000
    shm_size: 256m
    restart: always
    depends_on:
      stats-db-init:
        condition: service_completed_successfully
    command: postgres -c 'max_connections=200'
    environment:
      POSTGRES_DB: stats
      POSTGRES_USER: stats
      POSTGRES_PASSWORD: n0uejXPl61ci6ldCuE2gQU5Y
    volumes:
      - stats-db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U stats -d stats"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 10s

  # ──────────────────────────────────────────
  # Blockscout Backend (Elixir indexer + API)
  # ──────────────────────────────────────────
  backend:
    image: ghcr.io/blockscout/blockscout:latest
    container_name: baby-backend
    pull_policy: always
    restart: always
    stop_grace_period: 5m
    depends_on:
      db:
        condition: service_healthy
      redis-db:
        condition: service_started
    command: sh -c "bin/blockscout eval \"Elixir.Explorer.ReleaseTasks.create_and_migrate()\" && bin/blockscout start"
    extra_hosts:
      - 'host.docker.internal:host-gateway'
    links:
      - db:database
    env_file:
      - ./envs/common-blockscout.env
    environment:
      # ── BabyDriver zkSync 配置 ──
      CHAIN_TYPE: zksync
      CHAIN_ID: '271'
      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 批次索引 ──
      INDEXER_ZKSYNC_BATCHES_ENABLED: 'true'
      INDEXER_ZKSYNC_BATCHES_CHUNK_SIZE: '50'
      INDEXER_ZKSYNC_L1_RPC: http://host.docker.internal:8545/
      # ── 开发环境优化 ──
      DISABLE_MARKET: 'true'
      ACCOUNT_ENABLED: 'false'
      NFT_MEDIA_HANDLER_ENABLED: 'false'
      MICROSERVICE_SC_VERIFIER_ENABLED: 'true'
      MICROSERVICE_SC_VERIFIER_URL: http://smart-contract-verifier:8050/
      MICROSERVICE_SC_VERIFIER_TYPE: eth_bytecode_db
      MICROSERVICE_VISUALIZE_SOL2UML_ENABLED: 'true'
      MICROSERVICE_VISUALIZE_SOL2UML_URL: http://visualizer:8050/
      MICROSERVICE_SIG_PROVIDER_ENABLED: 'true'
      MICROSERVICE_SIG_PROVIDER_URL: http://sig-provider:8050/
      # ── 分布式节点 (单节点模式) ──
      RELEASE_NODE: producer@backend
      RELEASE_DISTRIBUTION: name
      RELEASE_COOKIE: baby_driver_secret
    volumes:
      - logs:/app/logs/

  # ──────────────────────────────────────────
  # 微服务
  # ──────────────────────────────────────────
  smart-contract-verifier:
    image: ghcr.io/blockscout/smart-contract-verifier:latest
    container_name: baby-sc-verifier
    pull_policy: always
    platform: linux/amd64
    restart: always
    env_file:
      - ./envs/common-smart-contract-verifier.env

  visualizer:
    image: ghcr.io/blockscout/visualizer:latest
    container_name: baby-visualizer
    pull_policy: always
    platform: linux/amd64
    restart: always
    env_file:
      - ./envs/common-visualizer.env

  sig-provider:
    image: ghcr.io/blockscout/sig-provider:latest
    container_name: baby-sig-provider
    pull_policy: always
    platform: linux/amd64
    restart: always

  stats:
    image: ghcr.io/blockscout/stats:latest
    container_name: baby-stats
    pull_policy: always
    platform: linux/amd64
    restart: always
    depends_on:
      stats-db:
        condition: service_healthy
      backend:
        condition: service_started
    extra_hosts:
      - 'host.docker.internal:host-gateway'
    env_file:
      - ./envs/common-stats.env
    environment:
      STATS__DB_URL: postgres://stats:n0uejXPl61ci6ldCuE2gQU5Y@stats-db:5432/stats
      STATS__BLOCKSCOUT_DB_URL: postgresql://blockscout:ceWb1MeLBEeOIfk65gU8EjF8@db:5432/blockscout
      STATS__CREATE_DATABASE: 'true'
      STATS__RUN_MIGRATIONS: 'true'
      STATS__BLOCKSCOUT_API_URL: http://backend:4000

  # ──────────────────────────────────────────
  # Frontend (Next.js)
  # ──────────────────────────────────────────
  frontend:
    image: ghcr.io/blockscout/frontend:latest
    container_name: baby-frontend
    pull_policy: always
    platform: linux/amd64
    restart: always
    depends_on:
      - backend
    env_file:
      - ./envs/common-frontend.env
    environment:
      # ── BabyDriver 品牌 ──
      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'
      # ── Logo (通过 nginx 代理提供) ──
      NEXT_PUBLIC_NETWORK_LOGO: http://localhost:3010/baby-assets/babydriver-logo.svg
      NEXT_PUBLIC_NETWORK_LOGO_DARK: http://localhost:3010/baby-assets/babydriver-logo-dark.svg
      # ── API 连接 ──
      NEXT_PUBLIC_API_HOST: localhost
      NEXT_PUBLIC_API_PORT: '3010'
      NEXT_PUBLIC_API_PROTOCOL: http
      NEXT_PUBLIC_API_WEBSOCKET_PROTOCOL: ws
      NEXT_PUBLIC_APP_HOST: localhost
      NEXT_PUBLIC_APP_PORT: '3010'
      NEXT_PUBLIC_APP_PROTOCOL: http
      # ── 微服务 ──
      NEXT_PUBLIC_STATS_API_HOST: http://localhost:8080
      NEXT_PUBLIC_VISUALIZE_API_HOST: http://localhost:8081
      NEXT_PUBLIC_HOMEPAGE_CHARTS: "['daily_txs']"
      NEXT_PUBLIC_API_SPEC_URL: https://raw.githubusercontent.com/blockscout/blockscout-api-v2-swagger/main/swagger.yaml
      # ── zkSync 特性 ──
      NEXT_PUBLIC_ROLLUP_TYPE: zkSync
      NEXT_PUBLIC_ROLLUP_L1_BASE_URL: http://localhost:8545

  # ──────────────────────────────────────────
  # Nginx Proxy
  # ──────────────────────────────────────────
  proxy:
    image: nginx
    container_name: baby-proxy
    restart: always
    depends_on:
      - backend
      - frontend
      - stats
    extra_hosts:
      - 'host.docker.internal:host-gateway'
    volumes:
      - "./baby-proxy:/etc/nginx/templates"
      - "./baby-assets:/baby-assets:ro"
    environment:
      BACK_PROXY_PASS: http://backend:4000
      FRONT_PROXY_PASS: http://frontend:3000
    ports:
      - "3010:3010"
      - "8080:8080"
      - "8081:8081"

volumes:
  blockscout-db-data:
  stats-db-data:
  redis-data:
  logs:

Step 2: 验证 YAML 语法

Run:

cd /Users/judybaby/CodeBase/github/Layer2/refs/blockscout/docker-compose
docker compose -f docker-compose-baby.yaml config --quiet

Expected: 无错误输出（YAML 有效）。

---

Task 4: 拉取镜像并启动所有服务

Context: 首次启动需要拉取约 2-3 GB 的 Docker 镜像。启动后 Blockscout 会自动运行数据库迁移、创建表结构、开始索引。

前置条件: era-core 节点运行在 host:3050

Files:

• Read: refs/blockscout/docker-compose/docker-compose-baby.yaml

Step 1: 确认 era-core 正在运行

Run:

curl -s -X POST http://localhost:3050 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

Expected: 返回当前区块号。如果 era-core 没运行，需要先启动：

cd /Users/judybaby/CodeBase/github/Layer2/era-core
source ~/.nvm/nvm.sh && nvm use 20
zkstack server --chain era 2>&1 &

Step 2: 拉取所有镜像

Run:

cd /Users/judybaby/CodeBase/github/Layer2/refs/blockscout/docker-compose
docker compose -f docker-compose-baby.yaml pull

Expected: 拉取 blockscout, frontend, stats, visualizer, sig-provider, smart-contract-verifier, postgres:17, redis:alpine, nginx。

Step 3: 启动所有服务

Run:

cd /Users/judybaby/CodeBase/github/Layer2/refs/blockscout/docker-compose
docker compose -f docker-compose-baby.yaml up -d

Expected: 所有容器启动。db-init 和 stats-db-init 完成后退出（正常）。

Step 4: 查看启动日志

Run:

docker compose -f docker-compose-baby.yaml logs -f backend --tail 50

Expected: 看到数据库迁移完成、开始索引的日志。关键日志：

• "Running migrations..." — 数据库迁移

• "Block Fetcher started" — 开始索引区块

• 无 ERROR 级别日志

Step 5: 确认所有容器状态

Run:

docker compose -f docker-compose-baby.yaml ps

Expected: 除 db-init 和 stats-db-init（Exited 0）外，所有容器 Up/Running。

---

Task 5: 验证索引 + API

Context: Blockscout 后端应该已自动从 block 0 开始索引 era-core 的所有区块。

Step 1: 检查 API 健康状态

Run:

curl -s http://localhost:3010/api/v2/stats | python3 -m json.tool

Expected: 返回 JSON，包含 total_blocks、total_transactions 等字段。total_blocks 应 > 0。

Step 2: 检查区块索引

Run:

curl -s http://localhost:3010/api/v2/blocks | python3 -m json.tool | head -30

Expected: 返回区块列表 JSON。应该能看到 block 0 及后续区块。

Step 3: 检查交易索引

Run:

curl -s http://localhost:3010/api/v2/transactions | python3 -m json.tool | head -30

Expected: 返回交易列表（如果有交易的话）。

Step 4: 检查 zkSync batch 信息

Run:

curl -s http://localhost:3010/api/v2/zksync/batches | python3 -m json.tool | head -30

Expected: 返回 zkSync batch 列表（如果 batch 索引已启用）。可能返回空列表或 404 — 取决于 era-core 是否已提交 batch 到 L1。

---

Task 6: 验证前端 + 品牌 + 最终确认

Context: 验证前端页面能正常显示 BabyDriver 品牌，区块数据可浏览。

Step 1: 检查前端可访问

Run:

curl -s -o /dev/null -w "%{http_code}" http://localhost:3010

Expected: 200

Step 2: 检查 logo 资源可访问

Run:

curl -s -o /dev/null -w "%{http_code}" http://localhost:3010/baby-assets/babydriver-logo.svg
curl -s -o /dev/null -w "%{http_code}" http://localhost:3010/baby-assets/babydriver-logo-dark.svg

Expected: 两个都返回 200。

Step 3: 验证 Stats API

Run:

curl -s http://localhost:8080/api/v1/counters | python3 -m json.tool

Expected: 返回 JSON（可能是空数据或初始统计）。如果返回错误可忽略（stats 服务需要一些时间收集数据）。

Step 4: 在浏览器中验证

用浏览器打开以下 URL 并检查：

• http://localhost:3010 — 首页显示 BabyDriver 名称和 logo

• http://localhost:3010/blocks — 区块列表

• http://localhost:3010/txs — 交易列表

• 点击任意区块进入详情页

Step 5: 记录最终状态

Run:

echo "=== Blockscout 容器状态 ==="
docker compose -f docker-compose-baby.yaml ps

echo ""
echo "=== era-core 区块高度 ==="
curl -s -X POST http://localhost:3050 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

echo ""
echo "=== Blockscout 索引状态 ==="
curl -s http://localhost:3010/api/v2/stats

Expected: 所有服务运行正常，区块已索引。

---

故障排除

Backend 连不上 era-core

# 检查 host.docker.internal 是否解析正确
docker exec baby-backend sh -c "wget -q -O- http://host.docker.internal:3050"

如果失败，检查 Docker Desktop 的 host.docker.internal 支持。

数据库迁移失败

# 查看详细错误
docker compose -f docker-compose-baby.yaml logs backend | grep -i error
# 重置数据库
docker compose -f docker-compose-baby.yaml down -v  # 删除 volumes
docker compose -f docker-compose-baby.yaml up -d     # 重新启动

前端显示空白

# 检查前端日志
docker compose -f docker-compose-baby.yaml logs frontend
# 检查 nginx 配置
docker exec baby-proxy nginx -t

索引停滞

# 检查 backend 日志
docker compose -f docker-compose-baby.yaml logs -f backend --tail 100
# 可能需要重启 backend
docker compose -f docker-compose-baby.yaml restart backend