Skip to content

Commit

Permalink
Merge pull request #11 from yg3630536/feature/doc-for-build-tool
Browse files Browse the repository at this point in the history 
* add doc for build by web and Optimize related installation documents
  • Loading branch information
@junqizhang-dev
junqizhang-dev committed Apr 24, 2020
2 parents 92c5c5a + 37ac96c commit ef2bdbb
Show file tree
Hide file tree
Showing 6 changed files with 136 additions and 67 deletions.
34 changes: 18 additions & 16 deletions readthedocs/zh_CN/docs/weidentity-build-with-deploy.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ WeIdentity JAVA SDK 安装部署工具（部署智能合约）

1.2 配置基本信息
'''''''''''''''''''''''''''''
weid-java-sdk 可以同时支持 FISCO BCOS 1.3 版本和 FISCO BCOS 2.0 版本。
最新版本的build-tool工具仅支持 FISCO BCOS 2.0 版本。


1.2.1 基本配置
Expand All @@ -50,7 +50,7 @@ weid-java-sdk 可以同时支持 FISCO BCOS 1.3 版本和 FISCO BCOS 2.0 版本
- 配置区块链节点信息，填入区块链节点 IP 和 Channel端口，示例如下：

.. note::
区块链节点的Channel端口说明见\ `FISCO BCOS 2.0配置文件说明 <https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/manual/configuration.html#rpc>`__\ 或 `FISCO BCOS 1.3 配置文件说明 <https://fisco-bcos-documentation.readthedocs.io/zh_CN/release-1.3/docs/web3sdk/config_web3sdk.html#java>`__\ 。
区块链节点的Channel端口说明见\ `FISCO BCOS 2.0配置文件说明 <https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/manual/configuration.html#rpc>`__\ 。

.. code:: shell
Expand All @@ -62,14 +62,6 @@ weid-java-sdk 可以同时支持 FISCO BCOS 1.3 版本和 FISCO BCOS 2.0 版本
blockchain_address=10.10.10.10:20200,10.10.10.11:20200
- 配置 FISCO BCOS 版本信息，如果您使用 FISCO BCOS 2.0 版本则配置为2，FISCO BCOS 1.3 则配置为 1：

.. code:: shell
blockchain_fiscobcos_version=2
- 配置机构名称，该名称也被用作后续机构间的 \ `AMOP <https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/manual/amop_protocol.html>`__ 通信标识。假设您的机构名为 test，您可以配置为：

.. code:: shell
Expand All @@ -82,6 +74,15 @@ weid-java-sdk 可以同时支持 FISCO BCOS 1.3 版本和 FISCO BCOS 2.0 版本
chain_id=1
- 配置数据库相关，该配置用于SDK存储相关数据使用：

.. code:: shell
mysql_address=0.0.0.0:3306
mysql_database=database
mysql_username=username
mysql_password=password
保存退出，即完成基本配置。

.. note::
Expand All @@ -97,9 +98,6 @@ weid-java-sdk 可以同时支持 FISCO BCOS 1.3 版本和 FISCO BCOS 2.0 版本

FISCO BCOS 2.0请参考\ `2.0 web3sdk客户端配置 <https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/sdk/sdk.html#sdk>`__\，将证书文件 ``ca.crt``， ``node.crt`` 和 ``node.key`` 复制出来，拷贝至当前目录下。

FISCO BCOS 1.3请参考\ `1.3 web3sdk客户端配置 <https://fisco-bcos-documentation.readthedocs.io/zh_CN/release-1.3/docs/tools/web3sdk.html>`__\，将证书文件 ``ca.crt`` 和 ``client.keystore`` 复制出来，拷贝至当前目录下 。


1.3 部署智能合约并自动生成配置文件
'''''''''''''''''''''''''''''''''''

Expand Down Expand Up @@ -147,7 +145,7 @@ FISCO BCOS 1.3请参考\ `1.3 web3sdk客户端配置 <https://fisco-bcos-documen
.. note::
| 发布 WeIdentity 智能合约的机构将会自动注册为委员会机构成员（ Committee Member ）。
| 发布 WeIdentity 智能合约会同时会在 ``weid-build-tools/output/admin`` 目录下动态生成私钥文件 ``ecdsa_key``，以及对应的公钥文件 ``ecdsa_key.pub``，此私钥后续用于注册权威机构，您可以将其保存到您的其他存储库里。
| 在根目录下会生成一个hash文件，此文件用于给其他不部署合约的机构使用。
至此，您已经完成 weid-java-sdk 的安装部署，您可以开始您的 Java 应用集成以及便捷工具体验。

Expand All @@ -160,11 +158,15 @@ FISCO BCOS 1.3请参考\ `1.3 web3sdk客户端配置 <https://fisco-bcos-documen
2.1 在自己的 Java 应用中引入 weid-java-sdk
'''''''''''''''''''''''''''''''''''''''''''''

在自己的 Java 应用通过 ``build.gradle`` 引入，目前 weid-java-sdk 暂时只支持 gradle 方式引入。
在自己的 Java 应用通过 ``build.gradle`` 引入。

::

compile("com.webank:weid-java-sdk:1.3.2")
compile("com.webank:weid-java-sdk:x.x.x")

.. note::
x.x.x为您使用的weid-java-sdk版本，建议使用最新版本。



2.2 配置您的 Java 应用
Expand Down
60 changes: 24 additions & 36 deletions readthedocs/zh_CN/docs/weidentity-build-without-deploy.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ WeIdentity JAVA SDK 安装部署工具（不部署智能合约）

1.2 配置基本信息
''''''''''''''''''''''''''''''''''''
weid-java-sdk 可以同时支持 FISCO BCOS 1.3版本和 FISCO BCOS 2.0 版本。
最新版本的build-tool工具仅支持 FISCO BCOS 2.0 版本。


1.2.1 基本配置
Expand All @@ -46,7 +46,7 @@ weid-java-sdk 可以同时支持 FISCO BCOS 1.3版本和 FISCO BCOS 2.0 版本
- 配置区块链节点信息，填入区块链节点 IP 和 Channel端口，示例如下：

.. note::
区块链节点Channel端口说明见\ `FISCO BCOS 2.0配置文件说明 <https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/manual/configuration.html#rpc>`__\ 或 `FISCO BCOS 1.3 配置文件说明 <https://fisco-bcos-documentation.readthedocs.io/zh_CN/release-1.3/docs/web3sdk/config_web3sdk.html#java>`__\ 。
区块链节点Channel端口说明见\ `FISCO BCOS 2.0配置文件说明 <https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/manual/configuration.html#rpc>`__\。

.. code:: shell
Expand All @@ -59,13 +59,6 @@ weid-java-sdk 可以同时支持 FISCO BCOS 1.3版本和 FISCO BCOS 2.0 版本
blockchain_address=10.10.10.10:20200,10.10.10.11:20200
- 配置 FISCO BCOS 版本信息，如果您使用 FISCO BCOS 2.0 版本则配置为2，FISCO BCOS 1.3 则配置为 1：

.. code:: shell
blockchain_fiscobcos_version=2
- 配置机构名称，该名称也被用作后续机构间的 \ `AMOP <https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/manual/amop_protocol.html>`__ 通信标识。

假设您的机构名为 test，您可以配置为：
Expand All @@ -80,6 +73,24 @@ weid-java-sdk 可以同时支持 FISCO BCOS 1.3版本和 FISCO BCOS 2.0 版本
chain_id=1
- 配置数据库相关，该配置用于SDK存储相关数据使用：

.. code:: shell
mysql_address=0.0.0.0:3306
mysql_database=database
mysql_username=username
mysql_password=password
- 配置CNS地址，配置你需要使用哪家机构的CNS地址：

.. code:: shell
cns_contract_follow=0x....
.. note::
一条联盟链里，当一家机构部署 WeIdentity 智能合约成功后，需要将CNS地址发给其他机构，或者使用可视化工具选择CNS进行启用。

保存退出，即完成基本配置。

1.2.2 配置节点证书和秘钥文件
Expand All @@ -91,8 +102,6 @@ weid-java-sdk 可以同时支持 FISCO BCOS 1.3版本和 FISCO BCOS 2.0 版本

FISCO BCOS 2.0请参考\ `2.0 web3sdk客户端配置 <https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/sdk/java_sdk.html>`__\ 将证书文件 ``ca.crt``， ``node.crt`` 和 ``node.key`` 复制出来，拷贝至当前目录下。

FISCO BCOS 1.3请参考\ `1.3 web3sdk客户端配置 <https://fisco-bcos-documentation.readthedocs.io/zh_CN/release-1.3/docs/tools/web3sdk.html>`__\ 将证书文件 ``ca.crt`` 和 ``client.keystore`` 复制出来，拷贝至当前目录下 。


1.3 部署智能合约并自动生成配置文件
''''''''''''''''''''''''''''''''''''
Expand All @@ -115,31 +124,8 @@ FISCO BCOS 1.3请参考\ `1.3 web3sdk客户端配置 <https://fisco-bcos-documen

如果执行过程没报错，大约半分钟左右可以编译完成。

1.4 配置您的配置文件

您需要向发布 WeIdentity 智能合约的机构索要智能合约地址，并将对应的智能合约地址填入对应的项。

::

cd resources/
vim fisco.properties

您需要将每个配置项替换成对应的智能合约地址，比如，如果 WeID Contract 的发布地址是0xabbc75543648af0861b14daa4f8582f28cd95f5e，
您需要将 ``weId.contractaddress`` 对应的值替换成 0xabbc75543648af0861b14daa4f8582f28cd95f5e，变成以下内容：

::

weid.contractaddress=0xabbc75543648af0861b14daa4f8582f28cd95f5e

其他的 ``cpt.contractaddress``， ``issuer.contractaddress``， ``evidence.contractaddress`` 和 ``specificissuer.contractaddress`` 都进行对应的智能合约地址替换，完成后保存退出即可。


至此，您已经完成 weid-java-sdk 的安装部署，您可以开始您的 Java 应用集成以及便捷工具体验。

.. note::
一条联盟链里，当一家机构部署 WeIdentity 智能合约成功后，需要将上述智能合约地址发给其他机构。

2 weid-java-sdk 的集成
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Expand All @@ -150,9 +136,11 @@ FISCO BCOS 1.3请参考\ `1.3 web3sdk客户端配置 <https://fisco-bcos-documen

::

compile("com.webank:weid-java-sdk:1.3.2")

compile("com.webank:weid-java-sdk:x.x.x")

.. note::
x.x.x为您使用的weid-java-sdk版本，建议使用最新版本。

2.2 配置您的Java应用
'''''''''''''''''''''''''''''''''
将 weid-build-tools 里配置好的配置文件拷贝至您的Java应用中：
Expand Down
26 changes: 18 additions & 8 deletions readthedocs/zh_CN/docs/weidentity-installation-by-sourcecode.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,9 +32,6 @@ WeIdentity JAVA SDK安装部署文档（源码方式）
若您使用FISCO BCOS 2.0, 请参考\ `2.0 web3sdk客户端配置 <https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/sdk/java_sdk.html>`__，
将证书文件 ``ca.crt``， ``node.crt`` 和 ``node.key`` 复制出来，拷贝至当前目录下。

若您使用FISCO BCOS 1.3, 请参考\ `1.3 web3sdk客户端配置 <https://fisco-bcos-documentation.readthedocs.io/zh_CN/release-1.3/docs/tools/web3sdk.html>`__，
将证书文件 ``ca.crt`` 和 ``client.keystore`` 复制出来，拷贝至当前目录下 。


- 配置基本信息

Expand All @@ -48,25 +45,38 @@ WeIdentity JAVA SDK安装部署文档（源码方式）

- 配置说明：

| ``blockchain_address`` ： 区块链节点 IP 和channel端口， channel端口的配置可以参考\ `FISCO BCOS 2.0 配置项说明 <https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/manual/configuration.html#rpc>`__ 进行配置，FISCO BCOS 1.3可以参考\ `FISCO BCOS 1.3 配置项说明 <https://fisco-bcos-documentation.readthedocs.io/zh_CN/release-1.3/docs/web3sdk/config_web3sdk.html#java>`__ 进行配置。
| ``blockchain_fiscobcos_version`` ：对接的FISCO BCOS版本。
| ``blockchain_address`` ： 区块链节点 IP 和channel端口， channel端口的配置可以参考\ `FISCO BCOS 2.0 配置项说明 <https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/manual/configuration.html#rpc>`__ 进行配置。
| ``org_id`` ：机构名称，该名称也被用作后续机构间的通信标识。
| ``chain_id`` ：用于标识您接入的区块链网络。
| ``mysql_address`` ：配置数据库的ip和port，例：0.0.0.0:3306
| ``mysql_database`` ：配置数据库名称
| ``mysql_username`` ：配置数据库用户名
| ``mysql_password`` ：配置数据库用户对应的密码

配置样例：
::

#节点的连接串，节点IP为10.10.10.10，和channel端口为20200。
blockchain_address=10.10.10.10:20200

# 2表示FISCO BCOS的版本为2.0, 1则表示FISCO BCOS 1.3
blockchain_fiscobcos_version=2

#机构名称
org_id=organizationA

#链标识
chain_id=1
#数据库ip和port
mysql_address=0.0.0.0:3306
#数据库名称
mysql_database=database
#数据库用户名
mysql_username=username
#数据库密码
mysql_password=password
.. note::
注意：如果您使用了Gradle 6.0+，那么您需要手动修改build.gradle中spotbug的Gradle插件版本号为2.0.0+。具体地，打开WeIdentity/build.gradle，将“classpath "gradle.plugin.com.github.spotbugs:spotbugs-gradle-plugin:1.6.5"”中的1.6.5改成2.0.0或更高版本。
Expand Down
63 changes: 63 additions & 0 deletions readthedocs/zh_CN/docs/weidentity-installation-by-web.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
.. role:: raw-html-m2r(raw)
:format: html

.. _weidentity-installation-by-sourcecode:

WeIdentity JAVA SDK安装部署文档（可视化版本）
=================================================

整体介绍
--------

可视化版本只需要简单的几步就可以完成安装，其他的操作都可以在网页上面进行完成，大大降低了操作难度。

.. note::
注意: 建议在内网安装部署。


1.下载安装脚本
""""""""""
.. code-block:: shell
wget -c https://github.com/WeBankFinTech/weid-build-tools/raw/develop/script/install_build_tool.sh
2.执行安装脚本
""""""""""

.. code-block:: shell
source ./install_build_tool.sh
3.启动Web服务
""""""""""

.. code-block:: shell
./start.sh
出现下列输出，则表示Web服务启动成功。

.. code-block:: shell
the server start successfully.
the server url: http://localhost:6102/index.html
.. note::
如果您想使用命令版本, 可以按照 `命令版本部署 - 1.2章节 <./weidentity-build-with-deploy.html>`_ 来操作。


附
""""""""""""""""""""""""""""""""

1. 请访问主页通过指引来完成配置和部署合约等相关操作。

* 需要提前准备区块链节点

* 需要有可访问的MySql数据库


2. 合约部署完成将会生成相关的配置文件:

* admin密钥文件目录 : ./output/admin/

* 资源文件目录(用于应用集成SDK): ./resources/
3 changes: 2 additions & 1 deletion readthedocs/zh_CN/docs/weidentity-installation.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,8 @@ WeIdentity Java SDK 安装部署

我们提供两种方式安装部署SDK（包括两步：首先将WeIdentity智能合约部署到区块链上，再集成SDK到您的Java工程中）：

* `安装部署工具方式 <./weidentity-build-with-deploy.html>`_ （推荐方式）
* `安装部署工具方式 - 可视化版本<./weidentity-installation-by-web.html>`_ （推荐方式）
* `安装部署工具方式 - 命令版本<./weidentity-build-with-deploy.html>`_
* `源码方式 <./weidentity-installation-by-sourcecode.html>`_

.. note::
Expand Down
17 changes: 11 additions & 6 deletions readthedocs/zh_CN/docs/weidentity-quick-tools.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,11 +45,15 @@ WeIdentity JAVA SDK 便捷使用工具
::

New weid has been created ----> did:weid:1:0x405a7ae297fc6d6fb02fb548db64b29f08114ca1
The related private key and public key can be found at /home/app/tonychen/test_gradle/weid-build-tools/output/create_weid/0x405a7ae297fc6d6fb02fb548db64b29f08114ca1.
The related private key and public key can be found at /home/app/tonychen/test_gradle/weid-build-tools/output/create_weid/xxx/0x405a7ae297fc6d6fb02fb548db64b29f08114ca1.

表明创建的 ``WeID`` 是did:weid:1:0x405a7ae297fc6d6fb02fb548db64b29f08114ca1。

在 ``weid-build-tools/output/create_weid/`` 目录下看到一些以 0x 开头的目录，找到跟刚刚生成的 WeIdentity DID 匹配的目录，里面包含了 WeIdentity DID，公钥 ``ecdsa_key.pub`` 和私钥 ``ecdsa_key``。
在 ``weid-build-tools/output/create_weid/xxx`` 目录下看到一些以 0x 开头的目录，找到跟刚刚生成的 WeIdentity DID 匹配的目录，里面包含了 WeIdentity DID，公钥 ``ecdsa_key.pub`` 和私钥 ``ecdsa_key``。

.. note::
xxx为您启用的CNS地址


2 注册 Authority Issuer (权威凭证发行者)
'''''''''''''''''''''''''''''''''''''''''''''''
Expand Down Expand Up @@ -105,11 +109,11 @@ WeIdentity JAVA SDK 便捷使用工具
[RegisterIssuer] Adding WeIdentity DID did:weid:1:0xe10e52f6b7c6751bd03afc023b8e617d7fd0429c in type: college
Specific issuers and types have been successfully registered on blockchain.

如果您需要注册多个机构，请将其 WeIdentity DID 用分号分割开，如下所示：
如果您需要注册多个机构，请将其 WeIdentity DID 用逗号分割开，如下所示：

::

./register_specific_issuer.sh --type college --weid did:weid:1:0x5efd256d02c1a27675de085b86989fa2ac1baddb;did:weid:0x6efd256d02c1a27675de085b86989fa2ac1baddb
./register_specific_issuer.sh --type college --weid did:weid:1:0x5efd256d02c1a27675de085b86989fa2ac1baddb,did:weid:0x6efd256d02c1a27675de085b86989fa2ac1baddb

- 移除特定类型机构

Expand Down Expand Up @@ -174,8 +178,9 @@ WeIdentity JAVA SDK 便捷使用工具
Begin to generate pojo from cpt...
All cpt:[1000] are successfully transformed to pojo.

The weidentity-cpt.jar can be found in /home/app/tonychen/test_gradle/weid-build-tools/dist/app/
The weidentity-cpt.jar can be found in /home/app/tonychen/test_gradle/weid-build-tools/output/pojo/0x8ce1fc7af86917b503d7d5aaa2987a33ccf97f767199a360712fee667a54ef80/d8acebb597d0428fac682ad188e4312d/weidentity-cpt.jar
Begin to generate presentation policy ...
Presentation policy template is successfully generated, you can find it at /home/app/tonychen/test_gradle/weid-build-tools/output/presentation_policy.

表明生成的 CPT 的 POJO 的jar包在 ``/home/app/tonychen/test_gradle/weid-build-tools/dist/app/`` 目录下， 生成的 presentation policy 模板在 ``/home/app/tonychen/test_gradle/weid-build-tools/output/presentation_policy`` 。
表明生成的 CPT 的 POJO 的jar包在 ``/home/app/tonychen/test_gradle/weid-build-tools/output/pojo/0x8ce1fc7af86917b503d7d5aaa2987a33ccf97f767199a360712fee667a54ef80/d8acebb597d0428fac682ad188e4312d/`` 目录下，
生成的 presentation policy 模板在 ``/home/app/tonychen/test_gradle/weid-build-tools/output/presentation_policy`` 。

0 comments on commit ef2bdbb

Please sign in to comment.