← COMP5565 全部讲次
Lab2a · 第 9 周

Lab2a 把 Fabric 网络跑起来:注册身份、调链码、升级链码

Lab 2 前半:交易九步怎么落到命令上,给注册脚本补上 Manager 角色,看懂创建和查询两个链码函数,再按生命周期把改过的链码升级上去。

一句话版

Lab 2 在虚拟机里跑一个电脑仓库的防伪系统:Creator 录入产品,Manager 逐级签字,Admin 查询。前半段做三件事:给注册脚本补上 Manager 角色,用命令行调创建和查询两个链码函数,再改一行代码把链码升级上去。网页前端和区块浏览器在 Lab2b,Fabric 的理论从 L06a 看起,交易流程在 L06c。

先认识这几个词

词 全称 / 读法 一句人话
chaincode 链码 Fabric 对智能合约的叫法,本 Lab 用 Go 写
peer 节点 存账本、跑链码的机器
orderer 排序节点 只给交易排顺序、打包成块,不看交易内容
CA Certificate Authority,证书颁发机构 给用户签发数字证书的那一方
钱包 wallet 存用户证书和私钥的地方,不存钱
世界状态 world state 账本里「每个键现在是什么值」的那张表,本 Lab 存在 CouchDB
背书 endorsement 指定的 peer 先把交易试跑一遍,对结果签名担保
读写集 read-write set 试跑时记下的「读了哪些键、要写哪些键」

题目地图

Task 在考什么 主要失分点
环境搭建 启动网络、注册 Admin 和 Creator 重启虚拟机后忘了重跑启动脚本
1 注册 Manager 证书属性怎样承载权限 漏写 ecert: true;把签字上限理解错
2 创建与查询 写交易和只读查询的区别 不知道产品的键从哪来
3 升级链码 链码生命周期四步 搜不到要改的那行;sequence 没加 1

前四页是背景,把 Lecture 6 的组件和交易流程压缩复述了一遍。这一页先把背景讲清,再逐题做。

概念卡

1. 一笔交易的九步:先执行、再排序、后验证

人话定义:它回答「我点一下创建,背后发生了什么」。Fabric 让背书者先在自己那份账上试算并签名,排序服务只管排队,每个 peer 最后再核对一遍。

例子:下图的 R 是领证书。① 应用把提案发给背书者,② 背书者试算出读写集并签名,③ 结果返回应用。④ 应用交给排序服务,⑤ 排序服务排好打包,⑥ 广播给各 peer。⑦ peer 逐笔核对读写集,⑧ 有效的写进账本,⑨ 通知应用结果。

课件里的 Fabric 交易生命周期图:左上 MSP 与右上 Client & Application 之间标 R;中间 Fabric SDK 与右侧蓝色 Endorser 之间标 1、3,Endorser 自环标 2;SDK 向下标 4 到红色 Orderer,Orderer 自环标 5,再标 6 指向左侧绿色 Committer;Committer 自环标 7,向下标 8 到 Ledger,向上标 9 回到 SDK
图片来源:COMP5565 Lab 2 DApp Development in Hyperledger Fabric, p.4
常见误解

以为验证失败的交易会被丢掉 → 第 8 步说得很清楚:它照样留在区块里,只是写集不生效。区块记录「发生过什么」,世界状态记录「现在是什么」。

试一下:排序服务在第 5 步会不会检查「这个用户有没有权限建产品」?

答案

不会。排序服务不看交易内容。权限检查发生在第 2 步,背书者试算链码时就查了,查不过拿不到背书。

回讲义:L06c Fabric(三):一笔交易的五步,先试算再排队

2. 钱包与证书属性:权限写在证书里

人话定义:它解决「链码怎么知道你是谁、能做什么」。注册时 CA 给你签一张 X.509 证书(数字证书的通用格式),权限作为属性写进证书。证书和私钥一起存在钱包里,发交易时用它签名。

例子:Creator 的证书带 canCreate = true,Manager 的证书带 canSignProduct = 3。所有人还带一个 username。链码执行时读这些属性:建产品先查 canCreate,签字先查 canSignProduct。本 Lab 的钱包是 File system 类型,就是本地一个 wallet 文件夹。

常见误解

以为钱包里存着币 → Fabric 没有原生币,钱包只存身份。课件列了四种钱包:CouchDB、In-memory、File system、HSM。

试一下:admin 去调建产品的函数,会成功吗?

答案

不会。admin 的证书里没有 canCreate 属性,链码返回 User does not have right to perform this action.。

回讲义:L07a-3 MSP:网络凭什么认你、把你当成什么角色

3. 写交易和只读查询

人话定义:它区分「要不要排队」。写操作(put / delete)要变成交易,走完九步才生效;读操作(get)直接查世界状态,不产生交易。

例子:invoke.js 调 createProduct,是写交易,要等背书、排序、提交。query.js 调 QueryAllProducts,是只读查询,立刻返回,账本上不留记录。

常见误解

以为查询也会上链 → 查询只读世界状态,做多少次区块数都不变。

试一下:新产品的键是谁定的?

答案

链码自己定。账本里有个叫 MaxProductId 的计数器,初始化时设为 2(测试产品占了键 1)。每建一个产品就用当前计数当键,再把计数加 1。

回讲义:L07b-1 Chaincode:用 Go 写合约,Submit 和 Evaluate 怎么选

4. 链码生命周期:装上去,再大家同意

人话定义:它回答「改了链码怎么让网络用上新版」。Fabric 2.x 部署链码分四步:Package 打包、Install 安装到 peer、Approve 各组织批准、Commit 提交到 channel(通道,一组组织共用的一本账)。前两步是装代码,后两步是各组织同意用它。

例子:本 Lab 把四步包进了 deployCC.sh,两个参数是 version 和 sequence。网络启动时装的是第 1 版,第一次升级跑 ./deployCC.sh 2 2,下一次是 ./deployCC.sh 3 3。

常见误解

以为升级链码会清空数据 → 升级只换处理逻辑,世界状态原封不动。

试一下:version 和 sequence,哪个是 Fabric 硬性要求每次加 1 的?

答案

sequence。它是链码定义被提交的次数,必须逐次加 1。version 只是标签,可以是任意字符串,本 Lab 让它同步加 1 是为了好记。

回讲义:L07b-1 Chaincode:用 Go 写合约,Submit 和 Evaluate 怎么选

逐题拆解

环境搭建。 操作步骤:

  1. 在 VirtualBox 里启动 “COMP5565 Lab 2” 镜像,等 Ubuntu 自动登录。
  2. 进入 ~/Training/fabric-samples/fabcomp,打开终端,运行 ./startFabric.sh。
  3. 看到 Setup is now complete. 就成功了。脚本拉起各容器、生成证书、装好链码 mycc,并写入一个测试产品。
  4. cd javascript,运行 node enrollAdmin.js 注册 Admin。
  5. 运行 node registerUser.js creator1 creator 注册 Creator。

每次重启虚拟机都要重跑 startFabric.sh。这一步对应交易九步里的 R:向 CA 领证书,存进钱包。

Task 1:给注册脚本补上 Manager

要改的是 javascript/registerUser.js。脚本里有一个按角色分支的 switch,creator 分支给证书加 canCreate。照它的样子加一个 manager 分支:

case 'manager':
    let stage = 0;
    if (args.length < 3) {
        stage = '3';          // 没给第三个参数时默认 3
    } else {
        stage = args[2];
    }
    attrs.push({name: 'canSignProduct', value: stage, ecert: true});
    attr_reqs.push({name: 'canSignProduct', optional: true});
    break;

这段答案依据的是公开流传的同源代码,没在课程虚拟机里跑过,但在等价环境(Fabric 2.5 官方测试网络加同源脚本)里实测通过。改好后运行 node registerUser.js manager1 manager 3,看到 Successfully registered and enrolled user manager1 就成功了;同源脚本打印的用户名带引号,课件截图里没有,两种都算成功。同一个名字再注册一次,会提示该身份已在钱包里。

关键是 ecert: true。领证书时没指定要哪些属性,CA 就默认写入标了 ecert 的属性,不标的话链码读不到。attr_reqs 本意是声明要带哪些属性,但脚本领证书时没把它传进去。

最后那个 3 是这位 Manager 的签字上限。产品新建时阶段为 0,每签一次加 1。上限为 3 的 Manager 能签当前阶段 0、1、2 的产品,签完把阶段推到 1、2、3。

一步一步看

目标:让 manager1 把 Macbook Pro 连签三次,再换一个低上限的 Manager,看出签字成不成只看上限是否大于当前阶段。

manager1 的上限是 3,拿 Task 2 新建的 Macbook Pro(最大阶段 3)连签三次,再看一次上限不够的情况。

  1. 产品在阶段 0。3 > 0 成立,签成,阶段变 1。签字记录里写的是签前的阶段 0。

    签字判断表第 1 行:manager1 上限 3,签前阶段 0,3 大于 0 成立,签成后阶段变 1,判断一格被标出

  2. 阶段 1。3 > 1 成立,签成,阶段变 2。

    签字判断表第 2 行:manager1 签前阶段 1,3 大于 1 成立,签成后阶段变 2,判断一格被标出

  3. 阶段 2。3 > 2 成立,签成,阶段变 3,等于最大阶段,产品签满。

    签字判断表第 3 行:manager1 签前阶段 2,3 大于 2 成立,签成后阶段变 3 即签满,判断一格被标出

  4. 换一个上限 1 的 Manager 去签停在阶段 1 的产品。1 > 1 不成立,背书时就报 User does not have rights to sign.。

    签字判断表第 4 行:上限 1 的 Manager 签阶段 1 的产品,1 大于 1 不成立,报错没有签字权限,判断一格被标出

Task 2:创建与查询

两个函数在 chaincode/computer/go/mycc.go。在 fabcomp/javascript/ 下运行:

node invoke.js creator1 createProduct "Macbook Pro" "Laptop" 3
node query.js admin QueryAllProducts

题目问看到了什么。输出是一个 JSON 数组,每个元素是 {"Key": 键, "Record": 产品内容}。现在有两条:

  • 键 "1":Test Product,创建者 admin,阶段 0,最大阶段 3;
  • 键 "2":Macbook Pro,描述 Laptop,创建者 creator1,阶段 0,签名为空,未完成。

JSON 里的字段名是小写的 name、description。阶段字段在 JSON 里叫 status,所以网页上显示 Status。

QueryAllProducts 按键的范围取数据,范围是字符串 "0" 到 "999999999"。计数器的键以字母 M 开头,排在范围外,所以不会混进结果。

一步一步看

目标:跟着世界状态里的键从初始化走到新建再到查询,看出新产品的键来自计数器,计数器本身为什么查不出来。

跟着世界状态里的键走一遍,就知道 Macbook Pro 为什么拿到键 "2"。

  1. startFabric.sh 跑完,initLedger 写了两个键:测试产品占 "1",计数器 MaxProductId 设成 2。

    世界状态表第 1 帧:键 1 是 Test Product,计数器 MaxProductId 值为 2,计数器的值一格被标出

  2. creator1 新建 Macbook Pro。链码拿当前计数 2 当新键,再把计数器加到 3。这笔交易写了两个键。

    世界状态表第 2 帧:新增键 2 存 Macbook Pro,计数器从 2 变成 3,新键 2 一格被标出

  3. admin 查询。范围 "0" 到 "999999999" 取回键 "1" 和 "2",MaxProductId 按字典序排在后面,不返回。

    世界状态表第 3 帧:查询按键范围取,键 1 和键 2 在范围内被返回,MaxProductId 在范围外不返回,这一格被标出

Task 3:改一行,升级链码

在 QueryAllProducts 的 return results, nil 之前加四行:

product := new(Product)
product.Signatures = []Signature{}
queryResult := QueryResult{Key: "testing", Record: product}
results = append(results, queryResult)

然后在 chaincode/computer/go 下运行 go build 确认能编译。再到上一级目录运行 ./deployCC.sh 2 2,看到 Chaincode initialization is not required. 即可。

回到 fabcomp/javascript/ 再查一次。题目问看到了什么:数组末尾多了一条,键是 "testing",内容各字段都是空值。前两个产品不变。

这说明两件事。新代码已经生效,peer 跑的是改过的链码。账本没被动过,“testing” 是每次查询时临时拼出来的,世界状态里没有这个键。

课件里的坑

  • [课件有误] p.4 第一句说步骤「depicted in Fig. 4」,实际是同页下方的 Fig. 3;Fig. 4 是下一页的实验环境图(p.4)。
  • [课件有误] p.10 让你把四行加在 return result, nil 之前,函数里的变量是 results,这一行是 return results, nil。照课件搜 return result, 会搜不到(p.10)。
  • [适用条件] p.8 说上限为 3 的 Manager 能在「≤ 3 的任何阶段」批准。按同源代码,当前阶段要小于 3 才能签,「≤ 3」指的是签完后到达的阶段(p.8)。
  • [读图提醒] p.9 说产品有 Stage 属性,存进 JSON 时字段名是 status,网页上显示 Status,三者是同一个东西(p.9)。
  • [读图提醒] p.2 说链码也用于给交易排序,这和 Lecture 6 的分工对不上。排序是 orderer 的事,考试按 Lecture 6 答(p.2)。
  • [补充核验] p.11 说 version 和 sequence 每次都要加 1。Fabric 硬性要求的只有 sequence,version 是标签(p.11)。

课后 10 分钟:考点复习

这 10 分钟怎么用:合上页面,先默写交易九步里每一步是谁做的、Manager 分支那几行代码;再把下面的完整例题从头推一遍,每一步的输出先自己写出来;最后回查两个最容易错的地方:签字上限按「签完后的阶段」算、升级时 sequence 要加 1。

必背

  1. Fabric 走 execute-order-validate:背书者先模拟执行并签名,排序服务只定顺序、不看交易内容,提交 peer 最后验证
  2. 验证失败的交易仍留在区块里,但它的写集不生效,世界状态不更新
  3. 钱包装的是身份(X.509 证书加私钥),不装钱;本 Lab 用 File system 钱包
  4. 用户权限写在证书属性里:Creator 带 canCreate,Manager 带 canSignProduct;属性设 ecert: true 才会写进证书,链码执行时读它判断权限
  5. 链码生命周期四步:Package、Install、Approve、Commit;升级时 sequence 必须加 1,本 Lab 让 version 同步加 1
  6. 升级链码只换处理逻辑,不动账本数据;Task 3 多出的 testing 是查询时临时拼出来的,账本里没有这个键

完整例题

网络刚启动完,测试产品已写入,Admin、creator1 已注册。接着依次做:(1)creator1 创建 “Macbook Pro” “Laptop” 3;(2)creator1 创建 “iPad Pro” “Tablet” 2;(3)admin 也去创建 “Mouse” “Wireless” 1;(4)按 Task 3 改代码并运行 ./deployCC.sh 2 2;(5)admin 运行 QueryAllProducts。问:第 3 步结果如何?第 5 步返回几条、各自的键是什么?此时计数器是几?下一次升级该用什么命令?

  1. 第 1 步:creator1 证书带 canCreate,通过检查。计数器当前是 2,新产品键为 "2",计数器变成 3。
  2. 第 2 步:同理,iPad Pro 的键为 "3",计数器变成 4。
  3. 第 3 步:admin 证书没有 canCreate,背书者试算时就返回 User does not have right to perform this action.。交易拿不到背书,不会上链,计数器仍是 4。
  4. 第 4 步:链码换成新版,世界状态不变。
  5. 第 5 步返回 4 条:键 "1" 测试产品、"2" Macbook Pro、"3" iPad Pro,最后是临时拼出来的 "testing"。计数器是 4,它不在查询范围里。
  6. 下一次升级:./deployCC.sh 3 3。

变式题

(一)用 node registerUser.js manager2 manager 1 注册 manager2。它去签当前阶段为 0 的产品、阶段为 1 的产品,结果各是什么?(二)产品一路建到键 "12",QueryAllProducts 返回的前四条键依次是什么?(三)第二次升级时手误写成 ./deployCC.sh 3 2,会怎样?

提示

(一)签字检查的条件是「上限小于等于当前阶段就拒绝」。(二)范围查询比较的是字符串,不是数字。(三)sequence 2 已经提交过一次了,Fabric 允许用同一个 sequence 换一份不同的定义吗?

参考答案与自检(非官方评分标准)

自检要点:① 用「上限 ≤ 当前阶段就拒绝」推出两个结果;② 说出字典序;③ 说出 sequence 必须加 1,旧链码继续生效。

(一) 阶段 0:上限 1 大于 0,签字成功,阶段变成 1。阶段 1:上限 1 不大于 1,返回 User does not have rights to sign.。上限为 1 的 Manager 只能完成第一级签字。

(二) "1"、"10"、"11"、"12"。字符串逐位比较,"10" 排在 "2" 前面。键 "2" 要排到这四条后面。

(三) sequence 2 已经提交过,Fabric 不允许用同一个 sequence 提交不同的定义,批准那一步就会报错。peer 继续跑第 2 版链码,改动没生效。改成 ./deployCC.sh 3 3 重跑即可。

闪卡自测

交易九步里,读写集是哪一步生成的?谁生成的?第 2 步,背书者模拟执行提案时生成,并签名。
验证失败的交易在区块里吗?世界状态变不变?在区块里;世界状态不变,它的写集不生效。
Task 1 去掉 ecert: true 会怎样?属性不进证书,链码读不到 canSignProduct,这位 Manager 签字时会被当成没有签字权限。
不带第三个参数注册 Manager,签字上限是几?按同源代码默认是 3。
Task 3 之后的 "testing" 存在世界状态里吗?不存在。它是查询函数每次临时追加的,账本里没有这个键。
Task 2 新建的 Macbook Pro 为什么键是 2?计数器 MaxProductId 初始化时设为 2,测试产品已占用键 1。
链码生命周期四步是什么?Package、Install、Approve、Commit。前两步装代码,后两步各组织同意并提交定义。

下一步

先把完整例题在虚拟机里原样跑一遍,四条查询结果和计数器的推算都对上了再往下走。然后试一次变式题(一):注册一个上限为 1 的 Manager,留着在 Lab2b 的网页上签字时验证报错。Lab2b 接着讲网页前端的签字、新建、筛选、搜索,以及在区块浏览器里看交易落进哪个区块。

下一讲 →
Lab2b Lab2b 在网页上签字、筛选、搜索,再到区块浏览器里找那笔交易

个人整理的学习笔记,不是官方材料;数字与结论以课件和讲师为准。