add docs (#80)

Signed-off-by: Yang Cheng <chengyang418@163.com>
Hyperledger-TWGC · Nov 6, 2020 · 9dc0f5a · 9dc0f5a
1 parent c7ef182
commit 9dc0f5a
Show file tree

Hide file tree

Showing 6 changed files with 298 additions and 0 deletions.
diff --git a/docs/FAQ.md b/docs/FAQ.md
@@ -0,0 +1 @@
+# 常见问题
diff --git a/docs/configfile.md b/docs/configfile.md
@@ -0,0 +1,150 @@
+# 配置文件说明
+
+我们为 Tape 提供了一个示例配置文件 `config.yaml`，你可以在项目根据下找到它。使用 Tape 进行测试之前，请根据您的区块链网络情况修改该配置文件。
+
+`config.yaml` 示例配置文件如下所示：
+
+```yaml
+# Definition of nodes
+peer1: &peer1
+  addr: localhost:7051
+  tls_ca_cert: ./organizations/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/msp/tlscacerts/tlsca.org1.example.com-cert.pem
+
+peer2: &peer2
+  addr: localhost:9051
+  tls_ca_cert: ./organizations/peerOrganizations/org2.example.com/peers/peer0.org2.example.com/msp/tlscacerts/tlsca.org2.example.com-cert.pem
+
+orderer1: &orderer1
+  addr: localhost:7050
+  tls_ca_cert: ./organizations/ordererOrganizations/example.com/msp/tlscacerts/tlsca.example.com-cert.pem
+
+# Nodes to interact with
+endorsers:
+  - *peer1
+  - *peer2
+# we might support multi-committer in the future for more complex test scenario,
+# i.e. consider tx committed only if it's done on >50% of nodes. But for now,
+# it seems sufficient to support single committer.
+committer: *peer2
+orderer: *orderer1
+
+# Invocation configs
+channel: mychannel
+chaincode: basic
+args:
+  - GetAllAssets
+mspid: Org1MSP
+private_key: ./organizations/peerOrganizations/org1.example.com/users/User1@org1.example.com/msp/keystore/priv_sk
+sign_cert: ./organizations/peerOrganizations/org1.example.com/users/User1@org1.example.com/msp/signcerts/User1@org1.example.com-cert.pem
+num_of_conn: 10
+client_per_conn: 10
+
+```
+接下来我们将逐一解析该配置文件的含义。
+
+首先，前三个部分：
+
+```yaml
+# Definition of nodes
+peer1: &peer1
+  addr: localhost:7051
+  tls_ca_cert: ./organizations/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/msp/tlscacerts/tlsca.org1.example.com-cert.pem
+
+peer2: &peer2
+  addr: localhost:9051
+  tls_ca_cert: ./organizations/peerOrganizations/org2.example.com/peers/peer0.org2.example.com/msp/tlscacerts/tlsca.org2.example.com-cert.pem
+
+orderer1: &orderer1
+  addr: localhost:7050
+  tls_ca_cert: ./organizations/ordererOrganizations/example.com/msp/tlscacerts/tlsca.example.com-cert.pem
+```
+
+定义了不同的节点，包括 Peer 节点和排序节点，配置中需要确认节点地址以及 TLS CA 证书（如果启用 TLS，则必须配置 TLS CA 证书）。其中节点地址格式为`地址:端口`。此处`地址`推荐使用域名，因此您可能还需要在 hosts 文件中增加节点域名和 IP 的映射关系。
+
+如果启用了双向 TLS，即你的 Fabric 网络中的 Peer 节点在 core.yaml 配置了 "peer->tls->clientAuthRequired" 为 "true"，则表明，不但服务端（Peer 节点）向客户端（Tape）发送的信息是经过加密的，客户端（Tape）向服务端（Peer 节点）发送的信息也应该是加密的，因此我们就需要在配置文件中增加 TLS 通信中需要使用的密钥，双向 TLS 配置示例如下：
+
+```yaml
+peer1: &peer1
+  addr: localhost:7051
+  tls_ca_cert: ./organizations/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/msp/tlscacerts/tlsca.org1.example.com-cert.pem
+  tls_ca_key: ./organizations/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls/server.key
+  tls_ca_root: ./organizations/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls/server.crt
+
+peer2: &peer2
+  addr: localhost:9051
+  tls_ca_cert: ./organizations/peerOrganizations/org2.example.com/peers/peer0.org2.example.com/msp/tlscacerts/tlsca.org2.example.com-cert.pem
+  tls_ca_key: ./organizations/peerOrganizations/org2.example.com/peers/peer0.org2.example.com/tls/server.key
+  tls_ca_root: ./organizations/peerOrganizations/org2.example.com/peers/peer0.org2.example.com/tls/server.crt
+
+orderer1: &orderer1
+  addr: localhost:7050
+  tls_ca_cert: ./organizations/ordererOrganizations/example.com/orderers/orderer0.example.com/msp/tlscacerts/tlsca.example.com-cert.pem
+  tls_ca_key: ./organizations/ordererOrganizations/example.com/orderers/orderer0.example.com/tls/server.key
+  tls_ca_root: ./organizations/ordererOrganizations/example.com/orderers/orderer0.example.com/tls/server.crt
+```
+
+其中三个 TLS 相关的证书/密钥说明如下：
+- `tls_ca_cert`：客户端 TLS 通信时使用的证书文件。
+- `tls_ca_key`：客户端 TLS 通信时使用的私钥文件。
+- `tls_ca_root`：CA 根证书文件。
+
+接下来的三个部分：
+
+```yaml
+# Nodes to interact with
+endorsers:
+  - *peer1
+  - *peer2
+# we might support multi-committer in the future for more complex test scenario,
+# i.e. consider tx committed only if it's done on >50% of nodes. But for now,
+# it seems sufficient to support single committer.
+committer: *peer2
+orderer: *orderer1
+```
+
+分别定义了角色为背书节点（endorsers）、提交节点（committer）和排序节点（orderer）的节点。
+
+`endorsers`: 负责为交易提案背书的节点，Tape 会把构造好的已签名的交易提案发送到背书节点进行背书。
+
+`committer`: 负责接收其他节点广播的区块提交成功的信息。
+
+`orderer`: 排序节点，目前 Tape 仅支持向一个排序节点发送交易排序请求。
+
+Tape 以 Fabric 用户的身份向区块链网络发送交易，所以还需要下边的配置：
+
+```yaml
+# Invocation configs
+channel: mychannel
+chaincode: basic
+args:
+  - GetAllAssets
+mspid: Org1MSP
+private_key: ./organizations/peerOrganizations/org1.example.com/users/User1@org1.example.com/msp/keystore/priv_sk
+sign_cert: ./organizations/peerOrganizations/org1.example.com/users/User1@org1.example.com/msp/signcerts/User1@org1.example.com-cert.pem
+num_of_conn: 10
+client_per_conn: 10
+```
+
+`channel`：通道名。
+
+`chaincode`：要调用的链码名。
+
+`args`：要调用的链码的参数。参数取决于链码实现，例如，fabric-samples 项目中提供的示例链码 [abac](https://github.com/hyperledger/fabric-samples/blob/master/chaincode/abac/go/abac.go) ，其功能为账户A和账户B之间的转账。如果想要以此链码作为性能测试的链码，执行操作为账户A向账户B转账10，则参数设置如下：
+
+```
+args:
+  - invoke
+  - a
+  - b
+  - 10
+```
+
+`mspid`：MSP ID 是用户属性的一部分，表明该用户所属的组织。
+
+`private_key`：用户私钥的路径。如果你使用 BYFN 作为你的测试网络，私钥路径为 `crypto-config/peerOrganizations/org1.example.com/users/User1@org1.example.com/msp/keystore/priv_sk` 。
+
+`sign_cert`：用户证书的路径。如果你使用 BYFN 作为你的测试网络，私钥路径为 `crypto-config/peerOrganizations/org1.example.com/users/User1@org1.example.com/msp/signcerts/User1@org1.example.com-cert.pem` 。
+
+`num_of_conn`：客户端和 Peer 节点，客户端和排序节点之间创建的 gRPC 连接数量。如果你觉得向 Fabric 施加的压力还不够，可以将这个值设置的更大一些。
+
+`client_per_conn`：每个连接用于向每个 Peer 节点发送 提案的客户端数量。如果你觉得向 Fabric 施加的压力还不够，可以将这个值设置的更大一些。所以 Tape 向 Fabric 发送交易的并发量为 `num_of_conn` * `client_per_conn`。
diff --git a/docs/gettingstarted.md b/docs/gettingstarted.md
@@ -0,0 +1,85 @@
+# 快速开始
+
+## 准备工作
+
+Go 1.11 或者更高版本。推荐 Go 1.13。Go 语言的安装请参考[这里](https://golang.google.cn/doc/install)。
+
+## 安装
+
+目前，你需要从源码安装 Tape，且支持本地编译 Docker 镜像。 
+
+使用如下命令克隆 Tape 仓库到本地：
+
+```
+git clone https://github.com/guoger/tape.git
+```
+
+如果已经配置 SSH 密钥，也可以使用如下命令克隆：
+
+```
+git clone git@github.com:guoger/tape.git
+```
+
+然后，执行如下命令，进入项目目录并编译：
+
+```
+cd tape
+go build ./cmd/tape
+```
+
+Tape 项目是一个 go module 工程，因此不用将项目保存到 `GOPATH` 下，任意目录都可执行编译操作。执行编译命令之后，它会自动下载相关依赖，下载依赖可能需要一定时间。编译完成后，会在当前目录生成一个名为 tape 的可执行文件。
+
+注意：如果下载依赖速度过慢，推荐配置 goproxy 国内代理，配置方式请参考[Goproxy 中国](https://goproxy.cn/)。
+
+## 编译 Docker（可选）
+
+Tape 支持本地编译 Docker 镜像，在项目根目录下执行以下命令即可：
+
+```shell
+docker build -t tape:latest .
+```
+
+执行成功之后本地会增加一个 tape:latest 的 Docker 镜像。
+
+## 修改配置文件
+
+请根据[配置文件说明](configfile.md)修改配置文件。
+
+注意：如果需要修改 hosts 文件，请注意相关映射的修改。
+
+## 运行
+
+执行如下命令即可运行测试：
+
+```
+./tape config.yaml 40000
+```
+
+该命令的含义是，使用 config.yaml 作为配置文件，向 Fabric 网络发送40000条交易进行性能测试。
+
+注意：**请把发送交易数量设置为 batchsize （Fabric 中 Peer 节点的配置文件 core.yaml 中的参数，表示区块中包含的交易数量）的整倍数，这样最后一个区块就不会因为超时而出块了。** 例如，如果你的区块中包含交易数设为500，那么发送交易数量就应该设为1000、40000、100000这样的值。
+
+
+## 日志说明
+
+我们使用 [logrus](https://github.com/sirupsen/logrus) 来管理日志，请通过环境变量 `STUPID_LOGLEVEL` 来设置日志级别。例如：
+
+```
+export STUPID_LOGLEVEL=debug
+```
+
+日志级别共有如下八级，默认级别为 `warn`：
+- panic
+- fatal
+- error
+- warn
+- warning
+- info
+- debug
+- trace
+
+## 注意事项
+
+- 请把 Tape 和 Fabric 部署在接近的位置，或者直接部署在同一台机器上。这样就可以防止因网络带宽问题带来的瓶颈。你可以使用类似 `iftop` 这样的工具来监控网络流量。
+- 可以使用类似 `top` 这样的指令查看 CPU 状态。在测试刚开始的时候，你可能会看到 CPU 使用率很高，这是因为 Peer 节点在处理提案。这种现象出现的时间会很短，然后你就会看到区块一个接一个的被提交。
+- 修改 Peer 的出块参数，可能会有不同的测试结果。如果你想测试最佳出块参数，请查看 [Probe](https://github.com/SamYuan1990/Probe) 项目，该项目的目的就是测试 Fabric 的最佳出块参数。
diff --git a/docs/images/tape.jpeg b/docs/images/tape.jpeg
diff --git a/docs/whatis.md b/docs/whatis.md
@@ -0,0 +1,43 @@
+# 介绍
+
+Tape 一款轻量级 Hyperledger Fabric 性能测试工具。
+
+## 项目背景
+
+Tape 项目原名 Stupid，最初由 [TWGC（Technical Working Group China，超级账本中国技术工作组）](https://wiki.hyperledger.org/display/TWGC)成员郭剑南开发，目的是提供一款轻量级、可以快速测试 Hyperledger Fabric TPS 值的工具。Stupid 取自 [KISS](https://en.wikipedia.org/wiki/KISS_principle) 原则 Keep it Simple and Stupid，目前已正式更名为 Tape，字面含义卷尺，寓意测量，测试。目前 Tape 已贡献到超级账本中国技术社区，由 [TWGC 性能优化小组](https://github.com/Hyperledger-TWGC/fabric-performance-wiki)负责维护。
+
+## 它不做什么
+
+- 它不使用任何 SDK
+- 它不会尝试部署 Fabric 网络
+- 它不会发现节点、链码或者策略
+- 它不会监控资源使用
+
+## 项目特点
+
+1. **轻量级**， Tape 实现过程中没有使用 SDK，直接使用 gRPC 向 Fabric 节点发送和接收请求；
+2. **易操作**，通过简单的配置文件和命令即可快速启动测试；
+3. **结果准确**，Tape 直接使用 gRPC 发送交易，并且对交易和区块处理的不同阶段单独拆分，使用协程及通道缓存的方式并行处理，大幅度提升了 Tape 自身的处理效率，从而可以准确的测试出 Fabric 的真实性能。
+
+## 文档阅读指南
+
+如果你想快速使用 Tape 测试 TPS，请参考[快速开始](docs/gettingstarted.md)；
+如果你想了解配置文件中各项参数的具体含义，请参考[配置文件说明](docs/configfile.md)；
+如果你想详细了解 Tape 工作流程，请参考[工作流程](docs/workflow.md)；
+如果你在使用过程中遇到了问题请参考[FAQ](docs/FAQ.md)，如果 FAQ 还不能解决你的问题，请在 github 中提 issue，或者发邮件咨询项目维护者。
+
+## 欢迎贡献
+
+如果你希望提交新的特性或者遇到了任何 Bug，欢迎在 github 仓库中开启新的 [issue](https://github.com/guoger/tape/issues)，同时也欢迎提交 [pull request](https://github.com/guoger/tape/pulls)。
+
+## 贡献者信息
+
+| 姓名   | 邮箱                 | 所属组织 | 角色   |
+| ------ | -------------------- | -------- | ------ |
+| 郭剑南 |                      | TWGC     | 维护者 |
+| 袁怿   |                      | TWGC     | 维护者 |
+| 程阳   | chengyang418@163.com | TWGC     | 维护者 |
+
+## 使用许可
+
+Tape 遵守 Apache 2.0 开源许可。
diff --git a/docs/workflow.md b/docs/workflow.md
@@ -0,0 +1,19 @@
+# 工作流程
+
+Tape 有多个工作协程组成，所以该流程是高度并行化且可扩展的。这些协程通过缓存通道互相连接，所以它们可以互相传递数据。
+
+整体工作流程如下图：
+
+![tape workflow](images/tape.jpeg)
+
+- **Singer**，签名交易提案协程，负责签名生成的交易提案，并将签名后的结果存入缓存通道中；
+- **Proposer**，提案发送线程，负责从缓存通道中取出已签名的交易提案，然后通过 gRPC 将已签名提案发送到背书节点，并将背书节点返回的背书结果写入另一个缓存通道；
+- **Integrator**，负责从缓存通道中取出背书后的结果，并封装成信封，信封是排序节点可接受的格式，然后将该信封再次存入一个单独的缓存通道；
+- **Broadcaster**，负责将从缓存通道中取出信封，并然后通过 gRPC 将信封广播到排序节点；
+
+以上四个协程可以启动不止一个，因此 Tape 实现高性能和可扩展性，Tape 自身不会成为性能瓶颈。
+
+排序节点生成区块后，会将区块广播到 Peer 节点，Peer 节点接收到区块并经过验证保存到本地账本之后，会向其他节点广播已提交区块，
+
+- **Observer**，接收到 Peer 节点广播的区块之后，会计算区块中交易数量，以及总耗时，当接收到区块的交易数量和运行 Tape 时输入的参数一致时，结束运行，并根据总耗时计算 TPS。
+