Data stash 1.2.0

docs/WeBankBlockchain-Data-Stash/configuration.md

@@ -1,5 +1,5 @@
 # 详细配置
-
+## 数据仓库
 数据仓库组件的完整配置选项如下：
 
 | 配置项 | 说明 | 是否必需 | 说明|
@@ -17,3 +17,19 @@
 |read.blocks|每下载多少文件开始执行入库|否|默认为5|
 |read.clean|yes-入库完成后清理文件。no-不清理|否|默认清理|
 
+## 数据同步
+
+数据同步模块完整配置选项如下：
+
+| 配置项 | 说明 | 是否必需 | 默认|
+| --- | --- | --- | --- |
+|stash.ip|数据仓库数据库IP地址|必选|127.0.0.1|
+|stash.port|数据仓库数据库端口|必选|3306|
+|stash.dbname|数据仓库数据库名|必选|stash|
+|stash.username|数据仓库数据库用户名|必选|root|
+|stash.password|数据仓库数据库密码|必选|123456|
+|node.groupId|待同步群组id|必选|1|
+|node.path|节点路径|必选|默认当前路径|
+|sync.endBlockNumber|指定同步截止区块号，后续区块从其他节点拉取|非必选|默认：10000|
+|sync.pageCount|指定除表_sys_hash_2_block_和表_sys_block_2_nonces_之外其他表的分页拉取行数，默认为1000行每页；|非必选|1000|
+|sync.bigTablePageCount|指定表_sys_hash_2_block_和表_sys_block_2_nonces_的分页拉取行数，默认为1000行每页|非必选|1000|

docs/WeBankBlockchain-Data-Stash/data-query-install.md

@@ -0,0 +1,75 @@
+### 数据裁剪查询
+
+#### 使用步骤
+
+##### 配置工程
+
+###### 配置文件设置
+
+修改application.properties文件中数据裁剪相关配置：
+
+```
+data.query.enable=true
+data.query.certPath=./config
+data.query.groupId=1
+data.query.nodeStr=127.0.0.1:20200
+data.query.topic=DB
+```
+
+###### 配置证书文件
+
+连接链节点时，需配置证书或证书路径。
+
+将链SDK证书拷贝到配置的证书路径下，如 **./config**下，SDK证书目录位于nodes/${ip}/sdk/目录下
+```
+# 假设SDK证书位于~/fisco/nodes/127.0.0.1/sdk/目录
+cp -r ~/fisco/nodes/127.0.0.1/sdk/* ./config/
+```
+
+#### 运行程序
+
+修改配置后，重新启动项目
+
+```
+bash stop.sh
+bash start.sh
+```
+
+#### 节点数据裁剪
+
+##### 节点配置
+
+FISCO BCOS节点在配置scalable存储模式时，对于本地经裁剪后缺少的数据，将通过Data-Stash访问数据源进行获取。
+
+###### 模式启用
+
+- 设置群组的ini配置文件中`[storage].type=scalable`来选择链的存储模式为`scalable`。
+- 设置群组的ini配置文件中`[storage].binary_log=true`来启用binlog。如用户使用build_chain脚本搭链，并选择scalable存储模式，配置文件会自动开启binlog。
+
+###### 文件组织
+
+节点使用scalable存储模式后，其数据目录内容如下：
+
+- `nodeX/data/groupX/block/Scalable/blocksDB/`下分文件夹存储区块数据。每个文件夹为独立的DB实例，用DB记录的首个块高来进行文件夹命名。用户在配置了数据仓库实现数据备份归档后，较旧（较低块高）的子文件夹**允许删除**。
+- `nodeX/data/groupX/block/Scalable/state`存储整体的状态数据，该文件夹**不可删除**。
+
+###### binlog
+
+binlog文件记录了每个区块的每个交易对区块链状态的修改结果。binlog机制的作用在于：
+
+1. 提供了区块维度的数据操作结果的记录；
+2. 节点可通过binlog文件而非通过原有的拉取区块重放交易的方式来恢复数据；
+3. binlog文件为“数据仓库”的快照构建提供数据来源。
+
+用户可通过设置群组的ini配置文件中`[storage].binary_log=true`来启用binlog（binlog默认关）。开启binlog后，`nodeX/data/groupX/BinaryLogs/`的目录如下。每个binlog文件以其记录的首个区块内容进行命名，且按从小到大的顺序来记录区块。如下图中，文件`18.binlog`记录的区块为块高18到块高29。
+
+```bash
+├── 0.binlog
+├── 18.binlog
+├── 30.binlog
+└── 32.binlog
+```
+
+##### 节点启动
+
+停止节点，在对节点数据进行上述裁剪后，启动节点

docs/WeBankBlockchain-Data-Stash/data-sync-install.md

@@ -0,0 +1,100 @@
+### 数据快速同步
+
+请在要同步数据的节点上执行以下步骤，同步前新节点保持在未启动状态，并清空节点data目录。
+
+扩容新节点参考[扩容节点](https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/tutorial/add_new_node.html?highlight=%E6%96%B0%E8%8A%82%E7%82%B9#id1)
+
+#### 获取启动脚本和配置文件
+
+```
+curl -#LO https://github.com/WeBankBlockchain/Data-Stash/releases/download/V1.2.0/data-sync-bash.tar.gz
+```
+
+```eval_rst
+.. note::
+    - 如果因为网络问题导致长时间无法下载，请尝试：
+    - curl -#LO https://gitee.com/WeBankBlockchain/Data-Stash/attach_files/730064/download/data-sync-bash.tar.gz
+
+```
+
+
+解压文件包至当前目录
+```
+tar -zxvf data-sync-bash.tar.gz && cd data-sync-bash && chmod -x data_sync.sh
+```
+
+data-sync目录如下：
+```
+├── data-sync
+│   ├── config.conf
+│   └── data_sync.sh
+```
+
+```eval_rst
+.. note::
+    - config.conf为配置文件，数据仓库数据源配置。
+    - data_sync.sh为启动脚本
+```
+
+
+#### 配置文件
+
+修改config.conf文件：该文件包含了所有的配置信息。以下配置信息是必须要配置的：
+
+```
+[stash]
+stash.ip=127.0.0.1
+stash.port=3306
+stash.dbname=stash
+stash.username=root
+stash.password=123456
+
+[node]
+#要导出的群组ID，会根据配置读取节点目录conf/下指定group.id.ini配置，进行数据同步
+node.groupId=1
+#节点路径，若选择在fisco对应节点目录下(如~/fisco/nodes/127.0.0.1/node0)执行下述步骤，则无需配置节点路径，默认即可。
+node.path=./
+
+[more]
+#同步截止区块号，如默认为10000，则同步0-9999号区块至新节点，后续区块将从其他节点同步拉取
+sync.endBlockNumber=10000
+```
+
+更多配置参照[数据同步配置](./configuration.html#id3)
+
+#### 启动脚本
+
+```
+bash data_sync.sh
+```
+
+```eval_rst
+.. note::
+    - 上述脚本会自动拉取对应系统的data-sync包，并自动读取节点群组的配置，同步数据到对应的节点存储源中，节点存储模式包括rocksdb/mysql/scalable三种。
+    - rocksdb/mysql模式同步数据包括区块和状态数据。
+    - scalable模式下，只同步状态数据，区块数据需要通过数据仓库获取，参考数据裁剪查询
+
+```
+
+
+看到如下日志，则表示执行成功：
+
+```
+... ...
+[2021-04-29 15:08:24][1/34] processing _sys_tables_
+[2021-04-29 15:08:24.287430] [0x00000001056c45c0] [trace]   [STORAGE]conversion end!
+[2021-04-29 15:08:24.296431] [0x00000001056c45c0] [debug]   [STORAGE][RocksDB][Commit]Write to db,encodeTimeCost=1,writeDBTimeCost=8,totalTimeCost=9
+[2021-04-29 15:08:24][1/34] _sys_tables_ downloaded items : 34 done.
+[2021-04-29 15:08:24][2/34] processing _sys_hash_2_block_
+[2021-04-29 15:08:24.322570] [0x00000001056c45c0] [trace]   [STORAGE]conversion table data,table name=_sys_hash_2_block_,new entry count=50,dirty entry count=0
+[2021-04-29 15:08:24.325145] [0x00000001056c45c0] [trace]   [STORAGE]conversion end!
+[2021-04-29 15:08:24.330759] [0x00000001056c45c0] [debug]   [STORAGE][RocksDB][Commit]Write to db,encodeTimeCost=4,writeDBTimeCost=1,totalTimeCost=5
+... ...
+```
+
+如节点群组1的配置为RocksDB模式，则同步后的数据可在节点data/group1/block/RocksDB/路径下看到，如下文件：
+
+```
+ls data/
+000006.log      000007.sst      CURRENT         IDENTITY        LOCK            LOG             MANIFEST-000008 OPTIONS-000005
+```

docs/WeBankBlockchain-Data-Stash/index.md

@@ -20,16 +20,16 @@
     - 备份数据的可信存储
     - 支持断点续传
     - 轻量级接入
+    - 数据裁剪和同步
     - ...
 ```
 ```eval_rst
 .. toctree::
    :maxdepth: 3
 
    intro.md
-   quickstart.md
+   install.md
    configuration.md
-   advance.md
    design.md
    faq.md
    appendix.md

docs/WeBankBlockchain-Data-Stash/install.md

@@ -0,0 +1,19 @@
+## 快速开始
+
+```eval_rst
+.. note::
+
+   本指引主要介绍如何通过Data-Stash为节点生成全量备份。全量备份是节点冷热分离、快速同步的基础。并提供数据裁剪和同步的使用方式。
+
+```
+
+
+```eval_rst
+.. toctree::
+   :maxdepth: 3
+
+   quickstart.md
+   data-query-install.md
+   data-sync-install.md
+
+```

docs/WeBankBlockchain-Data-Stash/quickstart.md

@@ -1,18 +1,6 @@
-# 快速开始
+### 数据仓库启动
 
-```eval_rst
-.. note::
-
-   本指引主要介绍如何通过Data-Stash为节点生成全量备份。全量备份是节点冷热分离、快速同步的基础。
-
-   若要使节点在仅保留热数据的情况下还能正常运行，需要先启动 `amdb-proxy <https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/manual/data_governance.html#amdb-proxy>`_ ，以通过amdb访问全量数据 。
-
-   若要将数据仓库数据导回节点实现节点同步或迁移，则需要先启动 `amdb-proxy <https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/manual/data_governance.html#amdb-proxy>`_ ，再启动 `fisco-sync <https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/manual/data_governance.html#fisco-sync>`_ 。fisco-sync的运行依赖于amdb。
-
-```
-
-
-## 前置依赖
+#### 前置依赖
 
 在使用本组件前，请确认系统环境已安装相关依赖软件，清单如下：
 
@@ -26,9 +14,9 @@
 
 如果您还未安装这些依赖，请参考[附录](appendix.md)。
 
-## 基础设置
+#### 基础设置
 
-### FISCO BCOS节点配置
+##### FISCO BCOS节点配置
 
 由于数据仓库组件用于生成节点的全量备份，所以要求节点拥有包括第一个区块在内的完整binlog日志，故需要确保该节点加入FISCO BCOS网络前就开启binlog生成选项。如果您的节点已经在运行中，请先停止该节点，并删除对应群组（以group1为例）的数据。例如：
 
@@ -59,7 +47,7 @@ binary_log=true
 0.binlog
 ```
 
-### Nginx配置
+##### Nginx配置
 
 FISCO BCOS节点的binlog日志存放在节点文件目录中，为了让外界能够访问这些binlog，现需要在节点所在服务器安装nginx并配置端口映射，这样外界即可根据该端口访问binlog。
 
@@ -122,9 +110,9 @@ nginx配置文件位于/usr/local/nginx/conf/nginx.conf。需要在http模块内
 
 ![](./picture/nginx_success.png)
 
-## 运行数据仓库组件
+#### 运行数据仓库组件
 
-### 下载源码
+##### 下载源码
 
 通过git 下载源码.
 
@@ -137,26 +125,22 @@ git clone https://github.com/WeBankBlockchain/Data-Stash.git
     - 如果因为网络问题导致长时间无法下载，请尝试：git clone https://gitee.com/WeBankBlockchain/Data-Stash.git
 ```
 
-### 编译源码
+##### 编译源码
 
 ```
-cd Data-Stash
-./gradlew clean bootJar
+cd Data-Stash/tools
 ```
 
-编译完成后，会生成dist目录，其具备如下结构：
+tools目录如下：
 ```
-dist
-│   start.sh
-│   stop.sh
-│   Data-Stash.jar
-└───config
-│   │   application.properties
-└───lib
-    │   ...
+├── tools
+│   ├── config
+│   │   ├── application.properties
+│   ├── start.sh
+│   └── stop.sh
 ```
 
-### 启动配置
+##### 启动配置
 
 在启动之间还需要进行配置，主要包括：
 - binlog获取端口
@@ -168,7 +152,6 @@ dist
 ### 配置nginx服务的binlog地址，如果连接多个节点的话，使用逗号分隔
 system.binlogAddress=http://www.example.com:5299/,http://www.example.com:5300/
 
-
 ### 数据库连接配置
 #### 禁用分库分表
 spring.shardingsphere.enabled=false 
@@ -183,17 +166,13 @@ spring.datasource.driverClassName=com.mysql.jdbc.Driver
     - Data-Stash并不会自动创建数据库，所以请预先建好数据库。
     - 若您的链是国密链，请配置system.encryptType=1. DataStash需要验证区块中的签名。
 ```
-### 运行程序
+##### 运行程序
 
 可以通过bash启动程序：
 ```
 chmod +x *sh
 bash start.sh
 ```
-也可以直接通过jar包启动：
-```
-java -jar Data-Stash.jar
-```
 
 如果日志出现下述字样，则表示运行成功：