Hyperledger Fabric - 官方 e2e_cli 範例快速佈署教學

發表於 更新於 分類於 Disqus： 文章字數： 6.8k 所需閱讀時間 ≈ 12 分鐘

e2e_cli 的場景是設定了一個簡單的 fabric 的網路場景，有兩個 Organization，有兩個 peer，並使用 solo ordering 服務

網路所有需要的加密文件，已經先放進去相對應目錄和配置文件裡面，無須自行配置

examples/e2e_cli 文件裡面包含了 docker-compose 文件和要用來創建和測試網路的腳本文件

下載 fabric 程式碼

1
git clone https://github.com/hyperledger/fabric.git

切換分支到 1.0

1
git checkout release-1.0

編譯 configtxgen 工具

Linux 下的指令：

1
2
cd $GOPATH/src/github.com/hyperledger/fabric
make configtxgen

會編譯出一個 configtxgen 為檔名的 binary file

路徑位於：$GOPATH/src/github.com/hyperledger/fabric/build/bin

執行腳本來執行所有任務，加快部署過程

執行該腳本會生成配置結果 本地網路 Chaincode 測試

進入 $GOPATH/src/github.com/hyperledger/fabric/examples/e2e_cli 目錄

利用腳本來從 Docker Hub 拉取鏡像：

1
2
3
4
# 使腳本可以執行
chmod +x download-dockerimages.sh
# 執行腳本
./download-dockerimages.sh

現在運行腳本，來啟動完整的網路

1
./network_setup.sh up <channel-ID>

如果沒有打 channel-ID 參數，channel 默認名稱是 mychannel

錯誤採坑解決：

1
Error: Error endorsing chaincode: rpc error: code = Unknown desc = Error starting container: API error (404): {"message":"network e2ecli_default not found"}

解決方法：

因為 docker 預設產生的網路應該是名稱應該是 ele_cli_default

但是 ele_cli 裡面的 docker 執行腳本網路名稱卻寫 elecli_default

因此需要去更改 ele_cli 裡面的 docker 網路名稱改成 ele_cli_default

位置：$GOPATH/src/github.com/hyperledger/fabric/examples/e2e_cli/base

裡面的 peer-base.yaml 裡面有個 CORE_VM_DOCKER_HOSTCONFIG_NETWORKMODE 要改成

ele_cli_default

改完後，要關閉 docker container，在重新啟動

1
./network_setup.sh up down

錯誤採坑解決：

1
Error: Error endorsing query: rpc error: code = Unknown desc = could not find chaincode with name 'mycc' - make sure the chaincode mycc has been successfully instantiated and try again - <nil>

解決方法：

通常出現這個錯誤 很有可能是 docker image 裡面有版本不符合 1.0 所需要的

可以用以下方式修改：

1
./download-dockerimage.sh -c x86_64-1.0.0 -f x86_64-1.0.0

會幫你的 docker image 找到 x86_64-1.0.0 的版本而不是原本它幫你下載的 x86_64-1.0.0-beta

可能是 beta 版的不符合 有夠雷 官方教學還說 ok

所以也可以在前面執行 download-dockerimages.sh 那邊不執行，改成直接去 docker pull 一個一個拉下來這樣也可以

啟動成功的畫面

1
2
3
===================== Query on PEER3 on channel 'mychannel' is successful =====================

===================== All GOOD, End-2-End execution completed =====================

可以透過 docker images 看到啟動哪些 Chaincode 鏡像

1
2
3
dev-peer1.org2.example.com-mycc-1.0   latest              88cf417424ea        13 hours ago        173MB
dev-peer0.org1.example.com-mycc-1.0   latest              732ce53d6744        13 hours ago        173MB
dev-peer0.org2.example.com-mycc-1.0   latest              2aa5a1cc7b54        13 hours ago        173MB

可以透過 docker ps 看到啟動哪些容器 會看到啟動四個 peer 容器 一個 orderer 容器 三個 Chaincode 容器

1
2
3
4
5
6
7
8
dev-peer1.org2.example.com-mycc-1.0
dev-peer0.org1.example.com-mycc-1.0   
dev-peer0.org2.example.com-mycc-1.0  
hyperledger/fabric-orderer  
 hyperledger/fabric-peer
hyperledger/fabric-peer 
hyperledger/fabric-peer
hyperledger/fabric-peer

可以看到 e2e_cli 資料夾裡面多了 crypto-config 跟 channel-artifacts 兩個資料夾

network_setup.sh 內容介紹

可以傳入四個參數：UP_DOWN (執行類型)、CH_NAME (頻道名稱)、CLI_TIMEOUT (用戶端逾時設定)、IF_COUCHDB (是否啟動 CouchDB 版本的 yaml 檔案)

如果沒有指定 CLI_TIMEOUT 預設為 10000

另外也指定了兩個官方準備好的 yaml 可執行檔

1
2
COMPOSE_FILE=docker-compose-cli.yaml
COMPOSE_FILE_COUCH=docker-couch.yaml

因為剛剛啟動沒有指定 IF_COUCHDB，因此預設執行 docker-compose-cli.yaml

該檔案位於 network_setup.sh 同級目錄下

如果執行 network_setup up 會預設執行內部的 networkUp 方法：

先判斷是否存在 crypto-config 目錄 預設情況是不存在 如果不存在 會呼叫 generateArtifacts.sh 指令來建立 crypto-config 目錄及所需的區塊練網路憑證等檔案

generateArtifacts.sh 內容介紹

要先注意前面有宣告兩個變數

1
2
export FABRIC_ROOT=$PWD/../..
export FABRIC_CFG_PATH=$PWD

這個代表在 Fabric 跟目錄下執行 而且設定檔的路徑就在目前路徑下

裡面有三個執行方法 執行順序為：generateCerts、replacePrivateKey、generateChannelArtifacts

  • generateCerts

    裡面指定了 cryptogen 檔案的路徑

    也就是在 fabric/realease/linux-amd64/bin

    如果裡面沒有 cryptogen 檔案 它會幫你 build 出來

    這個檔案功用是為了後續執行產生排序及驗收或同步節點憑證及檔案等內容 會出現在 crypto-config 目錄中

    1
    $CRYPTOGEN generate --config=./crypto-config.yaml

    透過以上的指令

    對應的設定檔就是目前目錄下的 crypto-config.yaml

    cropto-config.yaml 內容介紹

    1. OrdererOrgs：排序節點的組織的定義

      定義排序節點的時候會同時定義節點名稱 節點域名 以及 規範列表中節點所需的不帶域名的主機名稱

      可以設定多個排序服務節點 實現排序服務的叢集部署

    2. PeerOrgs：Peer 節點的組織的定義

      在定義 peer 節點時 與排序節點一樣類似的設定 節點域名 名稱等等

      設定有兩種方式：

      • 透過規範列表來指定
      • 透過範本建立的方式

      第一種寫法：

      在 Templaet 中指定了 Count 數量 代表意思是允許透過該範本定義建立 0~count-1 個所屬組織節點或主機

      Users 則是指除了 Admin 之外的建立使用者 其下 Count 定義代表建立的使用者數量

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      PeerOrgs:
        - Name: Org1
          Domain: org1.example.com
          Template:
            Count: 2
          Users:
            Count: 1
        - Name: Org2
          Domain: org2.example.com
          Template:
            Count: 2
          Users:
            Count: 1

      第二種寫法：

      在 Specs 中設定一組標準項目 每個標準項目由兩個欄位組成

      1
      2
      3
      4
      5
      6
      7
      - Name: Org1
         Domain: org1.example.com
      Specs:
            - Hostname: foo 
               CommonName: foo27.org5.example.com 
            - Hostname: bar
            - Hostname: baz

      也就是 Hostname 跟 CommonName

      Hostname 定義不帶域的主機名稱

      CommonName 可選參數 可以來重新定義範本檔案名稱

      預設格式為 Hostname.Domain

      下面沒特別指定的話

      就會變成 bar.org1.example.com baz.org1.example.com

  • replacePrivateKey 方法

    會取代 docker-compose-e2e-template.yaml 檔案中的 CAI_PERIVATE_KEY 為目前的目錄 crypto-config/peer/Organizations/org1.example.com/ca/ 下的_sk 結尾的檔案名稱

    還有取代 CA2_PERIVATE_KEY 為目前目錄 crypto-config/peerOrganizations/org2.example.com/ca/ 下的_sk 結尾的檔案名稱

    最後會產生新檔案在目前資料夾下 命名為 docker-compose-e2e.yaml 在該檔案下定義了 CA 的 CERTFILE 及 KEYFILE

    也透過 command 內建參數顯示啟動了 Fabric-CA 服務端

  • generateChannelArtifacts 方法

    跟 generateCerts 前面一樣 確定 configtxgen 該檔案存不存在 不存在會幫你 build

    最後透過該檔案來產生創世區塊 頻道檔案等資訊

    它會存取該目錄下的設定檔 configtx.yaml

    configtx.yaml

    這裡面定義了五大資訊

    • Profiles 設定檔
    • Organizations 組織節點資訊
    • Orderer 啟動模式
    • Application 應用
    • Capabilities 功能特性集合

之後判斷即將啟動的 Compose 檔案是否是 CouchDB 的

如果沒有指定 預設執行 docker-compose-cli.yaml 檔案

docker-compose-cli.yaml 檔案介紹

排序服務節點繼承了 base/docker-compose-base.yaml 中的 orderer.example.com 屬性

其他四個 peer 節點繼承了 base/docker-compose-base.yaml 中與容器名稱對應的屬性

繼承的檔案屬性，關鍵屬性如下：

  1. environment 設定外界的環境變數
  2. working_dir 目前容器啟動後的工作路徑
  3. volumes 外界實體機路徑掛載或指引到容器內的路徑
  4. ports 指定目前容器啟動後對應到實體機上的通訊 port
  5. depends_on 指定目前本身容器啟動後所依賴的啟動容器物件

這些節點設定資訊基本上已經滿足實際生產應用

真正使用這些服務節點進行 資料維護和管理的則是用客戶端或 SDK 來執行 也就是設定檔的 cli

直接看 cli 的 command 屬性 在 command 中指定當 cli 容器啟動後會執行目標的目錄中 scripts 目錄下的 script.sh 指令稿

Peer 節點及排序服務節點的操作分別有以下九個步驟：

  1. createChannel

    根據之前在 generateArtifacts.sh 指令稿中透過 configtx.yaml 設定檔產生的頻道檔案建立頻道

  2. joinChannel

    Peer 節點加入指定頻道

  3. updateAnchorPeers

    為頻道中的每個組織設定 Peer 節點

  4. installChaincode

    在 Peer0/Org1 和 Peer2/Org2 上安裝智慧合約

  5. instantiateChaincode

    在 Peer2/Org2 上對智慧合約進行實例化操作

  6. chaincodeQuery

    在 Peer0/Org1 上執行智慧合約中的查訊方法

  7. chaincodeInvoke

    在 Peer0/Org1 上執行智慧合約中的交易方法

  8. installChaincode

    在 Peer3/Org2 上安裝智慧合約

  9. chaincodeQuery

    在 Peer3/Org2 上執行智慧合約中的查詢方法

智能合約需要在每一台 Peer 節點伺服器上執行一次安裝操作 而智慧合約的產生實體操作與安裝合約不同 產生實體指需要執行一次即可 即假設有四台 Peer 節點伺服器 如果這四台節點伺服器都有執行同一份智慧合約的需求 則都需要執行一次智慧合約的安裝操作 但產生實體智慧合約只需要在其中任意一台就能完成 多次產生實體沒有額外的意義

同時執行智慧合約產生實體操作時需要確認背書方案 所謂背書就是對目前合約執行寫入的許可權控制方案 背書支援 and 和 or 的單例或混合撰寫方案

query 是執行合約但不發送讀寫集到排序服務

invoke 是既執行合約又同時把 Peer 節點傳回的讀寫集發送至排序服務形成資料寫入操作 最後產生區塊並同步到所有節點

介紹 script.sh

這個是 e2e_cli 中真正對 peer 節點 頻道 智能合約集合操作示範

一些需要注意的指令及坑

停止網路指令

1
./network_setup.sh down

這個會刪除所有 docker container 跟 相關的 docker image

刪除所有 docker image

1
docker rmi -f $(docker images -q)

network_setup.sh 坑

./network_setup.sh 這個腳本執行 如果你沒有相對應的 image 檔案

也會自動幫你下載 但注意 這邊它會幫你自動下載最新版本的 image

因此就會有版本不符合的錯誤

最好解決辦法 親自用 docker pull image 下來 是最保險的

基本上需要的 docker image 有

  1. hyperledger/fabric-tools

  2. hyperledger/fabric-couchdb

  3. hyperledger/fabric-kafka

  4. hyperledger/fabric-zookeeper

  5. hyperledger/fabric-orderer

  6. hyperledger/fabric-peer

  7. hyperledger/fabric-javaenv

  8. hyperledger/fabric-ccenv

  9. hyperledger/fabric-ca

  10. hyperledger/farbic-baseos

    注意，這個 image 執行 network_setup.sh 會自動幫你下載

    這個版本會是對的 所以它幫你下載 是 ok 的

    執行不會出錯

此外以上的 image 必須 tag 設置為 latest

否則 network_setup.sh 會自動判斷如果沒有 tag 為 latest 的 image

它會幫你自動下載 就會出錯！

注意 image 之版本問題

  1. hyperledger/fabric-couchdb 沒有 x86_64-1.1.0 版本
  2. hyperledger/fabric-kafka 沒有 x86_64-1.1.0 版本
  3. hyperledger/fabric-zookeeper 沒有 x86_64-1.1.0 版本

以上這三個 image 不必跟著 fabric source code 的版本跟著跑

基本上抓 latest 就可以 執行不太會出錯 有相容

其他 image 要跟著 fabric source code 的版本 才不會執行出錯

執行其他版本該注意事項

  1. image 版本要跟著 fabric source code 版本
  2. 有些 image 抓 latest 即可
  3. 將上述的錯誤採坑解決方法走過一遍

就開心執行 ^^

最後最後！請聽我一言！

如果你還沒有註冊 Like Coin，你可以在文章最下方看到 Like 的按鈕，點下去後即可申請帳號，透過申請帳號後可以幫我的文章按下 Like，而 Like 最多可以點五次，而你不用付出任何一塊錢，就能給我寫這篇文章的最大的回饋！