# 滚动升级

在集群中的 EMQX 节点可以一次一个地进行升级，无需停掉整个集群。这个过程被称为滚动升级。为了实现平滑的客户端会话迁移，在 EMQX 企业版中您可以使用集群重平衡功能，在升级节点之前将客户端从节点中迁移到其他节点。关于集群再平衡的更多信息，请参见[此文档](../deploy/cluster/rebalancing.md)。

## 升级到 EMQX 5.9 或更高版本的重要 License 说明

从 5.9.0 版本开始，EMQX 企业版采用商业源代码许可协议发布，替代了之前开源版与企业版分开的模式。

::: tip

关于 License 变更的详细信息，请参阅 [EMQX Licensing FAQ](https://www.emqx.com/zh/content/license-faq)。

:::

尽管升级 EMQX 的技术步骤（如替换可执行文件）与之前版本类似，但从 5.9.0 开始引入了关键的 License 变更，特别是对于集群部署。如果您正从 **5.9 之前的开源版本**升级，或从单节点部署切换到集群部署，请务必注意以下几点：

1. **新的 Licensing 模式**：EMQX 5.9.0 及以上版本默认提供 EMQX 社区版 License。该 License 允许启用所有功能，但仅支持单节点部署。
2. **集群要求**：之前的开源版本支持集群部署。而在 5.9.0 及以上版本中，默认情况下不再支持集群功能。如果您希望保留集群能力，必须[申请商业 License](./license.md#获取-license)。
3. **License 配置要求**：在集群中启动任何运行 5.9.0 及以上版本的节点之前，必须在该节点上正确[配置商业 License](./license.md#更新和设置-license)。如果未配置或配置错误，该节点将无法在集群中正常工作。

:::tip 注意
如果在 `emqx.conf` 中添加 License 的配置，那么来自 Dashboard、HTTP API 或 CLI 的更改会在节点重启后失效，
这是因为节点启动加载配置时，`emqx.conf` 和环境变量具有最高优先级。
:::

## 自 5.0 起的滚动升级路径

下表展示了自 5.0 版本以来支持的滚动升级路径矩阵。

- 以 `?` 结尾的版本号（如 `6.1?`）表示未来发布的版本。
- ✅：已支持，或计划支持。
- ⚠️：已支持，但存在限制。
- ❌：不支持。
- 🔄：计划在未来版本中提供完整支持。

详细信息请参见[发布说明](../changes/all-changes-ee.md)。

| 从\升级至 | 5.1  | 5.2  | 5.3  | 5.4  | 5.5  | 5.6  | 5.7  | 5.8  | 5.9  | 5.10 | 6.0  | 6.1? |
| --------- | ---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- |
| 5.0       | ✅    | ✅    | ✅    | ✅    | ✅    | ✅    | ✅    | ✅    | ⚠️[1] | ❌[2] | ❌[2] | ❌[2] |
| 5.1       | ✅    | ✅    | ✅    | ✅    | ✅    | ✅    | ✅    | ✅    | ✅    | ❌[2] | ❌[2] | ❌[2] |
| 5.2       |      | ✅    | ✅    | ✅    | ✅    | ✅    | ✅    | ✅    | ✅    | ❌[2] | ❌[2] | ❌[2] |
| 5.3       |      |      | ✅    | ✅    | ✅    | ✅    | ✅    | ✅    | ✅    | ❌[2] | ❌[2] | ❌[2] |
| 5.4       |      |      |      | ✅    | ✅    | ⚠️    | ✅    | ✅    | ✅    | ✅    | ✅    | ✅    |
| 5.5       |      |      |      |      | ✅    | ⚠️    | ✅    | ✅    | ✅    | ✅    | ✅    | ✅    |
| 5.6       |      |      |      |      |      | ✅    | ✅    | ✅    | ✅    | ✅    | ✅    | ✅    |
| 5.7       |      |      |      |      |      |      | ✅    | ✅    | ✅    | ✅    | ⚠️[4] | ⚠️[4] |
| 5.8       |      |      |      |      |      |      |      | ✅    | ⚠️[3] | ⚠️[3] | ⚠️[4] | ⚠️[4] |
| 5.9       |      |      |      |      |      |      |      |      | ✅    | ✅    | ⚠️[4] | ⚠️[4] |
| 5.10      |      |      |      |      |      |      |      |      |      | ✅    | ⚠️[4] | ⚠️[4] |
| 6.0       |      |      |      |      |      |      |      |      |      |      | ✅    | ✅    |
| 6.1?      |      |      |      |      |      |      |      |      |      |      |      | ✅    |

备注：

- [1] 升级前需从配置文件中删除旧的限流器配置（`etc/emqx.conf` 和 `data/configs/cluster-override.conf`）。
- [2] 升级将删除 pre-5.4 的路由表。需先升级至 5.9，并执行一次全集群重启（非滚动升级），然后再升级至 5.10 或更高版本。
- [3] Opentelemetry 请求头的配置支持是在 5.8.7 中引入的，其发布时间晚于 5.9.0 和 5.10.0。如果当前运行的是 5.8.7 或更高版本，则需滚动升级至 5.9.1 或 5.10.1。或者在升级过程中移除 OpenTelemetry 集成的头部配置。
- [4] 从 v5 升级到 v6 后，持久会话状态将会丢失。客户端重新连接后，在新节点上创建的会话将表现为“全新会话”。

## EMQX 5.10 或更高版本的滚动升级注意事项

从 EMQX 5.10.0 开始，仅支持 _v2_ 路由表。旧版的 _v1_ 路由表（在 5.4.0 之前的版本中为默认）已不再兼容。因此，仍在使用 *v1* 路由表的集群（尤其是从早期版本逐步滚动升级而来的集群）无法执行滚动升级到 5.10.0 或更高版本。

::: tip 重要说明

如果你的集群仍使用 *v1* 路由表，必须执行整集群重启以完成升级。

:::

### 检查当前路由表

在升级前，可以通过以下命令检查集群当前使用的路由表：

```
$ emqx eval 'emqx_router:get_schema_vsn()'
```

- 如果输出为 `v2`，则可以正常执行滚动升级。
- 如果输出为 `v1`，则需要按照下方步骤执行整集群重启。

### 升级使用 *v1* 路由表的集群

如果你的集群当前使用 *v1* 路由表，请按照以下步骤升级到 EMQX 5.10.0 或更高版本：

1. 停止集群中**所有节点**。
2. 删除所有配置文件中定义的 `broker.routing.storage_schema` 选项。
3. 将所有节点升级到 5.10.0 或更高版本。
4. 先启动核心节点。
5. 再启动复制节点。

## 如何执行滚动升级

**集群节点升级过程**

1. 使用集群重平衡将客户端从节点中清除。(可选)
2. 停止旧版本节点。
3. [备份](../operations/backup-restore.md)节点的配置文件和数据目录。
4. 安装新版本的 EMQX。
5. 启动新版本节点。

**Core/replicant 集群升级过程***

在 Core/Replicant 集群中，应分组交替升级节点，以保持集群的稳定性：
- 首先升级一个 核心节点（core node）。
- 然后升级一部分 从属节点（replicant nodes）（例如，当有三个核心节点时，可先升级大约三分之一的从属节点）。
- 继续在核心节点和从属节点之间交替升级，直到所有节点都完成升级。

这种方式可确保在整个升级过程中，从属节点始终能够连接到与其版本兼容的核心节点。

:::tip 注意
在滚动升级期间，请勿进行集群范围的配置更改。从 Dashboard、HTTP API 或 CLI 进行的配置更改将应用于集群中的所有节点。在滚动升级期间进行配置更改可能会导致节点不同步。
:::

## 使用 RPM 和 DEB 包进行升级
如果您使用的是 RPM 或 DEB 包，可以直接安装新版本包覆盖旧版本，以完成升级。

## 使用 Docker 进行升级
如果您使用的是 Docker 部署，可以通过拉取新版本镜像并重启容器的方式完成升级。

## 从开源版升级到企业版
如果您正在运行 EMQX 的开源版本，并希望升级到企业版，这个过程与升级到开源版的新版本相同。

在安装和升级方面，EMQX 的开源版和企业版没有区别。唯一的注意点是，在每次升级后，您需要手动为企业版节点[配置您的 License](./license.md)，
但是在所有节点升级之前，不能将 License 应用于整个集群。

例如，在 `etc/base.hocon` （如果升级到 `e5.8.5` 之前的版本，则在 `etc/emqx.conf`) 中添加以下行：
```
license.key = "你的 license"
```

:::tip 注意
如果在 emqx.conf 中添加 License 的配置，那么来自 Dashboard、HTTP API 或 CLI 的更改会在节点重启后失效，
这是因为节点启动加载配置时，`emqx.conf` 和环境变量具有最高优先级。
:::