利用Hyperledger Fabric开发你的第一个区块链应用

本文既是 Hyperledger Fabric（以下简称 Fabric）的实用教程，也是其学习、研究笔记。读者可以与作者一起，一步一步地学习 Fabric 基础知识，利用 Hyperledger Composer（以下简称 Composer）搭建 Fabric 本地开发环境，运行示例应用；并进一步分析、深入了解其技术结构与特点。

本文尽量不去简单复述其他相关文档，着重从实用角度与读者一起迅速建立对 Fabric 的直观认识，并在实践中逐渐理解区块链技术。本系列文章有三个部分，此为第一部分。

在本文示例中，Fabric 的版本为 1.1.0，Composer 的版本为 0.19.1。在以后的学习过程，它们可能随时有版本更新，而 micro 版本的改动应该对示例操作不会有影响。但仍请注意版本更新可能带来的变化。

基本概念与知识

基本概念与重要平台、技术、工具

用一句话来描述区块链：区块链是一个共享的不可修改的账本，可用来记录一个网络上所有交易的历史。这里所说的"交易"翻译自"Transaction"。也可以将之称为"事务"，本文将之统一称为"交易"。

Hyperledger 是 Linux 基金会主持的一个开源项目，启动于 2015 年，其核心目标是建立开放的、标准化的、企业级的、能支持商业交易的分布式账本的框架与基础代码。

Hyperledger Fabric 是 Hyperledger 项目的一个组成部分，是一个区块链框架的实现。它将成为区块链应用开发、解决方案的基础。Fabric 框架支持组件化、可插拔的共识服务（Consensus Service）、成员服务（Membership Service）；"许可（Permissioned）"特性使之为"私有性"、"保密性"提供了可靠的解决方案；智能合约（Smart Contracts）在 Fabric 中通过"Chaincode"得以实现。Fabric 最初是由 Digital Asset、IBM 贡献给 Hyperledger 项目的。

Hyperledger Composer 也是 Hyperledger 项目的一个组成部分。通过它，人们可以更快速、容易地建立区块链业务模型，进行区块链网络及应用的开发、部署，并与现有系统、数据进行集成。

本文中，对于 Fabric 的学习，正是以 Composer 作为入口与基础工具，这样学习的效率更高。在学习初期，Fabric 与 Composer 的知识是紧密结合的，在后期，我们会对这两项技术分别深入学习、研究。

知识准备

区块链技术涉及到的技术比较多，本文希望能帮助读者将焦点一直放在区块链本身上，即使对某项技术学习得不是非常深入，也不会影响对于 Fabric 的学习。一般来说，希望读者还是能对以下知识预先有所了解：Ubuntu，Docker，Node.js，Javascript，npm，CA。

安装 Fabric 之前的环境准备

Ubuntu 16.04 LTS 64-bit

Fabric 支持 MacOSX、*nix 或者 Windows 10 操作系统；Composer 支持 Ubuntu Linux 14.04 / 16.04 LTS (64-bit)或者 MacOS 10.12 操作系统。

现在，我们使用 Ubuntu16.04 LTS 64-bit，作为我们的区块链部署系统。对于 Ubuntu 系统的安装与管理，这里不再详述，但可以通过以下命令确认版本信息：

确认 Ubuntu Linux 版本

# cat /etc/issue
Ubuntu 16.04.4 LTS \n \l
# uname -a

系统用户

我们在学习过程中，几乎所有操作都通过一个专门的用户来完成（在本文示例中，使用的用户名为：fabric；读者可以根据需要使用自己的用户名，但请注意在后续示例中要相应修改）。请不要使用 root 用户。

添加一个新用户

# adduser fabric

将此用户加入 sudo 用户组

# usermod -aG sudo fabric

切换为 fabric 用户，并进入用户目录

#




    
 su fabric
$ cd ~

安装 Node.js, npm, Docker, Docker Compose, Python

现在需要安装 Node.js, Docker 等软件，Hyperledger 提供了一个脚本，可以用来自动安装。

下载并执行自动安装脚本

$ curl -O https://hyperledger.github.io/composer/latest/prereqs-ubuntu.sh
$ chmod u+x prereqs-ubuntu.sh
$ ./prereqs-ubuntu.sh

安装成功后，会显示以下内容，包括安装的软件名称及版本号。（后续版本可能会有变化。）

Installation completed, versions installed are:
Node:             v8.11.1
npm:              5.8.0
Docker:           Docker version 18.03.0-ce, build 0520e24
Docker Compose:   docker-compose version 1.13.0, build 1719ceb
Python:           Python 2.7.12
Please logout then login before continuing.

退出并重新登录

请退出当前用户会话，关闭客户端工具与 Ubuntu 的连接；并重新以用户 fabric 登录 Ubuntu，以使系统设置生效。

如果是自行手动安装这几项软件但版本号并不完全一致，可能会给后续过程带来一些障碍。所以，为节约时间，请尽量使用这个自动安装脚本；或手动安装这些版本的软件。

使用 Hyperledger Composer 安装 Fabric Runtime

现在，终于要正式开始安装 Composer 和 Fabric 了。

安装 Composer

Hyperledger Composer 是一个开放的开发框架、工具集，可以帮助人们更容易地开发、部署区块链应用。它支持 Fabric，并提供 Javascript SDK。我们可以通过 npm 来安装它的一系列组件。

安装 Composer 命令行工具 CLI

$ npm install -g composer-cli
$ npm view composer-cli version
0.19.1

当前，其版本为：0.19.1。

我们之后许多操作（安装、部署、管理）都将通过 Composer CLI 完成。

因为之前的 Node.js 是通过 nvm 安装的（请参考：prereqs-ubuntu.sh），并在这里使用了"-g"选项，所以默认设置下安装的 node modules 文件可以在这里找到：

~/.nvm/versions/node/v8.11.1/lib/node_modules

安装 Composer REST Server

$ npm install -g composer-rest-server
$ npm view composer-rest-server version
0.19.1

Composer REST server 可以根据我们开发、部署的区块链应用自动生成一些 RESTful API 接口，以方便通过浏览器、curl 等工具对之进行访问。

安装 generator-hyperledger-composer

$ npm install




    
 -g generator-hyperledger-composer
$ npm view generator-hyperledger-composer version
0.19.1

它包含了一组 Yeoman generator，可以在 Yeoman 中执行，以根据模板生成我们将要部署的区块链网络文件。

安装 Yeoman

$ npm install -g yo
$ npm view yo version
2.0.2

Yeoman 能根据定义好的 generator 迅速生成我们所需要的项目、应用的框架。

安装 Hyperledger Fabric Runtime

新建一个 Fabric Tools 目录

$ cd ~
$ mkdir fabric-tools
$ cd fabric-tools/

fabric-tools 目录是我们以后的工作目录，读者可以按需要改成自己期望的目录名。

下载 Fabric Dev Server

$ curl -O https://raw.githubusercontent.com/hyperledger/composer-
tools/master/packages/fabric-dev-servers/fabric-dev-servers.tar.gz

目前，fabric-dev-servers.zip 包含了 Fabric1.0 与 Fabric1.1 的两套安装脚本，及用于初始化的 Fabric 相关配置。解压后文件位于 fabric-tools/fabric-scripts 目录下。

解压 Fabric Dev Server

$ tar -xvf fabric-dev-servers.tar.gz

下载 Fabric Image 文件

$ ./downloadFabric.sh

默认情况下这个脚本最终会执行 fabric-scripts/hlfv11/downloadFabric.sh，hlfv11 表示 Hyperledger Fabric V1.1。这个过程会下载 5 个 docker image 文件，共约 3.6G，视网络情况，可能需要比较长的时间。下载完成后可以通过 docker images 命令查看。

$ docker images
REPOSITORY                   TAG             IMAGE ID          CREATED             SIZE
hyperledger/fabric-ca        x86_64-1.1.0    72617b4fa9b4      2 weeks ago         299MB
hyperledger/fabric-orderer   x86_64-1.1.0    ce0c810df36a      2 weeks ago         180MB
hyperledger/fabric-peer      x86_64-1.1.0    b023f9be0771      2 weeks ago         187MB
hyperledger/fabric-ccenv     x86_64-1.1.0    c8b4909d8d46      2 weeks ago         1.39GB
hyperledger/fabric-couchdb   x86_64-0.4.6    7e73c828fc5b      6 weeks ago         1.56GB

到这里，我们就非常迅速、方便的完成了 Fabric 的下载，及部署环境的安装，得益于 Docker Container 技术，并不需要我们做复杂的配置。接下来将要开始部署一个示例应用。在之前，我们要先启动 Fabric，并生成 PeerAdmin card。

启动 Fabric

$ ./startFabric.sh

startFabric.sh 最终会执行 ~/fabric-tools/fabric-scripts/hlfv11/startFabric.sh，里面有如下一行内容：

ARCH=$ARCH docker-compose -f "${DOCKER_FILE}" up -d

打开~/fabric-tools/fabric-scripts/hlfv11/composer/docker-compose.yml 我们可以看到有如下四个 Docker 应用的配置：ca.org1.example.com(CA Node)，orderer.example.com(Orderer Node)，peer0.org1.example.com(Peer Node)，couchdb(Database)。它们启动成功后即意味着 Fabric 区块链网络的核心部分已经处于运行状态了。

在 startFabric.sh 中，还有以下内容：

docker exec peer0.org1.example.com peer channel




    
 create ……
docker exec -e …… peer0.org1.example.com peer channel join ……

它们的作用是建立一个通道（Channel）并将刚启动的节点 peer0.org1.example.com 加入到这个通道。

通道（Channel）是 Fabric 中的重要概念与设计，它是网络成员间通讯的私有的子网络；网络中会有多个通道同时存在；每个交易都在认证、授权后在某个通道里执行；所有数据、交易、成员、通道信息都只对此通道的授权成员可见。

生成并导入 PeerAdmin Card

$ ./createPeerAdminCard.sh

这个脚本会生成一个 Card 文件，它包含了 Fabric 网络的信息以及管理员 PeerAdmin 与之连接所必须的信息；即管理员的身份证明文件；生成后这个文件会被导入到 Composer，你可以在~/.composer/cards/PeerAdmin@hlfv1 目录下找到被导入的 PeerAdmin Card 的文件内容。之后，Composer 会利用这个 Card 文件建立起到 Fabric 网络的连接。

在以后的学习中，我们会介绍如何建立一个自定义的 Card 文件。

部署第一个 Fabric 区块链业务网络

Fabric runtime 已经被成功安装、启动了，现在我们要部署第一个 Fabric 区块链业务网络。

准备业务网络

为使学习过程更容易，我们直接利用 Yeoman 及已经下载的 Generator 生成区块链网络框架。

在以后的章节中，我们会介绍如何按步骤手工完成定义、部署过程。

生成业务网络定义（Business Network Definition – BND）

$ yo hyperledger-composer:businessnetwork

参数 businessnetwork 来自于之前安装的 generator-hyperledger-composer，表示了一组对应的模板文件。可以在 ~/.nvm/versions/node/v8.11.1/lib/node_modules/generator-hyperledger-composer/generators/businessnetwork/templates/ 下找到即将生成的内容的模板。

运行会提示输入相关信息，为方便学习，建议 Business network name 定义为：tutorial-network；Namespace 定义为：org.example.biznet，其他信息可以自行决定内容。将定义的内容如下：

Business network name: tutorial-network
Description: The first blockchain network
Author name: Alice
Author email: alice@org.example.biznet
License: Apache-2.0
Namespace: org.example.biznet

执行成功后，在当前 ~/fabric-tools/ 目录下，新增了一个目录 tutorial-network, 里面有 index.js, package.json 等文件，以及 lib, models 两个目录，这就是将要部署的区块链业务网络定义。

进入 tutorial-network 目录

$ cd ~/fabric-tools/tutorial-network

后续的操作基本都在此目录下完成。

生成 .bna 文件

$ composer archive create -t dir -n .

执行成功后，在当前目录下会产生一个新文件 [email protected]，即是 tutorial-network 目录下文件的压缩包。解压后发现其中主要有文件及目录：lib/，models/，package.json，permissions.acl。我们会在以后详细解释、操作这些文件。

部署及启动业务网络

这是第一个示例区块链网络安装部署的最后一部分内容了。

部署示例业务网络 tutorial-network

$ composer network install --card PeerAdmin@hlfv1 --archiveFile tutorial-network@0.0.1.bna

或者

$ composer network install --c PeerAdmin@hlfv1 --a tutorial-network@0.0.1.bna

"composer network install" 命令会部署指定的 .bna 文件到 Fabric 网络。.bna 文件包括了这个业务网络的 Assets 模型、交易事务逻辑、访问控制规则等定义，但它并不能直接在 Fabric 上运行。.bna 文件是由 Composer 生成的，它是用 Composer 提供支持的一系列建模语言、规范定义的业务网络定义，我们必须将它先安装在 Fabric Peer 节点上。然后才可以在这个节点上启动运行这个业务网络。

参数 -c (--card) 应指定为在上一步骤中生成 PeerAdmin Card 文件。

参数 -a (--archiveFile) 应指定为将要部署的业务网络文件包。

启动业务网络

$ composer network start --networkName tutorial-network --networkVersion 0.0.1 --




    

networkAdmin admin --networkAdminEnrollSecret adminpw --card PeerAdmin@hlfv1 --file
networkadmin.card

"composer network start" 用指定的 Card 启动这个网络；同时会生成一个当前业务网络的管理员 Card 文件，即此示例中的 networkadmin.card。

这个文件是 zip 格式的压缩文件，解压缩后，可以发现包含两个文件：connection.json, metadata.json。其中，metadata.json 内容如下：

{"version":1,
"userName":"admin",
"businessNetwork":"tutorial-network",
"enrollmentSecret":"adminpw"}

"admin", "tutorial-network" 正是我们此前的定义的管理员用户名，及业务网络名。我们在以后可以通过类似 -c admin@tutorial-network 使用这个管理员身份。

导入 tutorial-network 管理员 Card

$ composer card import --file networkadmin.card

此时再查看 ~/.composer/cards 会发现新导入的 Card 文件。也可以直接通过命令查看。

查看导入的 Card 文件

$ composer card list
┌────────────────────────┬───────────┬──────────────────┐
│ Card Name              │ UserId    │ Business Network │
├────────────────────────┼───────────┼──────────────────┤
│ admin@tutorial-network │ admin     │ tutorial-network │
├────────────────────────┼───────────┼──────────────────┤
│ PeerAdmin@hlfv1        │ PeerAdmin │                  │
└────────────────────────┴───────────┴──────────────────┘

确认 tutorial-network 安装成功

$ composer network ping --card admin@tutorial-network

如果部署成功，会显示类似如下内容：

The connection to the network was successfully tested: tutorial-network
Business network version: 0.0.1
Composer runtime version: 0.19.1
participant: org.hyperledger.composer.system.NetworkAdmin#admin
identity: org.hyperledger.composer.system.Identity#...
Command succeeded

启动 REST Server

$ composer-rest-server

并在之后提示的选项中输入内容如下：

Card Name: admin@tutorial-network
Never use namespace
Enable authentication (default): No
Enable event publication over WebSockets (default): Yes
Enable TSL (default): No

也可以直接带参数运行命令行：

$ composer-rest-server -c admin@tutorial-network -n never

composer-rest-server 会根据部署的业务网络生成一系列 REST API,以方便用户通过浏览器或其他类似 curl 的应用程序访问这个区块链业务网络。如果在本机，我们可以通过这样的地址访问：

http://localhost:3000/explorer。

部署成功

到这里，我们就成功地通过 Hyperledger Composer 安装了 Hyperledger Fabric，并部署、启动了第一个区块链业务网络 tutorial-network。

访问区块链网络

现在我们可以开始访问部署成功的第一个 Fabric 区块链业务网络。

本文主要介绍通过浏览器和 curl 命令访问 REST Service。

通过浏览器访问 REST Service

在浏览器中输入 http://fabric11dev1:3000/explorer。

fabric11dev1 是当前部署运行 Composer REST Server 的机器名。如果从本机访问，可以使用 localhost，或者直接使用 IP 地址访问。后文不再对此特别说明。

图 1. 入口界面

SampleAsset 是这个区块链业务网络中定义的资产模型 (Asset)。表示一种有形或无形的可改变、转移的商品。

SampleParticipant 是这个业务网络的成员 (Participant)，可以拥有 Asset，提交 Transaction。

SampleTransaction 是一种交易或事务 (Transaction)，由成员提交到业务网络，用以改变、转移商品，或触发其他操作。

这些内容都可点击展开，显示 REST API 中对于此项内容的所有操作。

图 2. Participant 操作

点击 GET，POST 等按钮，可以进行展开并进行各种操作。

点击 POST 按钮，可添加一个新的 SampleParticipant。

图 3. 添加 SampleParticipant

在 data 输入框中，输入如下内容：

{
"$class": "org.example.biznet.SampleParticipant",
"participantId": "SP_1",
"firstName": "Alice",
"lastName": "Fabric"
}