部署自定义 Blockscout 区块链浏览器指南

介绍#

众所周知 blockscout 是以太坊生态的开源区块链浏览器，如果只是在本地开发环境中开发 blockscout 还是非常简单的，简单改一下配置文件的 rpc 基本上就可以无缝启动了。但可能是 blockscout 更新频繁，如果开发者想为自己的运营的链部署一个 blockscout 还是有点麻烦的，需要改的配置略为繁杂，坑点也比较多，所以笔者提供一个详细的部署指南，为大家提供参考。

总体思路#

整体上我们需要关心的文件都在 docker-compose 目录下，基本的操作也是在其下完成的，其次我们要关注到以及 services 目录下的 docker 容器服务配置文件， envs 目录下的环境变量文件，proxy 目录下的 Nginx 配置文件。大概的步骤为：

生成 SSL 证书
配置 docker-compose 启动文件
修改 envs 环境配置
修改 proxy Nginx 配置

服务器配置#

CPU: 4core / 8core

RAM: 8GB / 16GB / 32GB

DISK: 120gb or 500GB NVME SSD or Standard SSD

OS: Linux (Ubuntu 个人偏好), MacOS

前置条件#

Docker (V20+) 和 Docker Compose (V2+) 已安装
域名已配置（例如：testnetexplorer.karpak.paratrix.xyz）
SSL 证书已获取（用于 HTTPS 支持）
区块链 RPC 节点已设置（HTTP+WS），注意如果你需要再 rpc 节点上也得开启 https，否则 blockscout 无法连接
开放了 80/443/8080/8081 端口

部署步骤#

1. 准备 SSL 证书#

建议使用 certbot 生成 ssl 证书，以下是详细步骤：

1.1 安装 certbot#

# 安装 certbot
apt-get update
apt-get install -y certbot

1.2 生成证书（当 Docker 已占用 80 端口）#

blockscout 启动后，会占用 80 端口，所以使用 certbot 的 standalone 模式：

方法 1: 临时停止 Docker 服务

# 停止占用 80 端口的 Docker 容器
docker-compose -f custom-rpc.yml down

# 使用 certbot 生成证书
certbot certonly --standalone -d your-domain.com --email [email protected] --agree-tos --no-eff-email

# 生成完成后重启 Docker 服务
docker-compose -f custom-rpc.yml up -d

2.3 设置自动续期#

# 创建自动续期脚本
cat > /root/renew-cert.sh << 'EOF'
#!/bin/bash
# 证书自动续期脚本

# 设置日志文件
LOG_FILE="/var/log/cert-renewal.log"

# 记录开始时间
echo "$(date): 开始证书续期流程" >> $LOG_FILE

# 检查域名
DOMAIN="your-domain.com"

# 检查证书过期时间
EXPIRY=$(openssl x509 -in /etc/letsencrypt/live/$DOMAIN/fullchain.pem -text -noout | grep "Not After" | cut -d: -f2-)
EXPIRY_DATE=$(date -d "$EXPIRY" +%s)
CURRENT_DATE=$(date +%s)
DAYS_LEFT=$(( ($EXPIRY_DATE - $CURRENT_DATE) / 86400 ))

echo "$(date): 证书还有 $DAYS_LEFT 天过期" >> $LOG_FILE

# 如果证书将在30天内过期，则尝试续期
if [ $DAYS_LEFT -lt 30 ]; then
    echo "$(date): 证书将在30天内过期，尝试续期" >> $LOG_FILE
    
    # 停止 Docker 服务
    docker-compose -f custom-rpc.yml down >> $LOG_FILE 2>&1
    
    # 尝试使用certbot续期
    certbot renew >> $LOG_FILE 2>&1
    
    # 重启 Docker 服务
    docker-compose -f custom-rpc.yml up -d >> $LOG_FILE 2>&1
    
    echo "$(date): 证书续期流程完成" >> $LOG_FILE
else
    echo "$(date): 证书有效期充足，无需续期" >> $LOG_FILE
fi
EOF

# 添加执行权限
chmod +x /root/renew-cert.sh

# 添加到 crontab，每周日凌晨执行
echo "0 0 * * 0 /root/renew-cert.sh" | crontab -

1.3 证书位置#

生成的证书通常位于以下位置：

证书路径: /etc/letsencrypt/live/your-domain.com/fullchain.pem
私钥路径: /etc/letsencrypt/live/your-domain.com/privkey.pem

将这些路径配置到您的 Nginx 或其他服务中。

2. 自定义网络配置#

2.1 docker-compose 配置文件#

参考 docker-compose/anvil.yml 文件，创建 docker-compose/custom-rpc.yml 文件，先不配置 nft 相关的服务，配置您的区块链网络参数：
ps：docker-compose 的配置文件的环境变量实际上会覆盖 services 下的环境变量（也就是 envs 下的环境变量），所以您只需要配置您需要修改的环境变量即可。

version: '3.9'

services:
  # 基础服务配置
  redis-db:
    extends:
      file: ./services/redis.yml
      service: redis-db

  # 数据库初始化服务
  db-init:
    extends:
      file: ./services/db.yml
      service: db-init

  db:
    depends_on:
      db-init:
        condition: service_completed_successfully
    extends:
      file: ./services/db.yml
      service: db

  # 后端服务，如果挂了就啥都看不到了
  backend:
    depends_on:
      - db
      - redis-db
    extends:
      file: ./services/backend.yml
      service: backend
    links:
      - db:database
    environment:
        # 区块链网络特定配置
        ETHEREUM_JSONRPC_VARIANT: 'geth'  # 根据您的节点类型调整
        ETHEREUM_JSONRPC_HTTP_URL: 'https://your-rpc-endpoint'
        ETHEREUM_JSONRPC_TRACE_URL: 'https://your-rpc-endpoint'
        ETHEREUM_JSONRPC_WS_URL: 'wss://your-ws-endpoint'
        ETHEREUM_JSONRPC_FALLBACK_HTTP_URL: 'https://your-rpc-endpoint'
        ETHEREUM_JSONRPC_FALLBACK_TRACE_URL: 'https://your-rpc-endpoint'
        CHAIN_ID: '您的链ID'
        INDEXER_DISABLE_INTERNAL_TRANSACTIONS_FETCHER: 'true'  # 按需调整，建议先开启，有需要再打开
        INDEXER_DISABLE_PENDING_TRANSACTIONS_FETCHER: 'true'  # 按需调整，建议先开启，有需要再打开

  # 其他服务配置
  visualizer:
    extends:
      file: ./services/visualizer.yml
      service: visualizer

  sig-provider:
    extends:
      file: ./services/sig-provider.yml
      service: sig-provider

  frontend:
    depends_on:
      - backend
    extends:
      file: ./services/frontend.yml
      service: frontend
    environment:
      NEXT_PUBLIC_NETWORK_ID: '您的链ID'  # 例如: '262144'
      NEXT_PUBLIC_NETWORK_RPC_URL: https://your-rpc-endpoint
      NEXT_PUBLIC_API_HOST: 'your-domain'  # 例如: 'testnetexplorer.karpak.paratrix.xyz'
      NEXT_PUBLIC_API_PROTOCOL: https
      NEXT_PUBLIC_STATS_API_HOST: https://your-domain:8080
      NEXT_PUBLIC_NETWORK_NAME: 您的网络名称
      NEXT_PUBLIC_NETWORK_SHORT_NAME: 您的网络简称
      NEXT_PUBLIC_NETWORK_ID: 您的链ID
      NEXT_PUBLIC_NETWORK_CURRENCY_NAME: 您的货币名称
      NEXT_PUBLIC_NETWORK_CURRENCY_SYMBOL: 您的货币符号
      NEXT_PUBLIC_APP_HOST: your-domain
      NEXT_PUBLIC_APP_PROTOCOL: https
      NEXT_PUBLIC_VISUALIZE_API_HOST: https://your-domain:8081
      NEXT_PUBLIC_IS_TESTNET: true  # 根据您的网络类型设置
      NEXT_PUBLIC_API_WEBSOCKET_PROTOCOL: wss
      NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID: 您的WalletConnect项目ID # 不写的话不能验证合约 https://cloud.reown.com/
      NEXT_PUBLIC_NETWORK_LOGO: 您的网络Logo URL *建议找个oss存*
      NEXT_PUBLIC_NETWORK_ICON: 您的网络Icon URL *建议找个oss存*

  
  stats-db-init:
    extends:
      file: ./services/stats.yml
      service: stats-db-init

  stats-db:
    depends_on:
      stats-db-init:
        condition: service_completed_successfully
    extends:
      file: ./services/stats.yml
      service: stats-db

  # 统计服务配置，如果这个服务报错会导致看不到charts
  stats:
    depends_on:
      - stats-db
      - backend
    extends:
      file: ./services/stats.yml
      service: stats
    environment:
      STATS__BLOCKSCOUT_API_URL: https://your-domain # 这个很容易漏掉

  user-ops-indexer:
    depends_on:
      - db
      - backend
    extends:
      file: ./services/user-ops-indexer.yml
      service: user-ops-indexer

  # 代理服务配置
  proxy:
    depends_on:
      - backend
      - frontend
      - stats
    extends:
      file: ./services/nginx.yml
      service: proxy

2.2 相关命令：#

# 启动服务
docker-compose -f custom-rpc.yml up -d

# 查看日志
docker-compose -f custom-rpc.yml logs -f

# 停止服务
docker-compose -f custom-rpc.yml down

注意如果修改了配置文件需要重启服务，重新构建相关的镜像：

docker-compose -f custom-rpc.yml down
docker-compose -f custom-rpc.yml up -d

2.3 说明#

到此为止你应该就可以通过访问服务器 ip 就可以看到对应的前端页面了，可以打开浏览器的开发者工具，查看网络请求，检查下 rpc/api 是否正常工作，有些服务可能因为 ssl 导致跨域问题，咱们用 nginx 解决

3. 配置 Nginx 代理#

3.1 更新 Nginx 配置模板#

编辑 docker-compose/proxy/default.conf.template 文件，添加 HTTPS 支持：

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

# HTTP 服务器 - 重定向到 HTTPS
server {
    listen       80;
    server_name  your-domain;
    
    # 重定向所有 HTTP 请求到 HTTPS
    location / {
        return 301 https://$host$request_uri;
    }
}

# HTTPS 服务器
server {
    listen       443 ssl;
    server_name  your-domain;
    
    # SSL 证书配置
    ssl_certificate     /etc/nginx/ssl/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/privkey.pem;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_ciphers         HIGH:!aNULL:!MD5;
    
    proxy_http_version 1.1;

    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;
    }
}

# 统计服务 HTTPS 配置 (8080 端口)
server {
    listen       8080 ssl;
    server_name  your-domain;
    
    # SSL 证书配置
    ssl_certificate     /etc/nginx/ssl/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/privkey.pem;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_ciphers         HIGH:!aNULL:!MD5;
    
    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' 'https://your-domain' always;
    add_header 'Access-Control-Allow-Credentials' 'true' always;
    add_header 'Access-Control-Allow-Methods' 'PUT, GET, POST, OPTIONS, DELETE, PATCH' always;

    # 其他配置...
}

# 可视化服务 HTTPS 配置 (8081 端口)
server {
    listen       8081 ssl;
    server_name  your-domain;
    
    # SSL 证书配置
    ssl_certificate     /etc/nginx/ssl/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/privkey.pem;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_ciphers         HIGH:!aNULL:!MD5;
    
    # 其他配置...
}

3.2 更新 Nginx 服务配置#

编辑 docker-compose/services/nginx.yml 文件，添加 SSL 证书挂载和 HTTPS 端口：

services:
  proxy:
    image: nginx:1.25.1-alpine
    restart: always
    extra_hosts:
      - 'host.docker.internal:host-gateway'
    volumes:
      - "../proxy:/etc/nginx/templates"
      - "/root/certs/live/your-domain/fullchain.pem:/etc/nginx/ssl/fullchain.pem:ro"
      - "/root/certs/live/your-domain/privkey.pem:/etc/nginx/ssl/privkey.pem:ro"
    environment:
      BACK_PROXY_PASS: ${BACK_PROXY_PASS:-http://backend:4000}
      FRONT_PROXY_PASS: ${FRONT_PROXY_PASS:-http://frontend:3000}
    ports:
      - target: 80
        published: 80
      - target: 443
        published: 443
      - target: 8080
        published: 8080
      - target: 8081
        published: 8081

4. 启动服务#

使用以下命令启动您的自定义 Blockscout 区块链浏览器：

cd blockscout/docker-compose
docker-compose -f docker-compose/custom-rpc.yml up -d

5. 验证部署#

访问 https://your-domain 验证您的 Blockscout 区块链浏览器是否成功部署。

常见问题排查#

无法连接到区块链节点
- 检查 RPC 端点是否正确配置
- 确认网络连接是否通畅
- 验证防火墙设置是否允许相关端口
HTTPS 证书问题
- 确认证书路径正确
- 检查证书是否有效
- 验证 Nginx 配置是否正确引用证书文件
数据库初始化失败
- 检查数据库配置
- 查看日志以获取详细错误信息

总结#

通过以上步骤，您可以成功部署一个自定义的 Blockscout 区块链浏览器，支持 HTTPS 和 WSS 连接，并且可以通过自定义域名访问。主要修改包括：

添加 HTTPS/SSL 支持
自定义区块链网络参数
配置自定义域名
设置 RPC 端点
自定义网络品牌（名称、图标等）

请根据您的具体需求调整上述配置。

参考文档#

[1] docker-compose 部署文档https://docs.blockscout.com/setup/deployment/docker-compose-deployment
[2] 环境变量说明https://docs.blockscout.com/setup/env-variables
[3] 前端环境变量 https://github.com/blockscout/frontend/blob/main/docs/ENVS.md