.. role:: red :class: red .. role:: blue :class: blue .. role:: green :class: green .. raw:: html ======================== BAAS平台 ======================== .. note:: BAAS服务平台，是单位机构独立部署，用于管理本单位的证书、节点服务以及与区块链交互的可视化管理系统。本系统可通过可视化操作界面，实现会员单位的数字身份上链，CA、TLS-CA以及PEER节点的部署与管理，通道创建与加入，链码安装、升级、查询与执行等功能。 BAAS系统激活 ============== BAAS系统部署完成并成功启动，可通过浏览器输入BAAS服务系统所运行服务器的IP地址， 即可访问BAAS服务系统，首次访问需要完成系统的激活和管理员帐号密码的设置，如下图所示： .. image:: ./_static/images/baas_firstrun_01.png - \ **激活码**\ ：联盟管理系统授予会员单位使用BAAS服务系统的授权码； `如何获取激活码? `_ - \ **管理员帐号**\ ：填写本系统管理员登录帐号； - \ **管理员密码**\ ：填写本系统管理员登录密码； - \ **确认密码**\ ：再次填写系统管理员登录密码； 确认无误后，点击\ ``激活``\ 按钮，完成系统的激活。激活成功如下图所示: .. image:: ./_static/images/baas_firstrun_02.png .. _主机管理: 主机管理 ============== 主机管理，是对本单位CA、TLS-CA以及PEER节点服务所使用的服务器的管理。 .. important:: - 建议CA、TLS-CA使用一台主机服务器；每个PEER节点独立使用一台主机服务器。 - 所有添加的主机均需要完成服务器Docker、Docker-Compose的安装和联盟仓库的配置。具体操作详见：`环境配置 `_ 添加主机 ---------- .. image:: ./_static/images/baas_machine_01.png .. image:: ./_static/images/baas_machine_02.png ------ * \ **主机名称**\ ：填写主机名称，比如填写peer187，表示用于peer节点且该主机IP尾号为187，主机名称的目的是便于快速了解当前主机的用途； * \ **文件映射路径**\ ：用于存放联盟链节点服务的文件，使用绝对路径（以/开始的完整路径），当前路径必须存在，且当前主机登录用户对此目录有读写权限； * \ **IP**\ ：当前主机的IP地址，BAAS服务系统所在服务器要能与该IP通讯； * \ **SSH端口**\ ：一般为\ ``22``\ ，根据实际填写； * \ **CPU**\ ：当前服务器的CPU核数，比如：\ ``8核``\ * \ **内存**\ ：当前服务器的内存大小，比如：\ ``16G``\ * \ **登录方式**\ ：支持密码登录和证书登录，一般选择密码登录； * \ **用户名**\ ：登录当前主机的用户； * \ **密码**\ ：使用密码登录方式，则输入当前主机用户的登录密码； * \ **证书**\ ：使用证书登录，则上传对应的证书； 完成上述信息填写后，点击“提交”保存主机配置。 :blue:`提示：主机未被使用前，可以编辑或删除；主机被使用后，则禁止编辑、删除。` 数字身份 ============== 服务部署 -------------- 完成主机的添加后，开始配置\ ``CA``\ 、\ ``TLS-CA``\ 服务并启动。 操作：BAAS服务系统左侧菜单栏，点击“数字身份”栏目，如下图所示： .. image:: ./_static/images/baas_ca_01.png 一般\ ``CA``\ 端口填写\ ``7054``\ ，\ ``TLS-CA``\ 端口填写\ ``7055``\ ，并选择\ ``主机``\ （说明：选择主机是指当前服务部署在该主机上，具体见：:ref:`主机管理`），保存即可完成配置。 服务启动 -------------- 确认无误后，分别启动CA服务和TLS-CA服务。 .. image:: ./_static/images/baas_ca_02.png :blue:`提示：CA、TLS-CA服务启动后，不可编辑端口或更换主机。` 服务状态说明： - 运行中: 服务容器已运行，且正常提供服务； - 已停止: 服务容器已停止； - 异常: 服务容器已运行，且未正常提供服务； .. _提交数字身份: 提交数字身份 -------------- CA、TLS-CA服务启动成功后，自动激活“提交数字身份”按钮，点击此按钮并确认后，系统自动将本单位的数字身份提交到联盟管理系统。 .. image:: ./_static/images/baas_id_01.png 提交数字身份后，需要等待联盟管理员将本单位的数字身份上链，上链成功后，本单位正式成为安徽省教育联盟链会员。 .. image:: ./_static/images/baas_id_02.png .. _正式加入联盟: 正式加入联盟 -------------- 成为正式会员后，如下图所示： .. image:: ./_static/images/baas_id_03.png ``节点高校``\ 正式加入联盟后，可部署PEER节点，并可创建或加入通道，实现链码安装、升级，执行和查询等功能。 ``非节点高校``\ 暂时不能部署PEER节点，不能使用联盟链相关功能。 联盟链 ============== 节点 -------------- .. note:: 本章节主要实现单位内PEER节点的部署与启动。 新增节点 >>>>>>>>> 操作：BAAS服务系统左侧菜单“联盟链->节点->新增”，进入\ ``新增节点``\ 表单，如下图所示： .. image:: ./_static/images/baas_peer_01.png - 节点名称 节点名称由\ ``小写字母``\ 或\ ``小写字母与数字的组合``\ 且\ ``以字母开头``\ ，少于\ ``10``\ 个字符。建议填写\ ``peer+数字``\ ，如peer1，peer2，以此类推。 :red:`注意：节点名称一旦创建，不可修改。` - 节点端口 端口有效范围是 ``1-65535`` ，只要填写的端口未被使用均可使用。在Fabric示例中，一般第一个节点端口为\ ``7051``\ ，第二个节点端口为\ ``8051``\ ，第三个节点端口节点为\ ``9051``\ ，可参考此设置即可。 - 选择主机 是选择当前新增节点所部署的服务器。 确认无误后，点击\ ``提交``\ ，系统将检查数据合法性，并检查端口是否被占用。如果无误，则成功添加节点。 .. important:: - 建议生产环境中，每个PEER节点都单独使用一台服务器，尽量避免一台主机运行多个PEER节点。 - 请再次确定，当前选择的主机，是否已安装Docker、Docker-Compose以及联盟仓库的配置。未做过以上设置的主机无法运行PEER节点服务。 - 由于PEER节点要与其他组织（高校）的PEER节点通讯，请确保当前主机能访问教育网。 - 由于其他组织（高校）需要与本节点进行通讯，请确保当前主机中所设置的节点端口能被其他组织（高校）访问。 编辑节点 >>>>>>>>> 在节点未启动时，可以编辑节点信息，除节点名称不可编辑外，可编辑节点端口或者更换主机。 一旦节点启动，则禁止编辑节点信息。 删除节点 >>>>>>>>> 节点创建结束且未启动时，可以删除掉节点，重新添加。 一旦节点启动，则禁止删除节点。 启动节点 >>>>>>>>> 在将要启动节点的操作栏位，点击\ ``启动``\ 按钮并确认，等待节点启动完成。 停止节点 >>>>>>>>> 在将要停止节点的操作栏位，点击\ ``停止``\ 按钮并确认，等待节点停止完成。 通道 -------------- 通道的设立主要是为了应用数据的隔离，以在隐私上提供保护。通道可理解为帐本，通道中的所有成员共享帐本数据。 创建通道 >>>>>>>>> 成为联盟链正式会员，部署节点并启动后，可以创建通道。 操作：BAAS服务系统左侧菜单“联盟链->通道->新增”，进入\ ``新增通道``\ 表单，如下图所示： .. image:: ./_static/images/baas_channel_add_01.png - 通道名称 通道名称由\ ``小写字母``\ 或\ ``小写字母与数字的组合``\ 且\ ``以字母开头``\ ，少于\ ``50``\ 个字符。比如\ ``mychannel``\ ,\ ``channel1``\ ,首字符不能为数字，\ ``11channel``\ 则是错误的。 - 通道类型 通道类型目前支持\ ``公开``\ 和\ ``私密``\ 。\ ``公开``\ ：表示当前通道允许其他组织发现，并可申请加入；\ ``私密``\ ：表示当前通道只能自己使用，不显示在“申请加入通道”列表中，从而其他组织不能发现该通道。 所有非当前组织创建的公开类型的通道，都将在“申请加入通道”列表中，其他组织可申请加入。加入通道流程详见：:ref:`申请加入通道` - 通道策略 通道策略，目前仅支持\ ``大多数组织审批``\ 和\ ``任意组织审批``\ 。 - 大多数组织审批 该策略是指组织加入通道，需要通道内大多数组织(>50%)同意后才可加入。 - 任意组织审批 该策略是指组织加入通道，只需要通道内任一个组织同意后即可加入。 - 选择节点 创建通道时，至少需要选择一个PEER节点，用于从排序服务中获取通道上的区块来构建区块链账本。 对于未在创建通道时加入的PEER节点，如何加入通道，详见：:ref:`节点加入通道` .. _节点加入通道: 节点加入通道 >>>>>>>>>>>>>> PEER节点加入通道，用于从排序服务中获取通道上的区块来构建区块链账本。 操作：BAAS服务系统左侧菜单“联盟链->通道”，点击具体通道的\ ``节点加入通道``\ 按钮，如下图所示： .. image:: ./_static/images/baas_channel_peer_01.png 系统列出当前组织的所有节点，并显示是否已加入通道，对于未加入通道的节点，提供\ ``加入``\ 按钮，点击此按钮并确认后可将此节点加入通道。 :red:`注意：PEER节点加入通道后，不可退出。` 锚节点 >>>>>>>>> 组织的PEER加入通道后，他们应至少选择一个PEER成为锚定节点。为了利用诸如私有数据和服务发现之类的功能，需要PEER锚节点。每个组织都应在一个通道上设置多个锚节点以实现冗余。 .. important:: 本系统节点加入通道均自动设置为\ ``锚节点``\ .. _申请加入通道: 申请加入通道 >>>>>>>>>>>> 本组织可以申请加入其他组织创建的通道（通道类型需为\ ``公开``\ ）。 操作：BAAS服务系统左侧菜单“联盟链->通道->申请加入通道”，进入\ ``申请加入通道``\ 弹出层页面，如下图所示： .. image:: ./_static/images/baas_channel_add_02.png 根据通道加入策略（\ ``大部分组织审批``\ 和\ ``任意组织审批``\ ）的不同，加入通道的流程如下： - 任意组织审批 如果A组织创建的通道channel，类型为\ ``公开``\ ，加入策略为\ ``任意组织审批``\ ，当前组织可申请加入该通道，申请后，系统将审批消息发送给该通道内的所有组织，只要有通道内任意一个组织审批同意后，即可加入。 - 大部分组织审批 如果A组织创建的通道channel，类型为\ ``公开``\ ，加入策略为\ ``大部分组织审批``\ ，当前组织可申请加入该通道，申请后，系统将审批消息发送给该通道内的所有组织，需要由通道内大部分组织(>50%)审批同意后，才可加入。 申请加入通道审批 >>>>>>>>>>>>>>>>> 申请加入通道，系统将给通道内的其他组织发送消息，通知其他组织审批。 组织单位登录BAAS服务系统，在“联盟链->通道->待审批列表” 或 “消息”中对可查看需要本组织审批的申请加入通道的记录。如下图所示： .. image:: ./_static/images/baas_channel_approve_02.png 当前组织可点击\ ``审批``\ 按钮，或通过右上角\ ``消息``\ 中的快捷方式，直接进入审批页面，如下图所示： .. image:: ./_static/images/baas_channel_approve_01.png 满足通道策略，系统将申请的组织加入通道，并给申请的组织发送已成功加入通道的消息。 .. important:: 新组织加入通道后，需要自行将PEER节点加入该通道，具体详见：:ref:`节点加入通道` 通道详情 >>>>>>>>> 通道详情包括通道的基本信息、通道中的组织、节点、智能合约以及当前通道的区块和交易数据。 - 通道基本信息 包括通道名称、类型（\ ``公开``\ 与 \ ``私密``\ ）、通道策略（\ ``大多数组织审批``\ 与\ ``任意组织审批``\ ）、状态和创建时间等。 - 组织 当前通道中的所有组织。 - 节点 当前组织所有节点，并可查看是否已加入当前通道。 - 智能合约 当前组织关联该通道的智能合约列表，包括合约名称、label标签、合约版本、创建时间和状态。 - 区块 当前通道的所有区块数据。 - 交易 当前通道的所有交易数据。 智能合约 -------------- 引用：链码一般处理网络中的成员一致同意的商业逻辑，所以它类似于“智能合约”。链码可以在提案交易中被调用用来升级或者查询账本。 本文档混合采用\ ``智能合约``\ 、\ ``合约``\ 或\ ``链码``\ ，他们表示意思相同。 本系统中关于智能合约的功能，主要包括安装链码、升级链码、执行(invoke)链码和查询(query)链码以及查看链码的交易记录。 安装链码 >>>>>>>>> 安装链码的步骤如下： - 第1步: 链码打包 - 第2步: 创建合约 - 第3步: 安装 - 第4步: 投票 - 第5步: 启动链码 .. _链码打包: 链码打包 ::::::::: 本系统不支持链码在线打包功能。 自行打包命令如下： .. code-block:: shell peer lifecycle chaincode package fabcar.tar.gz --path a/b/c/ --lang golang --label fabcar_2 - ``fabcar.tar.gz`` : 为打包合约文件名 - ``--path`` : 智能合约路径 - ``--lang`` : 智能合约语言，支持golang、java、node - ``--label`` : 智能合约标签，起描述作用。在创建合约的表单中需要填写此参数 执行成功后，当前目录下将生成文件fabcar.tar.gz。 详细打包说明：`Package the smart contract `_ 创建合约 ::::::::: 在本系统中，有两处场景创建合约，分别是，组织\ ``手动创建合约``\ 和\ ``邀请创建合约``\ (接受其他组织安装合约的邀请)，其本质一样，只是流程略有不同。 \ ``手动创建合约``\ ，是指组织在创建合约表单，填写相关信息后创建；而\ ``邀请创建合约``\ ，是指组织\ ``手动创建合约``\ 并且成功安装后，系统将向链码所在通道的其他组织发出链码安装邀请，其他组织只需关联其节点后，即可创建合约。 创建合约后，即可在合约列表中显示，进而可以进行\ ``安装``\ 、\ ``投票``\ 和\ ``运行``\ 等阶段，完成链码的安装过程。 .. _手动创建合约: 手动创建合约 ''''''''''''' 操作：BAAS服务系统左侧菜单“联盟链->智能合约->创建合约”，进入\ ``创建合约``\ 表单，如下图所示： .. image:: ./_static/images/baas_cc_add_01.png 表单字段说明如下： - 智能合约名称 智能合约名称由\ ``小写字母``\ 或\ ``小写字母与数字的组合``\ 且\ ``以字母开头``\ ，少于\ ``50``\ 个字符。 - 版本号 版本号不超过\ ``10``\ 个字符。 版本号只是用于记录当前链码版本的说明用途，没有递增的强制要求，比如第一个版本为v1.0，第二个版本可以填写v0.1（这是极端情况，只是对该字段用途说明） - 关联通道 链码安装所在的通道。 - 投票准入率 当通道成员为它们的组织批准一个链码定义时，链码级别的策略被它们（通道成员）同意。 足够数量的通道成员需要批准链码定义来满 足 Channel/Application/LifecycleEndorsement 策略，在定义能够被提交到通道之前，默认设置为大多数通道成员批准定义， 一旦定义被提交，链码就可以使用。 - 背书策略 是指确定一笔交易需要的背书策略，任何把数据写进账本的链码调用需要被足够多的通道成员验证以此来满足背书策略。 目前本系统仅只支持单一的\ ``AND``\ 和\ ``OR``\ 的关系，即所有组织都要背书，或者所有组织中任意组织背书。暂不支持\ ``AND``\ 与\ ``OR``\ 并用的情况。 为了确保背书组织能够正常给交易背书，本系统要求所有的背书组织都必须投票（approve），即使已经满足了\ ``大于50%``\ 的策略要求。 比如，现在有5个组织,A、B、C、D、E，背书策略是A或（\ ``OR``\ ）B。安装链码时需要大多数组织同意，A和D、E已经投票，此时已 经满足了大部分组织同意，但仍需要组织B进行投票，以确保组织B可以为交易进行背书。 - 标签 打包链码时设置的智能合约标签，起描述作用。对于已经打包的链码，可查看metadata.json文件中的\ ``label``\ 字段。 - 上传智能合约文件 将智能合约打包成tar.gz格式文件。具体详见：:ref:`链码打包` - 关联节点 选择链码安装的节点，可以是一个或多个。 如果选择一个节点，表示链码安装到此节点上。系统支持在链码安装后，可以继续安装到其他节点，具体详见：:ref:`关联` .. _邀请创建合约: 邀请创建合约 ''''''''''''''' 被邀请的组织，可通过系统消息，进入合约创建表单页面，如下： .. image:: ./_static/images/baas_cc_install_01.png 选择节点，点击\ ``提交``\ ，并自动进入链码列表页。 .. important:: 节点必须加入当前链码所在通道，才能在节点列表中显示。 安装 ::::::::: ``创建合约``\ 或者\ ``邀请安装链码提交后``\ ，即可在合约列表中查看该合约，如下图所示： .. image:: ./_static/images/baas_cc_list_01.png 上图中\ ``安装(0/1)``\ 括号中的数字，第1个数字表示已经安装的Peer节点，当前值为0，表示没有PEER节点安装该链码；后一个数字表示关联的节点数量，当前值为1，表示有一个PEER节点关联了该链码，点击\ ``安装``\ ，则链码将安装到此节点上。如果这里数字为2，表示有两个节点关联了该链码，点击\ ``安装``\ ，则链码安装到2个关联的PEER节点上，以此类推。 本示例中，由于在“创建合约”时，仅关联了一个节点，所以这里总的关联节点是1。对于链码已经安装到节点后，如何针对新的节点安装链码？详见：:ref:`关联` .. important:: 如果链码已经启动，对于新安装的节点，在“关联”和“安装”后即可自动启动。无需再次“投票”和“启动”操作。 新节点的链码安装后，到启动完成，根据服务器当时的资源及性能情况，中间可能需要一点时间，一般在几秒至10几秒左右，请等待即可。 链码邀请 ::::::::: :ref:`手动创建合约`\ 被安装后，系统自动通知通道内的其他所有组织，邀请他们安装链码。 对于邀请发出后，如果有\ ``新组织``\ 加入通道后需要安装链码，可由之前安装过链码的组织，在\ ``链码详情页面``\ ，针对新组织发出链码安装\ ``邀请``\ 。 其他组织可登录BAAS服务系统，在\ ``消息``\ 中可查看邀请安装链码信息，具体安装详见：:ref:`邀请创建合约`。 .. _关联: 关联 ::::::::: 关联是指未安装链码的节点安装链码。 在智能合约列表中，点击\ ``关联``\ 链接，将弹出窗口，如下图所示： .. image:: ./_static/images/baas_cc_peer_01.png - 确保新的节点已加入该链码所在通道。具体详见：:ref:`节点加入通道`，也可以在当前页面点击\ ``加入``\ 按钮加入通道。 - 关联后，关闭弹出层窗口，在链码列表的操作栏，可以看到\ ``安装``\ 按钮被激活，点击\ ``安装``\ 即可。 解关联 ::::::::: 解关联，是指已经安装链码的节点移除该链码。 在智能合约列表中，点击“关联”，将弹出窗口，如下图所示： .. image:: ./_static/images/baas_cc_peer_01.png 对已经关联的节点，可进行\ ``解除关联``\ 操作。 投票 ::::::::: 组织链码安装成功后，即可投票。投票成功后，\ ``启动``\ 按钮被激活。 .. important:: 只要有一个节点安装了链码（并不要求必须所有节点都安装链码），就能投票。 安装链码，需要链码所在通道内的组织一半以上同意（投票）。 启动 ::::::::: 链码投票率满足策略，即通道成员大部分同意后，即可启动链码。 投票率是指当前链码所在通道的所有已投票组织与所有组织的比值。 升级链码 >>>>>>>>> 对于已经安装并启动的链码，如果需要升级，请使用\ ``升级``\ 链码功能。升级链码的名称必须与之前链码名称相同、版本必须不同。 同时在升级链码的表单中选择背书策略、填写标签和上传链码包，然后点击\ ``提交``\ 。如下图所示： .. image:: ./_static/images/baas_cc_upgrade_01.png 提交后，回到链码的操作列表，同安装链码流程，需要安装、投票和启动等环节，完成链码的升级。 链码的执行与查询 >>>>>>>>>>>>>>>> 链码的执行(invoke)与查询(query)，可通过链码列表中的操作按钮：\ ``调用``\ 进入。如下图所示： .. image:: ./_static/images/baas_cc_invoke_01.png - 函数名 链码中提供的函数名称 - 合约参数 链码中函数的参数。多个参数与半角逗号分隔，例如：a,b,c - 证书 用户的证书，详见：:ref:`拉取证书` - 证书私钥 用户的证书私钥，详见：:ref:`拉取证书` - 操作 - 查询 即类似于CLI中执行的 ``peer chaincode query`` 命令； - 上链 即类似于CLI中执行的 ``peer chaincode invoke`` 命令。 链码交易 >>>>>>>>> 查看当前链码的交易记录。 区块 -------------- 本组织所加入通道的所有区块数据。每个区块数据包括区块编码、所属通道、交易数量、数据哈希、区块哈希、上一个区块哈希、交易ID以及区块大小。 支持以通道、区块哈希或交易哈希检索区块数据。 交易 -------------- 是本组织所有产生的交易记录。每笔交易记录数据包括交易ID、所属通道、执行链码、链码版本、创建者和交易时间。 支持以通道、链码及交易ID检索交易数据。 操作日志 ============== 记录并查看系统中所有用户的操作记录。包括操作人、操作说明、操作IP和操作时间等。 管理员角权可查看所有用户的操作记录；其他角色用户只能查看自己的操作记录。 帐号与证书 ============== 用户通过右上角菜单（如下图所示），可修改用户的登录密码、拉取用户自己的证书和私钥，以及服务端备份私钥等功能。 .. image:: ./_static/images/baas_000.png .. _拉取证书: 拉取证书 -------------- 用户执行链码时需要提供\ ``证书``\ 和\ ``私钥``\ 。 系统只允许用户拉取一次，用户拉取后需要自行保存证书和私钥，系统不会保存用户私钥信息。 用户可以通过“备份私钥”功能，完成私钥备份。备份后，用户可随时通过“加密密码”来拉取用户的证书和私钥（具体功能详见：:ref:`备份私钥`）。 用户\ ``首次``\ 拉取证书和私钥，需要提供当前帐号的“登录密码”进行验证。验证成功后，系统将向CA注册(register)并拉取(enroll)证书和私钥，并提供下载，如下图所示： .. image:: ./_static/images/baas_cert_02.png 用户备份后，需要填写备份时的加密密码，才能再次拉取。 .. _备份私钥: 备份私钥 -------------- 前提：用户需要先拉取“证书”和“私钥”后才能备份私钥。 .. note:: 私钥备份，是系统通过用户输入的“加密密码”与“私钥”进行对称加密，并将加密结果存储在服务器。没有密码，任何人均无法得到用户的证书和私钥。 .. image:: ./_static/images/baas_cert_03.png 私钥备份后，用户可随时通过“加密密码”来获取用户的证书和私钥。 修改密码 -------------- 用户修改当前帐号密码。修改密码需要输入原密码，新密码和密码确认。 系统管理 ============== 用户管理 -------------- 系统支持多用户。管理员可以先添加“用户”角色，并为学生创建帐号，分配“用户”角色，这样学生可以依据其所分配的权限使用BAAS服务系统，比如安装、升级链码，查询与执行链码等操作。 - 新增用户 点击\ ``新增``\ 按钮，添加新的用户，如下图所示： .. image:: ./_static/images/baas_user_001.png - 修改用户 针对具体用户，点击\ ``编辑``\ 按钮，编辑当前用户信息。 除用户帐号不可修改外，其他信息均可修改，包括用户登录密码、用户角色、帐户状态以及用户的姓名、电话和邮箱等信息。 角色管理 -------------- 管理员可添加角色，系统默认仅有管理员角色，管理员角色拥有系统的所有权限。系统管理员可添加新角色，并给该角色赋予相应的权限。这样在添加用户时，可以赋予用户角色，使用户在角色限定的权限内操作。 .. image:: ./_static/images/baas_role_001.png - 添加角色名称 设定角色的名称，比如“用户”。角色的名字和描述均可自定义。 - 菜单分配 允许当前角色访问的菜单。 - 权限分配 允许当前用户操作的权限。 :red:`注意：已被使用的角色不可被删除。` 登录日志 -------------- 可查看系统中所有用户的登录日志记录。