Skip to content

Commit

Permalink
add v3.11.0 docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@bxq2011hust
bxq2011hust committed Aug 27, 2024
1 parent 1b0503d commit 4d8e163
Show file tree
Hide file tree
Showing 13 changed files with 327 additions and 64 deletions.
6 changes: 3 additions & 3 deletions 3.x/zh_CN/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,7 @@
# The short X.Y version.
version = '3.0'
# The full version, including alpha/beta/rc tags.
release = 'v3.9.0'
release = 'v3.11.0'

# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
Expand Down Expand Up @@ -369,12 +369,12 @@ def replace_source(app, exception):
for file in files:
if file.endswith('.html'):
html_path = os.path.join(root, file)

with open(html_path, 'r') as file:
lines = file.readlines()

new_lines = [line.replace('https://unpkg.com', 'https://npm.onmicrosoft.cn') for line in lines]
new_lines = [line.replace('https://cdnjs.cloudflare.com', 'https://cdn.bootcdn.net') for line in new_lines]
new_lines = [line.replace('https://cdnjs.cloudflare.com', 'https://cdn.bootcdn.net') for line in new_lines]

with open(html_path, 'w') as file:
file.writelines(new_lines)
128 changes: 128 additions & 0 deletions 3.x/zh_CN/docs/introduction/change_log/3_11_0.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,128 @@
# v3.11.0

## 新增

- 新增自动清理过期的Nonce列表。相关PR：[#4465](https://github.com/FISCO-BCOS/FISCO-BCOS/pull/4465)
- 新增`[log].rotate_time_point`支持设置日志滚动时间。相关PR：[#4465](https://github.com/FISCO-BCOS/FISCO-BCOS/pull/4465)
- 支持快照生成和导入功能。相关PR：[#4471](https://github.com/FISCO-BCOS/FISCO-BCOS/pull/4471)
- 支持通过p2p同步归档区块的交易和收据。相关PR：[#4556](https://github.com/FISCO-BCOS/FISCO-BCOS/pull/4556)
- 支持区块和状态数据分离存储。相关PR：[#4552](https://github.com/FISCO-BCOS/FISCO-BCOS/pull/4552)

## 修复

无

## 兼容性说明

### 兼容版本

需要升级的链的“数据兼容版本号（[compatibility_version](#id5)）”为如下版本时：

* 3.4.x、3.5.x，3.6.x、3.7.x、3.8.x、3.9.x、3.10.x：数据完全兼容当前版本，直接替换二进制即可完成升级
* 3.3.x、3.2.x、3.1.x、3.0.x：支持通过替换二进制进行灰度升级，若需使用当前版本的新特性，需升级数据兼容版本号，操作见[文档](#id5)
* 3.0-rc x：数据不兼容，无法升级，可考虑逐步将业务迁移至3.x正式版
* 2.x：数据不兼容，2.x版本仍持续维护，可考虑升级为2.x的最新版本

### 实验功能

效果：通过feature开关控制实验功能的开启

操作：升级节点可执行程序后，通过控制台命令`setSystemConfigByKey <feature名> 1` 开启对应实验功能，具体操作见文档升级方法部分

注意事项：

* feature操作不可逆，打开后不可关闭
* 需确认所有可执行程序版本相同后，再进行feature开启操作

| | Feature 名 | 默认状态 | 说明 |
|--------------|----------------------------|------|--------------------------------------------|
| 资产管理 | feature_balance | 关：0 | 默认关闭 |
| 资产操作预编译合约 | feature_balance_precompile | 关：0 | 默认关闭 |
| 计费模式 | feature_policy1 | 关：0 | 默认关闭 |
| 块内分片 | feature_sharding | 关：0 | 默认关闭，仅在从3.3、3.4升级至当前版本时，feature_sharding打开 |
| 同态加密 | feature_paillier | 关：0 | 默认关闭 |
| rpbft共识 | feature_rpbft | 关：0 | 默认关闭 |
| EVM升级至CANCUN | feature_evm_cancun | 关：0 | 默认关闭 |
| bug修复 | bugfix_\<bug_name\> | 开：1 | 从低版本升级默认关闭 |

**组件兼容性**

| | 推荐版本 | 最低版本 | 说明 |
|------------|-------------|---------------------|-------------------|
| WeBASE | 3.0.2 | 3.0.2 | |
| WeIdentity | v3.0.0-rc.1 | v3.0.0-rc.1 | |
| Console | 3.8.0 | 3.0.0 | |
| Java SDK | 3.8.0 | 3.0.0 | |
| CPP SDK | 3.8.0 | 3.0.0 | |
| Solidity | 0.8.26 | 最低 0.4.25，最高 0.8.26 | 需根据合约版本下载编译器（控制台） |
| WBC-Liquid | 1.0.0-rc3 | 1.0.0-rc3 | |

#### 升级方法

该操作仅支持将3.x版本升级为本版本，不支持3.0-rc或2.x的升级。

##### 查询数据兼容版本号（compatibility_version）

用[控制台](https://fisco-bcos-doc.readthedocs.io/zh_CN/latest/docs/operation_and_maintenance/console/console_commands.html#getsystemconfigbykey)
进行查询，如当前返回的版本为3.9.0

```
[group0]: /apps> getSystemConfigByKey compatibility_version
3.9.0
```

##### 替换节点二进制

需将**所有节点** 的二进制逐步替换为当前版本。为了不影响业务，替换过程能够以灰度方式进行，逐个替换并重启节点。替换过程中，当前的链仍然会以旧的数据兼容版本号的逻辑继续执行。当所有节点二进制替换完成并重启后，需用控制台修改数据兼容版本号为当前版本。

##### 设置数据兼容版本号（compatibility_version）

用[控制台](https://fisco-bcos-doc.readthedocs.io/zh_CN/latest/docs/operation_and_maintenance/console/console_commands.html#setsystemconfigbykey)
设置数据兼容版本号，如当前版本为3.11.0。

```bash
[group0]: /apps> setSystemConfigByKey compatibility_version 3.11.0
{
"code":0,
"msg":"success"
}

注：若开启权限治理功能，需要使用 setSysConfigProposal 命令
```

设置成功，再次查询，得到当前版本已升级为3.11.0

```
[group0]: /apps> getSystemConfigByKey compatibility_version
3.11.0
```

当前链已经完成升级，至此，**链开始以新的逻辑继续运行**，并支持了新的特性。

#### EVM升级至CANCUN使用说明

首先通过控制台命令`setSystemConfigByKey feature_evm_cancun 1`开启EVM升级至CANCUN功能，然后部署0.8.26版本的合约。

注意：在部署0.8.26版本合约时，需要在depoly 后面指定sol-version 为0.8.26，如下所示：

```
[group0]: /apps> deploy StorageSlot.sol --sol-version 0.8.26
transaction hash: 0x8f3564047e3dd2913ed30f193e10c2b8af2b24896ce10b8add8eb47b888d7505
contract address: 0x29f1926cab679bc8bdd0757fb92adf020c8bd398
currentAccount: 0x0296737557c85bde21b4cf766c3f85e2e4c14d66
// 否则使用默认0.8.11版本编译则会报错
[group0]: /apps> deploy StorageSlot.sol
Warning: SPDX license identifier not provided in source file. Before publishing, consider adding a comment containing "SPDX-License-Identifier: <SPDX-License>" to each source file. Use "SPDX-License-Identifier: UNLICENSED" for non-open-source code. Please see https://spdx.org for more information.
--> StorageSlot.sol
Error: Function "tload" not found.
--> StorageSlot.sol:127:22:
|
127 | value := tload(slot)
| ^^^^^
Error: Variable count for assignment to "value" does not match number of values (1 vs. 0)
```
111 changes: 111 additions & 0 deletions 3.x/zh_CN/docs/operation_and_maintenance/snapshot.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,111 @@
# 15. 快照功能

标签：``运维``，``快照``

---

## 简介

v3.11.0开始支持了快照的导入和导出功能，快照功能可以帮助用户快速备份和恢复链上数据，当新节点加入时也可以通过快照减少同步到最新状态所需要的时间。

## 生成快照

### 生成完整快照

生成完整快照是将区块链上的状态数据、交易和收据完整的导出，快照的大小与节点数据目录(例如`./data`)的大小相近，生成快照的时间与数据目录的大小成正比。操作命令如下，其中`-s`表示是否携带交易与收据，`-o`表示快照的输出目录：

```bash
# 生成完整快照，要在节点目录下执行
../fisco-bcos -s true -o ./
```

输出如下：

```bash
[2024-08-26 16:41:07] generating snapshot to ./ ...
current block number: 7883
Traverse RocksDB: data
".//snapshot/state/000000.sst" Finished. 1
".//snapshot/block/000000.sst" Finished. 2
generate snapshot success, the snapshot is in .//snapshot
[2024-08-26 16:41:09] generate snapshot success.
```

产生的快照位于输出目录下，例如`./snapshot`。

```bash
$ ls snapshot
block meta state
```

snapshot目录下包含了三个文件夹，分别是`block`、`meta`和`state`，其中：

- `block`文件夹包含区块中的交易和收据数据
- `meta`文件夹包含了快照的元信息
- `state`文件夹包含了区块链的状态数据

### 生成状态快照，不包含历史区块的交易和收据

生成状态快照是将区块链上的状态数据导出，不包含历史区块的交易和收据，相比于完整快照，状态快照的空间占用会小很多。操作命令如下，其中`-s`表示是否携带交易与收据，`-o`表示快照的输出目录：

```bash
# 生成状态快照，要在节点目录下执行
../fisco-bcos -s false -o ./
```

输出如下：

```bash
[2024-08-26 16:40:12] generating snapshot to ./ ...
current block number: 7883
Traverse RocksDB: data
".//snapshot/state/000000.sst" Finished. 1
generate snapshot success, the snapshot is in .//snapshot
[2024-08-26 16:40:12] generate snapshot success.
```

snapshot文件夹与完整快照类似，只是没有了block文件夹。

## 导入快照

导入快照功能可以从快照中恢复区块链的状态数据，导入快照的时间与快照的大小成正比。操作命令如下，其中`-i`表示快照的输入目录：

```bash
# 导入快照，要在节点目录下执行
../fisco-bcos -i ./snapshot
```

建议用户在通过快照生成新节点时，设置`config.ini`文件中`[storage].enable_separate_block_state=true`以避免快照导入过程中，可能出现的因为交易、收据和状态数据触发RocksDB的compaction，导致导入过程变慢。

导入过程中会提示用户选择导入方式，yes表示使用move模式，no表示使用copy模式，move模式会尝试移动快照中的文件，当可以移动时导入会很快，copy模式会拷贝快照中的数据，耗时取决于数据量大小。输出如下，

```bash
[2024-08-26 16:41:52] importing snapshot from ./snapshot ...
The block number of snapshot: 7883
the snapshot will be ingested into data, if yes the snapshot will be moved, if no the snapshot will be copy(yes/no)
no
check sst files success, ingest sst files
check sst files success, ingest sst files
The block number of this node: 7883
[2024-08-26 16:42:14] import snapshot success.
```
## 归档区块同步
在支持快照的同时，节点`config.ini`新增了配置项`[storage].sync_archived_blocks`，默认值为`false`，当设置为`true`时，节点会通过p2p请求同步已经归档的区块。
节点执行过下面两种操作的任意一种，就会存在归档区块：
- 节点从状态快照生成时，没有交易和收据的区块会被认为是归档区块。
- 节点通过归档工具做过归档。
从这种节点可以查询区块头，但当查询归档区块中的交易和收据时，节点会返回错误。
## 历史nonce清理功能
FISCO BCOS会存储最近1000个区块中交易的nonce，用来防范交易重放攻击，v3.11.0版本新增了历史nonce清理功能，会自动清理掉超出最近1000个块的nonce列表，减小节点存储压力，例如当前块高为1001，则提交1002时，会自动清理块高2的nonce列表。同时在命令行添加了手动清理历史区块nonce列表的命令，操作命令如下：
```bash
# 导入快照，要在节点目录下执行
../fisco-bcos --prune
```
6 changes: 3 additions & 3 deletions 3.x/zh_CN/docs/quick_start/air_installation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -49,18 +49,18 @@ sudo yum install -y curl openssl openssl-devel wget

```eval_rst
.. note::
如果因为网络问题导致长时间无法下载build_chain.sh脚本，请尝试 curl -#LO https://osp-1257653870.cos.ap-guangzhou.myqcloud.com/FISCO-BCOS/FISCO-BCOS/releases/v3.10.0/build_chain.sh && chmod u+x build_chain.sh
如果因为网络问题导致长时间无法下载build_chain.sh脚本，请尝试 curl -#LO https://osp-1257653870.cos.ap-guangzhou.myqcloud.com/FISCO-BCOS/FISCO-BCOS/releases/v3.11.0/build_chain.sh && chmod u+x build_chain.sh
```

```shell
# 创建操作目录
cd ~ && mkdir -p fisco && cd fisco

# 下载建链脚本
curl -#LO https://github.com/FISCO-BCOS/FISCO-BCOS/releases/download/v3.10.0/build_chain.sh && chmod u+x build_chain.sh
curl -#LO https://github.com/FISCO-BCOS/FISCO-BCOS/releases/download/v3.11.0/build_chain.sh && chmod u+x build_chain.sh

# Note: 若访问git网速太慢，可尝试如下命令下载建链脚本:
curl -#LO https://osp-1257653870.cos.ap-guangzhou.myqcloud.com/FISCO-BCOS/FISCO-BCOS/releases/v3.10.0/build_chain.sh && chmod u+x build_chain.sh
curl -#LO https://osp-1257653870.cos.ap-guangzhou.myqcloud.com/FISCO-BCOS/FISCO-BCOS/releases/v3.11.0/build_chain.sh && chmod u+x build_chain.sh
```

### 第三步. 搭建4节点非国密联盟链
Expand Down
10 changes: 5 additions & 5 deletions 3.x/zh_CN/docs/quick_start/solidity_application.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -432,7 +432,7 @@ repositories {
url "http://maven.aliyun.com/nexus/content/groups/public/"
}
maven {
url "https://oss.sonatype.org/content/repositories/snapshots"
url "https://oss.sonatype.org/content/repositories/snapshots"
}
}
Expand Down Expand Up @@ -564,7 +564,7 @@ $ cp -r nodes/127.0.0.1/sdk/* asset-app-3.0/src/main/resources/conf
### 第一步.将3编译好的Java合约引入项目中

```shell
cd ~/fisco
cd ~/fisco
# 将编译好的合约Java类引入项目中。
cp console/contracts/sdk/java/org/fisco/bcos/asset/contract/Asset.java asset-app-3.0/src/main/java/org/fisco/bcos/asset/contract/Asset.java
```
Expand Down Expand Up @@ -782,7 +782,7 @@ public class AssetClient {
初始化代码的主要功能为构造Client与CryptoKeyPair对象，这两个对象在创建对应的合约类对象(调用合约类的deploy或者load函数)时需要使用。

```java
// 函数initialize中进行初始化
// 函数initialize中进行初始化
// 初始化BcosSDK
@SuppressWarnings("resource")
ApplicationContext context =
Expand Down Expand Up @@ -821,9 +821,9 @@ TransactionReceipt receipt = asset.transfer(fromAssetAccount, toAssetAccount, am
在``asset-app-3.0/tool``目录下添加一个调用AssetClient的脚本``asset_run.sh``。

```shell
#!/bin/bash
#!/bin/bash

function usage()
function usage()
{
echo " Usage : "
echo " bash asset_run.sh deploy"
Expand Down
2 changes: 1 addition & 1 deletion 3.x/zh_CN/docs/tutorial/air/build_chain.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ FISCO BCOS提供了`build_chain.sh`脚本帮助用户快速搭建FISCO BCOS联

```shell
# 下载建链脚本
curl -#LO https://github.com/FISCO-BCOS/FISCO-BCOS/releases/download/v3.10.0/build_chain.sh && chmod u+x build_chain.sh
curl -#LO https://github.com/FISCO-BCOS/FISCO-BCOS/releases/download/v3.11.0/build_chain.sh && chmod u+x build_chain.sh

# Note: 若访问git网速太慢，可尝试如下命令下载建链脚本:
curl -#LO https://osp-1257653870.cos.ap-guangzhou.myqcloud.com/FISCO-BCOS/FISCO-BCOS/releases/v3.6.0/build_chain.sh && chmod u+x build_chain.sh
Expand Down
25 changes: 24 additions & 1 deletion 3.x/zh_CN/docs/tutorial/air/config.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -220,15 +220,37 @@ RPC配置示例如下：

存储配置位于`[storage]`，具体包括:

- `[storage].typs`: 区块链节点数据库类型，默认为RocksDB，支持TiKV，当配置TiKV时，需要对应配置`pd_addrs`,`pd_ssl_ca_path`,`pd_ssl_cert_path`,`pd_ssl_key_path`等参数;
- `[storage].data_path`: 区块链节点数据存储路径，默认为data;
- `[storage].enable_cache`: 是否开启缓存，默认为`true`;
- `[storage].key_page_size`: KeyPage存储方案中，存储页大小，单位是字节，要求不小于`4096`(4KB)，默认为`10240`(10KB);
- `[storage].key_page_size`: KeyPage存储方案中，存储页大小，单位是字节，要求不小于`4096`(4KB)，默认为`10240`(10KB);此配置项可修改为0，表示关闭keypage以获得更好的写入性能，如果已有节点修改此配置项为0，则需要清理数据重新同步区块链数据;
- `[storage].pd_addrs`: TiKV存储时，PD地址，多个地址用逗号分隔;
- `[storage].pd_ssl_ca_path`: TiKV存储时，PD SSL CA证书路径;
- `[storage].pd_ssl_cert_path`: TiKV存储时，PD SSL证书路径;
- `[storage].pd_ssl_key_path`: TiKV存储时，PD SSL私钥路径;
- `[storage].enable_archive`: 是否开启归档服务，默认为`false`;
- `[storage].archive_ip`: 归档服务监听的IP;
- `[storage].archive_port`: 归档服务监听的端口;
- `[storage].enable_separate_block_state`: 当使用RocksDB时是否开启区块状态分离，开启后交易收据会存放在另一个单独的数据库中以获得更好的性能，默认为`false`;
- `[storage].sync_archived_blocks`: 是否同步归档区块，默认为`false`，开启后会通过p2p同步已经归档的历史区块的交易和收据。

```ini
[storage]
; type can be tikv or rocksdb
type=rocksdb
data_path=data
enable_cache=true
; The granularity of the storage page, in bytes, must not be less than 4096 Bytes, the default is 10240 Bytes (10KB)
key_page_size=10240
pd_addrs=127.0.0.1:2379
pd_ssl_ca_path=
pd_ssl_cert_path=
pd_ssl_key_path=
enable_archive=false
archive_ip=
archive_port=
;enable_separate_block_state=false
;sync_archived_blocks=false
```

### 2.6 配置落盘加密
Expand Down Expand Up @@ -277,6 +299,7 @@ FISCO BCOS支持功能强大的[boostlog](https://www.boost.org/doc/libs/1_63_0/
- `[log].log_path`:日志文件路径。
- `[log].level`: 日志级别，当前主要包括`trace`、`debug`、`info`、`warning`、`error`五种日志级别，设置某种日志级别后，日志文件中会输大于等于该级别的日志，日志级别从大到小排序`error > warning > info > debug > trace`。
- `[log].max_log_file_size`：每个日志文件最大容量，**计量单位为MB，默认为200MB**。
- `[log].rotate_time_point`：日志滚动时间点，**默认为00:00:00**。

日志配置示例如下：

Expand Down
2 changes: 1 addition & 1 deletion 3.x/zh_CN/docs/tutorial/air/multihost.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ mkdir -p ~/fisco && cd ~/fisco
./download_bin.sh -v 3.4.0

# 下载开发部署工具build_chain
curl -#LO https://github.com/FISCO-BCOS/FISCO-BCOS/releases/download/v3.10.0/build_chain.sh && chmod u+x build_chain.sh
curl -#LO https://github.com/FISCO-BCOS/FISCO-BCOS/releases/download/v3.11.0/build_chain.sh && chmod u+x build_chain.sh
```

**生成多机节点配置**
Expand Down
Loading

0 comments on commit 4d8e163

Please sign in to comment.