> For the complete documentation index, see [llms.txt](https://yeasy.gitbook.io/blockchain_guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://yeasy.gitbook.io/blockchain_guide/10_fabric_op/upgrade.md).

# 如何升级版本

Fabric 保持了较好的向后兼容性，从 v1.0.0 版本开始支持手动升级到更高版本。

网络升级主要包括对如下资源进行升级：

* 核心组件：包括 Peer、Orderer、CA 等核心程序；
* 能力配置：更新通道配置中支持的能力集合版本号，以启动新的特性；
* 第三方资源：包括依赖的 CouchDB，以及旧网络中可能仍存在但升级到 Fabric 3.x 前必须迁移掉的 Kafka 排序服务。

## 能力类型

为了避免网络多个节点运行不同版本组件时出现分叉风险，自 1.1.0 版本起在通道配置中引入了能力（Capabilities），标记节点应当支持和启用的特性。如果某节点程序版本低于能力要求则无法加入或自动退出；同时通道内高版本的节点程序在提交校验时只启用指定的特性集合检查（可参考 core/handlers/validation/builtin）。

目前能力分为三种类型，分别管理不同范围，如下表所示。

| 类型                | 功能                       | 配置路径                              |
| ----------------- | ------------------------ | --------------------------------- |
| 通道（Channel）能力     | 通道整体相关能力，排序和 Peer 节点都得满足 | /Channel/Capabilities             |
| 排序（Orderer）能力     | 排序服务能力，只与排序节点有关          | /Channel/Orderer/Capabilities     |
| 应用（Application）能力 | 应用相关能力，只与 Peer 节点有关      | /Channel/Application/Capabilities |

如果要启用相应的能力，需要修改通道配置内对应配置。例如，用户可以指定通道能力为 v1.1.0，排序能力为 v1.1.0 模式下，而应用能力为 v1.3.0。此时，只有不低于 v1.1.0 版本（满足通道和排序能力的较大者）的排序节点，以及不低于 v1.3.0 版本（满足通道和应用能力的较大者）的 Peer 节点可以支持该通道。同时，即使排序节点和 Peer 节点程序版本更新（如 v2.x），仍然只会启用指定的能力集合。

需要注意能力配置只能调整到更新版本而不应回退，例如可以将能力模式 v1.3.0 更新为更高版本的 v1.4.0，反之无意义。这是因为旧版本的节点即便加入到通道内，仍然无法正常处理其中新版本启用阶段的交易。

其中，各能力集合的版本和内容（可参考 common/capabilities）如下表所示，注意并不与程序版本一致。

| 能力版本             | 起始程序版本 | 类型 | 能力内容                                     |
| ---------------- | ------ | -- | ---------------------------------------- |
| ChannelV1\_1     | v1.1.0 | 通道 | 仅供标记，程序版本为 1.1.0+                        |
| ChannelV1\_3     | v1.3.0 | 通道 | 支持 idemix                                |
| OrdererV1\_1     | v1.1.0 | 排序 | 重新提交和身份超时检查                              |
| OrdererV2\_0     | v2.0.0 | 排序 | 排序服务支持从 Kafka 切换到 Raft                   |
| ApplicationV1\_1 | v1.1.0 | 应用 | 禁止区块内重复交易Id                              |
| ApplicationV1\_2 | v1.2.0 | 应用 | 正式支持私有数据，支持升级私有数据成员组配置，细粒度的通道资源访问控制（ACL） |
| ApplicationV1\_3 | v1.3.0 | 应用 | 支持基于键值的背书                                |
| ApplicationV2\_0 | v2.0.0 | 应用 | 新的链码生命周期管理                               |
| ApplicationV2\_0 | v2.0.0 | 应用 | 支持链码操作                                   |

## 推荐升级步骤

### 升级排序服务

对于不改变排序模式的情况下，升级较为简单。

逐个停止排序节点，并备份本地数据，包括身份文件、账本数据、配置文件等。

升级排序服务程序。重新启动并检查是否工作正常，如获取区块、发送交易等。

*注：自 Fabric v2.3 起，Kafka 排序服务已被正式废弃；升级到 v3.x 之前，应先完成从 Kafka 到 Raft 的迁移。对于新部署网络，当前更稳妥的默认建议仍是优先使用 **Raft**；BFT 更适合在确有拜占庭容错需求时专项评估，而不应简单视为 v3.0+ 的默认首选。*

### 升级 Peer 节点

逐个停止 Peer 节点，并备份本地数据，包括身份文件、账本数据、链码包、配置文件等。

升级 Peer 程序。重新启动并检查是否工作正常，如查询信息、发送交易提案等。

链码包如果之前有引入旧的第三方库或者 Shim 包，或者需要启用新的 API，则还要执行链码升级操作。

### 升级 CA 服务

停止 Fabric-CA 服务，备份数据库。

升级 fabric-ca 程序，重新启动并检查是否工作正常，如获取根证书。

```bash
$ fabric-ca-client getcacert -u https://<fabric-ca-server>:7054 --tls.certfiles tls-cert.pem
```

### 升级通道配置

按照新的格式发送通道更新请求，特别是修改对应能力域值为新的版本。

对于 Fabric 2.x 中仍保留系统通道的旧网络，升级到 Fabric 3.x 前必须先按照官方流程迁移到 Channel Participation API 并移除系统通道；Fabric 3.x 不再支持系统通道，也不支持通过系统通道创建应用通道。

能力配置应按通道逐步更新：先确认排序节点、Peer 节点二进制版本均已满足目标能力，再分别更新各应用通道的 Channel、Orderer 和 Application 能力。更新后测试网络功能，如获取新区块、提交配置更新、调用链码等是否正常。

### 升级第三方组件

包括 CouchDB 等第三方组件，升级之前最好备份数据文件。

CouchDB 版本自 1.x 版本可以很容易升级到高版本，具体操作可以参考项目文档：<https://docs.couchdb.org/en/stable/install/upgrading.html。>

如果网络仍停留在 Kafka 排序服务上，更稳妥的做法不是继续升级 Kafka，而是尽快按照官方迁移文档转向 Raft，再继续进行 Fabric 主版本升级。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://yeasy.gitbook.io/blockchain_guide/10_fabric_op/upgrade.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.