滚动升级
在集群中的 EMQX 节点可以一次一个地进行升级，无需停掉整个集群。这个过程被称为滚动升级。为了实现平滑的客户端会话迁移，在 EMQX 企业版中您可以使用集群重平衡功能，在升级节点之前将客户端从节点中迁移到其他节点。关于集群再平衡的更多信息，请参见此文档。
升级到 EMQX 5.9 或更高版本的重要 License 说明
从 5.9.0 版本开始，EMQX 企业版采用商业源代码许可协议发布，替代了之前开源版与企业版分开的模式。
TIP
关于 License 变更的详细信息，请参阅 EMQX Licensing FAQ。
尽管升级 EMQX 的技术步骤（如替换可执行文件）与之前版本类似，但从 5.9.0 开始引入了关键的 License 变更，特别是对于集群部署。如果您正从 5.9 之前的开源版本升级，或从单节点部署切换到集群部署，请务必注意以下几点：
- 新的 Licensing 模式：EMQX 5.9.0 及以上版本默认提供 EMQX 社区版 License。该 License 允许启用所有功能，但仅支持单节点部署。
- 集群要求：之前的开源版本支持集群部署。而在 5.9.0 及以上版本中，默认情况下不再支持集群功能。如果您希望保留集群能力，必须申请商业 License。
- License 配置要求：在集群中启动任何运行 5.9.0 及以上版本的节点之前，必须在该节点上正确配置商业 License。如果未配置或配置错误，该节点将无法在集群中正常工作。
注意
如果在 emqx.conf 中添加 License 的配置，那么来自 Dashboard、HTTP API 或 CLI 的更改会在节点重启后失效， 这是因为节点启动加载配置时，emqx.conf 和环境变量具有最高优先级。
5.0 起支持的滚动升级路径
以下为 5.0 起支持的滚动升级路径矩阵。为便于阅读，矩阵被拆分为两张表；v5 末期版本（5.8 – 5.10）会同时出现在两张表中。
- 版本号末尾带
?的（如6.3?）表示尚未发布的版本。 - ✅：已支持，或计划支持。
- ⚠️：受限支持。
- ❌：不支持。
详细信息请参阅各版本的发布说明。
v5 内部 (5.0 – 5.10)
| 源\目标 | 5.1 | 5.2 | 5.3 | 5.4 | 5.5 | 5.6 | 5.7 | 5.8 | 5.9 | 5.10 |
|---|---|---|---|---|---|---|---|---|---|---|
| 5.0 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⚠️[1] | ❌[2] |
| 5.1 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌[2] |
| 5.2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌[2] | |
| 5.3 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌[2] | ||
| 5.4 | ✅ | ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ | |||
| 5.5 | ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ | ||||
| 5.6 | ✅ | ✅ | ✅ | ✅ | ✅ | |||||
| 5.7 | ✅ | ✅ | ✅ | ✅ | ||||||
| 5.8 | ✅ | ⚠️[3] | ⚠️[3] | |||||||
| 5.9 | ✅ | ✅ | ||||||||
| 5.10 | ✅ |
- [1] 升级前需要从配置文件（
etc/emqx.conf与data/configs/cluster-override.conf）中删除旧的限速器（limiter）配置。 - [2] 5.4 以前版本的路由表将会被丢弃。请先升级到 5.9，然后执行一次全集群重启（非滚动），再升级到 5.10 或更高版本。
- [3] OpenTelemetry header 配置支持是从 5.8.7 引入的，其发布日期晚于 5.9.0 和 5.10.0。运行 5.8.7 或更高 5.8.x 版本时，需通过滚动升级至 5.9.1 或 5.10.1。或者，在升级过程中移除 OpenTelemetry 集成的 header 配置。
升级到 v6 (5.8 – 6.3?)
| 源\目标 | 5.8 | 5.9 | 5.10 | 6.0 | 6.1 | 6.2 | 6.3? |
|---|---|---|---|---|---|---|---|
| 5.8 | ✅ | ⚠️[3] | ⚠️[3] | ⚠️[4] | ⚠️[4] | ⚠️[4] | ⚠️[4] |
| 5.9 | ✅ | ✅ | ⚠️[4] | ⚠️[4] | ⚠️[4] | ⚠️[4] | |
| 5.10 | ✅ | ⚠️[4] | ⚠️[4] | ⚠️[4] | ⚠️[4] | ||
| 6.0 | ✅ | ✅ | ✅ | ✅ | |||
| 6.1 | ✅ | ✅ | ✅ | ||||
| 6.2 | ✅ | ✅ | |||||
| 6.3? | ✅ |
- [4] 从 v5 升级到 v6 后，持久会话状态会丢失。客户端重新连接后，在新节点上创建的会话将表现为全新的（clean）会话。
EMQX 5.10 或更高版本的滚动升级注意事项
从 EMQX 5.10.0 开始，仅支持 v2 路由表。旧版的 v1 路由表（在 5.4.0 之前的版本中为默认）已不再兼容。因此，仍在使用 v1 路由表的集群（尤其是从早期版本逐步滚动升级而来的集群）无法执行滚动升级到 5.10.0 或更高版本。
重要说明
如果你的集群仍使用 v1 路由表，必须执行整集群重启以完成升级。
检查当前路由表
在升级前，可以通过以下命令检查集群当前使用的路由表：
$ emqx eval 'emqx_router:get_schema_vsn()'- 如果输出为
v2，则可以正常执行滚动升级。 - 如果输出为
v1，则需要按照下方步骤执行整集群重启。
升级使用 v1 路由表的集群
如果你的集群当前使用 v1 路由表，请按照以下步骤升级到 EMQX 5.10.0 或更高版本：
- 停止集群中所有节点。
- 删除所有配置文件中定义的
broker.routing.storage_schema选项。 - 将所有节点升级到 5.10.0 或更高版本。
- 先启动核心节点。
- 再启动复制节点。
如何执行滚动升级
集群节点升级过程
- 使用集群重平衡将客户端从节点中清除。(可选)
- 停止旧版本节点。
- 备份节点的配置文件和数据目录。
- 安装新版本的 EMQX。
- 启动新版本节点。
Core/replicant 集群升级过程*
在 Core/Replicant 集群中，应分组交替升级节点，以保持集群的稳定性：
- 首先升级一个 核心节点（core node）。
- 然后升级一部分 从属节点（replicant nodes）（例如，当有三个核心节点时，可先升级大约三分之一的从属节点）。
- 继续在核心节点和从属节点之间交替升级，直到所有节点都完成升级。
这种方式可确保在整个升级过程中，从属节点始终能够连接到与其版本兼容的核心节点。
注意
在滚动升级期间，请勿进行集群范围的配置更改。从 Dashboard、HTTP API 或 CLI 进行的配置更改将应用于集群中的所有节点。在滚动升级期间进行配置更改可能会导致节点不同步。
使用 RPM 和 DEB 包进行升级
如果您使用的是 RPM 或 DEB 包，可以直接安装新版本包覆盖旧版本，以完成升级。
使用 Docker 进行升级
如果您使用的是 Docker 部署，可以通过拉取新版本镜像并重启容器的方式完成升级。
从开源版升级到企业版
如果您正在运行 EMQX 的开源版本，并希望升级到企业版，这个过程与升级到开源版的新版本相同。
在安装和升级方面，EMQX 的开源版和企业版没有区别。唯一的注意点是，在每次升级后，您需要手动为企业版节点配置您的 License， 但是在所有节点升级之前，不能将 License 应用于整个集群。
例如，在 etc/base.hocon （如果升级到 e5.8.5 之前的版本，则在 etc/emqx.conf) 中添加以下行：
license.key = "你的 license"注意
如果在 emqx.conf 中添加 License 的配置，那么来自 Dashboard、HTTP API 或 CLI 的更改会在节点重启后失效， 这是因为节点启动加载配置时，emqx.conf 和环境变量具有最高优先级。