Merge pull request #1696 from wenlinlee/0602

add upgrade guide doc

3.x/zh_CN/docs/operation_and_maintenance/browser.md

@@ -1,4 +1,4 @@
-# 14. 区块链浏览器
+# 15. 区块链浏览器
 标签：``区块链浏览器`` ``图形化``
 
 ------

3.x/zh_CN/docs/operation_and_maintenance/data_index.md

@@ -1,4 +1,4 @@
-# 11. 数据治理通用组件
+# 12. 数据治理通用组件
 
 标签：``WeBankBlockchain-Data`` ``数据治理`` ``通用组件`` ``数据导出`` ``数据仓库`` ``数据对账``
 

3.x/zh_CN/docs/operation_and_maintenance/governance_index.md

@@ -1,4 +1,4 @@
-# 12. 多方协作治理组件
+# 13. 多方协作治理组件
 
 标签：``WeBankBlockchain-Governance`` ``区块链多方协作治理`` ``通用组件`` ``账户治理`` ``权限治理`` ``私钥管理`` ``证书管理``
 

3.x/zh_CN/docs/operation_and_maintenance/log/index.md

@@ -1,4 +1,4 @@
-# 13. 日志说明
+# 14. 日志说明
 标签： ``日志说明``  ``日志审计``
 使用手册：
 

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

@@ -1,4 +1,4 @@
-# 14. 运维手册
+# 15. 运维手册
 
 标签：``运维``
 
@@ -27,7 +27,7 @@ log_level|time|[module_name] content
 info|2022-11-21 20:00:35.479505|[SCHEDULER][blk-1]BlockExecutive prepare: fillBlock end,txNum=1,cost=0,fetchNum=1
 ```
 
-其中log_level为日志级别，从小到大包括trace、debug、info、warning、error、fatal，time表示日志打印时间，[module_name]表示模块名，包括共识、同步、交易池、存储等，content为具体日志内容。常规日志分析和问题定位，可查看[日志说明](./log_description.md)。
+其中log_level为日志级别，从小到大包括trace、debug、info、warning、error、fatal，time表示日志打印时间，[module_name]表示模块名，包括共识、同步、交易池、存储等，content为具体日志内容。常规日志分析和问题定位，可查看[日志说明](./log/index.md)。
 
 日志输出级别设定在config.ini文件配置，在测试环境中，建议设置为trace或debug级别，可以输出所有级别的日志，便于分析定位问题。在生产环境时，建议设置为info级别，减少日志输出量（trace和debug日志量较大），避免日志磁盘占用过多。
 

3.x/zh_CN/docs/operation_and_maintenance/upgrade_guide.md

@@ -0,0 +1,192 @@
+# 11. FISCO BCOS版本升级指引
+----------
+
+本文档主要从三个方面讨论FISCO BCOS的升级之路，以解答社区用户在FISCO BCOS实际应用过程中的升级需求。以由易至难、由近至远的思路分为以下三个部分：
+- 第一部分，指引完成FISCO BCOS 3.x版本之间的升级；
+- 第二部分，FISCO BCOS三种不同部署架构Air、Pro和Max之间升级；
+- 第三部分，如何实现从FISCO BCOS 2.0至3.0的升级。
+
+
+## 1. FISCO BCOS 3.x版本之间的升级
+
+FISOC BCOS每个版本都会在原有版本的基础上添加新的特性。包含两种升级方式，可根据升级需求选择：
+1. 提升系统稳定性与性能：仅升级节点可执行程序
+2. 使用新特性：升级节点可执行程序、升级链数据版本
+
+### 1.1 升级节点可执行程序
+
+- 升级效果：修复bug，并带来稳定性、性能的提升
+
+- 操作步骤：逐步停止节点服务，升级节点可执行程序为当前版本后，重启节点服务
+
+- 注意事项：推荐逐步替换可执行程序进行灰度升级，升级前备份原节点的所有账本数据，若操作失误造成升级失败，可通过原数据回滚到升级前的状态
+
+支持升级的版本：v3.0.0+
+
+### 1.2 升级链数据版本
+
+- 升级效果：可使用当前版本的最新特性
+
+- 操作步骤：先完成升级所有节点可执行程序，再参考以下步骤，通过发送交易升级链数据版本至新版本v3.x.x
+
+- 注意事项：务必备份原节点的所有账本数据，若操作失误造成升级失败，可通过原数据回滚到升级前的状态
+
+
+升级数据兼容版本号详细步骤如下：
+
+#### a. 查询数据兼容版本号（compatibility_version）
+
+用[控制台](https://fisco-bcos-doc.readthedocs.io/zh_CN/latest/docs/operation_and_maintenance/console/console_commands.html#getsystemconfigbykey)进行查询，如当前返回的版本为3.0.1
+
+``` 
+[group0]: /apps>  getSystemConfigByKey compatibility_version
+3.0.1
+```
+
+#### b. 替换节点二进制
+
+需将**所有节点**的二进制逐步替换为当前版本。为了不影响业务，替换过程能够以灰度方式进行，逐个替换并重启节点。替换过程中，当前的链仍然会以旧的数据兼容版本号的逻辑继续执行。当所有节点二进制替换完成并重启后，需用控制台修改数据兼容版本号为当前版本。
+
+#### c. 设置数据兼容版本号（compatibility_version）
+
+用[控制台](https://fisco-bcos-doc.readthedocs.io/zh_CN/latest/docs/operation_and_maintenance/console/console_commands.html#setsystemconfigbykey)设置数据兼容版本号，如升级版本至3.1.0。
+
+```
+[group0]: /apps>  setSystemConfigByKey compatibility_version 3.1.0
+{
+    "code":0,
+    "msg":"success"
+}
+
+注：若开启权限治理功能，需要使用 setSysConfigProposal 命令
+```
+
+设置成功，再次查询，得到当前版本已升级为3.1.0
+
+``` 
+[group0]: /apps>  getSystemConfigByKey compatibility_version
+3.1.0
+```
+
+当前链已经完成升级，至此，链开始以新的逻辑继续运行，并支持了新版本特性。
+## 2. FISCO BCOS Air、Pro和Max之间的升级
+通过深研不同场景用户的诉求，FISCO BCOS推出Air、Pro以Max三种不同的部署型态，用户可根据需求定制选择。但在实际应用过程中，随着业务与需求的变化，用户存在Air升级Pro、Pro升级Max此类的需求。本节基于此背景，探讨三种部署型态之间的升级操作。
+
+**注意**：升级之前请务必备份好数据，保证链可回滚至升级前的状态。
+![](https://fisco-bcos-doc.readthedocs.io/zh_CN/latest/_images/fisco_bcos_version.png)
+
+
+### 2.1 Air至Pro的升级
+要实现Air升级Pro，需要明白两者之间技术架构与部署形式的不同。
+- 相同点：Air与Pro之间底层存储数据库均是采用RocksDB
+- 不同点：Air采用all-in-one的封装模式，Pro由群组层+接入层的架构提供服务
+
+基于Air与Pro之间的异同，要实现Air至Pro的升级有以下两种方案：
+- 基于现有的Air节点，扩容一个Pro节点
+- 基于当前的Air节点，将其重构升级为Pro节点
+
+具体方案描述如下。
+
+#### 方案一：Air区块链扩容Pro节点
+基于现有的Air节点，在其基础上扩容一个pro节点，这样既可以保存之前Air的链上数据，扩容出的Pro节点又满足了业务需求。此方案的优点是操作简单，不需要改变现有组织架构。详细步骤如下：
+
+1.  利用BcosBuilder部署工具，部署tar服务，具体步骤可以参考[《搭建pro版区块链网络》](https://fisco-bcos-doc.readthedocs.io/zh_CN/latest/docs/tutorial/pro/installation.html)与[《Pro扩容节点》](https://fisco-bcos-doc.readthedocs.io/zh_CN/latest/docs/tutorial/pro/expand_node.html)；
+2.  在部署pro节点之前，配置pro/conf目录下的config-node-expand-example.toml文件，配置Air创世块文件路径等信息；
+3.  下载二进制，根据配置文件部署Pro节点，将扩容生成的Pro的ca文件替换为Air的根证书，具体扩容步骤可参考[《Pro节点扩容》](https://fisco-bcos-doc.readthedocs.io/zh_CN/latest/docs/tutorial/pro/expand_node.html)；
+4.  启动Pro节点，通过控制台连接Pro节点，将Pro节点添加至Air区块链网络；
+5.  pro节点同步至最新区块后，用户可选择是否下线Air节点服务。
+
+通过上述步骤，可在原有Air基础上扩容出Pro版节点，进而实现Air至Pro的升级，用户在业务使用过程中也可以再进一步扩容Pro网络。
+
+#### 方案二：Air区块链重构升级
+Air与Pro的底层存储模式相同，Air的区块链数据升级至Pro版后仍然可用。因此，理论上只需将Air目录结构重构为Pro的目录结构，通过部署相关Pro的服务，然后将之前Air的数据复用至Pro相应目录即可。此方案详细步骤如下：
+
+1. 停止Air节点，保存链上数据与链配置信息：将Air的节点数据/data目录、创世块、config.ini配置文件、证书等数据备份；
+2. 按照Pro版的目录结构，将Air链的目录文件结构重构为Pro的目录结构；
+3. 即通过BcosBuilder部署工具，部署Pro版的RPC、getawat以及node等服务；
+4. 通过BcosBuilder部署工具步骤部署Pro链，将创世块、config.ini、证书以及链数据data目录下的文件，替换为之前的Air的相关文件；
+5. 导入Air数据，将之前备份的Air的data数据导入至pro节点的数据目录，启动节点。
+
+通过上述操作，用户可以将原有Air网络替换为Pro网络，相对于方案一操作较复杂，需要用户对Air于Pro的组织结构较深的了解。
+
+
+### 2.2 Pro至Max版的升级
+因为Pro与Max采用不用的存储架构：Pro采用的单机性能突出的RocksDB，而Max版采用分布式存储架构tikvDB。所以在Pro升级至Max中，无法复用账本数据。在此情况下，只有扩容方案能实现Pro版升级Max。具体方案如下：
+
+
+### 方案：Pro区块链扩容Max节点
+Pro区块链扩容Max节点具体步骤如下：
+1. 利用BcosBuilder部署工具安装依赖，安装配置Tars服务；
+2. 下载安装tiup，部署启动Tikv；
+3. 下载Max搭链相关二进制，修改BcosBuilder/max/conf目录下的示例配置文件config-node-expand-example.toml，配置创世块路径(为Pro区块链创世块文件)等相关信息；
+4. 部署Max节点服务，扩容出Max节点，扩容完成后将生成的max节点目录的ca文件替换为原有Pro链的根证书，具体步骤可参考[《搭建Max版区块链网络》](https://fisco-bcos-doc.readthedocs.io/zh_CN/latest/docs/tutorial/max/installation.html)；
+5. 启动Max节点，通过控制台连接Max节点，将Max节点添加至原有的Pro区块链网络，查看链是否正常运行。Max节点同步至最新快后，可选择是否下线Pro节点。
+
+通过上述步骤，实现Pro网络扩容Max，原有Pro网络服务升级，用户可以体验大容量Max版功能，同样支持在后续使用中继续增加扩容Max节点。
+
+
+## 3. FISCO BCOS 2.0升级至3.0指引
+FISCO BCOS 3.0版本在2.0基础上进行架构升级和优化，在可扩展性、性能、易用性等方面取得了重大突破，其中包括：
+- Pipelined：区块流水线，连续且紧凑地生成区块；
+- 全方位并行计算：块内分片、DMC、DAG等并行机制，实现强大处理性能；
+- 区块链文件系统: 所见即所得的合约数据管理；
+- 权限治理框架：内置权限治理框架，多方投票治理区块链；
+- 分布式存储TiKV：分布式事务性提交，支撑海量存储；
+
+由于FISCO BCOS 3.0+版本相对于2.0进行了若干重大的重构，无法做到完美的向下兼容。而部分已上线2.x版本的用户，存在升级值3.0+的需求。为解决此问题，以下列举了几种可行升级方案，每个方案拥有不同的优缺点，适用于不同的业务场景。
+
+**注意**：升级之前请务必备份好数据，保证数据可回滚。
+### 方案一：数据重放
+
+数据重放是当前最为普遍的区块链数据迁移方法之一，因为简易、直观，相对而言副作用也比较小。
+
+实施方法：
+1. 使用最新版本的搭链脚本搭建一条3.0+新链；
+2. 使用数据导出组件快速导出区块链上的数据，获得链上所有方法和合约的执行历史及详细数据；
+3. 编写程序或脚本，将导出的数据按照块高进行数据重放。使得将生产环境的老链上的合约和交易，到新链上按原先的运行时序重新再执行一遍。
+
+本方案的优点：
+- 简易、直观，副作用小，即便升级失败不影响旧链运行
+
+本方案的缺点是：
+- 重放时间长：不适应长期运行的海量数据的场景，如果交易区块高度超过300万，则重放时间将超过1个月（假设共识和出块时间周期为1s）；
+- 无法保证同一区块执行的顺序：即使在重放时，按照区块的顺序提交和发送交易，但是同一区块内的交易执行的顺序仍然是随机的；
+- 无法保证交易精准落在原有的块高：由于区块打包共识的周期和次序具有随机性质，重放时很难保证具体的块高下的交易数量和次序。
+
+所以，本方案适用于对合约数据的一致性要求不严格，但对数据完整性有一定要求的场景；不适用于对数据的一致性非常严格、海量数据的场景。
+
+### 方案二：应用层适配
+
+本方案的核心设计无需改动历史链及数据，而在新老链之间提供一层数据适配层屏蔽链的细节处理，故而能减少对链的数据操作。而历史数据的完整性和精确性也是本方案最大的优势。
+
+实施方法：
+用户可以单独开发一个兼容新老链的数据适配应用，通过数据ID或日期等特征来作为路由区分的标志，对不同的数据进行路由。同时，新链上复制老链的智能合约。
+
+本方案的优点：
+- 具备良好的历史数据完整性和精确性
+
+本方案的缺点是：
+- 数据隔离：新链和老链之间的数据是物理隔离的，因此新老数据存在依赖关系的场景无法采纳本方案；
+- 维护成本高：必须维护新老两条链，硬件等维护成本高；
+- 开发成本高：必须开发一套独立的数据路由适配层，开发成本较高。
+
+因此，本方案适用于部分数据之间无依赖关系的场景；而一些数据强依赖的场景，例如积分、支付结算等场景无法适用。此外，此方案需要额外开发数据适配程序，其难度视具体的合约和场景而定，但是后续的各项维护成本非常高。
+
+### 方案三：跨链方案
+
+本方案类似于方案二，将新链与旧链当作两条链，事务涉及旧链数据时利用跨链平台发起跨链事务请求，此方案也不需要改动历史链及数据，相比于方案二无需再开发一套独立的数据路由适配层。
+
+实施方法：
+首先，利用最新建链脚本搭建一条新链，通过跨链平台WeCross将两条链连接，新业务均由新链处理，事务涉及历史数据跨链平台发起跨链事务请求，路由至两条链上去处理，处理结果存储至两条链中。
+
+本方案优点：
+- 开发成本低，无需开发数据适配应用；
+- 具有历史数据的完整性和精确性。
+
+
+本方案缺点：
+- 事务执行慢：跨链事务处理慢，性能不高，前期的每一笔事务均是跨链事务；
+- 维护成本高：必须维护新老两条链，硬件等维护成本高。
+
+本方案新链构建前期性能低，频繁的跨链路由对网络要求较高，此外使用者也需要维护两条链，维护成本较高。
+

3.x/zh_CN/index.rst

@@ -326,10 +326,11 @@ FISCO BCOS开源社区致力打造开放多元的开源联盟链生态，至今
    docs/operation_and_maintenance/add_new_node.md
    docs/operation_and_maintenance/stress_testing.md
    docs/operation_and_maintenance/upgrade.md
+   docs/operation_and_maintenance/upgrade_guide.md
    docs/operation_and_maintenance/data_index.md
    docs/operation_and_maintenance/governance_index.md
    docs/operation_and_maintenance/log/index.md
-   docs/operation_and_maintenance/docs/operation_and_maintenance.md
+   docs/operation_and_maintenance/operation_and_maintenance.md
 
 
 .. toctree::