Hyperledger Explorer

简介

Hyperledger Explorer is a simple, powerful, easy-to-use, well maintained, open source utility to browse activity on the underlying blockchain network. Users have the ability to configure and build Hyperledger Explorer on MacOS and Ubuntu.

下载

Hyperledger Explorer Version	Fabric Version Supported	NodeJS Version Supported
v1.0.0-rc2 (Dec 10, 2019)	v1.4.0 to v1.4.4	8.11.x
v1.0.0-rc1 (Nov 18, 2019)	v1.4.2	8.11.x
v0.3.9.5 (Sep 8, 2019)	v1.4.2	8.11.x
v0.3.9.4 (June 18, 2019)	v1.4.1	8.11.x
v0.3.9.3 (May 24, 2019)	v1.4	8.11.x
v0.3.9.2 (May 16, 2019)	v1.4	8.11.x
v0.3.9.1 (Feb 28, 2019)	v1.4	8.11.x
v0.3.9 (Feb 7, 2019)	v1.4	8.11.x
v0.3.8 (Dec 13, 2018)	v1.3	8.x.x
v0.3.7 (Sep 21, 2018)	v1.2	8.x.x
v0.3.6.1 (Sep 21, 2018)	v1.2	8.x.x
v0.3.6 (Sep 6, 2018)	v1.2	8.x.x
v0.3.5.1 (Sep 21, 2018)	v1.1	8.x.x
v0.3.5 (Aug 24, 2018)	v1.1	8.x.x
v0.3.4 (Jul 13, 2018)	v1.1	8.x.x

项目结构

blockchain-explorer
    |
    ├── app                     Application backend root, Explorer configuration
    |    ├── rest               REST API
    |    ├── persistence        Persistence layer
    |    ├── fabric             Persistence API (Hyperledger Fabric)
    |    └── platform           Platforms
    |    |    └── fabric        Explorer API (Hyperledger Fabric)
    |    └── test               Application backend test
    |
    └── client                     Web UI
         ├── public             Assets
         └── src                Front end source code
              ├── components    React framework
              ├── services      Request library for API calls
              ├── state         Redux framework
              └── static        Custom and Assets

安装

准备条件

Following are the software dependencies required to install and run hyperledger explorer:

• Nodejs 8.11.x (Note that v9.x is not yet supported)
• PostgreSQL 9.5 or greater
• jq
• Linux-based operating system, such as Ubuntu or MacOS

Verified Docker versions supported:

• Docker CE 18.09.2 or later
• Docker Compose 1.14.0

克隆仓库到本地

Clone this repository to get the latest using the following command.

git clone https://github.com/hyperledger/blockchain-explorer.git
cd blockchain-explorer 

设置数据库

• cd blockchain-explorer/app
• Modify explorerconfig.json to update PostgreSQL database settings.

"postgreSQL": {
    "host": "127.0.0.1",
    "port": "",
    "database": "fabricexplorer",
    "username": "hppoc",
    "passwd": "password"
}

Another alternative to configure database settings is to use environment variables, example of settings:

    export DATABASE_HOST=127.0.0.1
    export DATABASE_PORT=
    export DATABASE_DATABASE=fabricexplorer
    export DATABASE_USERNAME=hppoc
    export DATABASE_PASSWD=pass12345

Important repeat after every git pull (in some case you may need to apply permission to db/ directory from blockchain-explorer/app/persistence/fabric/postgreSQL run:

chmod -R  db/

运行创建的数据库脚本

Ubuntu

cd blockchain-explorer/app/persistence/fabric/postgreSQL/db
sudo -u postgres ./createdb.sh

MacOS

cd blockchain-explorer/app/persistence/fabric/postgreSQL/db
./createdb.sh 

Connect to the PostgreSQL database and run DB status commands:

\l View created fabricexplorer database.
\d View created tables.

If your Postgresql configured with TLS, read link how to configure connection to Postgresql with TLS

授权认证

cd blockchain-explorer/app

• Modify explorerconfig.json to update Authorization (JWT) settings.

"jwt": {
    "secret" : "a secret phrase!!",
    "expiresIn": "2 days"
}

• secret: secret string to sign the payload.

• expiresIn: expressed in seconds or a string describing a time span zeit/ms.

  Eg: 60, "2 days", "10h", "7d". A numeric value is interpreted as a seconds count. If you use a string be sure you provide the time units (days, hours, etc), otherwise milliseconds unit is used by default ("120" is equal to "120ms").

Fabric 网络设置

• Note: This section will take some time to complete.

• Setup your own network using the Building Your First Network tutorial from Hyperledger. Once you setup the network, please modify the values in /blockchain-explorer/app/platform/fabric/config.json accordingly.
• Hyperledger Explorer defaults to utilize fabric-samples/first-network.
• Make sure to set the environment variables CORE_PEER_GOSSIP_BOOTSTRAP and CORE_PEER_GOSSIP_EXTERNALENDPOINT for each peer in the docker-compose.yaml file. These settings enable the Fabric discovery service, which is used by Hyperledger Explorer to discover the network topology.

配置操作服务 Config-Operations-Service-Hyperledger-Explorer

运营服务

• 对等方和订购者托管一个HTTP服务器，该服务器提供RESTful“操作” API。此API与Fabric网络服务无关，旨在供运营商使用，而不是网络的管理员或“用户”使用，更多内容请参见 Operations Service

“结构样本/第一个网络”的样本配置

• 修改/fabric-samples/first-network/base/docker-compose-base.yaml文件，为每个订购者和每个对等方添加操作服务，然后重新启动光纤网络，以使操作服务广播指标和其他信息。请访问提供的docker-compose-base-sample.yaml示例。

• 订购者样本配置

  - ORDERER_OPERATIONS_LISTENADDRESS=0.0.0.0:  # operation RESTful API
  - ORDERER_METRICS_PROVIDER=prometheus  # prometheus will pull metrics from orderer via /metrics RESTful API

• 对等样本配置

  - CORE_OPERATIONS_LISTENADDRESS=0.0.0.0:  # operation RESTful API
  - CORE_METRICS_PROVIDER=prometheus  # prometheus will pull metrics from orderer via /metrics RESTful API

Note that each peer, and orderer need to have a different port, and it available  within your environment 

在本地设置Prometheus服务器并配置

• 后续操作如何设置Prometheus服务器入门
• 使用样本prometheus.yml启动prometheus。在本地
• 要查看配置是否正确，请启动prometheus，然后在浏览器中打开http：// localhost：9090。

设置Grafana

• 开始使用Grafana
• 登录到grafana http：// localhost：3000 / login，默认凭据admin / admin
• 导航到http：// localhost：3000 / dashboard / import
• 单击“上传.json文件”按钮，然后选择示例文件。

使用Docker设置Prometheus服务器和Grafana

• 在示例docker-compose文件中，我们已经完成了Prometheus服务器和Grafana设置的配置。如果要自定义配置，请参阅以下文件和官方说明（Prometheus / Grafana）。

  - app/platform/fabric/artifacts/operations/balance-transfer/prometheus.yml
  - app/platform/fabric/artifacts/operations/balance-transfer/balance-transfer-grafana-dashboard.json
  - app/platform/fabric/artifacts/operations/grafana_conf/provisioning/dashboards/dashboard.yaml
  - app/platform/fabric/artifacts/operations/grafana_conf/provisioning/datasources/datasource.yaml

• 使用以下命令启动服务后，在浏览器中打开http：// localhost：3000。您将能够看到Balance Transfer, Quick Summary预配置的仪表板。

  $ cd blockchain-explorer
  $ docker-compose down -v  # Just for cleaning up the old persist docker volumes
  $ docker-compose up -d

7.0 Configure Hyperledger Fabric

On another terminal:

• cd blockchain-explorer/app/platform/fabric
• Modify config.json to define your fabric network connection profile:

{
    "network-configs": {
        "first-network": {
            "name": "firstnetwork",
            "profile": "./connection-profile/first-network.json",
            "enableAuthentication": false
        }
    },
    "license": "Apache-2.0"
}

• "first-network" is the name of your connection profile, and can be changed to any name.

• "name" is a name you want to give to your fabric network, you can change only value of the key "name".

• "profile" is the location of your connection profile, you can change only value of the key "profile"

• Modify connection profile in the JSON file first-network.json:

  • Change "fabric-path" to your fabric network disk path in the first-network.json file:
    /blockchain-explorer/app/platform/fabric/connection-profile/first-network.json
  • Provide the full disk path to the adminPrivateKey config option, it ussually ends with "_sk", for example:
    "/fabric-path/fabric-samples/first-network/crypto-config/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp/keystore/aaacd899a6362a5c8cc1e6f86d13bfccc777375365bbda9c710bb7119993d71c_sk"
  • "adminUser" is the the admin user of the network, in this case it's fabric CA or an identity user.
  • "adminPassword" is the password for the admin user.
  • "enableAuthentication" is a flag to enable authentication using a login page, setting to false will skip authentication.

配置 Fabcar Sample

Setup Fabcar sample network by following Fabcar Sample Network from Hyperledger fabric samples.

• Make sure to set the environment variables CORE_PEER_GOSSIP_BOOTSTRAP and CORE_PEER_GOSSIP_EXTERNALENDPOINT for each peer in the docker-compose.yaml file. These settings enable the Fabric discovery service, which is used by Hyperledger Explorer to discover the network topology.
• Configure Fabcar sample network based on this link CONFIG-FABCAR-HLEXPLORER.md

配置 Balance Transfer Sample

Balance Transfer Sample network by following Balance Transfer Sample from Hyperledger fabric samples.

• Balance Transfer Sample network based on this link CONFIG-BALANCE-TRANSFER-HLEXPLORER.md

配置 Hyperledger Composer

Setup your own network using Composer Build your network from Hyperledger Composer. Once you setup the network, please modify the values in /blockchain-explorer/app/platform/fabric/config.json accordingly.

On another terminal.

git checkout v0.3.5.
cd blockchain-explorer/app/platform/fabric

• Modify config.json to update network-config
• Change "fabric-path" to your composer network path,Configure the Hyperledger composer based on this link CONFIG-COMPOSER-HLEXPLORER.md
• Modify "syncStartDate" to filter data by block timestamp
• Modify "channel" to your default channel

If you are connecting to a non TLS fabric peer, please modify "network-id.clients.client-id.tlsEnable" (true->false) in config.json. Depending on this configuration, the application decides whether to go TLS or non TLS route.

配置 Hyperledger Cello

Setup your fabric network using Setup Cello Platform from Hyperledger Cello. Once you setup the network, please modify the values in /blockchain-explorer/app/platform/fabric/config.json accordingly.

Optional: Configure Hyperledger Explorer for Cello

On another terminal.

git checkout v0.3.5.
cd blockchain-explorer/app/platform/fabric

• Modify config.json to update network-config.
• Change "fabric-path" to your cello network path,
• Configure the Hyperledger cello based on this link CONFIG-CELLO-HLEXPLORER.md

• Modify "syncStartDate" to filter data by block timestamp
• Modify "channel" to your default channel

If you are connecting to a non TLS fabric peer, please modify "network-id.clients.client-id.tlsEnable" (true->false) in config.json. Depending on this configuration, the application decides whether to go TLS or non TLS route.

构建 Hyperledger Explorer

Important: repeat the below steps after every git pull.

On another terminal:

./main.sh install

to install, run tests, and build project

./main.sh clean

to clean the /node_modules, client/node_modules client/build, client/coverage, app/test/node_modules directories

./main.sh test

to test REST API, and UI components to generate code coverage report 或者

cd blockchain-explorer
npm install
cd blockchain-explorer/app/test
npm install
npm run test
cd client/
npm install
npm run test:ci -- -u --coverage
npm run build

配置 Hyperledger Explorer for HTTPS

• Configure Hyperledger Explorer for HTTPS based on this link CONFIG-HTTPS-HLEXPLORER.md

启动 Hyperledger Explorer

• cd blockchain-explorer/app
• Modify explorerconfig.json to update sync properties
  • sync type (local or host), platform, blocksSyncTime(in min) details.

Sync Process Configuration

• Please restart Explorer if any changes made to explorerconfig.json

Host (Standalone)

• Ensure same configuration in Explorer explorerconfig.json if sync process is running from different locations

 "sync": {
    "type": "host"
 }

Local (Run with Explorer)

 "sync": {
    "type": "local"
 }

From a new terminal:

cd blockchain-explorer/
./start.sh (it will have the backend up).
./start.sh debug (it will have the backend in debug mode).
./start.sh print (it will print help).
Launch the URL http(s)://localhost:8080 on a browser.
./stop.sh (it will stop the node server).

From new terminal (if Sync Process in Standalone).

cd blockchain-explorer/

./syncstart.sh (it will have the sync node up).

./syncstop.sh (it will stop the sync node).

If the Hyperledger Explorer was used previously in your browser be sure to clear the cache before relaunching.

If Hyperledger Fabric network is deployed on other machine, please toggle DISCOVERY_AS_LOCALHOST in start.sh / syncstart.sh to 'false'.

配置日志

By using the following environmet variables, you can control log level of each component (app, db and console). You can set these ALL < TRACE < DEBUG < INFO < WARN < ERROR < FATAL < MARK < OFF string to each level. Each file is rolled by both date (7days) and size (8MB).

• LOG_LEVEL_APP
  • Log level regarding application layer. The logs are written to logs/app/app.log.
  • default DEBUG
• LOG_LEVEL_DB
  • Log level regarding backend layer. The logs are written to logs/db/db.log.
  • default DEBUG
• LOG_LEVEL_CONSOLE
  • Log level regarding console. The logs are written to logs/console/console.log.
  • default INFO
• LOG_CONSOLE_STDOUT
  • You can switch the destination of console log from file to standard output.
  • default false

Docker 运行 Hyperledger Explorer

There is also an automated deployment of the Hyperledger Explorer available via docker given the following requirements are met:

• BASH installed
• Docker is installed on deployment machine.
• Docker Compose is installed on deployment machine.

12.1 Docker Repository

• Hyperledger Explorer docker repository https://hub.docker.com/r/hyperledger/explorer/
• Hyperledger Explorer PostgreSQL docker repository https://hub.docker.com/r/hyperledger/explorer-db

12.2 Run Hyperledger Explorer Using Docker Compose

• Modify an example of docker-compose.yaml to align with your environment

  • networks > mynetwork.com > external > name

  networks:
      mynetwork.com:
          external:
              name: net_byfn 

  • services > explorer.mynetwork.com > volumes
    • Connection profile path (ex. ./examples/net1/config.json)
    • Connection profile directory path (ex. ./examples/net1/connection-profile, which is referred from config.json)
    • Directory path for crypto artifacts of fabric network (ex. ./examples/net1/crypto)

      volumes:
        - ./examples/net1/config.json:/opt/explorer/app/platform/fabric/config.json
        - ./examples/net1/connection-profile:/opt/explorer/app/platform/fabric/connection-profile
        - ./examples/net1/crypto:/tmp/crypto

  • When you connect the explorer to your fabric network through bridge network, you need to set DISCOVERY_AS_LOCALHOST to false for disabling hostname mapping into localhost.

      explorer.mynetwork.com:
          ...
          environment:
          ...
          - DISCOVERY_AS_LOCALHOST=false

• Run the following to start up explore and explorer-db services after starting your fabric network:

  cd /blockchain-explorer
  docker-compose up -d 

• To stop services without removing persistent data, run the following:

  docker-compose down

• In this docker-compose.yaml, two named volumes are allocated for persistent data (for Postgres data and user wallet), if you would like to clear these named volumes, run the following:

  docker-compose down -v

12.3 Docker 故障排查

• If you have an error on Explorer container as below, the initialisation of database might fail in some reasons.

  postgres://hppoc:password@192.168.10.11:5432/fabricexplorer
  error when connecting to db: { error: role "hppoc" does not exist

  In such a case, you need to clear the persistent data by running the following command.

  docker-compose down -v
  docker-compose up -d

• If you have an error on Explorer container as below, the Explorer might not have connected the network which your fabric network is belonging.

  <<<<<<<<<<<<<<<<<<<<<<<<<< Explorer Error >>>>>>>>>>>>>>>>>>>>>
  Error : [ 'Default client peer is down and no channel details available database' ]
  

  In such a case, you need to check whether the explorer container has belonged to the same network with your fabric network or not, with the following command.

  docker network inspect net_byfn  | jq ".[].Containers[].Name" | sort
  "cli"
  "dev-peer0.org1.example.com-mycc-1.0"
  "dev-peer0.org2.example.com-mycc-1.0"
  "dev-peer1.org2.example.com-mycc-1.0"
  "explorerdb.mynetwork.com"              <<---
  "explorer.mynetwork.com"                <<---
  "orderer.example.com"
  "peer0.org1.example.com"
  "peer0.org2.example.com"
  "peer1.org1.example.com"
  "peer1.org2.example.com"

  Or you need to check whether the explorer can ping to each peer on your fabric network or not, with the following command.

  docker exec explorer.mynetwork.com ping -c  peer0.org1.example.com
  PING peer0.org1.example.com (172.18.0.3):  data bytes
   bytes from 172.18.0.3: seq= ttl= time=0.064 ms
  
  --- peer0.org1.example.com ping statistics ---
   packets transmitted,  packets received, % packet loss
  round-trip min/avg/max = 0.064/0.064/0.064 ms

NPM Utility Scripts to Dockerize Application

Set the DOCKER_REGISTRY variable to the Container Registry you will use and login to that registry if you want to store your container there.

To build the container (auto-tagged as latest), run: npm run docker_build

To tag the container with your registry and the NPM package version, run: npm run docker_tag

To push the container to your registry, run: npm run docker_push

Hyperledger Explorer Swagger

• Once the Hyperledger Explorer has been launched go to http://localhost:8080/api-docs to view the Rust API description
• Enter bearer token in Authorize dialog that is generated by the application when you login to Hyperledger Explorer
  • Bearer token can be found using Chrome Developer Tools under the Network tab --> Name --> click on REST API request --> Request Headers --> Authorization: bearer

Logs

• Please visit the ./logs/console folder to view the logs relating to console and ./logs/app to view the application logs and visit the ./logs/db to view the database logs.
• Logs rotate every 7 days.

参考资料

源码：https://github.com/hyperledger/blockchain-explorer