Layer2 —— Blockscout 部署指南

简介

本指南详细介绍了如何为搭建的 Layer2 区块链网络部署 Blockscout 区块浏览器。Blockscout 是一个功能全面的开源区块链浏览器，专为以太坊虚拟机（EVM）兼容网络设计。它提供了直观的用户界面来查看交易、区块、合约和账户信息，是区块链项目不可或缺的基础设施组件。

一、系统环境准备

1.1 安装软件依赖

打开 Ubuntu-24.04 子系统

# 更新系统
sudo apt update && sudo apt upgrade -y

# 基础工具
sudo apt install -y curl wget git

# 编译工具 / 构建
sudo apt install -y build-essential make g++ gcc automake libtool cmake

# 系统库
sudo apt install -y libudev-dev libgmp-dev libgmp10 libssl-dev libncurses-dev

# 压缩 / 解压
sudo apt install -y zip unzip

# 监控工具
sudo apt install -y inotify-tools

# 安装 asdf
go install github.com/asdf-vm/asdf/cmd/asdf@v0.18.0
echo 'export PATH="$HOME/go/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# 安装 postgreSQL-17 数据库
curl -fsSL https://www.postgresql.org/media/keys/ACCC4CF8.asc|sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/postgresql.gpg
sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
sudo apt update
sudo apt install postgresql-17

# 安装 rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y

# 安装 docker-compose
sudo apt install docker-compose

1.2 配置 asdf

# 安装 Erlang、Elixir、Node.js 插件
asdf plugin add erlang
asdf plugin add elixir
asdf plugin add nodejs

# 用于 blockscout backend
asdf install erlang 27.3.4
asdf install elixir 1.17.3-otp-27
asdf install nodejs 20.17.0

# 用于 blockscout frontend
asdf install nodejs 22.11.0

# 加载 asdf 环境变量
export PATH="$HOME/.asdf/shims:$HOME/.asdf/bin:$PATH"
source ~/.bashrc

1.3 配置 Postgres 数据库

# 切换数据库管理员
su - postgres 			# for Root
sudo -i -u postgres 	# for user

# 创建数据库用户
createuser --interactive
# 输入角色名: YOUR_DBUSER_NAME
# 是否为超级用户? (y/n) y

# 创建数据库
createdb blockscout

# 修改用户密码
psql
ALTER USER YOUR_DBUSER_NAME WITH PASSWORD 'YourSecurePassword';
GRANT ALL PRIVILEGES ON DATABASE blockscout TO YOUR_DBUSER_NAME;
\q
exit
sudo systemctl restart postgresql

# 检查数据库设置是否成功
su - YOUR_DBUSER_NAME 		# for Root
sudo su - YOUR_DBUSER_NAME 	# for user
psql -d blockscout			# 如果能看到 blockscout=# 说明成功
\q
exit

# 查看 psql 运行状态
sudo systemctl status postgresql

二、构建 Blockscout Backend

2.1 克隆 Blockscout Backend 仓库

# 创建 blockscout 工作目录
cd ~
mkdir -p blockscout
cd blockscout

# 克隆 blockscout backend 并切换到最新 release 分支
git clone https://github.com/blockscout/blockscout.git backend
cd backend
git checkout v9.1.0 -b v9.1.0

# 安装 Mix 依赖并编译
mix do deps.get, local.rebar --force, deps.compile, compile

# 为数据库生成新的 secret_key_base
mix phx.gen.secret

2.2 编辑环境变量文件

创建 env_vars.env 文件

nano env_vars.env

填写以下变量：

export DATABASE_URL=postgresql://YOUR_DBUSER_NAME:YourSecurePassword@localhost:5432/blockscout
export SECRET_KEY_BASE= # generated by mix phx.gen.secret

export ETHEREUM_JSONRPC_VARIANT=geth
export ETHEREUM_JSONRPC_HTTP_URL=http://localhost:8545
export ETHEREUM_JSONRPC_WS_URL=ws://localhost:8546
export ETHEREUM_JSONRPC_TRACE_URL=http://localhost:8545

export API_V2_ENABLED=true
export PORT=4000
export MIX_ENV=prod

export CHAIN_ID=L2_CHAIN_ID
export L1_RPC=L1_RPC_URL

export COIN=ETH
export COIN_NAME="Sepolia ETH"
export COINGECKO_COIN_ID=ethereum
export DISPLAY_TOKEN_ICONS=true

export MICROSERVICE_SC_VERIFIER_ENABLED=true
export MICROSERVICE_SC_VERIFIER_URL=http://localhost:8082/
export MICROSERVICE_VISUALIZE_SOL2UML_ENABLED=true
export MICROSERVICE_VISUALIZE_SOL2UML_URL=http://localhost:8081/
export MICROSERVICE_SIG_PROVIDER_ENABLED=true
export MICROSERVICE_SIG_PROVIDER_URL=http://localhost:8083/

加载环境变量

source env_vars.env

# 查看 postgresql 运行状态
sudo systemctl status postgresql
# 创建数据库并迁移
mix do ecto.create, ecto.migrate

2.3 安装 Blockscout Backend 内置前端静态资源

# 安装 Node.js 依赖
cd apps/block_scout_web/assets
npm install
node_modules/webpack/bin/webpack.js --mode production
cd -
cd apps/explorer
npm install

# 编译静态资源
cd ../block_scout_web/
mix phx.digest

# 生成自签名证书以启用 HTTPS（开发环境）：
mix phx.gen.cert blockscout blockscout.local
cd ../..

将 blockscout 和 blockscout.local 添加到 /etc/hosts：

sudo nano /etc/hosts

# 添加以下行
127.0.0.1 	localhost blockscout blockscout.local
::1 		localhost blockscout blockscout.local

三、运行微服务

3.1 修改 stats.yml

cd docker-compose/services
nano stats.yml

将 stats.yml 文件的第 49 行改为自己的 postgresql 数据库，将 localhost 改为本机 IP

#STATS__BLOCKSCOUT_DB_URL=${STATS__BLOCKSCOUT_DB_URL:postgresql://blockscout:ceWb1MeLBEeOIfk65gU8EjF8@db:5432/blockscout}

STATS__BLOCKSCOUT_DB_URL=${STATS__BLOCKSCOUT_DB_URL:postgresql://YOUR_DBUSER_NAME:YourSecurePassword@YourIPADDR:5432/blockscout}

3.2 修改 user-ops-indexer.yml

nano user-ops-indexer.yml

修改 user-ops-indexer.yml 文件的第 15 和 16 行，替换自己的 postgresql 数据库和本机 IP

# USER_OPS_INDEXER__INDEXER__RPC_URL=${USER_OPS_INDEXER__INDEXER__RPC_URL:ws://host.docker.internal:8545/}
# USER_OPS_INDEXER__DATABASE__CONNECT__URL=${USER_OPS_INDEXER__DATABASE__CONNECT__URL:postgresql://blockscout:ceWb1MeLBEeOIfk65gU8EjF8@db:5432/blockscout}

USER_OPS_INDEXER__INDEXER__RPC_URL=${USER_OPS_INDEXER__INDEXER__RPC_URL:-ws://YourIPADDR:8546/}
STATS__BLOCKSCOUT_DB_URL=${STATS__BLOCKSCOUT_DB_URL:postgresql://YOUR_DBUSER_NAME:YourSecurePassword@YourIPADDR:5432/blockscout}

3.3 删除 explorer.conf.template

cd ../proxy
mv explorer.conf.template explorer.conf.template.backup

3.4 修改 common-stats.yml

cd ../envs
nano common-stats.env

将 common-stats.yml 的第 29 行修改为自己的后端服务

# STATS__BLOCKSCOUT_API_URL=http://host.docker.internal
STATS__BLOCKSCOUT_API_URL=http://YourIPADDR:4000

3.5 启动内置微服务

cd ..
docker-compose -f microservices.yml up -d
docker ps

此时如果 layer2 是启动状态，所有微服务都应该启动成功，如果失败查看 logs docker logs ServiceName

3.6 启动后端服务

返回 blockscout-backend 根目录并启动 Phoenix 服务器

cd ~/blockscout/backend/
mix phx.server

后端应运行在 http://localhost:4000（或配置的域名）

四、构建 Blockscout Frontend

4.1 克隆 Blockscout Frontend 仓库

# 克隆 blockscout frontend 并切换到最新 release 分支
cd ~/blockscout
git clone https://github.com/blockscout/frontend.git frontend
cd frontend
git checkout v2.3.2 -b v2.3.2

在 frontend 目录下新建 .tool-versions 文件并写入：

nodejs 22.11.0

4.2 在 configs/envs 与根目录下分别创建 .env.namepreset 和 .env 文件

# 应用基础配置
NEXT_PUBLIC_APP_HOST=localhost
NEXT_PUBLIC_APP_PORT=3000
NEXT_PUBLIC_APP_INSTANCE=localhost
NEXT_PUBLIC_APP_ENV=development

NEXT_PUBLIC_API_HOST=localhost
NEXT_PUBLIC_API_PORT=4000
NEXT_PUBLIC_API_PROTOCOL=http
NEXT_PUBLIC_API_WEBSOCKET_PROTOCOL='ws'

# 微服务配置
NEXT_PUBLIC_STATS_API_HOST=http://localhost:8080
NEXT_PUBLIC_VISUALIZE_API_HOST=http://localhost:8081

# 首页内容配置
NEXT_PUBLIC_HOMEPAGE_CHARTS=['daily_txs', 'coin_price', 'market_cap']
NEXT_PUBLIC_HOMEPAGE_HERO_BANNER_CONFIG={"background":["rgba(27, 74, 221, 1)"]}
NEXT_PUBLIC_HOMEPAGE_STATS=['total_blocks','average_block_time','total_txs','wallet_addresses','gas_tracker']

# 广告配置
NEXT_PUBLIC_AD_BANNER_PROVIDER=none
NEXT_PUBLIC_AD_TEXT_PROVIDER=none

# 区块链网络配置
NEXT_PUBLIC_NETWORK_NAME="YangFan"
NEXT_PUBLIC_NETWORK_ID=L2_CHAIN_ID
NEXT_PUBLIC_NETWORK_CURRENCY_NAME="Sepolia ETH"
NEXT_PUBLIC_NETWORK_CURRENCY_SYMBOL="ETH"
NEXT_PUBLIC_NETWORK_CURRENCY_DECIMALS=18

4.3 启动前端服务

# 安装项目依赖并启动前端调试
yarn install
yarn dev:preset namepreset

# 调试完成后启动服务
yarn build
yarn start

后端应运行在 http://localhost:3000（或配置的域名）

Hooray！Blockscout 部署成功！！！

五、故障排查

5.1 数据库最大连接数限制

PostgreSQL 的默认最大连接数（max_connections）通常为 100，Blockscout 后端和多个微服务会创建大量数据库连接，占用了所有可用连接槽。此时会遇到：FATAL: sorry, too many clients already 之类的错误，此时需要修改数据库默认最大连接数

sudo nano /etc/postgresql/*/main/postgresql.conf

max_connections = 500

更改后需要重启 PostgreSQL

sudo systemctl restart postgresql

5.2 JavaScript heap out of memory

yarn build 时可能会遇到 JavaScript 内存溢出，此时需要加载环境变量 NODE_OPTIONS

export NODE_OPTIONS="--max-old-space-size=4096"

5.3 后端连接数据库失败

在用户名和密码都正确的前提下数据库连接失败，可能时因为 PostgreSQL 数据库的认证配置限制了密码认证方式

sudo nano /etc/postgresql/17/main/pg_hba.conf

在 # IPv4 local connections:下添加

host    all             all             0.0.0.0/0               scram-sha-256

参考资料

• Blockscout 官方文档: https://docs.blockscout.com/setup/deployment/manual-deployment-guide
• 前端仓库: https://github.com/blockscout/frontend
• 后端仓库: https://github.com/blockscout/blockscout