10. 版本升级指南


本文档主要从三个方面讨论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)

控制台进行查询,如当前返回的版本为3.0.1

[group0]: /apps>  getSystemConfigByKey compatibility_version
3.0.1

b. 替换节点二进制

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

c. 开启新版本特性

从3.2.4、3.6.0版本开始,FISCO BCOS提供按需开启新特性、问题修复的能力,问题修复和新特性列表如下:

特性名 类型 作用 最低版本
bugfix_revert 问题修复 修复使用串行模式时(is_serial=true),智能合约回滚后没有撤销已写入状态数据的问题 3.2.4 3.6.0
bugfix_statestorage_hash 问题修复
bugfix_evm_create2_delegatecall_staticcall_codecopy 问题修复
bugfix_event_log_order 问题修复
bugfix_call_noaddr_return 问题修复
bugfix_precompiled_codehash 问题修复
bugfix_dmc_revert 问题修复 修复使用DMC模式时(is_serial=false,未启用feature_sharding),智能合约回滚后没有撤销已写入状态数据的问题
bugfix_keypage_system_entry_hash 问题修复
bugfix_internal_create_redundant_storage
feature_dmc2serial 新特性 3.2.4
feature_sharding 新特性
feature_rpbft 新特性
feature_paillier 新特性
feature_balance 新特性
feature_balance_precompiled 新特性
feature_balance_policy1 新特性
feature_paillier_add_raw 新特性
feature_predeploy 新特性

启用问题修复或新特性,在控制台执行

setSystemConfigByKey <特姓名>

d. 设置数据兼容版本号(compatibility_version)

控制台设置数据兼容版本号,如升级版本至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

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

设置链版本号后,3.6.x版本及以上的链会自动启用所有最低版本及以上的bugfix。

2. FISCO BCOS Air、Pro和Max之间的升级

通过深研不同场景用户的诉求,FISCO BCOS推出Air、Pro以Max三种不同的部署型态,用户可根据需求定制选择。但在实际应用过程中,随着业务与需求的变化,用户存在Air升级Pro、Pro升级Max此类的需求。本节基于此背景,探讨三种部署型态之间的升级操作。

注意:升级之前请务必备份好数据,保证链可回滚至升级前的状态。

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版区块链网络》《Pro扩容节点》

  2. 在部署pro节点之前,配置pro/conf目录下的config-node-expand-example.toml文件,配置Air创世块文件路径等信息;

  3. 下载二进制,根据配置文件部署Pro节点,将扩容生成的Pro的ca文件替换为Air的根证书,具体扩容步骤可参考《Pro节点扩容》

  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版区块链网络》

  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将两条链连接,新业务均由新链处理,事务涉及历史数据跨链平台发起跨链事务请求,路由至两条链上去处理,处理结果存储至两条链中。

本方案优点:

  • 开发成本低,无需开发数据适配应用;

  • 具有历史数据的完整性和精确性。

本方案缺点:

  • 事务执行慢:跨链事务处理慢,性能不高,前期的每一笔事务均是跨链事务;

  • 维护成本高:必须维护新老两条链,硬件等维护成本高。

本方案新链构建前期性能低,频繁的跨链路由对网络要求较高,此外使用者也需要维护两条链,维护成本较高。