Skip to content

Commit d71167c

Browse files
bxq2011hustbxq2011hust
authored
add v3.11.0 docs (#1825)
1 parent 1b0503d commit d71167c

File tree

14 files changed

+331
-74
lines changed

14 files changed

+331
-74
lines changed

‎3.x/zh_CN/conf.py

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -87,7 +87,7 @@
8787
# The short X.Y version.
8888
version = '3.0'
8989
# The full version, including alpha/beta/rc tags.
90-
release = 'v3.9.0'
90+
release = 'v3.11.0'
9191

9292
# The language for content autogenerated by Sphinx. Refer to documentation
9393
# for a list of supported languages.
@@ -369,12 +369,12 @@ def replace_source(app, exception):
369369
for file in files:
370370
if file.endswith('.html'):
371371
html_path = os.path.join(root, file)
372-
372+
373373
with open(html_path, 'r') as file:
374374
lines = file.readlines()
375375

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

379379
with open(html_path, 'w') as file:
380380
file.writelines(new_lines)

‎3.x/zh_CN/docs/introduction/change_log/3_11_0.md

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# v3.11.0
2+
3+
## 新增
4+
5+
- 新增自动清理过期的Nonce列表。相关PR：[#4465](https://github.com/FISCO-BCOS/FISCO-BCOS/pull/4465)
6+
- 新增`[log].rotate_time_point`支持设置日志滚动时间。相关PR：[#4465](https://github.com/FISCO-BCOS/FISCO-BCOS/pull/4465)
7+
- 支持快照生成和导入功能。相关PR：[#4471](https://github.com/FISCO-BCOS/FISCO-BCOS/pull/4471)
8+
- 支持通过p2p同步归档区块的交易和收据。相关PR：[#4556](https://github.com/FISCO-BCOS/FISCO-BCOS/pull/4556)
9+
- 支持区块和状态数据分离存储。相关PR：[#4552](https://github.com/FISCO-BCOS/FISCO-BCOS/pull/4552)
10+
11+
## 修复
12+
13+
无
14+
15+
## 兼容性说明
16+
17+
### 兼容版本
18+
19+
需要升级的链的“数据兼容版本号（[compatibility_version](#id5)）”为如下版本时：
20+
21+
* 3.4.x、3.5.x，3.6.x、3.7.x、3.8.x、3.9.x、3.10.x：数据完全兼容当前版本，直接替换二进制即可完成升级
22+
* 3.3.x、3.2.x、3.1.x、3.0.x：支持通过替换二进制进行灰度升级，若需使用当前版本的新特性，需升级数据兼容版本号，操作见[文档](#id5)
23+
* 3.0-rc x：数据不兼容，无法升级，可考虑逐步将业务迁移至3.x正式版
24+
* 2.x：数据不兼容，2.x版本仍持续维护，可考虑升级为2.x的最新版本
25+
26+
### 实验功能
27+
28+
效果：通过feature开关控制实验功能的开启
29+
30+
操作：升级节点可执行程序后，通过控制台命令`setSystemConfigByKey <feature名> 1` 开启对应实验功能，具体操作见文档升级方法部分
31+
32+
注意事项：
33+
34+
* feature操作不可逆，打开后不可关闭
35+
* 需确认所有可执行程序版本相同后，再进行feature开启操作
36+
37+
| | Feature 名 | 默认状态 | 说明 |
38+
|--------------|----------------------------|------|--------------------------------------------|
39+
| 资产管理 | feature_balance | 关：0 | 默认关闭 |
40+
| 资产操作预编译合约 | feature_balance_precompile | 关：0 | 默认关闭 |
41+
| 计费模式 | feature_policy1 | 关：0 | 默认关闭 |
42+
| 块内分片 | feature_sharding | 关：0 | 默认关闭，仅在从3.3、3.4升级至当前版本时，feature_sharding打开 |
43+
| 同态加密 | feature_paillier | 关：0 | 默认关闭 |
44+
| rpbft共识 | feature_rpbft | 关：0 | 默认关闭 |
45+
| EVM升级至CANCUN | feature_evm_cancun | 关：0 | 默认关闭 |
46+
| bug修复 | bugfix_\<bug_name\> | 开：1 | 从低版本升级默认关闭 |
47+
48+
**组件兼容性**
49+
50+
| | 推荐版本 | 最低版本 | 说明 |
51+
|------------|-------------|---------------------|-------------------|
52+
| WeBASE | 3.0.2 | 3.0.2 | |
53+
| WeIdentity | v3.0.0-rc.1 | v3.0.0-rc.1 | |
54+
| Console | 3.8.0 | 3.0.0 | |
55+
| Java SDK | 3.8.0 | 3.0.0 | |
56+
| CPP SDK | 3.8.0 | 3.0.0 | |
57+
| Solidity | 0.8.26 | 最低 0.4.25，最高 0.8.26 | 需根据合约版本下载编译器（控制台） |
58+
| WBC-Liquid | 1.0.0-rc3 | 1.0.0-rc3 | |
59+
60+
#### 升级方法
61+
62+
该操作仅支持将3.x版本升级为本版本，不支持3.0-rc或2.x的升级。
63+
64+
##### 查询数据兼容版本号（compatibility_version）
65+
66+
用[控制台](https://fisco-bcos-doc.readthedocs.io/zh_CN/latest/docs/operation_and_maintenance/console/console_commands.html#getsystemconfigbykey)
67+
进行查询，如当前返回的版本为3.9.0
68+
69+
```
70+
[group0]: /apps> getSystemConfigByKey compatibility_version
71+
3.9.0
72+
```
73+
74+
##### 替换节点二进制
75+
76+
需将**所有节点** 的二进制逐步替换为当前版本。为了不影响业务，替换过程能够以灰度方式进行，逐个替换并重启节点。替换过程中，当前的链仍然会以旧的数据兼容版本号的逻辑继续执行。当所有节点二进制替换完成并重启后，需用控制台修改数据兼容版本号为当前版本。
77+
78+
##### 设置数据兼容版本号（compatibility_version）
79+
80+
用[控制台](https://fisco-bcos-doc.readthedocs.io/zh_CN/latest/docs/operation_and_maintenance/console/console_commands.html#setsystemconfigbykey)
81+
设置数据兼容版本号，如当前版本为3.11.0。
82+
83+
```bash
84+
[group0]: /apps> setSystemConfigByKey compatibility_version 3.11.0
85+
{
86+
"code":0,
87+
"msg":"success"
88+
}
89+
90+
注：若开启权限治理功能，需要使用 setSysConfigProposal 命令
91+
```
92+
93+
设置成功，再次查询，得到当前版本已升级为3.11.0
94+
95+
```
96+
[group0]: /apps> getSystemConfigByKey compatibility_version
97+
3.11.0
98+
```
99+
100+
当前链已经完成升级，至此，**链开始以新的逻辑继续运行**，并支持了新的特性。

‎3.x/zh_CN/docs/introduction/change_log/index.rst

Lines changed: 32 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,28 @@ FISCO BCOS 设计 Feature控制特性功能开启关闭，用户可以根据自
2121
:maxdepth: 0
2222

2323
upgrade.md
24+
25+
v3.11.x
26+
------------------
27+
28+
.. admonition:: FISCO BCOS 3.x Releases
29+
30+
- `FISCO BCOS v3.11.0 <./3_11_0.html>`_ [`release <https://github.com/FISCO-BCOS/FISCO-BCOS/releases/tag/v3.11.0>`_]
31+
32+
.. admonition:: 查看节点和数据版本
33+
34+
- 查看Air版本FISCO BCOS节点二进制版本：``./fisco-bcos --version``
35+
- 查看Pro版本FISCO BCOS节点二进制版本：``./BcosNodeService --version``, ``./BcosRpcService --version``, ``./BcosGatewayService --version``
36+
- 查看Max版本FISCO BCOS节点二进制版本：``./BcosMaxNodeService --version``, ``./BcosRpcService --version``, ``./BcosGatewayService --version``, ``./BcosExecutorService --version``
37+
- 查看轻节点二进制版本：``../fisco-bcos-lightnode --version``
38+
- 查看轻节点相关文档，请参考 [`轻节点搭建工具 <https://fisco-bcos-doc.readthedocs.io/zh_CN/latest/docs/tutorial/lightnode.html>`_]
39+
40+
.. toctree::
41+
:hidden:
42+
:maxdepth: 0
43+
44+
3_11_0.md
45+
2446
v3.10.x
2547
------------------
2648

@@ -179,7 +201,7 @@ v3.3.x
179201
.. admonition:: FISCO BCOS 3.x Releases
180202

181203
- `FISCO BCOS v3.3.0 <./3_3_0.html>`_ [`release <https://github.com/FISCO-BCOS/FISCO-BCOS/releases/tag/v3.3.0>`_]
182-
204+
183205

184206
.. admonition:: 查看节点和数据版本
185207

@@ -209,7 +231,7 @@ v3.2.x
209231
- `FISCO BCOS v3.2.2 <./3_2_2.html>`_ [`release <https://github.com/FISCO-BCOS/FISCO-BCOS/releases/tag/v3.2.2>`_]
210232
- `FISCO BCOS v3.2.1 <./3_2_1.html>`_ [`release <https://github.com/FISCO-BCOS/FISCO-BCOS/releases/tag/v3.2.1>`_]
211233
- `FISCO BCOS v3.2.0 <./3_2_0.html>`_ [`release <https://github.com/FISCO-BCOS/FISCO-BCOS/releases/tag/v3.2.0>`_]
212-
234+
213235

214236
.. admonition:: 查看节点和数据版本
215237

@@ -241,7 +263,7 @@ v3.1.x
241263
- `FISCO BCOS v3.1.2 <./3_1_2.html>`_ [`release <https://github.com/FISCO-BCOS/FISCO-BCOS/releases/tag/v3.1.2>`_]
242264
- `FISCO BCOS v3.1.1 <./3_1_1.html>`_ [`release <https://github.com/FISCO-BCOS/FISCO-BCOS/releases/tag/v3.1.1>`_]
243265
- `FISCO BCOS v3.1.0 <./3_1_0.html>`_ [`release <https://github.com/FISCO-BCOS/FISCO-BCOS/releases/tag/v3.1.0>`_]
244-
266+
245267

246268
.. admonition:: 查看节点和数据版本
247269

@@ -265,7 +287,7 @@ v3.0.x
265287

266288
- `FISCO BCOS v3.0.1 <./3_0_1.html>`_ [`release <https://github.com/FISCO-BCOS/FISCO-BCOS/releases/tag/v3.0.1>`_]
267289
- `FISCO BCOS v3.0.0 <./3_0_0.html>`_ [`release <https://github.com/FISCO-BCOS/FISCO-BCOS/releases/tag/v3.0.0>`_]
268-
290+
269291

270292
.. admonition:: 查看节点和数据版本
271293

@@ -287,7 +309,7 @@ v3.0.0-rc4
287309
.. admonition:: FISCO BCOS 3.x Releases
288310

289311
- `FISCO BCOS v3.0.0-rc4 <./3_0_0_rc4.html>`_ [`release <https://github.com/FISCO-BCOS/FISCO-BCOS/releases/tag/v3.0.0-rc4>`_]
290-
312+
291313

292314
.. admonition:: 查看节点和数据版本
293315

@@ -309,9 +331,9 @@ v3.0.0-rc3
309331
.. admonition:: FISCO BCOS 3.x Releases
310332

311333
- `FISCO BCOS v3.0.0-rc3 <./3_0_0_rc3.html>`_ [`release <https://github.com/FISCO-BCOS/FISCO-BCOS/releases/tag/v3.0.0-rc3>`_]
312-
334+
313335
- v3.0.0-rc3不包括 ``FISCO BCOS Max`` 版本，Max版本的FISCO BCOS会在后续版本中推出
314-
336+
315337

316338
.. admonition:: 查看节点和数据版本
317339

@@ -332,9 +354,9 @@ v3.0.0-rc2
332354
.. admonition:: FISCO BCOS 3.x Releases
333355

334356
- `FISCO BCOS v3.0.0-rc2 <./3_0_0_rc2.html>`_ [`release <https://github.com/FISCO-BCOS/FISCO-BCOS/releases/tag/v3.0.0-rc2>`_]
335-
357+
336358
- v3.0.0-rc2不包括 ``FISCO BCOS Max`` 版本，Max版本的FISCO BCOS会在后续版本中推出
337-
359+
338360

339361
.. admonition:: 查看节点和数据版本
340362

@@ -356,7 +378,7 @@ v3.0.0-rc1
356378
.. admonition:: FISCO BCOS 3.x Releases
357379

358380
- `FISCO BCOS v3.0.0-rc1 <./3_0_0_rc1.html>`_ [`release <https://github.com/FISCO-BCOS/FISCO-BCOS/releases/tag/v3.0.0-rc1>`_]
359-
381+
360382
- v3.0.0-rc1不包括 ``FISCO BCOS Max`` 版本，Max版本的FISCO BCOS会在后续版本中推出
361383

362384
.. admonition:: 查看节点和数据版本

‎3.x/zh_CN/docs/operation_and_maintenance/snapshot.md

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
# 15. 快照功能
2+
3+
标签：``运维``，``快照``
4+
5+
---
6+
7+
## 简介
8+
9+
v3.11.0开始支持了快照的导入和导出功能，快照功能可以帮助用户快速备份和恢复链上数据，当新节点加入时也可以通过快照减少同步到最新状态所需要的时间。
10+
11+
## 生成快照
12+
13+
### 生成完整快照
14+
15+
生成完整快照是将区块链上的状态数据、交易和收据完整的导出，快照的大小与节点数据目录(例如`./data`)的大小相近，生成快照的时间与数据目录的大小成正比。操作命令如下，其中`-s`表示是否携带交易与收据，`-o`表示快照的输出目录：
16+
17+
```bash
18+
# 生成完整快照，要在节点目录下执行
19+
../fisco-bcos -s true -o ./
20+
```
21+
22+
输出如下：
23+
24+
```bash
25+
[2024-08-26 16:41:07] generating snapshot to ./ ...
26+
current block number: 7883
27+
Traverse RocksDB: data
28+
".//snapshot/state/000000.sst" Finished. 1
29+
".//snapshot/block/000000.sst" Finished. 2
30+
generate snapshot success, the snapshot is in .//snapshot
31+
[2024-08-26 16:41:09] generate snapshot success.
32+
```
33+
34+
产生的快照位于输出目录下，例如`./snapshot`。
35+
36+
```bash
37+
$ ls snapshot
38+
block meta state
39+
```
40+
41+
snapshot目录下包含了三个文件夹，分别是`block`、`meta`和`state`，其中：
42+
43+
- `block`文件夹包含区块中的交易和收据数据
44+
- `meta`文件夹包含了快照的元信息
45+
- `state`文件夹包含了区块链的状态数据
46+
47+
### 生成状态快照，不包含历史区块的交易和收据
48+
49+
生成状态快照是将区块链上的状态数据导出，不包含历史区块的交易和收据，相比于完整快照，状态快照的空间占用会小很多。操作命令如下，其中`-s`表示是否携带交易与收据，`-o`表示快照的输出目录：
50+
51+
```bash
52+
# 生成状态快照，要在节点目录下执行
53+
../fisco-bcos -s false -o ./
54+
```
55+
56+
输出如下：
57+
58+
```bash
59+
[2024-08-26 16:40:12] generating snapshot to ./ ...
60+
current block number: 7883
61+
Traverse RocksDB: data
62+
".//snapshot/state/000000.sst" Finished. 1
63+
generate snapshot success, the snapshot is in .//snapshot
64+
[2024-08-26 16:40:12] generate snapshot success.
65+
```
66+
67+
snapshot文件夹与完整快照类似，只是没有了block文件夹。
68+
69+
## 导入快照
70+
71+
导入快照功能可以从快照中恢复区块链的状态数据，导入快照的时间与快照的大小成正比。操作命令如下，其中`-i`表示快照的输入目录：
72+
73+
```bash
74+
# 导入快照，要在节点目录下执行
75+
../fisco-bcos -i ./snapshot
76+
```
77+
78+
建议用户在通过快照生成新节点时，设置`config.ini`文件中`[storage].enable_separate_block_state=true`以避免快照导入过程中，可能出现的因为交易、收据和状态数据触发RocksDB的compaction，导致导入过程变慢。
79+
80+
导入过程中会提示用户选择导入方式，yes表示使用move模式，no表示使用copy模式，move模式会尝试移动快照中的文件，当可以移动时导入会很快，copy模式会拷贝快照中的数据，耗时取决于数据量大小。输出如下，
81+
82+
```bash
83+
[2024-08-26 16:41:52] importing snapshot from ./snapshot ...
84+
The block number of snapshot: 7883
85+
the snapshot will be ingested into data, if yes the snapshot will be moved, if no the snapshot will be copy(yes/no)
86+
no
87+
check sst files success, ingest sst files
88+
check sst files success, ingest sst files
89+
The block number of this node: 7883
90+
[2024-08-26 16:42:14] import snapshot success.
91+
```
92+
93+
## 归档区块同步
94+
95+
在支持快照的同时，节点`config.ini`新增了配置项`[storage].sync_archived_blocks`，默认值为`false`，当设置为`true`时，节点会通过p2p请求同步已经归档的区块。
96+
97+
节点执行过下面两种操作的任意一种，就会存在归档区块：
98+
99+
- 节点从状态快照生成时，没有交易和收据的区块会被认为是归档区块。
100+
- 节点通过归档工具做过归档。
101+
102+
从这种节点可以查询区块头，但当查询归档区块中的交易和收据时，节点会返回错误。
103+
104+
## 历史nonce清理功能
105+
106+
FISCO BCOS会存储最近1000个区块中交易的nonce，用来防范交易重放攻击，v3.11.0版本新增了历史nonce清理功能，会自动清理掉超出最近1000个块的nonce列表，减小节点存储压力，例如当前块高为1001，则提交1002时，会自动清理块高2的nonce列表。同时在命令行添加了手动清理历史区块nonce列表的命令，操作命令如下：
107+
108+
```bash
109+
# 导入快照，要在节点目录下执行
110+
../fisco-bcos --prune
111+
```

‎3.x/zh_CN/docs/quick_start/air_installation.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -49,18 +49,18 @@ sudo yum install -y curl openssl openssl-devel wget
4949

5050
```eval_rst
5151
.. note::
52-
如果因为网络问题导致长时间无法下载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
52+
如果因为网络问题导致长时间无法下载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
5353
```
5454

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

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

6262
# Note: 若访问git网速太慢，可尝试如下命令下载建链脚本:
63-
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
63+
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
6464
```
6565

6666
### 第三步. 搭建4节点非国密联盟链

0 commit comments

Comments
 (0)