部署自定義 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