EMQX 企业版

简体中文

English
日本語

简体中文

English
日本語

Appearance

联系我们
联系我们

版本热升级 ​

热升级允许在不停止 EMQX Enterprise 节点的情况下应用补丁版本更新。升级过程中连接保持不中断，节点在下次重启时切换到新的 Release 目录。

热升级仅支持补丁版本（版本号第三位）跨度。例如，支持从 5.10.4 升级到 5.10.5，但不支持从 5.10.x 升级到 5.11.0。

热升级由 emqx_relup 插件驱动。插件通过 Dashboard 安装，所有升级操作均通过 emqx ctl relup CLI 执行。

重要提示

执行热升级前，请备份 data/、etc/ 和 log/ 目录。升级完成后无法原地回滚。

前提条件 ​

  • 每个节点上的 EMQX Enterprise 均处于运行状态。
  • 具有 Shell 访问权限，可在每个节点上执行 emqx ctl 命令。
  • emqx_relup 插件版本与当前 EMQX Enterprise 版本匹配。
  • 目标版本已作为受支持的升级路径包含在插件中（在步骤 2 中验证）。

步骤 1：安装 emqx_relup 插件 ​

参照通过 Dashboard 安装插件的说明，通过 Dashboard 安装插件。插件包发布地址为 https://packages.emqx.io/emqx-plugins/e<EMQX-VSN>/。

安装完成后，插件状态应显示为 running。

步骤 2：确认升级路径受支持 ​

列出已安装插件支持的版本跨度：

bash
emqx ctl relup list-supported-paths

在继续操作之前，确认当前 {from, target} 版本对出现在输出中。

步骤 3：准备压缩包和 SHA256 校验文件 ​

将以下两个文件复制到每个节点，可放置于 EMQX 进程可读的任意位置：

  • emqx-enterprise-<TargetVsn>-<os>-<arch>.tar.gz：EMQX Enterprise 目标版本压缩包。
  • emqx-enterprise-<TargetVsn>-<os>-<arch>.tar.gz.sha256：压缩包的 SHA256 摘要文件。支持纯摘要格式和 sha256sum 输出格式（<digest> <filename>）。
bash
scp emqx-enterprise-<TargetVsn>-<os>-<arch>.tar.gz       node1:/opt/upgrade/
scp emqx-enterprise-<TargetVsn>-<os>-<arch>.tar.gz.sha256 node1:/opt/upgrade/

.sha256 文件必须与压缩包放在同一目录下，且文件名为压缩包名加 .sha256 后缀。

步骤 4：执行升级 ​

在每个节点上，指定压缩包路径触发升级：

bash
emqx ctl relup upgrade /opt/upgrade/emqx-enterprise-<TargetVsn>-<os>-<arch>.tar.gz

升级程序将执行以下步骤：

  1. 验证 SHA256 摘要，摘要不匹配时拒绝继续。
  2. 解压压缩包并从 releases/emqx_vars 中读取目标版本号。
  3. 仅将运行时子目录（bin/、erts-*/、lib/、releases/）部署到 <RootDir>/relup/<TargetVsn>/。配置、数据、日志和插件仍保留在原始安装根目录下。
  4. 应用插件 .relup 目录中匹配的代码变更指令。
  5. 运行升级后回调。
  6. 将目标版本号写入 <RootDir>/relup/current。

集群范围的升级推进由操作者负责。建议逐节点升级，验证无误后再继续下一个节点。

步骤 5：验证节点 ​

升级命令返回后，确认节点状态正常：

bash
# 检查节点是否正在运行
emqx ctl status

# 确认版本标记文件已写入
cat <RootDir>/relup/current

# 查看升级状态和历史记录
emqx ctl relup status
emqx ctl relup logs

relup/current 文件应包含目标版本号字符串，emqx ctl status 应显示节点正在运行。

步骤 6：重启切换到新版本 ​

代码变更升级在当前运行的虚拟机中立即生效。若要完全切换到新的 ERTS 运行时和二进制文件，需重启节点：

bash
emqx restart

重启时，bin/emqx 脚本检测到 <RootDir>/relup/current 后，会切换执行 <RootDir>/relup/<TargetVsn>/ 中的程序。原始 <RootDir> 仍作为 data/、etc/、log/ 和 plugins/ 的权威目录。

步骤 7：清理临时文件 ​

整个集群切换到目标版本后，删除临时升级文件：

bash
rm /opt/upgrade/emqx-enterprise-<TargetVsn>-<os>-<arch>.tar.gz
rm /opt/upgrade/emqx-enterprise-<TargetVsn>-<os>-<arch>.tar.gz.sha256

插件不追踪源文件路径，插件内部无需额外清理。

回滚 ​

热升级完成后无法原地回滚。代码变更已对运行中的虚拟机生效，升级后回调可能已修改磁盘数据，本插件不支持撤销这些操作。

以下两种有限的恢复方式可供参考：

  • 重启前： 如果升级后代码出现异常，但磁盘状态仍与旧版本兼容，可删除版本标记文件并重启，恢复到旧版本目录：

    bash
    rm <RootDir>/relup/current
# 可选：rm -rf <RootDir>/relup/<TargetVsn>/
emqx restart

    此操作仅恢复启动路径，升级过程中对运行时状态的修改已生效，无法撤销。

  • 完整恢复： 从升级前的备份中恢复 data/ 目录，并重新安装旧版本的 EMQX。

请在规划升级窗口时充分考虑上述限制。

CLI 参考 ​

命令说明
emqx ctl relup upgrade <TarballPath>使用指定压缩包应用升级跨度。
emqx ctl relup list-supported-paths列出插件目录中支持的 {当前版本, 目标版本} 升级路径。
emqx ctl relup status显示当前升级状态：idle（空闲）、in-progress（进行中）或 hot-upgraded to <vsn>; pending on restart to boot from the new version（已完成热升级，待重启切换到新版本）。
emqx ctl relup logs打印本节点持久化日志表中的升级历史记录。
emqx ctl relup logs-clear清空本节点的升级日志表。